[TOC] ## 什么是“设计决策记录”（Architectural Decision Records，ADRs） 设计决策记录 (ADRs) 是一种记录软件开发过程中关键设计决策及其背后原因的文档方法。它帮助团队捕捉在开发中做出的重要架构或设计选择，解释为什么选择了某种方案，以及在当时的情况下有哪些权衡。ADRs 通常以轻量级的文本文件形式存在，适合长期维护的项目和团队知识共享。 ## 为什么需要 ADRs？ 1. **清晰记录决策历史**： * 让团队成员理解过去的设计选择，特别是对新成员很重要。 * 避免重复讨论或错误。 2. **知识共享与上下文传递**： * 帮助团队在变更时了解为什么做出某个设计。 * 提供变更上下文，便于未来做调整。 3. **决策可追溯性**： * 随时间推移，团队可以回溯特定设计的原因和影响。 * 有助于审查时提供透明性。 4. **团队对齐**： * 通过记录和讨论 ADR，团队可以达成共识。 ## 什么是“设计决策记录”（Architectural Decision Records，ADRs）？ **设计决策记录 (ADRs)** 是一种记录软件开发过程中关键设计决策及其背后原因的文档方法。它帮助团队捕捉在开发中做出的重要架构或设计选择，解释为什么选择了某种方案，以及在当时的情况下有哪些权衡。ADRs 通常以轻量级的文本文件形式存在，适合长期维护的项目和团队知识共享。 ## 为什么需要 ADRs？ 1. **清晰记录决策历史**： * 让团队成员理解过去的设计选择，特别是对新成员很重要。 * 避免重复讨论或错误。 2. **知识共享与上下文传递**： * 帮助团队在变更时了解为什么做出某个设计。 * 提供变更上下文，便于未来做调整。 3. **决策可追溯性**： * 随时间推移，团队可以回溯特定设计的原因和影响。 * 有助于审查时提供透明性。 4. **团队对齐**： * 通过记录和讨论 ADR，团队可以达成共识。 ## ADR 的存储与管理 ### 版本控制： ADR 文件通常保存在代码仓库的 docs/adr 文件夹中，作为团队共享文档。 工具支持： 可以使用开源工具（如 adr-tools）自动生成 ADR 模板并进行管理。 命名规则： 文件名通常包含决策的序号和简短标题，例如：001-use-reactjs.md。 ## ADR 的典型结构 ADRs 通常基于 Michael Nygard 提出的模板结构，内容如下： 1. **标题**：决策的名称（简洁且描述性）。 2. **上下文**：问题背景及为什么需要做这个决策。 3. **决策**：做出的具体决定是什么。 4. **理由**：为什么选择这个解决方案（包括考虑的权衡点）。 5. **替代方案**：列出其他考虑过的方案以及为什么未被采纳。 6. **后果**：当前决策可能带来的影响，包括技术债务或未来需要变更的部分。 ## 适用场景 * **技术选型**：选择框架、语言、库、工具。 * **架构变更**：微服务拆分、数据库设计、API 策略。 * **性能优化**：权衡不同性能方案。 * **团队流程**：如是否采用代码审查流程、CI/CD 工具等。 ## 示例 ### 标题：选择 React.js 作为前端框架 上下文： 项目需要一个动态前端框架。 团队成员对现有技术栈（如 Vue.js 和 Angular）存在分歧。 项目要求有高性能和组件化能力，并且需要与现有的后端 API 无缝集成。 决策： 决定采用 React.js 作为项目的前端框架。 理由： React.js 是一个成熟且活跃的框架，拥有强大的社区支持。 团队中已有 60% 成员熟悉 React，可以快速上手。 React 的组件化设计适合项目需求，并且其虚拟 DOM 提供了高性能的 UI 渲染。 替代方案： Vue.js：容易学习，但团队中熟悉的人较少。 Angular：功能强大，但复杂度较高，学习成本较大。 后果： 短期内能提高开发效率，因为大部分开发者已经熟悉 React。 长期来看，需要密切关注 React 的版本升级和与后端的兼容性问题。