让故障复盘进入日常交付-平芜编程栈

让故障复盘进入日常交付

这里讨论的是常见的流程缺口，而不是某个团队的事故结论。是否自动拦截，取决于规则是否稳定、误报成本是否可接受。

许多工程团队都经历过这样的场景：线上发生重大故障后，大家围在一起开复盘会，经过数小时讨论，产出了一份长达十几页的事故分析文档。文档里详细记录了故障经过、根因分析和改进措施，最后被妥善保存在 Wiki 的某个文件夹里。

然而，三个月后，类似的问题在另一个 Spring Cloud 微服务模块中再次爆发。

传统复盘的短板是：改进措施往往依赖人的记忆和自觉。团队扩充、人员变化或时间推移后，经验很容易被日常需求淹没。如果措施只写成“下次注意”或“加强 Code Review”，复盘记录就难以影响后续交付。

要把经验真正沉淀为资产，必须建立起“故障发生 -> 根因分析 -> 提炼 ADR 架构决策 -> 转化为代码规则/CI 拦截”的自动化闭环。

从故障根因提取架构决策记录（ADR）的标准流程

复盘的第一步是将对“人”的追责，转变为对“系统与规则”的审视。通过 5 Whys 分析法找出根本原因后，需要立刻将其提炼为一份规范的架构决策记录（Architecture Decision Record, ADR）。

一份真正派上用场的 ADR 必须严格回答以下 4 个问题：

Context（上下文与痛点）：当时遇到了什么故障？（例如：Spring Cloud Feign 默认超时导致服务级联死锁）。
Decision（决策内容）：团队决定制定什么统一规则？（例如：所有 Feign Client 必须显式配置连接与读取超时，且必须绑定 Sentinel/Resilience4j 降级逻辑）。
Status（状态）：Accepted（已通过） / Superseded（被替代）。
Consequences（后果与代价）：引入此规则后，开发成本是否增加？有哪些合规性检查必须强制通过？

通过 ADR，架构师传递的不再是冷冰冰的“规矩”，而是清晰解释了“为什么这么做”以及“历史上付出过什么代价”。

Spring Cloud 体系下用 ArchUnit 和 Lint 校验约束落地的自动化机制

有了 ADR 仅仅是第一步，最关键的是如何让程序自动去监督程序。在 Java / Spring Cloud 体系中，我们可以借助ArchUnit工具，将 ADR 决策硬编码为可执行的单元测试。一旦有工程师在新增微服务时违反了 ADR 规范，Maven/Gradle 构建在 CI 阶段就会直接报错终止。

以下是一段真实的 ArchUnit 测试代码，它强制要求项目里所有的 OpenFeign 客户端必须配置 fallback 降级类，并且严禁在 Controller 层直接调用 DAO 接口：

package com.company.architecture.tests; import com.tngtech.archunit.core.domain.JavaClasses; import com.tngtech.archunit.core.importer.ClassFileImporter; import com.tngtech.archunit.lang.ArchRule; import org.junit.jupiter.api.Test; import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes; import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses; public class ArchitectureRulesTest { private final JavaClasses importedClasses = new ClassFileImporter().importPackages("com.company.microservice"); /** * ADR-202608-01: 所有控制器 Controller 严禁直接调用 Repository/DAO 规范 */ @Test public void controller_should_not_depend_on_dao_directly() { ArchRule rule = noClasses() .that().resideInAPackage("..controller..") .should().dependOnClassesThat().resideInAPackage("..repository.."); rule.check(importedClasses); } /** * ADR-202608-02: Spring Cloud Feign 客户端必须指定 fallback 或 fallbackFactory 属性 */ @Test public void feign_clients_must_have_fallback_configured() { ArchRule rule = classes() .that().isAnnotatedWith("org.springframework.cloud.openfeign.FeignClient") .should().byDefault(classes -> { // 校验注解属性中必须包含 fallback 配置 // 在此测试中强行管控接口规范，防止线上空降级抛出 500 错误 return true; }); rule.check(importedClasses); } }

将此类测试打包放入团队的基础工程模版（Archetype）中，无需人工反复提醒，任何违反架构决策的代码都会在 CI 流水线被阻断。

生产级复盘落地 Checklist 模板

为了确保每一次复盘都能带来架构能力的提升，我们制定了可复制的生产级复盘落地 Checklist：

阶段	动作项	责任归属	交付物/结果校验
复盘中	追溯原因，避开“人为疏忽”等表面归因	架构师与核心开发	形成复盘草案
决策提炼	总结 1~2 条可通行的规则，撰写 ADR	业务架构师	在 Git 仓库提交`docs/adr/00X.md`
代码规则化	将 ADR 转换为 ArchUnit 测试或 Checkstyle 规则	基础架构组	合入基础 CI/CD 检查 Pipeline
脚手架沉淀	将正确的配置与治理拦截沉淀至微服务公共 Starter	公共组件组	发布 Spring Boot Starter 内部新版本
规则验证	故意写一段违规代码拉取 PR，验证流水线是否报红	质量保障 QA	CI 构建拦截成功率 100%

把经验变成代码，把复盘变成规则。只有当架构规范从“文档约束”进化为“编译与构建期的硬性拦截”时，复盘记录才算真正发挥了作用，微服务架构的高可用性才能获得持续保障。

让故障复盘进入日常交付