ChronicDisease_SpringBoot/docs/DevRule/05-依赖管理规范.md

05-依赖管理规范.md

概述

本规范定义了项目中依赖管理的原则和实践，确保依赖项的选择、版本控制和更新符合项目需求，并维护代码的稳定性和安全性。

依赖管理原则

1. 版本统一管理

• 在 pom.xml 的 <properties> 标签中定义依赖版本，避免在各依赖声明中硬编码版本号。

• 示例：

  <properties>
    <spring-boot.version>3.0.13</spring-boot.version>
  </properties>
  

2. 使用 Spring Boot BOM

• 通过 <dependencyManagement> 引入 spring-boot-dependencies BOM 来管理 Spring 生态相关依赖的版本。

• 示例：

  <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
  </dependencyManagement>
  

3. 依赖选择标准

• 优先选择官方维护、社区活跃的库。
• 选择与当前技术栈兼容的版本，特别是 Jakarta EE 兼容版本（如 Knife4j 的 Jakarta EE 版本）。
• 避免引入过多依赖，优先使用 Spring Boot 内置功能。

4. 版本稳定性

• 选择稳定版本，避免使用 SNAPSHOT 或 alpha/beta 版本。
• 定期检查并更新依赖版本，确保安全补丁和性能改进。

主要依赖规范

1. Spring Boot 生态

• 使用 Spring Boot 3.x 版本，确保 Jakarta EE 兼容性。
• 核心依赖包括：
  • spring-boot-starter：基础启动器
  • spring-boot-starter-web：Web 开发
  • spring-boot-starter-validation：参数校验

2. 数据访问层

• MyBatis-Plus：使用 3.5.3 版本，提供 ORM 功能。
• PageHelper：使用 1.4.2 版本，提供分页支持。
• MySQL Connector：使用 5.1.49 版本，确保数据库连接兼容性。

3. 工具库

• Lombok：使用 1.18.24 版本，简化 Java 代码。
• Hutool：使用 5.8.22 版本，提供通用工具方法。

4. API 文档

• Knife4j：使用 4.4.0 Jakarta EE 兼容版本，提供 API 文档生成。

当前项目实际依赖（摘自 pom.xml）

• Spring Boot 版本：3.0.13
• MyBatis-Plus：3.5.3
• PageHelper：1.4.2
• Lombok：1.18.24（scope=provided）
• Hutool：5.8.22
• MySQL Connector：5.1.49
• Knife4j（Jakarta）：knife4j-openapi3-jakarta-spring-boot-starter:4.4.0

注意：当前 pom.xml 中存在重复声明 spring-boot-starter-validation（出现了两次），建议去重以保持清晰。

依赖更新策略

1. 定期审查

• 定期检查依赖版本，关注安全漏洞和兼容性问题。
• 使用工具如 Maven Dependency Plugin 检查依赖树。

2. 兼容性测试

• 更新依赖后，进行全面测试，确保功能正常。
• 特别注意 Spring Boot 版本升级时的 breaking changes。

3. 版本锁定

• 在生产环境中，使用 Maven 的 dependency locking 机制确保版本一致性。

依赖冲突解决

1. 排除冲突依赖

• 使用 <exclusions> 标签排除不需要的传递依赖。

• 示例：

  <dependency>
    <groupId>com.example</groupId>
    <artifactId>example</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.unwanted</groupId>
            <artifactId>unwanted-artifact</artifactId>
        </exclusion>
    </exclusions>
  </dependency>
  

2. 依赖分析

• 使用 mvn dependency:tree 分析依赖树，识别冲突。
• 使用 mvn dependency:analyze 检查未使用的依赖。

安全考虑

1. 漏洞扫描

• 定期使用安全扫描工具检查依赖中的已知漏洞。
• 及时更新受影响的依赖版本。

2. 最小权限原则

• 只引入必要的依赖，避免过度依赖。
• 使用 <scope> 限制依赖作用域，如 provided 用于编译时依赖。

构建优化

1. 依赖瘦身

• 使用 Spring Boot 的 fat jar 打包，包含运行时依赖。
• 排除测试依赖和开发工具依赖。

2. 缓存管理

• 配置 Maven 仓库缓存，提高构建速度。
• 使用本地仓库镜像加速依赖下载。