内容总览
一、起源
1.1 手工管理 jar 的三个问题
在 Maven 出现之前,Java 项目的第三方库以 jar 文件形式由人工维护,典型做法是在项目内建 lib 目录,由开发者下载 jar 放入,并在 IDE 或构建脚本中配置 classpath。这种方式在工程规模扩大后暴露三类问题。
| 问题 | 具体表现 | 后果 |
|---|---|---|
| 版本不一致 | 同一库在不同项目、不同模块中放置不同版本的 jar,或同一目录下同时存在两个版本 | 编译通过的代码在另一环境运行失败;缺陷修复只在部分模块生效 |
| 传递依赖难以维护 | 所用库本身还依赖其他库,手工方式下必须逐个查出并下载 | 漏掉一个间接依赖即出现 ClassNotFoundException;补全过程无法复现 |
| classpath 冲突 | 多个 jar 提供相同包名或类名,或同一库的两个版本同时进入 classpath | 加载顺序决定实际生效的类,行为随机且与运行环境相关;NoSuchMethodError 难以定位 |
根因在于:依赖关系只存在于开发者的记忆与目录约定中,没有可被工具读取的机器可读描述,构建结果依赖机器状态。
1.2 Maven 依赖模型的解决思路
Maven 把依赖关系从"文件摆放"转变为"坐标声明 + 仓库解析",包含三个阶段。
- 坐标声明:项目在
pom.xml中用groupId、artifactId、version等要素声明需要什么构件,而不描述从哪里获取、放到哪里。 - 仓库解析:Maven 按本地仓库、远程仓库、镜像的顺序把坐标解析为具体文件,下载结果按固定目录结构缓存到本地仓库,同一坐标在任何机器上得到同一构件。
- 传递依赖自动展开与调解:Maven 递归读取每个构件的 POM,把其依赖加入依赖图;当同一构件出现多个版本时,按固定规则选取唯一版本。
由此得到两个直接收益:依赖描述的机器可读化使构建可复现;版本调解规则使冲突由隐式的 classpath 顺序问题变为显式的、可查询的依赖图问题(通过依赖树查看)。
二、原理
2.1 依赖坐标的六个要素
一个依赖声明由六个要素描述,其中前三个为必需项(可来自父 POM 继承),后三个有默认值。
| 要素 | 含义 | 是否必需 | 默认值 | 说明 |
|---|---|---|---|---|
groupId | 组织或项目组标识,通常为反转域名 | 是(可由父 POM 继承) | 无 | 与 artifactId 共同构成构件身份 |
artifactId | 构件标识,在同一 groupId 下唯一 | 是 | 无 | 不含版本信息 |
version | 版本号 | 是(在 dependencyManagement 中代为管理时可省略) | 无 | SNAPSHOT 后缀表示快照版本 |
type | 构件类型,即打包格式 | 否 | jar | 取值如 jar、war、pom、maven-plugin、test-jar |
classifier | 分类器,区分同一坐标下的不同产物 | 否 | 无(空字符串) | 如 sources、javadoc、tests |
scope | 依赖范围,决定参与哪些 classpath 以及是否传递 | 否 | compile | 详见 2.2 |
坐标的完整字符串形式为 groupId:artifactId:type:classifier:version,例如 org.springframework:spring-core:jar:5.3.30;classifier 为空时在命令中常写为 groupId:artifactId:type:version。
类型与分类器的作用:type 决定解析时查找的文件扩展名与打包方式;classifier 用于同一构件的附加产物,例如引入某库的 test-jar 时需要同时指定 type=test-jar 或 classifier=tests。<type> 的取值与作用在 Maven 官网完整配置 中有逐项说明,此处不重复。
2.2 依赖范围 scope 全解
2.2.1 各 scope 的语义
| scope | 语义 | 典型用途 |
|---|---|---|
compile | 默认值。编译、测试、运行全程可见,并随项目传递给下游 | 业务代码直接使用的工具库、框架 |
provided | 编译与测试可见,运行时由外部环境(容器、JDK)提供,不打入产物,不传递 | servlet-api(Tomcat 提供)、lombok(仅编译期注解处理) |
runtime | 编译期不可见,测试执行与运行期可见并打入产物,可传递 | JDBC 驱动、日志实现 |
test | 仅测试代码的编译与执行可见,不参与打包与运行,不传递 | JUnit、Mockito |
system | 语义接近 provided,但构件由 systemPath 指定本地绝对路径,不经过仓库解析 | 本地存在但未入私服的第三方 jar |
import | 仅用于 dependencyManagement 内,配合 type=pom 导入其他 POM 的依赖管理段,不引入实际依赖 | 导入 BOM,详见 2.6 |
2.2.2 各 scope 在三条 classpath 上的可见性对照
| scope | 主代码编译 | 测试编译与执行 | 运行(打入产物) | 是否传递给下游 | 是否参与依赖调解 |
|---|---|---|---|---|---|
compile | 可见 | 可见 | 可见 | 传递(compile) | 参与 |
provided | 可见 | 可见 | 不可见 | 不传递 | 参与(仅本模块) |
runtime | 不可见 | 可见 | 可见 | 传递(runtime) | 参与 |
test | 不可见 | 可见 | 不可见 | 不传递 | 仅测试依赖图内 |
system | 可见 | 可见 | 不可见 | 不传递 | 仅本模块 |
import | 不适用 | 不适用 | 不适用 | 不适用 | 不参与 |
2.2.3 provided 与容器部署
provided 的语义是"编译时需要这套 API,运行时由部署环境提供"。典型场景是 Servlet 容器:javax.servlet-api 或 jakarta.servlet-api 由 Tomcat 在运行时通过自身类加载器提供,若打包进 WAR 的 WEB-INF/lib,会与容器自带版本同时存在于类加载路径,形成版本冲突,同时违反 Servlet 规范。
要点:
provided依赖不会被打入最终产物(WAR 的WEB-INF/lib、可执行 JAR 的BOOT-INF/lib)。provided依赖不会传递给下游模块;下游若编译时需要,必须自行声明。- Spring Boot 的可执行 JAR 内嵌容器,因此使用内嵌容器时不需要
provided;只有以 WAR 部署到外部容器时才将容器相关依赖声明为provided。
2.2.4 test 不传递
test 依赖仅存在于当前模块的测试依赖图中,既不会出现在下游模块的编译或运行路径,也不会出现在下游模块的测试路径(因为没有义务向别的模块提供测试类)。若某框架的测试支持类需要跨模块复用,应通过 test-jar 类型显式发布与声明,而不是依赖 test scope 的传递性。
2.2.5 system 的风险与替代方案
system scope 配合 systemPath 的写法如下,其风险集中在"路径"这一非坐标属性上。
<dependency>
<groupId>com.example</groupId>
<artifactId>legacy-sdk</artifactId>
<version>1.0.0</version>
<scope>system</scope>
<systemPath>${project.basedir}/lib/legacy-sdk.jar</systemPath>
</dependency>
风险清单:
| 风险 | 说明 |
|---|---|
| 构建不可移植 | 路径是绝对路径或基于 basedir 的相对路径,换机器、换目录即失败 |
| 绕过仓库与校验 | 不走仓库解析,没有校验和,版本变更不会被依赖树反映 |
| 无法传递 | 下游模块必须重复同样的路径声明,违背坐标声明的初衷 |
| 工具链不完整 | 依赖树、依赖分析、收敛检查对该构件的判断失真 |
替代方案:用 mvn install:install-file 把本地 jar 装入本地仓库或私服,获得正式坐标后按普通依赖声明使用。
mvn install:install-file -Dfile=lib/legacy-sdk.jar \
-DgroupId=com.example -DartifactId=legacy-sdk -Dversion=1.0.0 -Dpackaging=jar
2.3 传递依赖与依赖调解
2.3.1 传递依赖如何逐层展开
Maven 解析依赖时,从当前项目的 <dependencies> 出发,读取每个构件的 POM,把其中符合传递条件的依赖加入依赖图,并递归处理,直至没有新节点。依赖图中的每个节点都记录了从根项目到该节点的路径,路径长度即"深度"。
进入依赖图的条件:
- 该依赖在来源 POM 中未被声明为
optional。 - 该依赖的 scope 允许传递(
compile、runtime可传递;provided、test、system不传递)。 - 该依赖通过
exclusions未被排除。
2.3.2 两条调解规则
同一个构件(groupId:artifactId)在依赖图中出现多个版本时,Maven 只保留一个版本,选取规则有两条,按顺序判断。
- 最短路径优先:路径深度最小的版本胜出,与版本号大小无关。
- 同深度先声明优先:路径深度相同时,在 POM 中声明位置靠前的路径胜出。
冲突示例一(同深度,先声明优先):
app
├── lib-a:1.0
│ └── common:1.0
└── lib-b:1.0
└── common:2.0
common 的两条路径深度都是 2,无法用规则一区分,此时按 lib-a 与 lib-b 的声明顺序决定:lib-a 在前则最终生效 common:1.0;声明顺序对调则生效 common:2.0。结论是:依赖的最终版本会被 pom.xml 中无关条目的顺序改变,因此实际项目中不应依赖声明顺序,而应用 dependencyManagement 显式固定。
冲突示例二(不同深度,最短路径优先):
app
├── common:1.0 (深度 1,直接依赖)
└── lib-b:1.0 (深度 1)
└── common:2.0 (深度 2,传递依赖)
common:1.0 深度更小,最终生效。即使 common:2.0 修复了缺陷或提供了新 API,只要没有显式覆盖,项目得到的仍是 1.0。
2.3.3 版本覆盖实际生效的判定顺序
调解结果只是候选,最终生效版本按以下顺序判定,前一步命中即停止。
| 顺序 | 判定来源 | 说明 |
|---|---|---|
| 1 | 依赖声明中显式写出的 version | 直接依赖上写了版本,即以该版本为准,dependencyManagement 不再介入 |
| 2 | 当前 POM 及其父 POM 的 dependencyManagement | 对直接依赖与传递依赖同样生效;命中即覆盖调解结果 |
| 3 | dependencyManagement 中 import 的 BOM | 按 2.6 的优先级规则参与,位于本 POM 直接声明条目之后 |
| 4 | 依赖调解结果(2.3.2 两条规则) | 无更优先来源时使用 |
该顺序的实际意义:只要在 dependencyManagement 中给出某构件的版本,无论它出现在依赖图的哪一层、路径多深,最终都会使用该版本。这也是 3.3 中依赖收敛方案的基础。
2.3.4 依赖范围对传递的影响
上游(直接依赖)的 scope 与传递依赖自身的 scope 共同决定传递结果,对照表如下。
| 传递依赖自身 scope \ 上游 scope | compile | runtime | provided | test |
|---|---|---|---|---|
compile | compile | runtime | 不传递 | 不传递 |
runtime | runtime | runtime | 不传递 | 不传递 |
provided | 不传递 | 不传递 | 不传递 | 不传递 |
test | 不传递 | 不传递 | 不传递 | 不传递 |
由表可得三点结论:
provided与test作为上游 scope 时,其所有传递依赖都不进入下游依赖图,下游需要时须自行声明。runtime上游会让其compile传递依赖在下游降级为runtime,即对下游编译期不可见。- 下游项目若在自身
dependencyManagement中声明了相关构件,可以对传递进来的版本再做覆盖,作用与 2.3.3 顺序 2 一致。
2.4 optional 与 exclusions
2.4.1 optional 的语义
optional 解决的是"库自身的一个可选功能依赖"。声明为 optional 的依赖对当前项目完全生效(参与编译、测试、运行),但不向下传递:依赖当前项目的下游项目不会通过该路径获得该构件。
<dependency>
<groupId>com.example</groupId>
<artifactId>pdf-export</artifactId>
<version>2.0.0</version>
<optional>true</optional>
</dependency>
适用判断:
- 该功能是"可选"的,用户不使用该功能时不需要该构件 → 用
optional。 - 该构件是库正常工作的必需依赖,但下游应该使用另一个版本或另一个实现 → 用
exclusions加上文档说明,或由下游自行覆盖版本。
2.4.2 exclusions 的写法与生效范围
exclusions 写在某一条依赖声明内部,用于把该依赖的特定传递依赖从依赖图中剔除。
<dependency>
<groupId>com.example</groupId>
<artifactId>some-starter</artifactId>
<version>1.0.0</version>
<exclusions>
<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
要点:
- 排除条目只需要
groupId与artifactId,写version没有匹配作用,且会在版本变化后误导维护者。 - 生效范围仅为该条依赖的这条路径。若同一构件还通过其他路径进入依赖图,仍会存在,需要通过依赖树全量核对。
- 支持通配:
<groupId>*</groupId>可以排除该依赖的全部传递依赖,代价是失去对该依赖所需运行库的保障,属于需要谨慎使用的写法。
2.4.3 排除的副作用与排查方式
排除属于删除依赖图节点,副作用是运行期或编译期缺少类,表现为 NoClassDefFoundError、ClassNotFoundException、NoSuchMethodError。
排查路径:
# 确认某构件是否仍在依赖树中,以及保留的版本
mvn dependency:tree -Dincludes=commons-logging:commons-logging
# 显示被省略的节点,观察排除/调解前后的差异
mvn dependency:tree -Dverbose
判定原则:先确认该构件是否被代码或框架实际加载(异常栈中的类名与应用日志),再确认排除是否必要;若确需替换实现,应在排除后显式引入替代构件并固定版本。
高危 排除传递依赖会改变运行时 classpath 组成。兜底方式:改动前用 mvn dependency:tree -DoutputFile=target/tree-before.txt 留存依赖树,改动后对比并执行完整测试;异常无法定位时,直接移除对应 <exclusion> 并重新构建即可回滚。
2.5 dependencyManagement 与 dependencies 的分工
两个元素名字接近,职责完全不同。
| 对比项 | dependencyManagement | dependencies |
|---|---|---|
| 作用 | 为依赖声明提供版本、scope、exclusions 等默认配置 | 真正把依赖引入 classpath |
| 是否引入依赖 | 不引入,不出现在任何 classpath | 引入 |
| 生效条件 | 仅当 <dependencies> 中声明了同一构件且未写 version 时提供版本 | 声明即生效 |
| 继承行为 | 子模块继承该列表 | 父 POM 中的 dependencies 会被所有子模块无条件继承 |
| 覆盖方式 | 子模块在自己的 dependencyManagement 中重新声明同一坐标即可覆盖 | 子模块直接在 dependencies 中写 version(优先级更高) |
| 典型位置 | 父 POM、独立 BOM 构件 | 各业务模块 |
三条规则有利于理解实际效果:
- 只写在
dependencyManagement中的条目不会产生任何依赖,必须同时在某个模块的dependencies中引用才会进入 classpath。 - 子模块引用依赖时不写
version,版本沿继承链取最近一次dependencyManagement声明。 - 若某个模块在
dependencies中显式写了version,该版本优先,父 POM 的集中管理在此处被绕过。
版本应当集中在父 POM 或 BOM 的原因:
- 同一构件在多个模块间出现版本漂移时,依赖树差异会导致运行行为差异,集中声明将这类差异收敛到一处。
- 升级动作从"逐模块修改"变为"改一处或换一个 BOM 版本",便于回归。
dependencyManagement中的版本对传递依赖同样生效,是抑制冲突的首选手段(见 3.4)。
2.6 BOM 与 import scope
2.6.1 BOM 的结构与作用
BOM(Bill of Materials)是一个 packaging 为 pom 的构件,内容只有依赖管理段,不含代码,作用是把一组经过兼容性验证的版本固定下来供其他项目引用。
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>example-bom</artifactId>
<version>1.0.0</version>
<packaging>pom</packaging>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>example-common</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</dependencyManagement>
</project>
2.6.2 import scope 的写法
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
语法约束:
<type>pom</type>与<scope>import</scope>必须同时出现。- 只能位于
<dependencyManagement>内;写在<dependencies>中不会导入任何内容,也不会生效。
2.6.3 版本优先级
导入的 BOM 与被导入方的声明合并时,按以下优先级决定同一构件的版本:
- 当前 POM 的
dependencyManagement中直接声明的条目优先于任何 import 进来的条目。 - 存在多个 import 时,按声明顺序,先声明的 BOM 优先。
- 上层父 POM 的
dependencyManagement与子模块自身声明之间,按继承链就近原则,子模块声明优先。
因此"先 import 官方 BOM,再在本 POM 中显式声明个别构件版本"是常见且可控的覆盖写法。
2.6.4 Spring Boot 的 BOM 与 starter 的关系
| 角色 | 构件 | 内容 |
|---|---|---|
| BOM | spring-boot-dependencies | packaging=pom,只含 dependencyManagement,管理 Spring 生态及常用第三方库的版本 |
| Parent | spring-boot-starter-parent | 以父 POM 形式提供 BOM 能力,并附带插件版本、资源过滤、属性等约定 |
| Starter | spring-boot-starter-* | 实际的依赖集合,引入即可获得功能所需的一组依赖,版本由 BOM 提供,声明时无需写 version |
两种使用方式:继承 spring-boot-starter-parent 会同时获得 BOM 与父 POM 中的插件配置等约定;在已有父 POM 的项目中,无法再继承第二个父 POM,此时改为 import spring-boot-dependencies,只取版本管理能力。Starter 的清单与适用场景见 Spring Boot Starter 汇总,多模块组织方式见 企业级项目实践指导手册。
2.6.5 自制公司 BOM
做法:单独建一个 packaging=pom 的仓库或模块,dependencyManagement 中声明公司内部组件版本,并可 import 上游开源 BOM,然后 mvn deploy 到私服(发布配置见 Maven-repositories 与 distributionManagement),业务项目 import 该 BOM。
收益与约束:
- 公司内部组件版本统一,业务项目声明内部组件时不再写
version。 - BOM 版本号即"技术栈版本",升级动作收敛为改一个版本号。
- BOM 需要单独维护与发布流程,变更必须配套兼容性验证;内部组件发版后需同步更新 BOM 版本。
2.6.6 import 与直接继承的取舍
| 对比项 | import BOM | 继承父 POM |
|---|---|---|
| 数量限制 | 可导入多个 | 只能有一个父 POM |
| 影响范围 | 仅依赖管理段 | 依赖管理、properties、插件配置、repositories 等一并继承 |
| 组合能力 | 可组合多个技术栈的 BOM | 需要靠多层父 POM 链,调整成本高 |
| 适用场景 | 多技术栈项目、跨项目统一版本 | 单一项目内多模块共享构建约定 |
判断标准:需要共享的是"版本"时用 import;需要共享的是"构建约定"(插件配置、属性、资源处理)时用继承。二者可以同时使用:继承公司父 POM 以获得构建约定,再 import 各技术栈 BOM 获得版本管理。
2.7 依赖解析顺序
坐标到文件的解析按下述顺序进行,任一步成功即停止。
本地仓库(默认 ${settings.localRepository},通常为 ~/.m2/repository)
│ 未命中
▼
按 POM 中 <repositories> 声明顺序依次请求远程仓库(settings.xml 中激活 profile 的仓库同样参与)
│ 均未命中
▼
解析失败,记录失败信息并在更新周期内不再重试
镜像(<mirrors>)不在上述顺序的末尾,而是请求发出前的重定向:mirrorOf 匹配到的仓库请求会被改发到镜像地址,被镜像的原始仓库不再被访问。
关键结论:
- 一旦某个仓库成功提供构件,后续仓库不再尝试,因此"多个仓库存在同一坐标的不同内容"时,声明顺序靠前的仓库生效。
mirrorOf=*会把包括中央仓库与私服在内的全部请求指向同一地址,该地址若缺少内部构件,解析会直接失败且不会回落到原始仓库。仓库与镜像配置细节见 Maven-repositories 与 distributionManagement。
SNAPSHOT 与 release 的差别:
| 对比项 | release 版本 | SNAPSHOT 版本 |
|---|---|---|
| 版本可复用性 | 同一坐标内容不变,本地仓库命中即视为最终版本 | 同一坐标内容可变,需通过元数据解析具体时间戳版本 |
| 更新检查 | 不检查更新,除非使用 -U | 按仓库的 updatePolicy(always、daily、interval:X、never)检查 |
| 依赖元数据 | 不需要 maven-metadata.xml | 依赖 maven-metadata.xml 解析最新快照 |
| 使用限制 | 可用于发布物 | 不应出现在发布物中(见 3.5) |
解析失败的判定边界:
- 仓库返回 404 时,Maven 在本地仓库写入
.lastUpdated记录,并在updatePolicy周期内不再对该仓库重试。 - 网络不可达、认证失败、超时等非 404 情况同样可能导致写入
.lastUpdated。 - 校验和(
.sha1、.md5)不匹配时,按checksumPolicy判定为失败或仅告警;失败时同样留下失败记录。 - 判定"是仓库问题还是本地问题"的方法:用
mvn dependency:get强制获取单个坐标,或直接在浏览器中请求仓库 URL 对应路径。
高危 -U 强制更新(mvn -U clean package)会绕过 updatePolicy 对所有 SNAPSHOT 与失败记录重新发起请求。在依赖规模较大或私服受限时可能产生大量请求并拖慢构建;且若私服本身尚未发布新快照,强制更新无法解决问题。兜底方式:该参数不修改任何持久化内容,去掉 -U 即恢复原行为;如需精细控制,只对目标坐标执行 mvn dependency:get -U -Dartifact=groupId:artifactId:version。
2.8 本地仓库与解析痕迹
2.8.1 坐标到目录结构的映射
映射规则:groupId 中的 . 替换为路径分隔符,其余要素逐层作为目录名,文件名为 artifactId-version[-classifier].type。
${localRepository}/${groupId 以 / 分隔}/${artifactId}/${version}/${artifactId}-${version}[-${classifier}].${type}
示例:
~/.m2/repository/org/springframework/boot/spring-boot-starter-web/3.2.0/
├── spring-boot-starter-web-3.2.0.pom
├── spring-boot-starter-web-3.2.0.pom.sha1
├── _remote.repositories
该规则使得"某个依赖是否已下载""下载到的是哪个版本"可以直接通过文件系统确认,无需读取 POM。
2.8.2 解析痕迹文件的作用
| 文件 | 位置 | 作用 |
|---|---|---|
_remote.repositories | 与构件文件同目录 | 记录构件各文件来自哪个仓库 id;解析时用于判断本地缓存是否可满足当前解析上下文 |
*.lastUpdated | 与构件文件同目录 | 记录某次下载失败(含仓库 id 与时间戳);存在时在该仓库的 updatePolicy 周期内不再重试 |
*.sha1、*.md5 | 与构件文件同目录 | 校验和,用于判断构件是否完整 |
常见现象与原因:
- 更换镜像或调整仓库配置后报"构件找不到",但文件明明存在:
_remote.repositories中记录的来源仓库已不在当前解析上下文,Maven 认为该缓存不可复用。删除该文件或整个坐标目录可消除。 - 报错信息中带
was cached in the local repository或resolution will not be reattempted:*.lastUpdated生效,位于更新周期内。 - 构件文件存在但大小为 0 或缺失
.jar:下载中断导致的残缺缓存。
2.8.3 清理与重解析的边界
推荐做法:只删除目标坐标的 version 目录(例如 ~/.m2/repository/com/example/broken-lib/1.0.0/),再重新构建,范围可控且不影响其他依赖。
高危 强制清理本地仓库(删除整个 ~/.m2/repository)会使所有依赖重新下载,在中央仓库访问受限或私服限流的环境下可能导致构建长时间阻塞甚至无法完成。兜底方式:清理前确认镜像与私服可达,或先备份该目录;仅在确认本地仓库大面积损坏时才整体清理。
三、实现
3.1 版本集中管理
3.1.1 父 POM 集中声明
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>example-parent</artifactId>
<version>1.0.0</version>
<packaging>pom</packaging>
<properties>
<spring.boot.version>3.2.0</spring.boot.version>
<jackson.version>2.15.3</jackson.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>example-common</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>${jackson.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
</project>
子模块引用时不写版本:
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>example-common</artifactId>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
</dependencies>
3.1.2 import BOM
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.example</groupId>
<artifactId>example-bom</artifactId>
<version>2.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
3.1.3 两种做法对比
| 维度 | 父 POM 集中声明 | import BOM |
|---|---|---|
| 载体 | 项目自身的父 POM | 独立的 packaging=pom 构件 |
| 复用范围 | 仅本项目模块 | 任意项目,可跨团队 |
| 附带影响 | 同时继承 properties、插件配置等 | 仅继承依赖管理段 |
| 组合能力 | 受单继承限制 | 可同时导入多个 BOM |
| 变更成本 | 改父 POM,需重新发布父 POM 版本 | 改 BOM 版本号,业务项目按需升级 |
| 适用场景 | 单一项目多模块 | 多项目、多技术栈统一版本 |
3.2 依赖树与冲突排查
3.2.1 常用参数与过滤
# 打印依赖树
mvn dependency:tree
# 只显示指定构件的分支(支持 * 通配,格式 groupId:artifactId:type:version,后段可省略)
mvn dependency:tree -Dincludes=org.slf4j:slf4j-api
# 排除指定构件后的依赖树
mvn dependency:tree -Dexcludes=commons-logging:commons-logging
# 显示被省略的节点(定位冲突的关键)
mvn dependency:tree -Dverbose
# 输出到文件,便于与改动前对比
mvn dependency:tree -DoutputFile=target/tree-after.txt
# 指定单模块与依赖它的模块
mvn -pl example-web -am dependency:tree
-Dverbose 与默认输出的差别:默认输出只保留调解后的最终版本,被舍弃的节点不显示;-Dverbose 会打印这些节点及其状态,是判断"为什么是这个版本"的必要手段。
3.2.2 omitted for conflict 的判读
-Dverbose 输出中的状态含义:
| 状态文本 | 含义 |
|---|---|
omitted for conflict with x.y.z | 该节点版本在依赖调解中落败,最终使用 x.y.z |
omitted for duplicate | 同一构件在该路径上已出现过,属于重复声明 |
omitted for conflict with a banned dependency | 该版本被 dependencyManagement 或 bannedDependencies 规则排除 |
| 无状态标记 | 该节点即最终生效版本 |
omitted for conflict 本身不等于缺陷:只有当落败版本提供的 API 被代码或其他库实际调用时,才会以 NoSuchMethodError、AbstractMethodError、NoClassDefFoundError 的形式暴露。因此判读思路是"从异常类反向定位构件,再看该构件是否存在被舍弃的版本"。
3.2.3 dependency:analyze 与 analyze-only
| 目标 | 行为 | 输出含义 |
|---|---|---|
dependency:analyze | 分析依赖并会编译项目 | Used undeclared dependencies:代码用到但未直接声明,靠传递依赖侥幸存在;Unused declared dependencies:声明了但代码未直接使用 |
dependency:analyze-only | 与 analyze 相同,但不编译项目 | 同上,适合在已编译产物上快速执行 |
mvn dependency:analyze
mvn dependency:analyze-only
判读注意:Unused declared dependencies 未必可以直接删除——反射加载、SPI 实现、注解处理器、运行期必需但编译期无引用的依赖都会落入该类别。删除前需确认其在运行期是否被使用。
3.2.4 从一个报错到具体路径的完整步骤
- 从异常信息取出全限定类名,判断其所属构件(
NoSuchMethodError、AbstractMethodError的消息中通常包含类名与方法签名;NoClassDefFoundError包含类名)。 - 在依赖树中按构件过滤,确认该构件是否存在多个版本:
mvn dependency:tree -Dverbose -Dincludes=com.example:target-lib
- 观察各节点的状态行,记录落败版本及其完整路径,确认落败版本是被哪条路径引入的。
- 选择修复手段(优先级见 3.4):在
dependencyManagement中固定版本;或调整声明顺序使正确路径胜出;或在错误路径上使用exclusion后显式引入。 - 验证:
mvn dependency:tree -Dverbose -Dincludes=...确认最终版本,mvn clean verify确认测试通过,并在运行环境复现原报错路径。
3.3 依赖收敛与约束
3.3.1 maven-enforcer-plugin 配置示例
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.4.1</version>
<dependencies>
<!-- requireUpperBoundDeps 由 extra-enforcer-rules 提供 -->
<dependency>
<groupId>org.codehaus.mojo</groupId>
<artifactId>extra-enforcer-rules</artifactId>
<version>1.7.0</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>enforce-dependency-rules</id>
<!-- 绑定到最早的阶段,使违规尽早暴露 -->
<phase>validate</phase>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<!-- 同一构件的所有路径必须收敛到同一版本 -->
<dependencyConvergence/>
<!-- 最终版本不得低于路径中出现过的最高版本 -->
<requireUpperBoundDeps/>
<!-- 禁止指定坐标,searchTransitive 控制是否检查传递依赖 -->
<bannedDependencies>
<searchTransitive>true</searchTransitive>
<excludes>
<exclude>commons-logging:commons-logging</exclude>
<exclude>log4j:log4j</exclude>
<exclude>org.example.internal:*</exclude>
</excludes>
</bannedDependencies>
</rules>
<fail>true</fail>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
3.3.2 三条规则的作用与差异
| 规则 | 检查内容 | 失败示例 |
|---|---|---|
dependencyConvergence | 同一构件在依赖图中是否只存在一个版本 | common:1.0 与 common:2.0 同时出现在不同路径,即使调解后只用一个版本,也视为不收敛并失败 |
bannedDependencies | 是否引入了禁止的坐标,支持通配与 searchTransitive | 项目引入了 commons-logging,违反统一日志门面的约定 |
requireUpperBoundDeps | 最终生效版本是否低于路径中出现过的最高版本 | 调解取 common:1.0,而图中存在 common:2.0,说明发生了降级,规则失败 |
dependencyConvergence 与 requireUpperBoundDeps 的区别:前者要求所有路径版本完全相同,是更强的约束;后者只禁止"取到更低版本",允许路径上出现更高版本。
3.3.3 启用位置
- 在父 POM 的
build/plugins中启用,使规则覆盖所有模块;子模块如需单独调整,可在自身build/plugins中覆盖配置。父 POM 统一管理插件版本与配置的几种模式见 Maven-build 配置实践。 - 绑定到
validate阶段,使违规在构建最开始就暴露,避免浪费后续阶段的时间。 - 插件版本集中管理的方式与
pluginManagement的关系见 Maven 常用插件。
3.3.4 失败时的处理策略
| 失败规则 | 处理方式 |
|---|---|
dependencyConvergence | 在 dependencyManagement 中固定该构件版本,使所有路径收敛到同一版本 |
requireUpperBoundDeps | 提升到路径中的最高版本;若最高版本不可用(缺失或 API 不兼容),用 exclusion 隔离引入旧版本的路径 |
bannedDependencies | 移除对应依赖,或对传递引入的依赖做排除并替换为允许的构件 |
可先以 <fail>false</fail> 运行,把违规当作告警观察一段时间,确认违规清单后再改为 true 作为构建门禁。
3.4 指定版本的手段与取舍
| 手段 | 作用范围 | 侵入性 | 维护成本 | 适用场景 |
|---|---|---|---|---|
在依赖上直接写 version | 单个模块的单个依赖 | 低,但版本分散 | 高(多处重复) | 单体项目、临时验证 |
在 dependencyManagement 中覆盖 | 继承该 POM 的所有模块,且对传递依赖生效 | 中,集中一处 | 低 | 默认手段 |
| 排除后引入替代版本 | 单条路径 | 高 | 高 | 仅当无法用依赖管理收敛时 |
最小干预原则:优先使用 dependencyManagement 固定版本;只有在需要改变依赖图结构(剔除某条路径)时才使用 exclusion;直接在依赖上写版本仅用于过渡或局部验证。
避免到处写 exclusion 的原因:
exclusion描述的是"路径"而不是"意图"。上游构件升级后依赖结构变化,原有的exclusion可能失效,同时留下不再需要的条目。- 排除只作用于被声明的那条路径,新引入的依赖仍可能带进被排除的旧版本,形成"排了但仍然存在"的情况。
- 排除了旧版本却没有引入替代版本时,运行期缺少类的风险直接由构建产物承担。
- 当项目中出现大量
exclusion时,依赖图的可读性下降,问题根因难以定位,此时应当通过 BOM 或父 POM 统一治理。
高危 在 dependencyManagement 中覆盖传递依赖版本,或在依赖上排除传递依赖,会改变运行期 classpath 的实际组成,可能引入不兼容的 API 或缺少类。兜底方式:改动前留存依赖树(-DoutputFile)与当前生效版本清单,改动后执行完整测试与关键路径验证;出现异常时恢复原声明并重新构建即可回滚。
3.5 多模块下的依赖管理
3.5.1 模块间依赖与 reactor 顺序
- Maven 依据模块之间的依赖关系确定构建顺序(reactor 顺序),而不是依据
<modules>中的书写顺序;无依赖关系的模块之间按声明顺序构建。 - 模块间依赖同样以坐标声明,版本通常由父 POM 的
dependencyManagement统一为${project.version},避免每个子模块重复写当前项目版本。 - 只构建部分模块时使用
-pl(指定模块)与-am(同时构建其依赖模块):
mvn -pl example-web -am clean install
3.5.2 SNAPSHOT 的使用与限制
| 使用方式 | 说明 |
|---|---|
| 模块间联调 | 开发阶段子模块引用 -SNAPSHOT 版本,配合 mvn install 或 reactor 内解析使用 |
| 发布限制 | 发布物不允许引用 -SNAPSHOT;正式版本引用快照会导致其他环境构建结果不可复现,且多数私服会拒绝向 release 仓库部署含快照依赖的构件 |
| 更新行为 | 快照解析受 updatePolicy 控制,同一台机器可能持有旧快照;跨机器构建需确认快照已重新部署 |
| 版本管理 | 发布前应统一将 -SNAPSHOT 改为正式版本号(可用 mvn versions:set),并确认依赖树中不存在快照坐标 |
3.5.3 install 与依赖解析的关系
mvn install会把构件安装到本地仓库,之后其他项目、IDE 的独立构建才能按坐标解析到该构件(install与deploy所绑定的生命周期阶段见 Maven 生命周期与插件绑定)。- 只执行
mvn package时,构件不进入本地仓库;同一次 reactor 构建内部的模块依赖由 reactor 直接解析,跨项目或单独打开某模块构建时会报找不到构件。 - 因此"某个内部模块改动后其他项目看不到变化",通常是因为未执行
install,或本地仓库中仍是旧版本。
3.5.4 父 POM 中的依赖继承策略
| 策略 | 行为 | 适用性 |
|---|---|---|
父 POM 写 <dependencies> | 所有子模块无条件继承并引入这些依赖 | 仅用于全项目确实都需要的依赖(如统一的日志门面、测试框架) |
父 POM 只写 <dependencyManagement> | 只提供版本,不引入依赖,子模块按需声明 | 推荐做法,避免把无关依赖强加给所有模块 |
父 POM 中大量写 <dependencies> 会带来两个问题:无关模块被迫引入不需要的构件,扩大依赖图与冲突面;以及该依赖一旦需要调整,影响范围覆盖全部模块。
3.6 依赖升级与安全
3.6.1 versions 插件
# 列出可用的依赖新版本
mvn versions:display-dependency-updates
# 列出插件的新版本
mvn versions:display-plugin-updates
# 修改当前项目版本号(可用于发布前去掉 SNAPSHOT)
mvn versions:set -DnewVersion=1.0.0
3.6.2 升级的验证要点
- 依赖结构:升级前后各执行一次
mvn dependency:tree -DoutputFile=...,对比新增与消失的节点,确认没有引入新的多版本共存。 - 收敛约束:执行带 enforcer 规则的构建,确认
dependencyConvergence、requireUpperBoundDeps、bannedDependencies均通过。 - 编译与测试:完整执行
mvn clean verify,关注编译告警中的弃用 API 提示。 - 运行时验证:启动应用并覆盖关键路径,重点关注序列化、数据库访问、日志与 HTTP 客户端相关行为。
- 回滚准备:升级以单独提交的形式进行,出现问题时直接回退版本声明。
3.6.3 漏洞扫描与私服治理的衔接
- 漏洞扫描的数据来源是依赖清单:扫描工具读取
dependency:tree的结果或构建产物的依赖列表,与漏洞库比对,因此 3.1 中的版本集中管理同时也是扫描结果可治理的前提。 - 私服在下载阶段拦截禁用版本与未审批构件,与构建阶段的扫描形成两道闸门:前者阻止引入,后者发现已引入。
- 仓库地址、
releases/snapshots开关与认证的配置方式见 Maven-repositories 与 distributionManagement。
3.6.4 许可合规检查
- 许可风险主要来自传递依赖:直接依赖的许可证通常经过确认,间接引入的构件可能采用传染性许可或商用限制。
- 检查方式:使用
license-maven-plugin汇总依赖的许可证清单,生成第三方许可报告,随发布物归档。 - 处理原则:维护禁止使用的许可清单,命中时替换构件、申请例外,或在分发方式上做隔离。
- 检查频率:新增依赖时检查一次,发布前复核一次,避免存量依赖长期未审视。发布前的产物要求见 Maven 版本管理与发布流程。
3.7 常见故障与排查路径
| 现象 | 常见原因 | 定位手段 |
|---|---|---|
无法解析依赖,提示 Could not resolve dependencies / Could not find artifact | 坐标错误、目标仓库没有该构件、网络或认证问题 | mvn -X dependency:tree 查看请求了哪些仓库;mvn dependency:get -Dartifact=g:a:v 单独验证 |
| 坐标拼写错误 | groupId 或 artifactId 写错、版本号不存在 | 对照本地仓库或私服的目录结构确认实际坐标;mvn dependency:tree -Dincludes=... 确认是否解析到预期构件 |
| 私服缺件 | 该构件未同步到私服;仓库的 releases 或 snapshots 被置为 false;部署到了另一个仓库 | 直接请求仓库 URL 对应路径确认文件是否存在;检查 <repositories> 中的 enabled 配置 |
| 镜像与代理配置问题 | mirrorOf 把请求重定向到不含该构件的镜像;settings.xml 中的代理不可用 | mvn help:effective-settings 查看生效配置;临时移除镜像验证是否为镜像导致 |
本地仓库损坏、*.lastUpdated 残留 | 下载中断、校验和失败、更换仓库或镜像 | 删除该坐标的版本目录(含 *.lastUpdated、_remote.repositories)后重新构建;错误信息中出现 was cached in the local repository 即为该情况 |
运行期 NoClassDefFoundError / ClassNotFoundException 与 scope 有关 | 依赖被声明为 provided 或 test,或被打包插件过滤,运行环境中不存在该构件 | mvn dependency:tree 确认该构件与 scope;mvn dependency:copy-dependencies -DincludeScope=runtime 查看实际进入运行期的构件 |
运行期 NoSuchMethodError / AbstractMethodError / NoClassDefFoundError 与版本冲突有关 | 运行时加载的是调解落败版本;同一库的两个大版本同时存在 | mvn dependency:tree -Dverbose -Dincludes=g:a 查看各版本与路径;结合异常中的类名与方法签名定位构件 |
| 快照未更新 | updatePolicy 未到期;私服未部署新快照;本地为旧缓存 | mvn -U clean package(见 2.7 的高危说明);确认私服上快照的时间戳版本 |
| 依赖下载长时间无响应 | 仓库不可达或代理配置异常 | mvn -o clean package 以离线模式验证本地是否完整;mvn -X 查看正在请求的地址 |
| 构建通过但打包产物在容器中启动失败 | 依赖被打入产物但运行环境缺少相应配置,或容器内 classpath 与本地不一致 | 检查打包产物中的依赖列表与 scope;确认容器使用的 JDK 与本地一致 |
3.8 依赖声明规范(可落地清单)
| 规范 | 具体做法 | 目的 |
|---|---|---|
| 版本只出现在一处 | 版本统一写在父 POM 的 dependencyManagement 或 import 的 BOM 中,子模块与业务模块声明依赖时不写 version | 消除版本漂移,升级只需改一处 |
| 按 scope 正确声明 | 编译期需要而运行环境提供的用 provided;仅测试使用的用 test;仅运行期需要的用 runtime | 保证打包产物与运行环境一致,减少冲突面 |
| 禁止发布物引用 SNAPSHOT | 发布前将版本改为正式版本,并确认依赖树中无 -SNAPSHOT 坐标 | 构建结果可复现,可通过私服发布策略校验 |
| 测试依赖限定 scope | JUnit、Mockito、断言库等一律声明为 test | 避免测试库进入主 classpath 并传递到下游 |
不使用 system scope | 本地 jar 先通过 install:install-file 进入本地仓库或私服,再以普通坐标声明 | 保证构建可移植、构件可校验 |
| 避免重复与无用依赖 | 同一构件不在同一 POM 中重复声明;定期执行 mvn dependency:analyze 检查 Unused declared dependencies 与 Used undeclared dependencies | 缩小依赖图,降低冲突概率 |
| 排除依赖时写明原因 | 每个 <exclusion> 旁用注释说明排除原因与替代方案 | 便于后续判断该条目是否仍然必要 |
| 版本收敛作为构建门禁 | 在父 POM 中启用 maven-enforcer-plugin 的 dependencyConvergence、requireUpperBoundDeps、bannedDependencies | 使版本冲突在构建阶段暴露,而不是在运行期暴露 |
| 依赖树定期留存 | 发布前保存 dependency:tree 输出,升级前后对比 | 便于回溯版本变化与定位回归 |
四、总结
- 依赖管理的本质是把依赖关系从文件摆放变为坐标声明:POM 描述需要什么,Maven 负责解析、下载与缓存,同一坐标在不同机器上得到同一构件。
- 坐标六要素中
type、classifier、scope有默认值,scope决定依赖参与哪些 classpath 以及是否传递,是打包产物与运行环境是否一致的直接原因。 - 传递依赖由 Maven 递归展开,冲突按"最短路径优先、同深度先声明优先"调解;这条规则会受 POM 中声明顺序影响,因此实际项目应以
dependencyManagement显式固定版本,而不依赖调解结果。 optional让依赖不向下传递,exclusions让指定路径的传递依赖不进入依赖图;前者表达"可选功能",后者表达"剔除某条路径",后者的副作用是运行期可能缺少类。dependencyManagement只声明版本不引入依赖,dependencies才真正引入;版本集中在父 POM 或 BOM 中,是控制版本漂移与简化升级的前提。- BOM 通过
<type>pom</type>与<scope>import</scope>导入,可组合多个技术栈且只影响依赖管理段;本 POM 直接声明的条目优先于导入条目。自制公司 BOM 把"技术栈版本"收敛为一个可管理的版本号。 - 解析顺序为本地仓库、按声明顺序的远程仓库,镜像在请求发出前重定向;SNAPSHOT 需按
updatePolicy检查更新,release 一旦缓存即视为最终版本。 - 本地仓库以
_remote.repositories记录来源、以*.lastUpdated记录下载失败;排查"文件存在却报找不到"与"不再重试"这两类现象时应先看这两个文件,清理时按坐标目录删除而非整体删除本地仓库。 - 依赖冲突排查依赖
dependency:tree -Dverbose:默认输出只保留调解后的版本,-Dverbose才显示被省略的节点与状态;omitted for conflict需要通过异常中的类名反向确认是否真正造成影响。 maven-enforcer-plugin把版本收敛从人工检查变为构建门禁;dependencyConvergence、requireUpperBoundDeps、bannedDependencies分别约束"版本一致""不发生降级""不引入禁用构件"。- 指定版本的手段按干预程度递增为:依赖管理覆盖、直接声明、排除后引入替代版本;
exclusion描述路径而非意图,应把它的使用范围控制到最小。 - 依赖声明规范的目标是让依赖图可解释:版本单一来源、scope 与用途匹配、不引用快照、不留无用依赖、约束进入构建门禁。