一个公司里十个 Java 项目，往往有六种 JDK、四种 Spring Boot、三种 Maven 插件版本。它在平时没有症状——直到某个 CVE 公布，你需要在一天内说清"哪些服务受影响、多久能全部升上去"。答案取决于一件平时没人管的事：版本基线。
1. 基线的四个维度
| 维度 | 基线内容 | 失控后的直接代价 |
|---|---|---|
| JDK 版本 | 主版本 + 发行版（Temurin/Zulu 等） | 字节码目标不一致、GC 参数分叉、容器镜像翻倍 |
| 框架版本 | Spring Boot / 核心中间件客户端 | CVE 响应无法批量、行为差异难复现 |
| 构建工具 | Maven/Gradle 版本、插件版本 | 同一份源码在不同机器产出不同包 |
| 依赖白名单 | 允许的库与版本区间 | 同类库并存（两个 JSON、两个日志门面） |
四者的优先级不同：JDK 与构建工具最该锁死（它们决定产物），框架版本可按"允许的区间"管理（业务需要弹性），依赖白名单则是最容易失控、也最容易被忽略的一项。
2. "每个项目自己定版本"为什么会失控
| 失控方式 | 机制 | 表现出来 |
|---|---|---|
| CVE 响应 | 版本分散，无法统一评估与批量升级 | 安全公告发布一周后仍在盘点是哪些服务 |
| 类冲突 | 不同版本的同名类被同时加载 | NoSuchMethodError、LinkageError 只在某些请求路径出现 |
| 培训与协作成本 | 每个人熟悉的是自己项目那套写法 | Code Review 变成风格争论，交接靠口口相传 |
| 构建不可复现 | 插件版本浮动、依赖来自不同仓库 | 本地能跑、CI 挂，或反之 |
真正的成本不在"统一"，而在变更的传导速度：基线统一后，一次 JDK 升级是一次平台动作；分散后它是一百次项目动作，每次都要重新论证。
3. BOM 与依赖管理：机制差异与生效范围
dependencyManagement 只是"版本声明"，不引入依赖；BOM 是被导入的一组 dependencyManagement。两者经常被混为一谈。
<!-- 父 POM：声明版本，子模块省略 version -->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>platform-bom</artifactId>
<version>2024.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
| 写法 | 作用 | 生效范围 | 风险 |
|---|---|---|---|
<parent> 继承 |
继承父 POM 全部配置 | 单继承链 | 只能有一个父，耦合强 |
dependencyManagement |
只约束版本，不引入 | 本 POM 及子模块 | 忘记声明依赖时 "没生效" |
import + pom（BOM） |
引入外部受管版本集合 | 导入处及其子模块 | BOM 之间的顺序决定覆盖 |
platform vs import |
Maven 3.9 / Gradle 的 BOM 引入方式 | 后者是 Gradle 语法 | 语义近似，解析细节不同 |
两个易错点：导入顺序即优先级（后导入的覆盖先导入的），以及**scope=import 只对 dependencyManagement 有效**。写成普通 dependencies 时它会被当普通依赖解析，报找不到 pom 类型的构件。
4. 传递依赖冲突的三类症状
| 症状 | 触发条件 | 定位难度 |
|---|---|---|
NoSuchMethodError / AbstractMethodError |
编译期版本高、运行期版本低 | 低，栈里直接给类名 |
ClassCastException（同类不同加载器/版本） |
两个版本的同名类同时在场 | 中，需要看 -verbose:class |
| 静默行为差异 | API 兼容但默认值变了（序列化、超时、编码） | 高，无异常，只有结果不对 |
读法比工具更重要：
mvn -q dependency:tree -Dincludes=com.fasterxml.jackson.core
mvn dependency:tree -Dverbose -Dincludes=org.slf4j # 显示被忽略的候选
mvn dependency:analyze # 声明了未用 / 用了未声明
-Dverbose 输出的 omitted for conflict 才是关键：它告诉你"本来还有另一个版本，被调解规则砍掉了"。只看树的第一层等于没看——冲突几乎总在第三、四层。
5. 依赖收敛策略
三条可直接落地的规则：禁止直接引用间接依赖（用到的每个库都显式声明）、统一日志门面（只允许 slf4j + 一个实现）、排除传递依赖要有判据（不是"报错就 exclude"）。
<plugin>
<artifactId>maven-enforcer-plugin</artifactId>
<executions><execution><goals><goal>enforce</goal></goals>
<configuration><rules>
<bannedDependencies>
<excludes>
<exclude>commons-logging:commons-logging</exclude>
<exclude>log4j:log4j</exclude>
<exclude>org.apache.logging.log4j:log4j-to-slf4j</exclude>
</excludes>
<searchTransitive>true</searchTransitive>
</bannedDependencies>
<dependencyConvergence/>
</rules></configuration>
</execution></executions>
</plugin>
dependencyConvergence 会在同一依赖出现多个版本时直接失败。它在存量项目上通常一开就红一片，所以正确做法是先加规则、把失败当告警跑一段时间，再切成阻断。
6. 升级节奏：小步快跑 vs 大版本迁移
| 方式 | 适用 | 代价结构 |
|---|---|---|
| 小步快跑（每月一次补丁级） | 基线已统一 | 单次成本低，但需要稳定 CI 与回归能力 |
| 大版本迁移（一年一次集中） | 跨 JDK 或框架大版本 | 前置成本高，一次性风险集中，需要并行环境 |
| 长期不动 | 遗留系统、无专职维护 | 表面零成本，实则把成本推到"必须动的那天" |
迁移清单固定四件事：兼容性核对（按目标版本官方迁移指南逐条过）→ 依赖树重排 → 编译与测试通过 → 灰度验证与回滚开关。少任何一件，迁移就会变成"改到能跑为止"。
7. 构建可重现
可重现的判据很硬：同一 commit 在任意机器上产出字节相同的包。三个前提：
<build>
<pluginManagement>
<plugins>
<plugin><artifactId>maven-compiler-plugin</artifactId><version>3.13.0</version></plugin>
<plugin><artifactId>maven-surefire-plugin</artifactId><version>3.2.5</version></plugin>
<plugin><artifactId>maven-jar-plugin</artifactId><version>3.4.1</version></plugin>
</plugins>
</pluginManagement>
</build>
<!-- ~/.m2/settings.xml：内网镜像 + 禁止快照外泄 -->
<mirrors><mirror>
<id>internal</id><mirrorOf>central</mirrorOf>
<url>https://NEXUS_URL/repository/maven-public/</url>
</mirror></mirrors>
第三件事是时间戳与文件顺序：project.build.outputTimestamp 固定 jar 内条目时间，否则两次构建字节必然不同；插件版本不锁时，mvn 会解析到当时最新版本。
8. 多模块拆分的边界
| 信号 | 该拆 | 不该拆 |
|---|---|---|
| 发布节奏不同 | 一方日更、一方季度更 | 同一次上线必须同版本 |
| 依赖方向清晰 | 下游只依赖上游 API 模块 | 双向引用靠"公共模块"打补丁 |
| 团队边界明确 | 各自有 owner 与 CI | 一个团队维护全部模块 |
| 构建时间 | 单模块构建成为瓶颈 | 拆完反而要装十几个 SNAPSHOT |
判据只有一句：拆分是为了独立发布，不是为了目录好看。拆完还需要能独立构建与独立部署，否则只是把编译期耦合换成了发布期耦合。
9. 质量门禁：阻断还是告警
| 检查项 | 建议策略 | 理由 |
|---|---|---|
| 编译警告（deprecation、unchecked） | 告警，按季度收敛 | 一次性阻断会逼出 @SuppressWarnings 滥用 |
| 静态检查（空指针、资源泄漏） | 新增代码阻断、存量告警 | 差量门禁的性价比最高 |
| 依赖漏洞扫描（CVE） | 高危阻断，中低危告警 + 期限 | 阻断标准要写死，否则每次争论 |
| 依赖收敛 / 白名单 | 新项目阻断 | 存量项目先告警，避免一次性瘫痪 |
| 单测覆盖率 | 不看总数，看增量 | 总数可被无意义测试刷高 |
# CI 里的差量门禁骨架
mvn -B verify -DskipTests=false
mvn -B org.owasp:dependency-check-maven:check -DfailBuildOnCVSS=7
门禁的关键不是严格程度，而是规则稳定：同一份代码昨天过今天不过，团队就会开始绕过门禁，而不是修问题。
10. 验证与组织落地
升级验证的三件套：契约测试（接口行为不变）、金丝雀（小流量对比错误率与 P99）、回滚方案（旧包与旧配置同时可回）。三者缺一，升级就只能靠"看起来没问题"。
组织上的分工建议：
| 角色 | 负责 | 不负责 |
|---|---|---|
| 平台团队 | 维护 BOM、JDK 镜像、构建模板、门禁规则 | 业务代码适配 |
| 业务团队 | 按基线升级、修复自身兼容问题 | 修改公共 BOM |
| 架构/技术委员会 | 决定基线版本与升级窗口 | 日常版本仲裁 |
BOM 的所有权必须唯一。多个团队各自"顺手改一下 BOM"，等于回到各项目自定版本的原点。
排错
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 本地能跑、CI 报类找不到 | 插件或依赖版本浮动、仓库不同源 | 锁插件版本、统一镜像 |
| 加了 BOM 但版本没变 | 子模块显式写了 version |
删掉显式版本，或确认导入顺序 |
dependencyConvergence 一开全红 |
存量冲突未收敛 | 先降级为告警，逐模块收敛 |
| 两次构建包字节不同 | 缺 outputTimestamp、文件顺序不定 |
加时间戳属性，禁用可变插件 |
| 同一接口在不同服务行为不同 | 框架小版本不一致 | 用 BOM 统一，按版本矩阵核对 |
| 升级后偶发序列化异常 | 默认值变更（如 Jackson 配置） | 显式配置关键默认项，不依赖隐式行为 |
边界
| 场景 | 不必做的事 | 理由 |
|---|---|---|
| 单人小项目 | 完整 BOM + 门禁体系 | 治理成本高于收益 |
| 已稳定的遗留系统 | 为统一而统一的大迁移 | 风险大于收益，按 CVE 定点修 |
| 只读的内部工具 | 覆盖率门禁、静态检查阻断 | 维护者与用户是同一个人 |
| 交付型项目（客户指定环境） | 强制内部基线 | 环境由合同决定，需按客户版本核对 |
| 试验性原型 | 锁死所有版本 | 探索期需要换库自由 |
自测
- 基线的四个维度里，哪两个最该完全锁死？为什么？
dependencyManagement与import型 BOM 的区别，各自生效范围有多大？-Dverbose输出里的omitted for conflict说明了什么？- 为什么"报错就 exclude"是错的依赖收敛策略？
- 构建可重现除锁插件版本外，还缺哪两件事？
- 依赖漏洞扫描该在什么条件下从告警切成阻断？