架构决策记录(ADR)是记录架构决策的轻量级方法，帮助团队理解架构演进的原因和过程。
本文系统介绍ADR的核心概念、编写方法和实战案例，帮助你建立架构决策文档化体系。
架构决策问题：
1. 决策原因不明确
├─ 为什么选择这个技术？
├─ 有什么替代方案？
└─ 为什么放弃其他方案？
2. 决策过程不透明
├─ 谁参与了决策？
├─ 考虑了哪些因素？
└─ 如何达成共识？
3. 决策结果不持久
├─ 决策文档丢失
├─ 新人不了解历史
└─ 重复讨论已决策事项
| 价值 | 说明 |
|---|
| 知识沉淀 | 记录决策原因和过程 |
| 沟通工具 | 帮助团队理解架构 |
| 避免重复 | 不重复讨论已决策事项 |
| 历史追溯 | 追踪架构演进历程 |
# ADR {编号}: {标题}
## 状态
{提议 | 已接受 | 已弃用 | 已取代}
## 日期
{YYYY-MM-DD}
## 背景
{描述决策的背景和问题}
## 决策
{描述做出的决策}
## 理由
{说明为什么做出这个决策}
## 后果
{描述决策带来的后果}
## 备选方案
{列出考虑过的替代方案}
# ADR 001: 使用Redis作为缓存
## 状态
已接受
## 日期
2026-09-07
## 背景
系统需要高性能缓存来减少数据库压力，当前数据库查询响应时间超过100ms，需要优化到10ms以内。
## 决策
使用Redis作为分布式缓存，采用Cluster模式部署。
## 理由
1. Redis性能优秀，单线程10万+ QPS
2. 支持多种数据结构，满足不同场景
3. 社区活跃，文档完善
4. 团队有使用经验
## 后果
1. 引入新的中间件，增加运维成本
2. 需要处理缓存一致性问题
3. 缓存故障可能影响系统可用性
## 备选方案
1. **Memcached**: 不支持数据结构，功能有限
2. **本地缓存**: 不支持分布式，数据不一致
3. **数据库缓存**: 性能提升有限
| 原则 | 说明 |
|---|
| 简洁明了 | 用简单语言描述 |
| 客观中立 | 客观记录决策过程 |
| 及时更新 | 决策变更时更新ADR |
| 便于搜索 | 使用统一编号和标签 |
ADR流程：
1. 提出决策
├─ 识别架构问题
├─ 收集信息
└─ 起草ADR
2. 评审决策
├─ 技术评审
├─ 团队讨论
└─ 达成共识
3. 记录决策
├─ 更新ADR状态
├─ 提交到代码库
└─ 通知团队
4. 跟踪决策
├─ 定期回顾
├─ 更新后果
└─ 必要时修订
| 类型 | 说明 | 示例 |
|---|
| 技术选型 | 技术方案选择 | 数据库、框架、中间件 |
| 架构模式 | 架构风格选择 | 微服务、单体、Serverless |
| 设计决策 | 具体设计选择 | API设计、数据模型 |
| 流程决策 | 开发流程选择 | CI/CD、代码审查 |
docs/adr/
├── 001-use-redis-for-caching.md
├── 002-adopt-microservices-architecture.md
├── 003-use-kafka-for-messaging.md
├── 004-adopt-gitflow-workflow.md
└── README.md
# ADR 005: 选择消息队列
## 状态
已接受
## 日期
2026-09-07
## 背景
系统需要解耦和异步处理，需要选择消息队列中间件。
## 决策
使用Apache Kafka作为消息队列。
## 理由
1. 高吞吐量，支持百万级消息/秒
2. 消息持久化，支持回放
3. 分布式架构，高可用
4. 社区活跃，生态完善
## 后果
1. 部署和运维复杂度增加
2. 需要学习Kafka配置和调优
3. 消息顺序性需要特别处理
## 备选方案
1. **RabbitMQ**: 吞吐量较低，适合中小规模
2. **RocketMQ**: 功能丰富，但社区相对较小
3. **Pulsar**: 新兴技术，生产验证不足
# ADR 006: 采用微服务架构
## 状态
已接受
## 日期
2026-09-07
## 背景
业务快速迭代，单体架构难以满足需求，需要拆分服务。
## 决策
采用微服务架构，按业务领域拆分服务。
## 理由
1. 独立部署，快速迭代
2. 故障隔离，提高可用性
3. 技术异构，灵活选型
4. 团队自治，提高效率
## 后果
1. 系统复杂度增加
2. 需要处理分布式事务
3. 运维成本增加
4. 需要完善的监控体系
## 备选方案
1. **单体架构**: 简单但难以扩展
2. **SOA**: 过于复杂，不适合快速迭代
3. **Serverless**: 技术不成熟，成本难控
| 建议 | 说明 |
|---|
| 及时记录 | 决策后立即记录 |
| 简洁明了 | 一页纸原则 |
| 版本控制 | ADR与代码一起版本控制 |
| 定期回顾 | 定期回顾和更新 |
| 问题 | 原因 | 解决方案 |
|---|
| ADR过时 | 未及时更新 | 定期回顾 |
| ADR缺失 | 未建立流程 | 团队培训 |
| ADR不一致 | 多人编写 | 统一模板 |
