架构决策记录 从当时的取舍到可追溯的替代历史
先看案例与关系图,再把方法应用到自己的材料和记录。
章节速览8 节 · 展开选择
接手一个项目,往往不难找到“用了什么”,难的是回答“为什么当时这样选”。提交记录可能只写迁移完成,配置只显示当前工具;几个月后,原来的限制已经变化,团队却仍在沿用旧结论。
引用溯源帮助核对主张的出处,反例笔记帮助修订过强结论。本文再补一层:为一次重要选择保留当时的条件、替代方案与接受的代价。以下资料检索场景完全是教学案例,不是本站部署方案或实际性能报告。
记录的是一次选择,而不是工具说明书
架构决策记录通常简称ADR。它适合记录会影响接口、依赖、系统结构或质量要求的选择。不要为每次变量改名创建一份记录,也不要把整个系统设计压进一篇巨型文档。
Michael Nygard的原始文章提出用短记录保存重要决策及其背景;本文沿用“上下文、决策、状态、后果”的骨架,加入教学用的候选比较和复核触发条件。后两项是本文的写作建议,并非所有ADR模板必须包含的字段。
工具手册解释操作方式,实验报告保存测量方法和结果,ADR解释为什么在给定条件下选择某条路径。三者可以互相链接。把测试日志全部复制进ADR,会让决策理由淹没;只写“性能好,所以采用”,又无法回查这个判断究竟依据什么。
先拆开事实、假设和偏好
设一个教学团队要为一批资料提供检索。题设要求断网时仍可查询,首版只有一个编辑者,资料更新可以随安装包发布。团队比较本地索引与远程检索服务。
| 记录项 | 本例中的内容 | 应如何处理 |
|---|---|---|
| 硬约束 | 断网仍能完成规定查询 | 不满足就不能作为唯一查询路径 |
| 当前事实 | 首版只有一个编辑者 | 写清观察范围,不推广到未来 |
| 工作假设 | 可接受随安装包更新资料 | 应由需求方确认,而非开发者代猜 |
| 偏好 | 希望减少运行服务的维护工作 | 可以权衡,不能伪装成硬约束 |
| 未知项 | 后续是否需要权限分组 | 保留待确认项与负责人 |
“业务永远不会多人编辑”不是当前事实;“以后可能需要多人编辑”也不是立即部署复杂服务的充分理由。好的上下文会把这两种不确定性都留下,让读者知道选择依赖什么。
三个区域表示推理层次,不是量化评分;远程服务若另有本地后备,应作为不同的完整候选方案重新比较。
查看原图比较完整方案,别给工具随意打总分
本地索引方案需要把检索数据带到设备上,并解决更新与版本对应;远程服务方案需要可用的连接,并负责服务端运行。这里比较的是这些完整安排,不是把两个产品名放在表头后凭印象评分。
| 候选 | 断网查询 | 数据更新安排 | 本例的主要代价 |
|---|---|---|---|
| 本地索引随包分发 | 满足题设路径 | 发布新包 | 包体与更新流程需要管理 |
| 仅远程查询 | 不满足硬约束 | 服务端更新 | 离线时没有查询路径 |
| 远程加本地后备 | 需验证后备覆盖 | 两条更新路径 | 需要定义版本差异与回退行为 |
在这个题设中,“仅远程查询”不能靠其他偏好的高分抵消离线失败;混合方案也不能因为有本地副本就自动视为满足。它必须说明副本覆盖哪些资料、多久更新,以及离线时的用户承诺。
本文不提供通用评分权重,因为权重本身就是团队目标的表达。如果确实使用评分,应同时保存原始指标、单位、权重来源与敏感性分析。几个含义不同的序数分数直接求和,常会制造没有证据支持的精确感。
一份填写完整的教学记录
ADR-001:首版采用随安装包分发的本地索引。状态:已接受。 以下身份与流程同样是假设设定,不代表真实团队审批。
上下文: 首版需离线查询,只有一个资料编辑者;资料可随版本发布,但这个更新节奏仍需在验收前由需求负责人确认。当前没有跨设备即时同步要求,也没有得到权限分组的正式需求。
决策: 首版在设备上查询随包分发的索引。资料版本与应用发布记录关联。新增资料先经过内容审核,再进入下一次发布;查询界面应能让用户找到资料版本。
理由: 该路径直接覆盖题设中的离线要求,并避免首版同时维护在线与离线两条检索路径。团队接受更新不是即时到达的代价。这是当前需求下的取舍,不是关于本地检索始终优于远程服务的判断。
后果: 发布流程增加索引生成与版本检查;设备上的旧包会保留旧资料;如果资料涉及敏感权限,分发副本的访问边界必须另行评估。以上是需要落实或验证的责任,不是写进记录就已经获得的能力。
验证与复核: 验收应在断网环境使用规定查询集检查结果及资料版本;负责人确认资料更新节奏。若出现即时更新、多编辑者并发或权限隔离的新需求,重新比较完整方案。复核触发不等于自动切换方案,结论仍需证据。
条件变化后,用新记录替代旧理由
AWS的ADR流程说明采用接受后保留记录、通过新ADR建立替代关系的方式。本文据此区分:讨论中的提案可以修订;已经接受的实质性选择发生变化时,用新记录说明变化,而不是把旧文改成“我们从一开始就计划如此”。
假设后来正式增加跨设备即时更新要求。ADR-002可以重新比较远程查询加离线后备,但它还必须定义离线副本的权限与更新承诺。ADR-002仍在讨论时,ADR-001继续是当前已接受的选择。只有新选择被接受并明确替代范围,才把旧记录标成被替代,并链接新记录。若仅替代更新方式,不能让读者误以为离线承诺也被撤销。
flowchart TD
A[新条件出现] --> B[创建新提案]
B --> C{完成评审}
C -->|尚未接受| D[保留当前决策]
C -->|接受| E[明确替代范围]
E --> F[双向链接新旧记录]
状态关系用于阅读历史,并不执行系统切换。实际迁移可能尚未开始,也可能按阶段进行;应链接任务和验收记录,避免用文档状态冒充运行状态。
flowchart TD
A[团队接受选择] --> B[记录决策状态]
A --> C[安排实现任务]
C --> D[执行验收]
D --> E[记录运行状态]
B --> F[回查当时理由]
E --> F
三种常见误写及其修订
“选择方案甲,因为它最好”应改成“在离线约束与当前更新节奏下选择甲,并接受发布延迟”。前一句缺少比较对象与成立范围,后一句才让未来读者知道应复核什么。
“方案乙没有缺点”应改成列出尚未测量的风险与验证方法。没有发现风险与已经证伪风险不是同一回事;没有出现事故,也不足以证明最初假设正确。
“负责人批准,所以技术方案正确”混淆了治理与证据。负责人可以接受已知代价,但批准不能替代性能、权限或正确性验证。相反,一次测试通过,也不能代替团队对成本与责任的选择。
用两个问题检查自己的记录
新提案已经写完,旧记录是否立即变成“被替代”?
不能。提案尚未被接受时,旧选择仍可能有效。应记录提案状态、评审结果和替代范围,再建立明确关系;实现与上线进度另行说明。
离线要求取消,是否已经证明应该采用远程服务?
没有。只说明原先排除“仅远程查询”的一个理由不再成立。仍需比较更新、成本、权限和可靠性等当前条件,不能把约束解除当成另一方案的充分证明。
可以先为手头一个反复争论的选择写一页记录:留下问题、约束、完整候选、当前决定、接受的代价,以及下一次复核的信号。让另一位读者只看这页回答“条件怎样变会动摇结论”。回答不出时,优先补条件和理由,而不是添加更多形容词。
参考资料与使用边界
- Michael Nygard:Documenting Architecture Decisions,用于ADR结构与保留历史的来源说明;本文案例和候选比较为原创。
- AWS:Architectural decision record process,用于提案、评审、接受与替代过程的说明;这是特定指南的流程,不是所有组织必须遵守的统一标准。