架构债是什么
架构债的表现是结构层面的失控：模块间依赖成网（循环依赖）、分层规则名存实亡、公共模块变成垃圾场、改一个功能要动多个不相干的包。它与代码级坏味道的区别在于规模——单个类改好没用，得靠边界收口与调用迁移，治理周期通常以季度计。
基本信息
| 症状 | 循环依赖 / 分层失效 / 共享大杂烩模块 / 变更一触多动 |
|---|---|
| 检测 | 依赖分析工具、变更耦合分析与依赖矩阵的差异 |
| 治理 | 先封新入口，再逐步迁移调用 |
| 节奏 | 按调用量与团队优先级分批，不以一次性大扫除收尾 |
常见症状与线索
- 两个包互相 import，编译期靠同一次构建掩盖了环形依赖
- 分层目录齐全，但用例层直接调用持久化类
- tools 或 common 模块被所有模块依赖，里面塞着互不相关的工具
- 改一个报表字段要同时改四个模块，改动集呈现固定的群体模式
- 同一份配置或枚举在多处复制，口径开始分叉
- 新功能只能塞进已有的大模块，因为拆出新模块会触发循环依赖
治理节奏示意
治理节奏示意
1. 标记违规包，产出依赖报告与违规计数
2. 新增代码禁止新违规（在 CI 里设门禁）
3. 按调用量与团队优先级分批迁移存量
4. 违规计数进入周报，观察趋势是否下降
5. 拆出边界时同步补测试，避免迁移引入回归症状与检测手段
| 症状 | 检测手段 | 产出 |
|---|---|---|
| 循环依赖 | 依赖分析工具、编译顺序异常 | 环清单与打断点建议 |
| 分层失效 | 架构约束检查规则 | 违规调用点列表 |
| 大杂烩模块 | 被依赖数与内容主题统计 | 拆分候选清单 |
| 变更一触多动 | 变更耦合分析 vs 依赖矩阵 | 隐式耦合的可疑长链 |
治理要两条腿走路：只禁新违规不动存量，违规计数常年恒定，团队很快失去动力；只做存量迁移不封新入口，边还边欠，永远追不上。
变更耦合分析与依赖矩阵的差异很有价值：代码上没依赖、但总是一起改的文件，往往说明存在隐式的共享知识或复制粘贴的口径，值得先补文档与测试再谈解耦。