【iSAQB软件架构】架构决策记录-ADR

ADR（Architecture Decision Record，架构决策记录） 是一种轻量级、可追溯的决策管理工具 ，用于记录软件架构演进中的关键技术选择及其背后的逻辑。它解决了传统设计文档的痛点------"为什么当初选择这个方案？" 的集体失忆问题。以下是其核心解析：

ADR 的核心价值

问题场景	ADR的解决方式
新成员质疑技术选型	提供历史决策背景与权衡分析
重复讨论已解决的架构问题	明确记录备选方案拒绝原因
技术债务归因模糊	关联决策与后续后果
架构演进缺乏连续性	形成决策链（通过`Supersedes`链接）

ADR 标准结构（精简必选部分）

markdown 复制代码

# [简短决策标题]  
## 状态  
  提议 (Proposed) | 已通过 (Accepted) | 已弃用 (Deprecated) | 已取代 (Superseded)  
## 背景  
  [待解决的问题/需求，用数据支撑]  
  > 例：订单查询接口 p99 延迟达 2s，超出 SLA 要求的 500ms  
## 选项分析  
  | 选项 | 优点 | 缺点 |  
  |------|------|------|  
  | A    | ...  | ...  |  
  | B    | ...  | ...  |  
## 决策  
  [选择的方案 + **理由**]  
  > 例：采用 Redis 缓存而非数据库分片，因业务存在 80% 的查询重复率  
## 后果  
  [需付出的代价/后续影响]  
  > 例：需运维团队维护 Redis 集群，增加 2 节点成本 $200/月

ADR 实践指南

1. 决策粒度控制

✅ 记录跨模块影响的决策（如消息队列选型、认证方案）
❌ 不记录纯实现细节（如类命名规范）

2. 版本化存储

目录结构示例：

bash 复制代码

docs/adr/
├─ 0001-use-redis-for-query-caching.md  # 按顺序编号
├─ 0002-adopt-grpc-instead-of-rest.md
└─ README.md  # 索引所有ADR

3. 生命周期管理

评审通过方案过时被新方案替代提议已通过已弃用已取代新ADR链接

4. 工具链集成

生成工具 ：adr-tools（命令行自动创建模板）
bash 复制代码
```
adr new "Use Redis for caching"
```
文档展示：VS Code + Markdown Preview Enhanced 插件

ADR vs. 传统设计文档

维度	ADR	传统设计文档
目标	记录为什么选择	描述是什么
更新频率	每次架构变更追加新记录	大版本重构时整体重写
可读性	单文件聚焦单一决策	冗长综合文档
可追溯性	通过状态链追踪演进	依赖文档版本对比

经典案例

markdown 复制代码

# 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 即可还原历史上下文。