架构决策记录ADR

架构决策记录 (ADR)

架构决策记录 (ADR) 是一种用于记录软件架构决策的实践方法。它旨在捕获重要的设计选择及其背后的理由，以便在项目演进过程中提供清晰的上下文和指导。

为什么使用 ADR？

• 知识共享： 帮助团队成员理解架构决策的背景和原因。
• 一致性： 确保架构决策得到一致的执行。
• 可追溯性： 方便追踪决策的演变过程，了解不同方案的权衡。
• 学习： 从过去的决策中吸取经验教训。

识别决策

在进行架构设计时，我们需要识别出需要做出决策的关键点。以下是一些指导原则：

• 关注重要性和紧急程度： 优先考虑对系统架构有重大影响，且需要尽快做出的决策。
• 评估信息完整性： 确定是否需要立即决策，或者可以等待获取更多信息后再做决定。
• 借鉴经验： 参考个人或团队的经验，以及业界公认的设计方法和实现。
• 维护决策清单： 创建并维护一个待办决策事项清单，确保所有关键决策都得到处理。

使用规范

以下是使用 ADR 的规范流程：

1. 识别决策并撰写 ADR 文档

• 发起人职责： 识别需要进行架构决策的问题，并主动承担起草 ADR 文档的责任。
• 文档内容： 按照预定义的 ADR 模板，清晰、完整地记录决策的背景、问题、备选方案、最终选择、以及相关的影响和后果。

2. 发起评审会讨论

• 组织评审： 将 ADR 文档提交给相关团队成员或架构评审委员会进行评审。
• 收集反馈： 在评审会议上，充分听取各方意见，收集反馈和建议。
• 迭代改进： 根据评审结果，对 ADR 文档进行必要的修改和完善。

3. 做出决策并维护到项目

• 明确决策结果： 在充分讨论和权衡后，明确最终的架构决策。
• 记录决策： 将最终决策结果更新到 ADR 文档中。
• 实施决策： 将决策应用到实际的项目开发中。
• 持续维护： 随着项目的演进，定期审查和更新 ADR，确保其与实际情况保持一致。

3.1 创建目录

在项目根目录下创建以下目录（所有文档维护再docs目录）：

/docs/adr
-> 0001-xxx-decision.md
-> 0002-yyy-decision.md

3.2 创建文件

请将模版保存为 adr-template.md

格式

{编码}-{决策内容}.md

编码规则

前两位为分类，后两位根据决策时间先后从0自增。

• 0xxx：业务相关
• 1xxx：
• 2xxx：编码相关（编程语言、编码风格、代码格式化、日志、注释规范等）
• 3xxx：中间件相关（SOA、微服务、dubbo、分布式锁）
• 5xxx：前端相关
• 6xxx：安全相关
• 7xxx：测试相关
• 8xxx：部署与基础设施相关
  • 80xx：计算相关（云平台）
  • 81xx：存储相关（数据库、缓存、队列、zk等）
  • 82xx：通讯相关（网络等）
• 9xxx：文档相关（格式、模版等）

模版

# 概览 Summary

*   参与决策人：
*   时间：yyyy-MM-dd

## 问题 Issue

> 描述要解决什么问题以及为什么是现在这个时间点来解决这个问题

例如：
> 我们需要选择一种新的身份验证方法。我们当前的系统使用基于密码的身份验证，这容易受到攻击。我们需要一种更安全的方法来保护用户帐户。

## 决策 Decision

> 最终选择了哪个备选方案，其后果/代价是什么

例如：
> 我们决定使用多因素身份验证 (MFA)。MFA 通过要求用户提供多种身份验证因素来增加安全性。此决策的后果是用户需要设置 MFA，并且登录过程会稍微复杂一些。

## 状态 Status

> 草稿/待评审/已通过，可以根据你所在组织的架构决策流程来定义

例如：
> 已通过

# 上下文 Context

## 假设 Assumptions

> 描述在做出决策时带着什么假设，由于各种原因在决策当时，尚无法验证

例如：
> 我们假设所有用户都拥有智能手机或平板电脑，可用于接收 MFA 代码。

## 约束 Constraints

> 描述在解决该问题时有什么限制条件，例如预算/时间线/资源

例如：
> 我们需要在三个月内实施 MFA。我们有一个专门用于此项目的工程师。

## 备选方案 Positions

> 一组备选方案，如果有人总是问“你们有没有考虑过这种方案”，那么这里是回应的好地方。每个备选方案除了方案本身的描述外，还应该说明如果选择了该方案会有什么后果/代价

例如：
> *   **基于密码的身份验证：** 这是我们当前的系统。它易受攻击。
> *   **多因素身份验证 (MFA)：** 这是一种更安全的身份验证方法。它需要用户提供多种身份验证因素。
> *   **生物识别身份验证：** 这是一种非常安全的身份验证方法。它使用生物识别数据（例如指纹或面部扫描）来验证用户。但是，它也可能很昂贵且难以实施。

## 论点 Argument

> 

例如：
> 我们选择 MFA 是因为它是一种安全且相对容易实施的身份验证方法。

## 影响 Implications

> 列举采用该决策后带来的影响，比如需要大家学习。

例如：
> *   用户需要设置 MFA。
> *   登录过程会稍微复杂一些。
> *   我们需要培训用户如何使用 MFA。

# 相关的 Related

## 相关的决策 Related decisions

> 列举相关的架构决策，它们也有助于帮助读者理解决策推导过程

例如：
> *   选择身份验证方法
> *   选择授权方法

## 相关的要求 Related requirements

> 列举对相关工具、人员的要求

例如：
> *   需要 MFA 身份验证服务器。
> *   需要一位工程师来实施 MFA。

## 相关的工件 Related artifacts

例如：
> *   MFA 实施计划
> *   MFA 用户指南

## 相关的架构原则 Related principles

> 列举相关的架构原则，它们也有助于帮助读者理解决策推导过程

例如：
> *   安全第一
> *   用户体验至上

# 记录 Notes

参考文献

• 来自 Cognitect 的《记录架构决策》（DOCUMENTING ARCHITECTURE DECISIONS）
• 来自 BetterProgramming 的《一款简单而强大的工具来记录你的架构决策》（A Simple but Powerful Tool to Record Your Architectural Decisions）——他们称之为 LADR（Lightweight ADR，轻量级 ADR），但是我们使用的格式类似。
• 《软件架构基础》（Fundamentals of Software Architecture）一书也有一个关于架构决策记录的好章节。