架构与系统设计 / 系统课时

用 ADR 记录关键架构决策

用 ADR 记录关键架构决策

关键架构选择如果只存在于会议和聊天记录里,人员变化后就很难解释“为什么当初这样做”。ADR(Architecture Decision Record)用一份短文档记录背景、选项、决策和后果,让重要取舍可以追溯,也能在条件变化时判断是否需要重新决策。

学习目标

  • 判断哪些架构选择值得写 ADR,而不是把所有讨论都文档化。
  • 用统一结构记录背景、备选方案、决策理由和后果。
  • 管理 ADR 的状态与后续变更,避免文档和真实系统脱节。

只记录真正重要的决策

ADR 适合记录影响范围大、修改成本高、存在明显取舍的选择,例如数据库类型、服务拆分边界、跨服务一致性策略、消息中间件、部署模型或公共认证方案。

反过来,局部变量命名、普通代码重构、可随时替换且没有长期后果的实现细节,通常不需要 ADR。判断时可以问三个问题:这个决定半年后还会影响系统吗?新人是否需要知道为什么这么选?如果要推翻它,成本是否明显高于普通代码修改?只要其中两项答案为“是”,通常就值得记录。

用固定结构把决策写完整

ADR 不需要很长,但必须把“为什么”和“代价”写清楚。一个实用结构包括状态、背景、决策、备选方案、后果和后续动作。

下面是一份可直接采用的片段示例,实际项目可保存为 docs/adr/0007-use-postgresql-for-order-service.md:

text
# ADR 0007:订单服务使用 PostgreSQL

状态:Accepted
日期:<TIME>

背景:
订单服务需要事务、唯一约束和按用户查询能力,预计一年内数据量低于 2 TB。
团队已有 PostgreSQL 运维经验,交付窗口为 10 周。

备选方案:
1. PostgreSQL:事务能力成熟,团队熟悉,扩展路径清晰。
2. MongoDB:开发灵活,但团队缺少生产运维经验。
3. 自建分库分表:容量上限更高,但当前复杂度和交付成本过大。

决策:
采用 PostgreSQL,先使用单主多读副本架构。

后果:
获得成熟事务与较低运维风险;同时接受单主写入扩展上限。
当写入峰值接近当前容量的 60% 时重新评估分片方案。

这不是“会议纪要”,而是一个可长期阅读的决策快照。读者应该能在几分钟内回答四件事:当时面临什么问题、考虑过什么方案、为什么选当前方案、为此接受了什么代价。

把取舍写成可验证的理由

“PostgreSQL 更稳定”“Kafka 更专业”这类表述几乎没有复用价值。理由应尽量连接到具体质量目标和约束,例如“10 周内上线且团队已有 PostgreSQL 值班经验,因此优先降低交付与运维风险”。

备选方案也不要只列名字,要写出为什么没有选。尤其是被否决方案的优势必须保留,否则后人看到新需求时无法判断旧结论是否仍成立。

管理状态而不是覆盖历史

ADR 一旦被接受,不要在条件变化后直接改写成新的结论,否则旧系统为什么长成现在这样会失去证据。常见状态可以保持简单:Proposed、Accepted、Deprecated、Superseded。

当新决策替代旧决策时,创建新的 ADR,并在两份记录中互相引用。例如 ADR 0019 替代 ADR 0007,就让 0007 标记为 Superseded,并注明“由 ADR 0019 替代”。这样既保留历史,又能让读者快速找到当前有效结论。

把 ADR 接入日常决策流程

ADR 不应变成架构评审后的补作业。更有效的做法是在关键方案形成时先写 Proposed 版本,让评审围绕同一份背景、选项和权衡展开;达成结论后改为 Accepted,并把必要的验证项放进后续任务。

每次重要架构变化前,先搜索相关 ADR:如果背景条件没有变化,应尊重原有决策;如果容量、组织能力、法规或业务目标已经改变,就基于新的证据创建替代 ADR。这样 ADR 才是活的决策索引,而不是无人维护的文档仓库。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 ADR 记录关键架构决策

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通