什么是 Architecture Decision Records (ADRs)？
Architecture Decision Records (ADRs) 是捕获重要架构决策及其上下文、后果和理由的文档。每个 ADR 记录一个重要的设计选择——如采用微服务架构、选择云提供商或选择技术栈——确保关键知识在团队成员变化和系统演变时持续存在。ADRs 为维护跨时间的一致、可维护架构提供技术基础。
作为拥有数十年设计大规模系统经验的资深软件架构师，我发现记录架构决策是项目中最关键的活动之一。经过多年演变的复杂系统如果不理解关键设计选择背后的理由，就无法得到适当维护。这就是 Architecture Decision Records 或 ADRs 发挥作用的地方。
ADR 是捕获重要架构决策及其上下文和后果的文档。例如，我们可能有一个关于采用微服务架构、选择特定云提供商或选择重写遗留子系统的 ADR。目标是明确阐述重大架构决策的动机、考虑的替代方案和影响。
我建议每个架构师为他们的系统维护一个 ADR 集合，与代码库一起存储，并随着新决策的制定而不断更新。每个 ADR 应包括简洁的标题、状态（提议的、接受的、弃用的等）、决策出现的上下文、实际做出的决策，以及任何重要的影响或值得注意的额外细节。链接到相关的 ADRs 也有助于理解相互依赖的选择。
ADRs 的主要好处是它们提供了一个技术记录，在团队成员来来去去时跨时间持续存在。没有适当的文档，重要的上下文会丢失，先前的决策会一遍又一遍地重新讨论。新工程师通过查阅 ADR 集合可以更快地了解系统设计。当遇到令人困惑或次优的代码时，追溯回原始 ADR 有助于解释情况。ADR 集合还通过揭示先前考虑的约束和权衡来帮助未来的决策。
从流程的角度来看，我建议在架构会议上定期审查 ADRs，并要求技术负责人对有影响的决策签字。可以创建轻量级 ADRs 来探索潜在想法，而更持久的 ADRs 捕获未来的承诺。版本控制允许跟踪变更，并有助于向利益相关者传达这些变更。还有一些新兴工具促进 ADR 管理作为内部开发者门户的一部分。
本质上，ADRs 实现了对于一致和可维护架构至关重要的结构化思维和外部文档。随着系统和组织的扩展，架构知识保留在个人头脑中变得不可行。我鼓励所有软件团队采用架构决策记录的实践，以确保其关键系统的长期健康。如果你有任何其他问题，请告诉我！
Frequently Asked Questions
ADR 中应该包括什么？
每个 ADR 应包括简洁的标题、状态（提议的、接受的、弃用的、被取代的）、决策出现的上下文、实际做出的决策，以及重要的影响或后果。此外，包括考虑的替代方案、评估的权衡，以及链接到相关的 ADRs 以显示相互依赖性。目标是不仅捕获决定了什么，还包括为什么决定以及它对系统有什么影响。
ADR 应该多详细？
ADRs 应该足够详细以捕获基本上下文和推理，但要简洁到可以快速阅读。大多数有效的 ADRs 范围在 200-500 字。重点是捕获”为什么”而不是详尽的技术文档。可以为探索性想法创建轻量级 ADRs，而更持久的 ADRs 捕获承诺的决策。适当的详细程度在彻底性和可维护性之间取得平衡。
我什么时候应该创建 ADR？
每当做出将影响系统结构、行为或演变的重大架构决策时，创建 ADR。这包括技术选择、架构模式、系统边界、数据建模方法和集成策略。不是每个决策都需要 ADR——专注于难以逆转、具有广泛影响，或没有上下文会让未来开发者困惑的决策。
ADRs 应该存储在哪里？
ADRs 应该与你的代码库一起存储在版本控制中，通常在专用的 /docs/adr/ 目录中。这确保它们与系统一起演变并仍然对开发者可访问。使用 markdown 格式保持它们简单和可版本控制。一些团队使用与内部开发者门户集成的专用 ADR 工具，但 git 中的纯 markdown 文件通常就足够了，并且更普遍可访问。
ADRs 与其他文档有何不同？
ADRs 与技术规范、需求文档和设计文档的不同之处在于它们的焦点。规范描述构建什么，需求描述所需能力，设计文档描述详细实现。ADRs 专门捕获这些元素背后的架构决策——关于系统结构、技术选择和设计模式的选择，指导如何通过详细设计实现需求。
ADR 的状态生命周期是什么？
ADRs 通常经历状态：Proposed（正在考虑）、Accepted（决策已做出并实施）、Deprecated（决策不再推荐但仍在使用），以及 Superseded（被新决策取代，链接到替换 ADR）。这个生命周期帮助团队跟踪哪些决策是当前的，哪些是历史的，以及架构思维如何随时间演变。
ADRs 如何帮助团队入职？
ADRs 通过为新工程师提供对系统背后架构理由的即时洞察，极大地加速入职。新团队成员不必想知道”他们为什么这样构建它？“，可以查阅 ADR 集合以理解决策背后的上下文、约束和权衡。这减少了困惑，防止重新讨论已定的决策，并帮助新贡献者在既定的架构模式中更有效地工作。
About the Author
Vinci Rufus 是一位拥有数十年设计大规模系统经验的软件架构师和作家。他撰写关于软件架构最佳实践、新兴开发范式，以及使团队能够构建可维护系统的文档实践。他的工作专注于在不断演变的代码库中进行架构决策和知识管理的实用方法。