架构决策记录 (ADR)

架构决策记录 (ADR) 是一份文档，记录了重要的架构决策及其上下文和后果。

内容:

什么是架构决策记录?
如何开始使用 ADR
如何使用工具开始使用 ADR
如何使用 git 开始使用 ADR
ADR 的文件名约定
编写优秀 ADR 的建议
ADR 示例模板
ADR 的团队合作建议
更多信息

模板:

示例:

更多语言的翻译

什么是架构决策记录?

架构决策记录 (ADR) 是一份文档，记录了重要的架构决策及其上下文和后果。

架构决策 (AD) 是一个解决重要需求的软件设计选择。

架构决策日志 (ADL) 是为特定项目(或组织)创建和维护的所有 ADR 的集合。

架构上重要的需求 (ASR) 是对软件系统架构有可衡量影响的需求。

所有这些都属于架构知识管理 (AKM) 的范畴。

本文档的目标是提供 ADR 的快速概览，如何创建它们，以及在哪里查找更多信息。

缩写:

AD: 架构决策
ADL: 架构决策日志
ADR: 架构决策记录
AKM: 架构知识管理
ASR: 架构上重要的需求

如何开始使用 ADR

要开始使用 ADR，请与您的团队成员讨论以下方面。

决策识别:

AD 有多紧急和重要?
必须现在做出决定，还是可以等到了解更多信息后再决定?
个人和集体经验，以及公认的设计方法和实践，都可以帮助进行决策识别。
理想情况下，维护一个决策待办事项列表，作为产品待办事项列表的补充。

决策制定:

存在许多决策制定技术，既有一般性的，也有特定于软件架构的，例如对话映射。
群体决策是一个活跃的研究课题。

决策实施和执行:

AD 用于软件设计；因此必须与资助、开发和运营系统的利益相关者进行沟通并获得他们的接受。
架构明显的编码风格和关注架构问题和决策的代码审查是两种相关的做法。
在软件演进中现代化软件系统时，也必须(重新)考虑 AD。

决策共享(可选):

许多 AD 在项目之间重复出现。
因此，当采用明确的知识管理策略时，过去决策的经验，无论好坏，都可能成为有价值的可重用资产。

决策文档:

存在许多决策捕获的模板和工具。
参见敏捷社区，例如 M. Nygard 的 ADR。
参见传统软件工程和架构设计流程，例如 IBM UMF 和 CapitalOne 的 Tyree 和 Akerman 建议的表格布局。

更多信息:

上述步骤改编自维基百科上的架构决策条目

如何使用工具开始使用 ADR

您可以按照自己的意愿开始使用带工具的 ADR。

例如:

如果您喜欢使用 Google Drive 和在线编辑，那么您可以创建一个 Google 文档或 Google 表格。
如果您喜欢使用源代码版本控制，如 git，那么您可以为每个 ADR 创建一个文件。
如果您喜欢使用项目规划工具，如 Atlassian Jira，那么您可以使用该工具的规划跟踪器。
如果您喜欢使用 wiki，如 MediaWiki，那么您可以创建一个 ADR wiki。

如何使用 git 开始使用 ADR

如果您喜欢使用 git 版本控制，那么以下是我们如何为典型的带有源代码的软件项目开始使用 git 的 ADR。

创建 ADR 文件的目录:

$ mkdir adr

为每个 ADR 创建一个文本文件，例如 database.txt:

$ vi database.txt

在 ADR 中写任何您想写的内容。参考本仓库中的模板获取想法。

将 ADR 提交到您的 git 仓库。

ADR 的文件名约定

如果您选择使用典型的文本文件创建 ADR，那么您可能想要制定自己的 ADR 文件名约定。

我们更喜欢使用具有特定格式的文件名约定。

示例:

choose-database.md
format-timestamps.md
manage-passwords.md
handle-exceptions.md

我们的文件名约定:

名称使用现在时祈使动词短语。这有助于可读性，并与我们的提交消息格式相匹配。
名称使用小写字母和破折号(与本仓库相同)。这是可读性和系统可用性的平衡。
扩展名是 markdown。这对于轻松格式化很有用。

编写优秀 ADR 的建议

优秀 ADR 的特征:

理由:解释做出特定 AD 的原因。这可以包括上下文(见下文)、各种潜在选择的利弊、功能比较、成本/收益讨论等。
具体:每个 ADR 应该只涉及一个 AD，而不是多个 AD。
时间戳:标识 ADR 中每个项目的编写时间。这对于可能随时间变化的方面尤为重要，如成本、时间表、扩展等。
不可变:不要更改 ADR 中的现有信息。相反，通过添加新信息来修改 ADR，或通过创建新的 ADR 来取代它。

ADR 中优秀"上下文"部分的特征:

解释您组织的情况和业务优先事项。
根据您团队的社会构成和技能组成，包含理由和考虑因素。
包含相关的利弊,并用符合您需求和目标的术语描述它们。

ADR中良好的"结果"部分的特征:

解释做出决定后会发生什么。这可以包括影响、结果、输出、后续行动等。
包含任何后续ADR的信息。一个ADR触发更多ADR需求是比较常见的,比如当一个ADR做出一个大的总体选择时,进而产生更多较小决策的需求。
包含任何事后审查流程。团队通常会在一个月后审查每个ADR,将ADR信息与实际情况进行比较,以便学习和成长。

新的ADR可能会取代先前的ADR:

当做出的AD取代或使先前的ADR无效时,应创建新的ADR

ADR示例模板

我们在网上收集的ADR示例模板:

ADR的团队合作建议

如果您正在考虑在团队中使用决策记录,以下是我们通过与多个团队合作学到的一些建议。

您有机会引导您的团队成员,通过一起讨论"为什么",而不是强制规定"什么"。例如,决策记录是团队思考更明智、沟通更好的一种方式;如果决策记录只是事后强制的文书工作要求,那就没有价值。

一些团队更喜欢使用"decisions"这个名称,而不是缩写"ADRs"。当一些团队使用"decisions"作为目录名时,就好像灯泡亮了,团队开始在目录中放入更多信息,如供应商决策、规划决策、调度决策等。所有这些类型的信息都可以使用相同的模板。我们假设人们用词("decisions")比用缩写("ADRs")学习更快,而且当去掉"record"一词时,人们更有动力写工作进展文档,此外一些开发人员和一些管理人员不喜欢"architecture"这个词。

理论上,不可变性是理想的。实践中,可变性对我们的团队更有效。我们在现有ADR中插入新信息,加上日期戳,并注明该信息是在决策之后到达的。这种方法会导致一个我们都可以更新的"活文档"。典型的更新是当我们通过新队友、新产品、我们使用的实际结果,或事后第三方变化(如供应商能力、定价计划、许可协议等)获得信息时。