架构决策记录ADR在大型分布式系统重构中的落地在大型分布式系统演进的过程中每一个接手遗留系统的研发人员都会经历这种时刻看到一段极其诡异的代码逻辑或架构选型去问老员工老员工说“这是前年某某架构师定的具体原因记不清了”去翻内部 Wiki文档早已三年没更新与现实代码南辕北辙。系统就在这种“谁也不敢动、谁也解释不清”的恐慌中不断腐化最终彻底沦为不可维护的“技术大泥球”。很多团队不是没有做架构设计而是把设计文档写在离代码十万八千里的在线文档平台上。随着人员流动、需求迭代文档和代码彻底脱节。引入架构决策记录Architecture Decision Records, ADR将关键技术决策作为不可变快照与代码一同纳入 Git 版本控制是解决架构失忆症Architectural Amnesia最行之有效的工程手段。什么是 ADR 及其核心价值ADR 最初由架构师 Michael Nygard 提出。它不是冗长的大部头架构白皮书而是一篇篇结构极简、短小精悍的 Markdown 文件通常存放在代码仓库的docs/adr/目录下。每个 ADR 记录了一次关键技术选型背后的上下文、备选方案权衡、最终决定以及产生的副作用Consequences。ADR 具备四个核心原则与代码同源管理Doc-as-Code存储在 Git 仓库中随着代码分支一起提 PR、一起 Merge。代码改动在哪里决策记录就沉淀在哪里。不可变历史Immutable Append-only一旦某个 ADR 状态变为Accepted已采纳后续严禁直接在原文件上修改决策内容。如果技术路线发生变更必须新建一个 ADR 并声明Supersedes ADR-0003取代旧决策。重视权衡Trade-offs而非单纯的结论任何架构决策都有代价。ADR 最珍贵的部分不是记录“选了什么”而是记录“为什么不选方案 B 和方案 C”以及“接受了什么负面代价”。轻量短小通篇控制在一到两页以内5 分钟内可通读完毕。ADR 的标准结构规范MADR 模板业内通常遵循 Markdown ADRMADR标准格式包含以下核心要素# ADR-0012: 订单结算链路从 Seata AT 强一致切换为 RocketMQ 事务消息最终一致 - **状态**: Accepted (已采纳) - **决策人**: 李然架构师、张三订单组负责人 - **决策日期**: 2026-09-26 - **关联 Issue/PR**: PR #1042 ## 1. 上下文与业务痛点 (Context) 当前订单中心在创建订单、扣减库存、发放优惠券环节使用了 Seata AT 模式实现分布式事务。 随着大促峰值 QPS 突破 3000Seata TC事务协调器成为全链路最大瓶颈 - 数据库全局行锁竞争剧烈死锁与事务超时重试占比达到 8.4%。 - 核心下单接口平均响应时间从 45ms 劣化至 280ms。 - 业务方明确表示库存和优惠券允许 3 秒以内的最终一致性无需在下单主线程中强同步扣减。 ## 2. 候选方案对比 (Considered Options) 1. **方案 A优化现有 Seata AT 配置** - 增加 TC 节点并调优连接池优化数据源代理。 - 评估无法彻底消除全局锁等待扩展上限受限。 2. **方案 B基于 RocketMQ 事务消息实现最终一致性** - 本地写入订单主库与发送半事务消息绑定下游库存服务监听 MQ 异步扣减。 - 评估下单接口耗时可降至 30ms 以内彻底解耦上下游需处理消息幂等与异步补偿逻辑。 3. **方案 C采用 Saga 状态机模式** - 业务复杂度过高需要为每一个步骤编写正向与补偿接口重构周期预计超过两个月。 ## 3. 最终决策 (Decision Outcome) 决定采用 **方案 B (基于 RocketMQ 事务消息的最终一致性)**。 具体技术约束如下 - 下游消费端库存服务、营销服务必须基于 order_id 实现严格的 Redis 数据库唯一键幂等校验。 - 引入定时对账调度任务T1 凌晨执行对卡在中间态的订单进行兜底对账与人工告警。 ## 4. 带来的后果与代价 (Consequences) ### 正面收益 (Positive) - 下单链路 P99 响应延迟预计由 280ms 降至 50ms 以内。 - 彻底消除下单对库存服务的同步强依赖库存服务瞬时抖动不再阻断主交易。 ### 负面代价与技术债务 (Negative) - 增加了消息积压的风险需要对 RocketMQ Broker 扩容并配置消费延迟报警。 - 用户端在极端情况下会感知到短暂的“订单已生成但优惠券显示未核销”的状态延迟约 500ms~1s。 ### 中性妥协 (Neutral) - 原有的 Seata AT 依赖包将在两个迭代后从代码库中彻底剔除。在大型重构中推进 ADR 的实操机制再好的规范如果没有流程保障也会被业务迭代的压力冲垮。在研发团队落地 ADR 时可以通过以下三道机制实现常态化┌─────────────────────────────────────────────────────────────┐ │ 1. 架构评审触发点 (Trigger) │ │ 凡涉及分库分表、跨服务通信协议变更、持久层替换、缓存策略调整 │ │ 必须先在 feature 分支提交 ADR 草案 │ └──────────────────────────────┬──────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 2. Pull Request 同行评审 (Peer Review) │ │ 团队在 Git PR 评论区对 ADR 进行技术推演与可行性质疑 │ └──────────────────────────────┬──────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 3. 合并生效与索引归档 (Merge ADR Indexing) │ │ PR 合并至主干状态由 Proposed 转为 Accepted │ │ CI 脚本自动生成 README.md 决策索引大盘 │ └─────────────────────────────────────────────────────────────┘借助命令行工具集成研发日常可以借助adr-tools或轻量级 Shell 别名快速初始化 ADR降低书写摩擦力# 初始化仓库的 ADR 根目录 $ adr init docs/architecture/decisions # 创建新的架构决策 $ adr new 采用 Redis 本地二级缓存解决热点商品大促读击穿 # 自动生成docs/architecture/decisions/0013-caching-strategy.md架构师的复盘与治理建议不要事无巨细记录所有改动新增一个字段、写一个简单的 CRUD 接口不需要写 ADR。ADR 只服务于“具有深远影响、重构成本高、存在多种技术分歧”的重大决策。定期组织 ADR 状态盘点在季度架构复盘会上重新审视半年前标记为Accepted的 ADR。如果业务场景已发生变化及时立项提交流程将其置为Superseded并立新决策保持架构知识库的绝对真实性。