# 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 文档生成。

## 依赖更新策略

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