跳至主要內容

静态检查、依赖治理与技术债：团队怎样持续限制退化

高谷深陵大约 11 分钟约 3338 字

一次构建可以编译成功，同时包含不符合项目约定的依赖、未维护的库和容易误用的接口。静态工具把其中一部分问题提前显示出来：报告指向具体文件或依赖路径，开发者再据此修正代码、调整规则或安排迁移。

规则的价值取决于它检查什么，以及发现问题后能采取什么动作。格式、架构、依赖解析和漏洞风险需要分别判断，不宜合成一个没有上下文的“质量分”。

源代码、编译产物与依赖图的不同检查
源代码、编译产物与依赖图的不同检查

不同工具能发现哪些问题

先确定输入与规则能力

检查类型观察对象典型发现不能据此确定
格式与语法约定源文本、语法树星号导入、命名、局部复杂度业务规则正确、运行无故障
字节码或静态分析编译产物、控制流等反向依赖、部分空值与资源问题所有反射和运行配置行为
依赖规则Maven 解析图与版本同坐标版本分歧、禁止的依赖版本兼容、没有漏洞
软件成分与漏洞检查组件清单、公告数据库已知受影响组件和版本实际可利用程度、未知漏洞
行为测试真正执行的代码和断言输出错误、约束失效、恢复异常未覆盖的输入与生产规模

Checkstyle 的 AvoidStarImport 针对 import 语法，适合演示一条规则怎样进入构建；它不判断程序是否安全。AvoidStarImport

架构测试则可以读取实际 class，检查包和类型依赖。例如分层与依赖方向使用 ArchUnit 拒绝领域层引用 JDBC 适配器。不同检查相互补充，不需要让一个工具承担全部任务。

高置信规则先进入默认构建

选择规则时，先在代表性代码上检查告警。明确的重复依赖或禁止访问内部模块通常容易处理；复杂的潜在空值路径可能需要人工判断。规则一启用就产生数千条无法解释的警告，会让团队逐渐忽略整个报告。

可以先阻止新增的明确问题，再分批修复历史项。每条规则写清适用代码、排除范围和修复方式；误报应缩小条件或配置精确例外，而不是全项目关闭检查。

自动格式化适合统一空格、导入顺序等机械内容。它应与语义修改分开提交，避免大量无关行遮住真正的行为变化。格式检查通过后，评审仍需关注输入、事务、并发和兼容性。

Maven 实际使用哪个依赖版本

声明版本、传递路径和最终选择

应用依赖 A，A 又依赖 B，这就是传递依赖。同一个 B 可以经不同路径到达项目，并且声明不同版本。Maven 按依赖调解和版本管理规则确定实际使用的版本；通常的 nearest definition 规则还受 dependencyManagement 等因素影响。Maven 依赖机制

应用
├── commons-text 1.14.0
│   └── commons-lang3
└── 直接声明 commons-lang3

只看顶层 pom 的两个 dependency，不能完整知道传递路径。dependency:tree 显示解析结果；开启 verbose 可以观察被省略或调解的候选。多模块工程要在实际运行模块核对，测试模块与生产制品的 classpath 可能不同。

scope 也影响可见范围。test 依赖用于测试，provided 依赖通常由运行环境提供，runtime 依赖参与运行而非普通编译。将缺失的生产依赖误放进 test，可能让测试通过却使打包运行失败。

dependencyManagement 管版本，dependency 引入组件

父 POM 或导入的 BOM 可以统一依赖版本。它们提供管理规则，但不会仅因列出某个坐标，就自动把这个依赖加入每个模块。模块仍然需要声明自己使用的组件。

排除传递依赖前，要查清它是否在反射、SPI、序列化或运行实现中使用。删掉一条树上的路径能消除冲突，也可能导致运行时报 ClassNotFoundException。升级后既要看树，也要构建最终制品并执行相关行为。

依赖插件和构建插件也要固定版本。可重复构建还涉及 JDK、仓库来源、构建输入和生成器；公开制品版本固定不等于整个环境完全不变。需要更强控制时，保存实际组件清单与制品摘要，避免把某次本机解析结果作为所有读者的固定值。

两条 Enforcer 规则的判断不同

dependencyConvergence 要求同一依赖在图中沿不同路径使用一致版本。requireUpperBoundDeps 则关注解析出的版本是否低于传递依赖要求的最高版本。最终选择了最高版本，并不意味着整张图的声明已经一致，也不意味着库之间一定兼容。依赖收敛规则、上界依赖规则

不要通过同时启用大量名字相近的规则，假定得到更强保证。先明确要避免哪种解析情况，再给出一个能失败的最小对照，确认规则真正观察到它。

运行真实构建规则与失败对照

正常工程先完成构建

下载 构建规则实验，在 Linux amd64 解压进入 quality-build-rules。需要 Bash、Docker Engine，普通用户具备 Docker 权限及目录写权限。脚本使用宿主 UID/GID，缓存保存在 .m2，构建镜像为 Maven 3.9.12 与 Java 17。

固定工具版本：Enforcer 3.6.2、Maven Checkstyle Plugin 3.6.0、Checkstyle 10.23.1。工具插件与实际 Checkstyle 引擎是两项独立版本，配置中都已固定。Enforcer 插件、Checkstyle 插件用法

bash run-docker.sh clean verify
bash run-docker.sh dependency:tree \
  -Dincludes=org.apache.commons:commons-lang3 -Dverbose

预期构建成功，LabelTest 为 1 项通过，Checkstyle 为零违规。测试实际调用 Commons Text 的 HTML 转义及 Commons Lang 的字符串处理，检查空输入和 <x> 的输出。

正常配置将 commons-lang3 管理并直接声明为 3.19.0。Commons Text 1.14.0 的原始 POM 依赖 3.18.0，进入本工程后由管理规则统一为 3.19.0。Commons Text 固定版本 POM

让直接版本与传递版本分歧

conflict profile 只将直接声明改为 3.18.0，保留 dependencyManagement 对传递路径的 3.19.0 管理，构造真实的两条版本路径：

if bash run-docker.sh -Pconflict validate > conflict.log 2>&1; then
  echo '预期依赖冲突没有中断构建' >&2
  exit 1
fi
grep -q 'Dependency convergence error' conflict.log || exit 1
grep -q '3.18.0' conflict.log || exit 1
grep -q '3.19.0' conflict.log || exit 1

预期 Maven 非零退出，日志包括：

commons-text:1.14.0 → commons-lang3:3.19.0
直接依赖           → commons-lang3:3.18.0
Dependency convergence error

诊断中的两条路径分别指向 3.19.0 与 3.18.0。检查错误名称和两个版本，可以区分依赖冲突与镜像拉取、仓库访问失败。

去掉 profile 后执行 bash run-docker.sh clean verify，应恢复成功。生产修复需要选择经过兼容测试的统一版本，不能只以“数字更大”为理由强行覆盖。

用源码违规检查规则是否接入

star-import profile 将编译和检查的源码目录切换到独立夹具，其中含有合法 Java 语法 import java.util.*;。它可以由 javac 接受，但违反本实验的导入规则。

if bash run-docker.sh -Pstar-import clean verify > imports.log 2>&1; then
  echo '预期导入违规没有中断构建' >&2
  exit 1
fi
grep -q 'AvoidStarImport' imports.log || exit 1
grep -q 'java.util' imports.log || exit 1
bash run-docker.sh clean verify

预期报告指向夹具 Label.java 第 2 行，包含 AvoidStarImport。恢复正常源码后再次通过。两个 profile 只用于分别触发已知负例，不应作为正常应用运行参数。

Java 25 可按同一组命令对照：

BUILD_IMAGE=maven:3.9.12-eclipse-temurin-25 bash run-docker.sh clean verify

编译目标保持 Java 17。检查报告、日志与缓存留在解压目录，命令结束后没有常驻服务。

历史问题、漏洞与升级怎样处理

历史基线应精确到问题身份

如果旧代码有 10 项违规，改动后仍是 10 项，可能是修复了 2 项又新增了 2 项。只比较总数会隐藏新增问题。基线应记录规则、具体类型或位置及原因，以集合差异判断新增和已修复项。

行号随着编辑变化，适合作为跳转信息，不宜总是作为唯一身份。类型名、成员和目标依赖更稳定；工具版本变化可能改变诊断格式，此时应单独迁移基线并审读差异，不能自动接受全部新报告。

例外还需要负责维护的人、到期条件和替代措施。模板与评审使用真实 ArchUnit 诊断验证例外只能覆盖指定依赖，新违规和过期记录仍会失败。

漏洞公告需要核对部署内容

发现受影响坐标后，先核对它是否进入生产制品、实际版本如何解析、受影响功能是否使用，以及公告所述条件是否成立。只在测试 classpath 中出现的组件，与生产请求可以触达的组件，处理优先级可能不同。

不可达性判断应有依据，不能因为应用没有直接调用某个方法就草率关闭漏洞。反射、框架自动装配和可控输入可能形成间接路径。没有把握时，先限制暴露面并按项目安全流程处理。

组件清单与扫描结果应关联制品版本。依赖库、基础镜像、JDK 和原生库各自可能受公告影响；这份实验只演示 Maven 收敛和源码规则，没有运行漏洞扫描服务，也不作“依赖无漏洞”的结论。

升级一次，检查多个兼容面

小范围升级通常更容易定位。先阅读官方变更与迁移说明，调整版本，检查解析树，再运行编译、单元测试、数据库或协议集成测试，并构建真正要部署的制品。

升级可能改变序列化默认值、连接池配置、数据库驱动行为或日志上下文实现。源代码没有编译错误，仍可能出现运行差异。针对实际使用功能保留对照结果，比只记录“已升级到最新版”更有用。

回退也受状态变化影响。库升级如果伴随数据库迁移或消息格式收缩，回退旧二进制前必须确认它仍能读取已写内容。制品可重新下载，不代表业务状态也能自动恢复。

技术债按维护影响安排

重复逻辑、难以测试的长事务、跨模块内部访问和过时依赖，都可能增加未来改动成本。记录具体影响：哪种修改要触碰多个地方，哪类故障难以恢复，哪些升级被旧接口阻塞。

处理顺序结合业务频率、故障风险和改造成本。经常修改且容易出错的代码值得优先整理；长期稳定的旧实现可以先补行为测试。大规模重写前，先用一项小变更验证拆分方式是否确实降低修改成本。

现象先核对后续动作
本地通过、CI 失败JDK、插件版本、profile、工作目录使用同样输入复现，不直接关闭规则
依赖已经统一却运行失败API、SPI、资源与行为兼容缩小升级范围，恢复或适配实际使用点
告警总数下降但出现新问题规则和问题身份集合单独处理新增违规
报告很多但无人处理误报比例、修复成本、责任分配精简无效规则，安排有价值修复
排除依赖后缺类运行使用、反射及传递来源恢复必要依赖，统一兼容版本

工具规则应保持可解释：给出问题位置、产生原因和修复入口。对必须人工判断的设计问题，保留评审空间，不将所有工程选择压成一个数字阈值。

权威资料与规范地址

源码导入规则与静态检查

依赖解析、版本收敛与构建约束

跳到正文