# 05-依赖管理规范.md

## 概述

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

## 依赖管理原则

### 1. 版本统一管理
- 在 `pom.xml` 的 `<properties>` 标签中定义依赖版本，避免在各依赖声明中硬编码版本号。
- 示例：
  ```xml
  <properties>
      <spring-boot.version>3.0.13</spring-boot.version>
  </properties>
  ```

### 2. 使用 Spring Boot BOM
- 通过 `<dependencyManagement>` 引入 `spring-boot-dependencies` BOM 来管理 Spring 生态相关依赖的版本。
- 示例：
  ```xml
  <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>` 标签排除不需要的传递依赖。
- 示例：
  ```xml
  <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 片段说明思路，仅供参考）：
```xml
<!-- 统一在 <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>
```