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 仓库缓存，提高构建速度。
使用本地仓库镜像加速依赖下载。

可选映射库建议（补充）

说明：为降低手动复制属性导致的错误并统一映射规则（例如 Long -> String 的 id 映射），团队可以选择引入映射库（如 MapStruct）以生成高效且可维护的转换代码。此处为可选建议：

若采纳 MapStruct，推荐在 pom.xml 中通过 <dependencyManagement> 或 <properties> 约定 MapStruct 及其注解处理器的版本，并在 05-依赖管理规范.md 中记录推荐版本。示例版本：MapStruct 1.5.x（请根据项目的 Spring Boot / Java 版本选择兼容版本）。
引入映射库后，应在 Code Review 与 CI 中加入对生成代码的检查，确保映射规则（如 id 字段转为字符串）在 mapper 接口中有明确配置。
若不引入映射库，请在 01-代码风格指南.md 中保留映射示例（手动 copy + 显式 id.toString()）作为团队约定。

与 API 文档相关的依赖（补充）

说明：生成正确的 Swagger/OpenAPI 文档依赖于项目中所使用的文档库及其兼容版本（例如 springdoc-openapi 与 Knife4j）。泛型返回类型在文档中不被正确解析，通常靠注解显式声明解决，但依赖版本也会影响行为。建议：

保持 springdoc-openapi 与 knife4j 的版本在依赖管理中统一声明，并记录推荐版本（当前项目使用 knife4j-openapi3-jakarta-spring-boot-starter:4.4.0，请参考与之兼容的 springdoc-openapi 版本）。
若使用 springdoc-openapi，必要时在配置中通过 OpenApiCustomiser 或 ModelConverters 注册额外模型（additionalModels）以帮助生成器解析自定义类型。
依赖示例与说明需写入本文件，以便团队在引入或升级文档依赖时遵循统一版本策略。

示例（pom 片段说明思路，仅供参考）：

<!-- 统一在 <properties> 中声明文档组件版本 -->
<properties>
  <springdoc.version>1.6.14</springdoc.version>
  <knife4j.version>4.4.0</knife4j.version>
</properties>

<!-- 依赖管理区 -->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>${springdoc.version}</version>
</dependency>
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
  <version>${knife4j.version}</version>
</dependency>

05-依赖管理规范.md 6.5 KB History Raw