良好的设计笔记记录权衡、所选方向以及哪些证据会在未来改变决策。
为什么架构决策会卡住
团队花费数周时间争论架构，是因为他们试图预测未来。但好的架构不在于永远正确——而在于用清晰的标准做出可逆的决策。
ADR 模式（架构决策记录）
使用此模板记录每个重要决策：
# ADR-001: 选择 PostgreSQL 而非 MongoDB
## 背景
我们需要一个支持复杂查询和事务的用户数据库。
## 决策
使用 PostgreSQL 15，支持 JSONB。
## 影响
### 积极影响
- ACID 事务确保数据完整性
- 原生支持复杂连接
- 强大的生态系统和工具链
- 团队已有 PostgreSQL 经验
### 消极影响
- Schema 变更灵活性不如 NoSQL
- 水平扩展更复杂
- 初期运维开销更高
## 可逆性
中等。可以迁移但需要投入。
## 评审标准
以下情况需重新评估：
- 数据量超过100万条时查询性能下降
- 每周或更频繁地需要 Schema 变更
- 团队报告关系模型存在显著摩擦
好的架构笔记是什么样子
1. 记录权衡
每个决策都有成本。诚实地记录下来：
不好： “我们选择 React 因为它流行”
好： “尽管 Vue 的学习曲线更简单，但我们选择 React，因为团队已经熟悉 JSX 模式，而且我们需要更大的组件生态”
2. 明确陈述假设
假设:
- 第一年日活用户量保持在1万以下
- 团队规模保持在3-5名开发人员
- 预算允许每月500美元的infra支出
- 初期不需要实时协作功能
当假设改变时，重新评估决策。
3. 定义成功指标
如何判断决策是否正确？
需跟踪的指标：
- API 响应时间 P95 < 200ms
- 数据库查询平均时间 < 50ms
- 部署频率：每周至少2次
- 新开发人员上手时间：< 2天
4. 记录什么情况会改变你的决定
最好的架构决策包含退出标准：
以下情况我们将重新考虑此决策：
☐ 性能基准显示下降30%以上
☐ 团队速度连续3个冲刺低于15个故事点/冲刺
☐ 客户需求要求根本性架构变更
☐ 出现能2倍更好地解决我们核心问题的新技术
常见架构决策类别
数据存储
- SQL vs NoSQL
- 单一数据库 vs 多语言持久化
- 托管服务 vs 自托管
通信模式
- REST vs GraphQL vs gRPC
- 同步 vs 异步
- 事件驱动 vs 请求-响应
部署策略
- 单体 vs 微服务
- Serverless vs 容器 vs 虚拟机
- 单区域 vs 多区域
开发方法
- 框架选择（React、Vue、Angular 等）
- 语言选择
- 测试策略
何时编写 ADR
编写 ADR 的情况：
- ✅ 存在多个可行选项
- ✅ 决策影响多个团队
- ✅ 后期更改成本高昂
- ✅ 团队成员在方案上有分歧
跳过 ADR 的情况：
- ❌ 存在明显的最佳选择
- ❌ 决策容易逆转
- ❌ 影响仅限于一名开发人员
- ❌ 纯粹是偏好问题
保持 ADR 活力
月度评审
浏览最近的 ADR。假设是否仍然有效？
基于触发条件的评审
当指标触及评审标准时，自动重新审视决策。
淘汰旧 ADR
在被替换时标记决策为已废弃。保留历史以供学习。
示例：真实 ADR 实操
# ADR-003: 使用 Redis 管理会话
日期: 2026-03-15
状态: 已接受
## 背景
当前应用内存中的会话存储无法跨多个实例扩展。
## 考虑的选项
1. **Redis** - 快速、成熟、原生支持 TTL
2. **数据库会话** - 运维更简单但速度较慢
3. **JWT tokens** - 无状态但难以轻易失效
## 决策
使用 Redis，用户会话 TTL 设为30分钟。
## 理由
- 亚毫秒级读写性能
- 自动过期防止陈旧会话
- 可在负载均衡实例之间共享会话
- 团队有 Redis 运维经验
## 实现说明
- 使用 Redis 集群模式实现高可用
- 仅存储会话 ID 和最小用户上下文
- 实现 Redis 不可用时的优雅降级
## 评审日期: 2026-06-15
检查：规模化时的会话存储性能、运维复杂度
结论
架构决策不需要完美——它们需要被记录、可逆和可衡量。好的笔记将争论转化为实验，将观点转化为可验证的假设。
少写、更好地记录、更快地决策。