架构决策记录(ADR)：让架构演进有据可循

为什么当年的架构选择这么做？团队成员各执己见，却找不到决策依据？随着系统演进，新人难以理解过去的架构选择——这正是架构决策记录（ADR）要解决的问题。

什么是架构决策记录？

架构决策记录（Architecture Decision Records, ADR） 是一种轻量级的文档形式，用于记录架构决策的背景、方案、后果和替代选项。每一个ADR本质上是一份简短的备忘录，阐明"做了什么决定"、"为什么这样做"、"考虑了哪些替代方案"。

一个标准的ADR通常包含以下字段：

• 标题：决策的名称
• 状态：提议中 / 已接受 / 已废弃 / 已取代
• 背景：促使我们需要做决策的问题和上下文
• 决策：我们决定采取的方案
• 后果：决策后的正面和负面影响
• 替代方案：被否决的方案及原因

为什么需要 ADR？

1. 传承知识

软件系统的寿命往往远超预期。当核心成员离开时，新人面对的是一个"看似不合理"的系统，却找不到解释。ADR让隐性知识显性化，让历史决策有据可查。

2. 促进协作

架构决策往往涉及多方利益。通过 ADR 文档化讨论过程，团队成员可以更清晰地理解彼此的观点，减少后期"为什么当初要这样做"的困惑。

3. 支持审计与复盘

当系统出现问题或需要重构时，回顾 ADR 能帮助团队理解当初的权衡和约束条件，避免重复犯错。

4. 降低认知负荷

新人不需要阅读冗长的设计文档，只需查阅 ADR 就能快速了解系统演进的脉络。

ADR 实战模板

\`markdown

ADR-001: 采用微服务架构替代单体架构

状态

已接受

背景

随着业务复杂度提升，当前单体应用面临以下问题：

• 部署频率受限：每次发布需要停机数分钟
• 扩展困难：某模块CPU密集但只能整体扩展
• 技术栈僵化：无法为不同模块选择最适合的技术

决策

采用微服务架构，将核心业务拆分为5个服务：用户服务、订单服务、商品服务、支付服务、通知服务。

后果

正面：

• 支持独立部署，部署频率可提升至每日多次
• 可按服务维度扩展，优化资源成本
• 各服务可独立选择技术栈

负面：

• 运维复杂度提升，需要引入服务治理能力
• 分布式事务处理增加了开发成本
• 跨服务调用延迟增加

替代方案

1. 模块化单体：在单体架构内通过模块化解耦——未采用，扩展性问题仍然存在
2. 服务化（SOA）：引入ESB——未采用，ESB单点故障风险高 `\

最佳实践

1. 保持简洁

ADR 不是详细的设计文档，控制在1-2页为宜。一个好的 ADR 应该在15分钟内能读完。

2. 编号连续

使用序号（如 ADR-001, ADR-002）便于引用和追踪。不要随意删除已废弃的 ADR，保持历史的完整性。

3. 与代码库一起管理

将 ADR 放在代码仓库的 docs/adr/ 目录下，与代码一起版本化管理。这样可以在代码审查时顺便审查 ADR 变更。

4. 定期回顾

建议每个季度回顾一次活跃的 ADR，检查是否仍然有效。当业务上下文发生重大变化时，考虑更新或废弃相关 ADR。

5. 建立决策流程

在架构设计流程中明确"先有 ADR 再实现"的规范。对于重大决策，要求至少有一个 ADR 作为提案。

工具支持

社区提供了多种 ADR 工具：

• adr-tools：命令行工具，支持创建、列出、更新 ADR
• adr-log：生成 ADR 变更日志
• ADR Viewers：VS Code 插件，提供可视化浏览

总结

架构决策记录不是负担，而是投资。它用极低的成本，为团队提供了：

• 历史决策的可追溯性
• 团队共识的显性化
• 架构演进的连续性
• 组织知识的传承

在这个快速变化的时代，每一个架构决策都值得被认真记录。今天的文档，就是明天最宝贵的遗产。

---

如果你对 ADR 有任何问题或想分享你的实践经验，欢迎在评论区留言！