maven依赖

发表于 2021-09-28 更新于 2025-08-01 分类于 maven Waline：阅读次数：本文字数： 4.8k 阅读时长 ≈ 4 分钟

Maven 依赖管理：从基础配置到冲突解决

Maven 的核心功能之一是依赖管理，它通过标准化的方式管理项目所需的 Jar 包，自动处理依赖的下载、传递和版本控制。本文将详细讲解 Maven 依赖的配置、范围、传递性及冲突解决策略。

依赖的基本配置

Maven 依赖通过 pom.xml 中的 <dependencies> 标签管理，每个依赖通过 GAV 坐标 唯一标识：

<dependencies>
  <!-- 单个依赖配置 -->
  <dependency>
    <groupId>组织标识</groupId> <!-- 如 org.springframework.boot -->
    <artifactId>项目标识</artifactId> <!-- 如 spring-boot-starter-web -->
    <version>版本号</version> <!-- 如 2.7.0 -->
    <scope>依赖范围</scope> <!-- 如 compile、test，可选 -->
    <!-- 其他可选配置：exclusions、type 等 -->
  </dependency>
</dependencies>

GAV 坐标：groupId（组织）、artifactId（项目）、version（版本）三者组合唯一确定一个依赖，Maven 通过坐标从仓库下载 Jar 包。
版本规范：通常包含主版本（如 2）、次版本（如 7）、修订号（如 0），快照版以 -SNAPSHOT 结尾（如 2.7.0-SNAPSHOT）。

依赖范围（scope）

依赖范围控制依赖在 Maven 生命周期各阶段 的可见性（如编译、测试、运行），以及是否传递给下游项目。Maven 提供 6 种依赖范围：

范围	主程序编译	测试编译	主程序运行	测试运行	打包（如 Jar）	依赖传递性	典型场景
`compile`	✅	✅	✅	✅	✅	可传递	核心依赖（如 Spring 核心包）
`test`	❌	✅	❌	✅	❌	不可传递	测试框架（如 JUnit、Mockito）
`provided`	✅	✅	❌	✅	❌	不可传递	容器提供的依赖（如 Servlet API）
`runtime`	❌	✅	✅	✅	✅	可传递	运行时依赖（如 JDBC 驱动）
`system`	✅	✅	❌	✅	❌	不可传递	本地 Jar 包（需指定路径）
`import`	-	-	-	-	-	特殊处理	导入依赖管理配置（仅用于 `dependencyManagement`）

关键范围解析：

compile（默认）：
- 全程有效，是最常用的依赖范围。
- 例如：spring-core 需在编译、测试、运行阶段都存在。
test：
- 仅用于测试相关的代码（src/test/java）。
- 例如：junit-jupiter-api 仅在执行 mvn test 时需要。
provided：
- 编译和测试时需要，但运行时由容器（如 Tomcat）提供，避免打包冲突。
- 例如：javax.servlet-api 在 Tomcat 中已存在，无需打入项目 Jar/War。
runtime：
- 编译时不需要（代码不直接依赖其 API），但运行时必须存在。
- 例如：mysql-connector-java（JDBC 驱动，代码通过 JDBC 接口调用，编译时无需具体驱动）。

system：

与provided类似，但依赖不从 Maven 仓库下载，需通过systemPath指定本地路径：

<dependency>
  <groupId>com.example</groupId>
  <artifactId>local-sdk</artifactId>
  <version>1.0</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/lib/local-sdk.jar</systemPath> <!-- 相对项目根目录的路径 -->
</dependency>

注意：不推荐使用，会导致项目移植性变差（需手动同步本地 Jar 包）。

import：

仅用于dependencyManagement中，导入其他 POM 的依赖管理配置：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>2.7.0</version>
      <type>pom</type>
      <scope>import</scope> <!-- 导入 Spring Boot 的依赖管理 -->
    </dependency>
  </dependencies>
</dependencyManagement>

依赖的传递性与原则

Maven 依赖具有传递性：若项目 A 依赖 B，B 依赖 C，则 A 会自动依赖 C（除非 B 对 C 的依赖范围是 test、provided 等不可传递的范围）。

传递性依赖可能导致版本冲突，Maven 通过以下原则解决：

1. 路径最短优先

依赖路径短的版本优先被采用。
示例：

项目 A 直接依赖 C:1.0（路径长度 1）。
项目 A 依赖 B，B 依赖 C:2.0（路径长度 2）。
结果：A 最终使用 C:1.0（路径更短）。

2. 声明顺序优先

若依赖路径长度相同，则在 pom.xml 中先声明的依赖版本优先。
示例：

<dependencies>
  <!-- 先声明：依赖 B，B 依赖 C:1.0 -->
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>B</artifactId>
    <version>1.0</version>
  </dependency>
  
  <!-- 后声明：依赖 D，D 依赖 C:2.0 -->
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>D</artifactId>
    <version>1.0</version>
  </dependency>
</dependencies>

A 到 C 的路径长度均为 2（A→B→C 和 A→D→C）。
结果：A 最终使用 C:1.0（因 B 先声明）。

3. 覆写优先（就近原则）

子项目中显式声明的依赖版本，优先于父项目或传递依赖的版本。
示例：

父项目依赖 C:1.0。
子项目显式声明依赖 C:2.0。
结果：子项目使用 C:2.0（覆写父项目配置）。

依赖冲突解决

尽管 Maven 有冲突解决原则，但仍可能出现不符合预期的版本依赖（如低版本存在 Bug）。此时需手动干预，常用方法如下：

1. 排除依赖（exclusions）

通过 <exclusions> 标签排除传递依赖中不需要的版本：

<dependency>
  <groupId>org.apache.hadoop</groupId>
  <artifactId>hadoop-client</artifactId>
  <version>2.6.0</version>
  <!-- 排除冲突的日志依赖 -->
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId> <!-- 无需指定版本，会排除所有版本 -->
    </exclusion>
    <exclusion>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
    </exclusion>
  </exclusions>
</dependency>

注意：<exclusion> 中只需指定 groupId 和 artifactId，无需 version，会排除所有匹配的传递依赖。

2. 锁定版本（dependencyManagement）

在 dependencyManagement 中声明依赖版本，统一管理项目中所有依赖的版本（包括传递依赖）：

<!-- 仅声明版本，不实际引入依赖 -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.13.0</version> <!-- 锁定版本为 2.13.0 -->
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- 实际引入依赖（无需指定 version，继承自 dependencyManagement） -->
<dependencies>
  <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
  </dependency>
</dependencies>

作用：

统一项目依赖版本，避免传递依赖带来的版本混乱。
dependencyManagement 仅声明版本，不实际引入依赖，需在 <dependencies> 中显式引入才会生效。

3. 查看依赖树（辅助工具）

使用 mvn dependency:tree 命令查看依赖树，定位冲突的依赖路径：

mvn dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-databind

-Dincludes 可过滤指定依赖，便于快速定位问题。
输出结果中，冲突的版本会被标记为 omitted for conflict with x.x.x。

依赖管理最佳实践

优先使用 dependencyManagement：统一管理版本，减少冲突概率。
避免使用 system 范围：尽量将本地 Jar 包安装到仓库（mvn install:install-file）。
定期检查依赖更新：使用 mvn versions:display-dependency-updates 查看可更新的依赖。
最小化依赖范围：如测试依赖用 test，容器提供的依赖用 provided，减少打包体积。
排除冗余依赖：通过 mvn dependency:analyze 识别未使用的依赖，及时清理。