ADR（Architecture Decision Record，架构决策记录） 是一种轻量级、可追溯的决策管理工具，用于记录软件架构演进中的关键技术选择及其背后的逻辑。它解决了传统设计文档的痛点——“为什么当初选择这个方案？” 的集体失忆问题。以下是其核心解析：
ADR 的核心价值
| 问题场景 | ADR的解决方式 |
|---|---|
| 新成员质疑技术选型 | 提供历史决策背景与权衡分析 |
| 重复讨论已解决的架构问题 | 明确记录备选方案拒绝原因 |
| 技术债务归因模糊 | 关联决策与后续后果 |
| 架构演进缺乏连续性 | 形成决策链（通过Supersedes链接） |
ADR 标准结构（精简必选部分）
# [简短决策标题]
## 状态
提议 (Proposed) | 已通过 (Accepted) | 已弃用 (Deprecated) | 已取代 (Superseded)
## 背景
[待解决的问题/需求，用数据支撑]
> 例：订单查询接口 p99 延迟达 2s，超出 SLA 要求的 500ms
## 选项分析
| 选项 | 优点 | 缺点 |
|------|------|------|
| A | ... | ... |
| B | ... | ... |
## 决策
[选择的方案 + **理由**]
> 例：采用 Redis 缓存而非数据库分片，因业务存在 80% 的查询重复率
## 后果
[需付出的代价/后续影响]
> 例：需运维团队维护 Redis 集群，增加 2 节点成本 $200/月
ADR 实践指南
1. 决策粒度控制
- ✅ 记录跨模块影响的决策（如消息队列选型、认证方案）
- ❌ 不记录纯实现细节（如类命名规范）
2. 版本化存储
- 目录结构示例：
docs/adr/ ├─ 0001-use-redis-for-query-caching.md # 按顺序编号 ├─ 0002-adopt-grpc-instead-of-rest.md └─ README.md # 索引所有ADR
3. 生命周期管理
4. 工具链集成
- 生成工具：
adr-tools（命令行自动创建模板）adr new "Use Redis for caching" - 文档展示：VS Code + Markdown Preview Enhanced 插件
ADR vs. 传统设计文档
| 维度 | ADR | 传统设计文档 |
|---|---|---|
| 目标 | 记录为什么选择 | 描述是什么 |
| 更新频率 | 每次架构变更追加新记录 | 大版本重构时整体重写 |
| 可读性 | 单文件聚焦单一决策 | 冗长综合文档 |
| 可追溯性 | 通过状态链追踪演进 | 依赖文档版本对比 |
经典案例
# 002：使用 Kafka 替代 RabbitMQ 处理订单事件
## 状态：已通过 (2025-03-20)
## 背景
- 黑五流量峰值 10万订单/秒，RabbitMQ 集群出现堆积
- 监控显示 RabbitMQ 单集群吞吐上限 5万/秒
## 选项分析
| 选项 | 优点 | 缺点 |
|------------|-----------------------|---------------------|
| RabbitMQ | 团队熟悉，运维简单 | 横向扩展需重构集群 |
| Kafka | 吞吐量 >100万/秒 | 需学习新运维知识 |
## 决策
选择 Kafka：
- 满足未来 3 年流量增长需求
- 运维成本可通过培训降低（计划投入 5人日）
## 后果
- 需改造订单服务事件发布代码
- 新增 Kafka 监控到 Grafana 看板
💡 关键洞察：ADR 不是增加文档负担，而是将日常决策转化为组织资产。当团队在 2 年后质疑“为什么用 Kafka 不用 Pulsar？”时，只需打开
docs/adr/002.md即可还原历史上下文。