Architecture Decision RecordAWS 架构决策记录流程
架构决策记录(ADR)是一份文档,用于描述团队就其计划构建的软件架构的某个重要方面所做出的选择。每个 ADR 描述架构决策、其背景及其后果。ADR 具有状态,因此遵循一个生命周期。有关 ADR 的示例,请参阅附录。
ADR 流程会输出一组架构决策记录。这组记录构成决策日志。决策日志提供项目背景以及详细的实施和设计信息。项目成员浏览每个 ADR 的标题即可概览项目背景,阅读 ADR 则可深入了解项目的实施和设计选择。
团队接受某个 ADR 后,它就变为不可变。如果新的见解要求做出不同的决策,团队会提出新的 ADR。团队接受新的 ADR 后,它将取代之前的 ADR。
ADR 流程的范围
项目成员应为每一项影响软件项目或产品、具有架构意义的决策创建 ADR,包括以下方面(Richards 和 Ford 2020):
结构(例如微服务等模式)
非功能性需求(安全性、高可用性和容错性)
依赖关系(组件的耦合)
接口(API 和已发布的契约)
构建技术(库、框架、工具和流程)
功能性和非功能性需求是 ADR 流程最常见的输入。
ADR 的内容
当团队发现需要 ADR 时,一名团队成员会根据项目统一的模板开始撰写 ADR。(有关模板示例,请参阅 ADR GitHub 组织。)模板简化了 ADR 的创建,并确保 ADR 涵盖所有相关信息。每个 ADR 至少应定义决策的背景、决策本身,以及该决策对项目及其交付物的后果。(有关这些部分的示例,请参阅附录。)ADR 结构最强大的特点之一是,它关注决策的原因,而不是团队如何实施。理解团队为何做出该决策,会让其他团队成员更容易采纳它,并防止未参与决策过程的其他架构师在将来推翻该决策。
ADR 采纳流程
每位团队成员都可以创建 ADR,但团队应当确立 ADR 所有权的定义。作为 ADR 所有者的每位作者都应积极维护并传达 ADR 的内容。为明确这种所有权,本指南在以下各节中将 ADR 作者称为 ADR 所有者。其他团队成员始终可以为 ADR 做出贡献。如果在团队接受 ADR 之前其内容发生变化,所有者应批准这些变化。
团队识别出某项架构决策及其所有者后,ADR 所有者在流程开始时提交处于已提议(Proposed)状态的 ADR。处于已提议状态的 ADR 已准备好接受评审。
随后,ADR 所有者启动该 ADR 的评审流程。ADR 评审流程的目标是决定团队是接受该 ADR、认定其需要返工,还是拒绝该 ADR。包括所有者在内的项目团队对 ADR 进行评审。评审会议应以一段专门用于阅读 ADR 的时间开始。平均而言,10 到 15 分钟就足够了。在此期间,每位团队成员阅读文档,并添加评论和问题以标记不清楚的主题。评审阶段结束后,ADR 所有者逐条宣读并与团队讨论每条评论。
如果团队发现了可改进 ADR 的行动项,ADR 的状态保持为已提议。ADR 所有者拟定这些行动项,并与团队协作为每项行动指派负责人。每位团队成员都可以为行动项做出贡献并解决它们。重新安排评审流程是 ADR 所有者的责任。
团队也可以决定拒绝该 ADR。在这种情况下,ADR 所有者会补充拒绝的理由,以避免将来就同一主题再次讨论。所有者将 ADR 状态更改为已拒绝(Rejected)。
如果团队批准该 ADR,所有者会添加时间戳、版本和利益相关者列表。然后所有者将状态更新为已接受(Accepted)。
ADR 以及它们所形成的决策日志代表团队做出的决策,并提供所有决策的历史记录。团队在可能的情况下,将 ADR 用作代码评审和架构评审的参考。除了执行代码评审、设计任务和实施任务之外,团队成员还应查阅 ADR,了解产品的战略性决策。
作为一项良好实践,每项软件变更都应经过同行评审,并且至少需要一人批准。在代码评审期间,代码评审者可能会发现违反一个或多个 ADR 的变更。在这种情况下,评审者会要求代码变更的作者更新代码,并分享指向该 ADR 的链接。作者更新代码后,经同行评审者批准并合并到主代码库中。
ADR 评审流程
在团队接受或拒绝 ADR 之后,应将其视为不可变的文档。更改现有 ADR 需要创建新的 ADR,为新的 ADR 建立评审流程,并批准该 ADR。如果团队批准新的 ADR,所有者应将旧 ADR 的状态更改为已取代(Superseded)。