构建与依赖 / 系统课时

传递依赖与依赖路径

传递依赖与依赖路径

项目只在 pom.xml 里声明一个库,构建结果里却常常出现更多 JAR。本节用真实依赖树追踪这些库的来源,并说明 scope、optional 和 exclusion 如何改变传递路径,最后形成一套可复用的排查顺序。

学习目标

  • 能区分直接依赖与传递依赖,并读懂一条完整依赖路径。
  • 能用 dependency:tree 定位某个库是被谁带入项目的。
  • 能判断作用域、可选依赖和排除规则是否会截断传递。

从一个直接依赖看传递结果

下面的完整 pom.xml 只直接声明 Apache HttpClient 4.5.14。它自己的 POM 还声明了 HttpCore 等依赖,因此 Maven 解析项目时会继续读取这些坐标,把符合传递规则的库加入当前项目的依赖图。

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>dependency-path-demo</artifactId>
  <version>1.0-SNAPSHOT</version>

  <dependencies>
    <!-- 只声明一个直接依赖,便于观察它带入的传递依赖 -->
    <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.14</version>
    </dependency>
  </dependencies>
</project>

配置生效后,在该 pom.xml 所在目录执行 Maven Dependency Plugin 的 tree 目标。下面固定使用插件 3.11.0;该版本要求 Maven 3.6.3 及以上、JDK 8 及以上。

bash
mvn org.apache.maven.plugins:maven-dependency-plugin:3.11.0:tree -Dincludes=org.apache.httpcomponents:httpcore

预期输出的关键路径如下,下载进度和耗时会因本地仓库状态不同而变化。

text
[INFO] com.example:dependency-path-demo:jar:1.0-SNAPSHOT
[INFO] \- org.apache.httpcomponents:httpclient:jar:4.5.14:compile
[INFO]    \- org.apache.httpcomponents:httpcore:jar:4.4.16:compile

第一层 httpclient 是项目直接声明的依赖,下一层 httpcore 是它带入的传递依赖。排查时不要只看“项目里有这个 JAR”,而要把从项目根节点到目标库的整条路径读出来。

用过滤条件追踪某个库

大型项目的依赖树可能有几百行,直接全看很慢。-Dincludes=groupId:artifactId 会只保留与目标坐标有关的路径,适合回答“这个库为什么会进来”。例如继续只追踪 httpcore,并开启 verbose 查看被冲突调解省略的节点。

bash
mvn org.apache.maven.plugins:maven-dependency-plugin:3.11.0:tree -Dincludes=org.apache.httpcomponents:httpcore -Dverbose

预期结果仍应包含 httpclient:4.5.14 -> httpcore:4.4.16 这条路径;当前示例没有第二个 httpcore 版本,因此不会出现 omitted for conflict。

text
[INFO] com.example:dependency-path-demo:jar:1.0-SNAPSHOT
[INFO] \- org.apache.httpcomponents:httpclient:jar:4.5.14:compile
[INFO]    \- org.apache.httpcomponents:httpcore:jar:4.4.16:compile

实际项目可先复制报错类所在 JAR 的 groupId 和 artifactId,再用同样命令过滤。若目标库出现多条路径,就继续比较每条路径的深度、版本和作用域,而不是立刻在 POM 里盲目加版本。

哪些规则会截断传递

传递并不等于“下游所有依赖都无条件进入”。最常见的三个截断点可以直接按下表检查;遇到树上缺库时,先看这些规则,比反复删除本地仓库更有效。

规则 具体行为 排查时看什么
optional=true 依赖对声明它的项目可用,但不会自动继续传给依赖该项目的下游项目 打开上游 POM,检查目标依赖是否标记为可选
<exclusions> 只切断指定依赖路径,不会全局禁止同一坐标从其他路径进入 检查当前直接依赖节点下是否排除了目标 groupId:artifactId
scope Maven 会按作用域组合规则决定传递后的有效作用域,某些组合会被省略 在 dependency:tree 中检查每个节点末尾的 compile、runtime、test 等

例如,项目依赖 A,而 A 把 Z 标记为 optional,项目不会仅因为依赖 A 就得到 Z;如果项目确实需要 Z,应在自己的 dependencies 中显式声明。排除规则也只针对一条父依赖路径,同一个 Z 仍可能从 B 路径再次进入。

按固定顺序定位依赖来源

真实项目里建议固定使用四步:先确认目标坐标,再过滤依赖树,随后找出第一层直接依赖,最后才决定是否排除或显式声明版本。这样能避免把“来源问题”和“版本冲突问题”混在一起。

  1. 从异常堆栈、IDE External Libraries 或 JAR 名称确认目标 groupId:artifactId。
  2. 执行 dependency:tree -Dincludes=目标坐标 -Dverbose,保留完整路径证据。
  3. 找到路径上离项目最近的直接依赖,打开它的 POM 核对 scope、optional 和排除项。
  4. 只有确认该路径不该存在时才加 <exclusions>;如果代码确实直接使用目标库,优先在当前项目显式声明它,而不是依赖偶然的传递关系。

依赖树的价值不是把所有 JAR 列出来,而是把“谁带进来的、经过哪条路径、最终以什么作用域出现”一次说清。以后遇到缺类、重复版本或意外引入库时,都先保存这条路径证据再修改 POM。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

传递依赖与依赖路径

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通