1 / 4概念
Toolchain: Build and Dependencies
判断一份构建是否可信,看的不是 pom.xml 有多整齐,而是能否指出某个类最终来自哪个坐标的哪个版本。Maven 用固定生命周期约束顺序,Gradle 用任务图换取自由;两者的核心工作相同:把声明解析成一条确定的 classpath。
1 概念
1.1 一句话定义
Maven 把构建写成一条固定的生命周期,每个阶段绑定若干插件 goal;Gradle 把它写成一张有向无环的任务图,用 dependsOn 连边。两者消费同一类输入,输出同一种东西:一条 classpath 与一份产物。
1.2 它解决什么问题
- 传递依赖:声明一个库会带进十几个坐标,版本需要收敛,冲突需要裁决。
- 顺序约束:编译、测试、打包、安装有先后,写错顺序就会得到过期产物。
- 多模块统一版本:父工程集中声明版本,子模块只写差异。
- 跨机器一致:wrapper 钉住构建工具,toolchain 钉住 JDK。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 测试框架、扩展模型与容器化依赖 | Testing |
可执行 jar、jlink、native image 与发布 | Packaging and Release |
类加载顺序与 ClassLoader 隔离 | Class Loading |
| 自动配置与 bean 生命周期 | Spring Boot |
| 流水线编排、缓存键与并行 | CI/CD |
| 私有仓库、制品代理与凭据 | Private Registry |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| lifecycle | Maven 固定的阶段序列 | 不是插件清单 |
| phase / goal | 阶段与绑定在阶段上的插件目标 | 不是同一抽象 |
| task | Gradle 的执行单元 | 与 goal 不能互换 |
dependencyManagement | 只声明版本,不引入依赖 | 不写版本也能编译 |
| BOM | 可导入的版本清单 | 靠 import scope 生效 |
| scope | 依赖进入哪条 classpath | 不是生命周期阶段 |
| wrapper / toolchain | 钉构建工具版本 / 钉 JDK | 两者管的不是一件事 |
| version catalog | Gradle 的集中版本文件 | 不是 BOM |
SNAPSHOT | 可变版本 | 同版本内容会漂移 |
| 冲突裁决 | Maven 取最近者,Gradle 取最高者 | 两个默认规则不同 |
2 机制
2.1 心智模型
Maven 的模型是一条直线:阶段有序,goal 挂在阶段上,执行到某阶段就把之前的阶段全部跑完。Gradle 的模型是一张图:配置阶段生成任务与边,执行阶段只跑被请求任务的闭包。直线可预测,图可复用。
2.2 机制拆解
- 默认绑定:
jar打包下,process-resources绑resources:resources,compile绑compiler:compile,test绑surefire:test,package绑jar:jar。 - 继承与导入:子 POM 继承父 POM 的依赖、插件与
properties;type为pom、scope为import的依赖在解析前展开,其dependencyManagement并入当前工程。 - scope 语义:scope 决定依赖进入哪条 classpath,以及是否被打进产物;
provided与test都不进入最终 jar。 - Gradle 三阶段:初始化阶段由
settings.gradle.kts决定参与构建的工程,配置阶段注册任务并连边,执行阶段按拓扑序运行。 - 两类缓存:配置缓存序列化配置阶段的结果,构建缓存按输入哈希取回任务输出;脚本读取时钟或主机名会让前者失效,输入声明不全会让后者出错。
- 解析裁决:Maven 取深度最小的版本,同深度取先声明者;Gradle 默认取最高版本,可用
resolutionStrategy改写。
2.3 完整枚举
Maven 默认生命周期共二十三个阶段,下表给出全部阶段与 jar 打包下的默认绑定:
| 阶段 | 默认绑定 | 作用 |
|---|---|---|
validate | — | 校验工程结构与配置 |
initialize | — | 初始化构建状态 |
generate-sources | — | 生成主源码 |
process-sources | — | 处理主源码 |
generate-resources | — | 生成资源 |
process-resources | resources:resources | 复制并过滤资源 |
compile | compiler:compile | 编译主源码 |
process-classes | — | 编译后处理字节码 |
generate-test-sources | — | 生成测试源码 |
process-test-sources | — | 处理测试源码 |
generate-test-resources | — | 生成测试资源 |
process-test-resources | resources:testResources | 复制测试资源 |
test-compile | compiler:testCompile | 编译测试源码 |
process-test-classes | — | 测试字节码后处理 |
test | surefire:test | 运行单元测试 |
prepare-package | — | 打包前处理 |
package | jar:jar | 生成 jar |
pre-integration-test | — | 集成测试前准备 |
integration-test | — | 运行集成测试,failsafe 声明后生效 |
post-integration-test | — | 集成测试后清理 |
verify | — | 校验产物,failsafe 在此核对结果 |
install | install:install | 安装到本地仓库 |
deploy | deploy:deploy | 发布到远程仓库 |
六个 scope 的可见范围与产物归属:
| scope | 编译 | 测试 | 运行 | 进入产物 | 典型用途 |
|---|---|---|---|---|---|
compile | 是 | 是 | 是 | 是 | 普通库 |
provided | 是 | 是 | 否 | 否 | 容器提供的 API |
runtime | 否 | 是 | 是 | 是 | JDBC 驱动、日志实现 |
test | 否 | 是 | 否 | 否 | 测试框架与断言库 |
system | 是 | 是 | 否 | 否 | 显式路径,缺乏可移植性 |
import | — | — | — | — | 只在 dependencyManagement 导入 BOM |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 冷构建 | 十秒到数分钟 | 由模块数、注解处理器与测试数决定 |
| 增量构建 | 数百毫秒到数秒 | 命中构建缓存时可更低 |
| 依赖树深度 | 三到六层 | 越深越容易触发版本冲突 |
| 本地仓库体积 | 数百 MB 到数 GB | 多版本共存是常态 |
3 实践
3.1 最小示例
父 POM 导入 BOM,子模块只写坐标;版本由 BOM 供给,scope 决定进入哪条 classpath。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.3.5</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
追踪 ./mvnw verify:解析先展开 dependencyManagement 里的 BOM,jackson-databind 由此拿到版本;postgresql 因 runtime 不进入编译 classpath。执行从 validate 走到 verify,package 写出 jar,verify 是最后一个没有副作用的阶段。若另一条路径带进更旧的 jackson-databind,深度更大的那条失效,因为 Maven 取最近者。
Gradle 用 platform() 导入同一份 BOM,作用域改由 configuration 名表达:
dependencies {
implementation(platform("org.springframework.boot:spring-boot-dependencies:3.3.5"))
implementation("com.fasterxml.jackson.core:jackson-databind")
runtimeOnly("org.postgresql:postgresql")
}
3.2 常用操作与参数
| 操作 | 命令 | 说明 |
|---|---|---|
| 打印依赖树 | ./mvnw dependency:tree | 定位哪条路径带进了该版本 |
| 只看某个坐标 | ./mvnw dependency:tree -Dincludes=com.fasterxml.jackson.core | 缩小到一条路径 |
| 打印有效 POM | ./mvnw help:effective-pom | 看清继承与 BOM 合并后的最终取值 |
| Gradle 依赖列表 | ./gradlew dependencies --configuration runtimeClasspath | 按 configuration 查看解析结果 |
| 解释冲突来源 | ./gradlew dependencyInsight --dependency jackson-databind | 说明为什么选中该版本 |
| 固定产物时间 | -Dproject.build.outputTimestamp=2026-01-01T00:00:00Z | 让 jar 内时间可复现 |
3.3 标准流程
- 提交 wrapper,用 toolchain 指定 JDK,并把编码固定为
UTF-8。 - 版本只在一处声明:父 POM 的
dependencyManagement或libs.versions.toml。 - 依赖按 scope 或 configuration 归位,运行期才需要的库不要写进编译路径。
- 主干禁止动态版本与
SNAPSHOT,它们只允许出现在开发分支。 - 固定插件版本与
outputTimestamp,在 CI 跑verify,发布单独一步执行deploy。
3.4 与相邻技术的组合
- Spring Boot:版本由
spring-boot-dependencies统一供给,打包插件接在package之后。 - CI/CD:缓存本地仓库与 Gradle 缓存,缓存键带上
pom.xml与版本目录的哈希。 - Private Registry:解析与发布走同一个 registry,凭据放
settings.xml或环境变量。 - Code Quality:Checkstyle 与 SpotBugs 绑到
verify,让告警成为构建结果的一部分。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 定制程度 | 只用标准阶段 / 需要条件化任务 | 定制越多,Gradle 的收益越大 |
| 模块规模 | 单模块 / 几十个模块 | 多模块更依赖增量与统一版本 |
| 版本落点 | 父 POM / 版本目录 | 决定一处声明的具体写法 |
| 团队经验 | 只熟 Maven / 只熟 Gradle / 都熟 | 决定学习与维护成本 |
| 反馈预算 | 分钟级可接受 / 要求秒级 | 决定是否投入构建缓存 |
| 复现要求 | 内部试用 / 对外交付 | 决定约束的严格程度 |
3.6 决策规则
- 服务端标准工程、团队以 Maven 为主时,用 Maven 加 BOM,维护面最小。
- 需要条件化任务、跨语言编排或 Kotlin DSL 时,选 Gradle。
- 冲突优先用 BOM 或
constraints收敛,exclude只用于修不掉的错误传递。 - 新增依赖前先看一次依赖树,确认它不会替换已有版本。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| Maven | 阶段写死,行为可预测 | 插入自定义步骤要写插件 | 多人协作的标准服务 |
| Gradle | 缓存与增量能力强,脚本可编程 | 配置与调试门槛更高 | 构建逻辑不标准的工程 |
| Bazel | 跨语言、远程缓存、结果可复现 | 迁移与学习曲线都陡 | 已有平台支持的大型 monorepo |
3.8 何时不该用
- 单个类的示例程序,
javac加java已经够用。 - 团队没有 Gradle 经验、构建逻辑又简单时,不要为速度引入新工具。
- 只为跑一个测试时,用 IDE 或
--tests,不必全量构建。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
运行期 NoSuchMethodError | 编译期按新版签名调用,运行期却加载到旧版 | 用依赖树定位路径,靠 BOM、constraints 或 exclude 对齐 |
运行期 ClassNotFoundException | 依赖被标成 provided 或 test,运行时不提供 | 修正 scope,补齐声明 |
| 测试一个都没执行 | 命名不符合 *Test,或跳过参数被打开 | 按约定命名,检查跳过开关 |
| 本地通过、CI 失败 | CI 的 JDK 与构建工具版本和本地不同 | wrapper 加 toolchain,CI 固定镜像 |
| 同一 commit 的 jar 校验和不同 | 时间戳、条目顺序、解析到不同版本 | 锁定 outputTimestamp,去掉动态版本 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
使用 LATEST、RELEASE 或范围版本 | 每次解析结果都可能变 | 固定版本,定期升级 |
生产依赖 SNAPSHOT | 同版本内容漂移,回滚失去基线 | 发布正式版 |
用 exclude 解决所有冲突 | 隐式丢功能,故障推迟到运行期 | 先用约束收敛版本 |
CI 用 install 代替 verify | 污染本地仓库,掩盖绑定问题 | verify 加独立发布步骤 |
4.3 可观测信号
依赖树、有效 POM、构建扫描报告、构建缓存命中率、配置缓存命中率、产物 SHA-256。排障顺序固定为:解析结果、生命周期绑定、环境差异。
4.4 安全 / 性能 / 一致性边界
- 供应链边界:依赖校验和、仓库签名与凭据都属于构建的一部分,缺任一项都无法证明产物来源。
- 复现边界:同一 commit、同一 wrapper、同一 JDK、同一时间戳,四个条件同时成立才可复现。
- 性能边界:增量与缓存只允许改变耗时,不允许改变语义;输入不全的缓存就是错误来源。
- 一致性边界:本地与 CI 的解析结果应一致,否则失败会被推迟到发布之后。