架构治理的7月实践从代码规范到架构决策记录的体系化落地方法一、架构治理的起点——不是规范文档而是决策记录很多人对架构治理的理解停留在写规范文档和代码审查上7月份的实践让我意识到架构治理的真正起点不是规范本身而是架构决策记录。为什么做这个设计当时有哪些备选方案决策的约束条件和预期效果是什么这些信息如果不记录下来几个月后没人能还原当时的决策逻辑导致后续的修改充满风险。7月份我在团队里推行了ADR的实践每做一个架构决策都写一份简短记录包含标题、状态提议/已接受/已废弃、上下文、决策内容、后果和备选方案六个要素。一个月下来积累了十几份ADR在后来的技术评审和新人交接中发挥了超出预期的价值。二、代码规范的三层递进——从格式化到架构约束代码规范不是一个维度的问题而是三个层次递进的设计。第一层是格式化规范。缩进、命名、注释格式、import排序这些由Checkstyle或Spotless等工具自动约束不需要人工审查。7月份我们把Checkstyle规则从Sun规范切换到Google规范主要是因为Google规范对Javadoc的要求更合理——不强制要求每个方法都写文档注释而是要求公共API必须有完善的文档。第二层是架构约束规范。这一层比格式化更难落地因为它约束的不是代码风格而是代码结构。比如Controller层不能直接调用Mapper必须经过Service层Service层不能跨模块直接调用必须通过Facade接口工具类不能依赖Spring Bean。这些约束无法用Checkstyle检查需要借助ArchUnit来验证。下面是一个用ArchUnit验证分层架构的示例它把架构约束从代码审查变成了自动化测试。Test public void controllerShouldNotDirectlyCallMapper() { JavaClasses classes new ClassFileImporter() .importPackages(com.liran.order); ArchRule rule noClasses() .that().resideInAPackage(..controller..) .should().accessClassesThat().resideInAPackage(..mapper..) .because(Controller must call Service, not Mapper directly); try { rule.check(classes); } catch (AssertionError e) { fail(架构违规Controller 直接调用了 Mapper 层 请通过 Service 层间接访问。详情 e.getMessage()); } } Test public void serviceShouldNotHaveCircularDependency() { JavaClasses classes new ClassFileImporter() .importPackages(com.liran.order); SliceRule sliceRule slices() .matching(com.liran.order.service.(*)..) .should().beFreeOfCycles(); sliceRule.check(classes); }第三层是运行时规范。有些架构约束在编译时无法检查需要运行时监控。比如单个方法的执行时间不能超过某个阈值、数据库连接使用后必须归还、线程池的使用必须受控。这些约束通过APM埋点、熔断器配置和连接池监控来保障核心是异常自动告警而不是人工检查。三、代码审查的效能提升——从全量审查到分层卡点7月份我调整了团队的代码审查策略。之前的做法是每次Pull Request都做全量审查结果是审查者疲劳、反馈慢、质量参差不齐。调整后的策略是分层卡点第一层自动化检查编译、格式化、单元测试、ArchUnit约束不通过不能进入人工审查。第二层是必要审查项接口变更、事务边界、并发安全、异常处理这部分不能跳过。第三层是可选审查项代码可读性、命名清晰度、注释适当性审查者自行决定深度。分层后的效果明显人工审查的时间从平均45分钟降到了20分钟而发现的架构级问题反而增加了因为审查者的精力从琐碎的格式化问题中释放出来可以聚焦在真正重要的架构决策上。四、技术债务的管理——从感觉驱动到数据驱动技术债务的管理在7月份也从感觉驱动转向了数据驱动。之前判断技术债务的严重程度靠主观感觉这块代码需要重构。现在靠的是具体指标圈复杂度超过15的方法数量、重复代码的比例、未覆盖的测试行数、SonarQube上的代码坏味道数量、以及线上故障中与技术债务相关的占比。我把团队的技术债务分成了三个等级并定义了不同的处理策略。紧急级已经导致线上问题或即将导致线上问题的债务必须在本迭代内处理。重要级显著影响开发效率或代码质量的债务纳入下个迭代计划。观察级暂不构成实质性影响但值得关注的债务记录但不排期。三个等级的管理不是一次性清理而是持续治理每个迭代固定分配20%的资源用于技术债务处理迭代结束时重新评估债务等级。五、架构治理的度量——治理做得好不好看这四个指标架构治理做了不少工作但到底有没有效果7月底我给自己定义了四个度量指标。第一个指标是架构违规率ArchUnit扫描发现的架构违规数量除以总类数。7月初这个数字是4.7%7月底降到了1.2%。第二个指标是技术债务增长率每个月新增的技术债务项数量。7月份新增17项但清理了23项净减少6项。第三个指标是代码审查效率从PR提交到合入的平均时长从6月的6.2小时降到了7月的3.8小时。第四个指标是线上故障中架构类问题的占比7月一共3个线上故障其中0个与架构设计缺陷直接相关。架构治理目标不是追求零违规、零债务而是建立一套可持续的治理机制让架构质量在迭代中逐步改善。7月的实践证明了这条路是可行的8月继续。资料说明本文中的协议、版本、性能、成本和行业趋势应以可核验的一手资料为准。未标注统计口径的比例、时间表和预测仅作工程讨论不应视为行业事实。可参考 0731 资料来源索引并在发布前将具体来源贴到对应断言之后。