用 ADR 保存架构决策

ADR 用一份短文档保存一个重要架构决定及其理由。它让后来的人知道“当时为什么这样选”，避免团队只看到代码结果， 却不知道约束、备选方案和风险。

Table of contents

ADR 是什么

**ADR（Architecture Decision Record，架构决策记录）**是一个有编号、可版本控制的决策文档。多份 ADR 按时间 组成架构决策日志。

ADR 不替代完整技术方案。技术方案可以包含大量分析和实验；ADR 提取最终决定、关键证据和长期后果。

适合记录的决定通常具有至少一个特征：

• 影响多个模块、团队或长期数据。
• 改回去的成本高，或迁移需要多个版本。
• 改变性能、可用性、安全、合规或成本边界。
• 团队比较过多个都合理的选项。
• 新成员只看代码无法理解选择原因。

变量重命名和普通缺陷修复通常不需要 ADR。

一个 ADR 只记录一个决定

把多个决定写在一份 ADR 中，会导致它们无法独立废弃。例如，“选择 Java 版本”和“选择数据库”应使用两个编号。

推荐使用不可复用的顺序编号：

docs/adr/
├── 0001-选择Java版本基线.md
├── 0002-订单数据由订单服务拥有.md
└── 0003-采用事务性发件箱发布领域事件.md

文件名保持稳定。决定被替代后，不要删除旧文件；将状态改为“已被替代”，并链接到新 ADR。

填写六个核心部分

下载架构决策记录模板查看下载，然后依次填写下面六部分。

状态

状态说明决定处于哪个生命周期阶段。使用“提议中、已接受、已拒绝、已废弃、已被替代”这类明确值。

背景

背景描述需要解决的问题、业务目标和无法改变的约束。不要在背景中提前宣布方案。

决策驱动因素

驱动因素是团队比较方案时使用的标准，例如 JDK 支持周期、框架兼容性、迁移窗口和运维能力。尽量写成可衡量条件。

备选方案

记录认真考虑过的方案，包括“保持现状”。每个方案写出收益、代价、风险和退出路径。

决定

用一句话写清选择，再列出关键理由。不要写“经过讨论决定使用某技术”，这没有保存任何可复核信息。

后果

后果同时包含正面和负面影响。负面后果不是文档缺陷，而是团队必须管理的成本。

阅读一个完整示例

ADR-0001：选择 Java 版本基线查看下载比较 Java 17、 21 和 25，并选择 Java 21 作为学习工程的最低基线。

这个示例没有声称 Java 21 对所有组织都最佳。它明确限定了教学工程的兼容性、虚拟线程需求和迁移范围，并设置了 重新评估条件。

让 ADR 进入决策流程

ADR 的价值来自使用方式，不来自模板本身。按下面流程让决定可以被讨论和验证。

1. 在实现前创建“提议中”ADR，并指定决策负责人。
2. 链接支持结论的实验、容量模型、安全评估和官方文档。
3. 邀请受影响模块、运维、安全和业务代表评审。
4. 记录未解决异议，不要用“大家同意”覆盖分歧。
5. 决定后更新状态、日期、负责人和实施计划。
6. 在代码、部署配置或服务目录中链接 ADR。
7. 到达重新评估条件时，新建 ADR 替代旧决定。

决策负责人对形成明确结论负责，但不意味着可以忽略受影响团队。负责人要确保意见被记录、证据得到检查，并在 截止时间内做出选择。

避免四种失效方式

识别常见失效方式，可以让 ADR 保持短小和可信。

• 事后补理由：实现完成后才编写 ADR，容易把结果包装成唯一正确选项。
• 只写优点：没有负面后果的选型文档通常没有完成真实比较。
• 永不更新状态：已经废弃的决定仍显示“已接受”，会误导新成员。
• 记录所有小事：低成本决定过多会淹没真正重要的架构约束。

完成阶段验收

为你当前项目选择一个仍有争议的重要决定，使用模板创建 ADR。它至少应包含两个备选方案、一项可验证证据、一个 负面后果和一个重新评估条件。

请一名没有参加原讨论的同事阅读。如果对方能回答问题是什么、为何这样选、要承担什么成本以及何时重审，这份 ADR 就完成了基本目标。

下一步

回到Java 架构师完整学习路线与博客目录，进入 01.Java基础，开始构建第一个可测试的 Java 项目。