静态检查、依赖治理与技术债：团队怎样持续限制退化
规则越来越多，为什么代码质量反而变成大量可忽略告警？ 如果答案只落在“大家遵守约定”，边界就会随人员、交付压力和代码规模一起失效。静态检查的价值不在告警数量，而在高置信规则能阻止新增缺陷。技术债需要可归属、可到期、可观察的预算；依赖治理需要锁定解析结果、解释传递图并验证升级，而不是只看声明版本。
结构质量首先是一张可计算的图
代码结构可以表示为有向图：类、包或模块是节点，import、字段类型、方法签名、继承、注解、调用和反射配置形成边。目录树只显示节点被放在哪里，依赖图才显示谁真正知道谁。所谓“内层”“外层”也不是视觉位置，而是边被允许指向的方向。
源码规则检查格式和局部语法，编译器插件利用类型信息，字节码分析寻找跨方法缺陷，架构测试检查依赖图，依赖解析器生成实际版本闭包。流水线按严重度、置信度和变更范围决定阻断，并保存 baseline 与趋势。
一个边界至少有四种强度：文档约定、包可见性、构建模块隔离、运行时制品隔离。文档适合解释意图，package-private 与模块 exports 限制编译访问，多模块构建隔离 classpath，独立进程再增加部署与故障边界。并非所有系统都需要最强隔离，但选择弱边界时要明确它靠什么门禁防止退化。
从一次变更追踪耦合怎样扩散
规则分为立即阻断、增量阻断、度量和实验四级。既有债务建立 fingerprint baseline，新变更不得增加，高风险逐项修复。依赖记录 declared/resolved/locked、来源、许可、漏洞、可达性和升级测试，BOM/constraint 统一版本决策。
一次启用数千历史告警会迫使团队全局忽略；质量门禁只看总数会阻止偿债提交；Maven 最近定义或动态版本可能造成依赖漂移；锁文件不更新不验证则只是陈旧快照；漏洞数量不结合可达性和暴露面会误排优先级。
这类失败常被误诊为“开发不规范”，实际根因通常是规则不可执行、职责没有 owner 或历史债务没有迁移路径。正确修复不是再写一页规范，而是把允许边、禁止边、转换点、事务 owner 和例外期限放进代码与流水线。
模块边界要同时控制可见性和依赖方向
模型转换是边界的收费站
Service、Repository 与 Mapper 按决策所有权分工
配置、错误、日志和测试必须有统一默认语义
配置需要固定源优先级、类型绑定、未知键策略、范围/组合校验和启动失败规则。字符串散落在业务代码会让同一配置被不同模块以不同默认值解释。密钥不进入普通配置回显，动态配置还要有版本、原子快照、回调隔离和失败保留旧值策略。
静态检查要按可见事实选择工具
Checkstyle 官方文档明确其单文件分析限制；SpotBugs 从字节码匹配缺陷模式；ArchUnit 导入 class 文件构建依赖并检查 layer、slice、cycle。它们是实现例子，不是规则本身。规则要先写明意图、证据、误报边界和修复方式，再选择能观察该事实的工具。
高置信安全/正确性问题可立即阻断；大量历史风格问题适合 baseline 后增量阻断；实验规则先度量误报。规则失败消息应包含 ruleId、违规边、为何危险、允许替代和例外入口，否则开发者只会添加 suppress。
可运行模型一：让结构退化变成数字
javac --release 17 -Xlint:all -Werror QualityBudgetDemo.java
java QualityBudgetDemo预期输出：
baselineViolations=120 newViolations=4 fixed=9 current=115 budgetDelta=-5 gatePass=false模型把“感觉不整洁”转换为依赖违规、字段泄漏、事务 owner、未知配置、质量预算或例外状态。反向实验要修改一个输入使门禁从通过变失败，并解释失败为何对应真实风险。只输出一个综合分数会掩盖根因，计数必须能回到具体边、字段、用例或规则。
可运行模型二：证明失败不会被平均值隐藏
javac --release 17 -Xlint:all -Werror DependencyDriftDemo.java
java DependencyDriftDemo预期输出：
declared=8 resolved=23 locked=22 dynamic=1 vulnerable=2 unused=1 reproducible=false第二个模型专门保留少数失败：一个循环、两处 SQL 泄漏、一个缺失上下文、一项未锁定依赖或一个无 owner 例外。质量门禁不能因为总体通过率很高就放过系统性缺口；某些不变量是 all-or-nothing。
依赖治理要看解析结果，不只看声明
Maven 的传递依赖和最近定义调解、BOM/dependencyManagement，Gradle 的 constraint、version catalog 与 dependency locking 都会改变最终 classpath。评审一行依赖声明不能回答实际选中了哪个版本、为何选中、来自哪个仓库以及是否可复现。
漏洞优先级结合可达性、运行环境、数据暴露和修复可用性；unused 依赖仍扩大供应链与镜像；重复库可能引起类冲突。升级不是“版本越新越好”，而是小批次更新、兼容测试、行为对比和可回滚制品。
技术债必须有预算、趋势和终止条件
预算至少区分高风险正确性债、结构债、依赖债、测试债和可读性债。严重度乘数量的简单总分会让大量格式问题稀释一个安全缺陷。门禁采用分层阈值：高风险零容忍，中风险不得新增，低风险看趋势和变更触达范围。
模板、评审与例外形成闭环
模板提供最小可运行骨架：模块边界、依赖约束、类型化配置、错误入口、日志字段、测试层和构建门禁。模板不预装所有组件，不复制业务层空壳，也不生成无法删除的抽象。生成后就是普通代码，持续接受同一门禁。
评审根据风险分级。低风险由自动检查和一名 owner 验证；涉及数据迁移、公开契约、并发、一致性、权限或不可逆变更时，必须给出反向实验、指标、灰度和回滚。评审者验证证据能否支撑不变量，而不是重新编写提交者方案。
例外不是口头批准或永久 suppress。它具有规则、范围、owner、原因、风险、补偿控制、到期和删除条件；到期后流水线自动失败或要求重新评估。全局例外风险最大，优先缩小到文件、模块、依赖坐标或具体违规指纹。
安全与可观测不能被“代码质量”稀释
质量信号本身要可观测：规则通过率、baseline 总量与新增量、循环数、模块 API 面积、依赖更新年龄、未知配置、错误上下文缺失、flaky test 和例外到期。趋势按模块和 owner 展示，不用一个全项目“质量分”驱动表面优化。
门禁失败保存可行动证据而非完整源码或秘密。依赖报告与 SBOM 需要访问控制；日志样本脱敏；评审记录避免复制客户数据。质量平台拥有读取代码的高权限，其插件、规则包和生成模板也必须锁版本、审计来源并最小授权。
架构决策记录应该留下什么
记录模块节点、允许边、公开 API、模型 owner、转换损失、事务 owner、查询边界、配置优先级、错误目录、日志字段、测试层、规则能力、baseline、解析依赖图、例外与回滚。每条约束都链接到自动检查或反向实验。
静态检查的价值不在告警数量，而在高置信规则能阻止新增缺陷。技术债需要可归属、可到期、可观察的预算；依赖治理需要锁定解析结果、解释传递图并验证升级，而不是只看声明版本。 对这一主题，最终必须守住：新增代码不扩大高置信债务，任一发布依赖图都可复现、可解释并经过风险验证。如果结构只能从架构图看出、无法从构建产物和测试证明，它还不是工程事实。
应用服务、领域、Repository、Mapper 和 Query Service 的所有权唯一。配置未知键与组合错误阻止启动，错误身份和日志脱敏稳定。测试层对应真实边界，不共享可变 Fixture 或生产特权分支。
静态规则匹配其可观察事实，历史 baseline 不吸收新增违规。declared/resolved/locked 依赖图可复现，升级和漏洞有验证证据。技术债与例外有 owner、补偿、期限和可执行关闭条件。
高风险变更没有反向实验、观测和回滚证据就不能发布。两个 Java 17 模型严格编译运行，输出与正文一致。
实现依据
以下官方资料用于核对语言可见性、架构检查和依赖解析能力；具体工具只实现部分规则，不替代工程边界本身：
Checkstyle standard checks。SpotBugs bug descriptions。Maven dependency mechanism