KNOWLEDGE NOTES阅读地图
8个主要章节
3张图片与图示
2组对照与手算表

先看案例与关系图,再把方法应用到自己的材料和记录。

章节速览8 节 · 展开选择

接手一个项目,往往不难找到“用了什么”,难的是回答“为什么当时这样选”。提交记录可能只写迁移完成,配置只显示当前工具;几个月后,原来的限制已经变化,团队却仍在沿用旧结论。

引用溯源帮助核对主张的出处,反例笔记帮助修订过强结论。本文再补一层:为一次重要选择保留当时的条件、替代方案与接受的代价。以下资料检索场景完全是教学案例,不是本站部署方案或实际性能报告。

记录的是一次选择,而不是工具说明书

架构决策记录通常简称ADR。它适合记录会影响接口、依赖、系统结构或质量要求的选择。不要为每次变量改名创建一份记录,也不要把整个系统设计压进一篇巨型文档。

Michael Nygard的原始文章提出用短记录保存重要决策及其背景;本文沿用“上下文、决策、状态、后果”的骨架,加入教学用的候选比较和复核触发条件。后两项是本文的写作建议,并非所有ADR模板必须包含的字段。

工具手册解释操作方式,实验报告保存测量方法和结果,ADR解释为什么在给定条件下选择某条路径。三者可以互相链接。把测试日志全部复制进ADR,会让决策理由淹没;只写“性能好,所以采用”,又无法回查这个判断究竟依据什么。

先拆开事实、假设和偏好

设一个教学团队要为一批资料提供检索。题设要求断网时仍可查询,首版只有一个编辑者,资料更新可以随安装包发布。团队比较本地索引与远程检索服务。

记录项 本例中的内容 应如何处理
硬约束 断网仍能完成规定查询 不满足就不能作为唯一查询路径
当前事实 首版只有一个编辑者 写清观察范围,不推广到未来
工作假设 可接受随安装包更新资料 应由需求方确认,而非开发者代猜
偏好 希望减少运行服务的维护工作 可以权衡,不能伪装成硬约束
未知项 后续是否需要权限分组 保留待确认项与负责人

“业务永远不会多人编辑”不是当前事实;“以后可能需要多人编辑”也不是立即部署复杂服务的充分理由。好的上下文会把这两种不确定性都留下,让读者知道选择依赖什么。

先检查断网查询硬约束,再比较维护代价,最后列出尚未验证的假设
约束先筛选,偏好再比较

三个区域表示推理层次,不是量化评分;远程服务若另有本地后备,应作为不同的完整候选方案重新比较。

查看原图

比较完整方案,别给工具随意打总分

本地索引方案需要把检索数据带到设备上,并解决更新与版本对应;远程服务方案需要可用的连接,并负责服务端运行。这里比较的是这些完整安排,不是把两个产品名放在表头后凭印象评分。

候选 断网查询 数据更新安排 本例的主要代价
本地索引随包分发 满足题设路径 发布新包 包体与更新流程需要管理
仅远程查询 不满足硬约束 服务端更新 离线时没有查询路径
远程加本地后备 需验证后备覆盖 两条更新路径 需要定义版本差异与回退行为

在这个题设中,“仅远程查询”不能靠其他偏好的高分抵消离线失败;混合方案也不能因为有本地副本就自动视为满足。它必须说明副本覆盖哪些资料、多久更新,以及离线时的用户承诺。

本文不提供通用评分权重,因为权重本身就是团队目标的表达。如果确实使用评分,应同时保存原始指标、单位、权重来源与敏感性分析。几个含义不同的序数分数直接求和,常会制造没有证据支持的精确感。

一份填写完整的教学记录

ADR-001:首版采用随安装包分发的本地索引。状态:已接受。 以下身份与流程同样是假设设定,不代表真实团队审批。

上下文: 首版需离线查询,只有一个资料编辑者;资料可随版本发布,但这个更新节奏仍需在验收前由需求负责人确认。当前没有跨设备即时同步要求,也没有得到权限分组的正式需求。

决策: 首版在设备上查询随包分发的索引。资料版本与应用发布记录关联。新增资料先经过内容审核,再进入下一次发布;查询界面应能让用户找到资料版本。

理由: 该路径直接覆盖题设中的离线要求,并避免首版同时维护在线与离线两条检索路径。团队接受更新不是即时到达的代价。这是当前需求下的取舍,不是关于本地检索始终优于远程服务的判断。

后果: 发布流程增加索引生成与版本检查;设备上的旧包会保留旧资料;如果资料涉及敏感权限,分发副本的访问边界必须另行评估。以上是需要落实或验证的责任,不是写进记录就已经获得的能力。

验证与复核: 验收应在断网环境使用规定查询集检查结果及资料版本;负责人确认资料更新节奏。若出现即时更新、多编辑者并发或权限隔离的新需求,重新比较完整方案。复核触发不等于自动切换方案,结论仍需证据。

条件变化后,用新记录替代旧理由

AWS的ADR流程说明采用接受后保留记录、通过新ADR建立替代关系的方式。本文据此区分:讨论中的提案可以修订;已经接受的实质性选择发生变化时,用新记录说明变化,而不是把旧文改成“我们从一开始就计划如此”。

假设后来正式增加跨设备即时更新要求。ADR-002可以重新比较远程查询加离线后备,但它还必须定义离线副本的权限与更新承诺。ADR-002仍在讨论时,ADR-001继续是当前已接受的选择。只有新选择被接受并明确替代范围,才把旧记录标成被替代,并链接新记录。若仅替代更新方式,不能让读者误以为离线承诺也被撤销。

状态关系用于阅读历史,并不执行系统切换。实际迁移可能尚未开始,也可能按阶段进行;应链接任务和验收记录,避免用文档状态冒充运行状态。

三种常见误写及其修订

“选择方案甲,因为它最好”应改成“在离线约束与当前更新节奏下选择甲,并接受发布延迟”。前一句缺少比较对象与成立范围,后一句才让未来读者知道应复核什么。

“方案乙没有缺点”应改成列出尚未测量的风险与验证方法。没有发现风险与已经证伪风险不是同一回事;没有出现事故,也不足以证明最初假设正确。

“负责人批准,所以技术方案正确”混淆了治理与证据。负责人可以接受已知代价,但批准不能替代性能、权限或正确性验证。相反,一次测试通过,也不能代替团队对成本与责任的选择。

用两个问题检查自己的记录

新提案已经写完,旧记录是否立即变成“被替代”?

不能。提案尚未被接受时,旧选择仍可能有效。应记录提案状态、评审结果和替代范围,再建立明确关系;实现与上线进度另行说明。

离线要求取消,是否已经证明应该采用远程服务?

没有。只说明原先排除“仅远程查询”的一个理由不再成立。仍需比较更新、成本、权限和可靠性等当前条件,不能把约束解除当成另一方案的充分证明。

可以先为手头一个反复争论的选择写一页记录:留下问题、约束、完整候选、当前决定、接受的代价,以及下一次复核的信号。让另一位读者只看这页回答“条件怎样变会动摇结论”。回答不出时,优先补条件和理由,而不是添加更多形容词。

参考资料与使用边界

  1. Michael Nygard:Documenting Architecture Decisions,用于ADR结构与保留历史的来源说明;本文案例和候选比较为原创。
  2. AWS:Architectural decision record process,用于提案、评审、接受与替代过程的说明;这是特定指南的流程,不是所有组织必须遵守的统一标准。