架构决策记录（Architectural Decision Record）

如果你所在的团队是一个快速迭代的团队，正在不断进行新的产品尝试，你可能没有时间事无巨细的记录完整的技术文档。

但是对于一些重大和基础的架构调整决策，可以通过一种叫 “架构决策记录（ADR，Architectural Decision Record）” 的方式记录下来 —— 尤其是当你是团队中技术负责人的时候。

ADR 可以记录在代码仓库，或者单独的 Notion、Jira 中。一般 ADR 中会包含如下内容

• 决策名称
• 决策背景
• 决策考虑的影响因素
• 决策方案（多个）
• 决策比较
• 决策结果
• 后续影响记录，以及可能的反思（经验教训）

为什么需要记录架构变更

• 知识共享：使团队成员（包括开发人员、测试人员、运维人员等）理解为什么做出特定的架构决策。
• 决策追溯：在项目的生命周期中，能够追溯架构决策的演变。随着业务需求的变化或者技术环境的改变，可能需要回顾之前的决策。比如，当系统性能出现问题时，通过查看 ADR 可以了解到当初在数据库选型（如选择关系型数据库 MySQL 而不是 NoSQL 数据库 MongoDB）方面的考虑因素，进而评估是否需要对该决策进行调整。因为并不是所有的人都能在半年甚至一年后，记清楚当初做某个决策的原因。
• 自我提升：回顾曾经的决策和所带来的结果，我们会从中学到成功或者失败的经验。

什么样的变更适合被定义为 “重大架构调整”

• Structure（软件结构）：
  • 对于微服务等模式，若对微服务架构进行大规模调整可视为重大架构调整。
    例如，将一个功能复杂的大型微服务拆分成 5 个以上有明确业务边界的微服务，或者将多个关联紧密的微服务合并成一个以优化内部通信。同时，微服务间通信机制的重大变更，如从 RESTful API 改为 gRPC，也属于此类。这种结构的改变会对整个系统的运行和拓展产生深远影响。
• Non - functional requirements（非功能性需求）：
  • Security（安全性）：从简单的用户名密码认证改为多因素认证（如结合硬件令牌、生物识别技术），或者从仅在传输层加密升级到全链路加密等涉及安全机制的重大变化。这些调整关乎系统数据和用户信息的保护，一旦出现问题可能导致严重后果。
  • High availability（高可用性）：像从单数据中心部署改为多数据中心异地容灾部署，或者将服务器的冗余级别从 N + 1 提升到 2N 等。高可用性的调整直接影响系统在面对故障时的持续服务能力，对业务连续性至关重要。
  • Fault tolerance（容错能力）：从没有故障隔离机制到引入断路器模式、舱壁模式等复杂的容错设计，或者对关键组件的容错策略进行重大修改。容错能力的变化影响系统在异常情况下的稳定性和恢复能力。
• Dependencies（依赖项）：
  • 包括组件间的耦合关系、依赖的添加/删除/替换等。
    例如，原本 A 组件依赖 B 组件，现在调整为 B 组件依赖 A 组件这种逻辑依赖关系的重大变化。或者当引入新的、对整个系统运行逻辑有重大影响的中间件（如分布式事务协调中间件）时，都应算作重大调整。依赖关系的改变可能波及多个相关组件，影响系统的功能和稳定性。
• Interfaces（接口）：
  • APIs（应用程序编程接口）：API 的重大版本更新，如 API 的请求参数、响应格式、功能语义有大量改变（超过 50%的接口方法有修改）。这种变化会影响使用这些 API 的所有相关系统或模块的集成和功能实现。
  • Published contracts（已发布的协议）：从遵循 HTTP/1.1 协议改为 HTTP/3 协议，或者对自定义协议的消息格式、通信流程进行了重构等情况。协议的变更可能导致系统间通信的不兼容，需要各方进行相应调整。
• Construction techniques（构建技术）：
  • Libraries（库）：从使用传统的 ORM 库切换到新的基于数据映射模式的库，这种库的更换可能需要对数据访问层的代码进行大量修改。
  • Frameworks（框架）：如从使用传统的 MVC 框架转换到基于微前端架构的框架，框架的改变意味着整个应用的架构模式和开发方式都要随之改变。
  • Tools（工具）：从使用简单的构建工具（如 Makefile）升级到复杂的持续集成/持续部署（CI/CD）工具链，这不仅影响开发流程，还可能改变代码的部署和运维方式。
  • Processes（流程）：从瀑布式开发流程转变为敏捷开发流程与 DevOps 实践相结合的流程等。开发流程的改变会影响整个团队的协作模式、项目进度和质量管控。

此外，判断架构调整是否重大还可以从以下维度考虑：

• 对业务影响的程度：如果架构调整导致超过 30%的业务功能需要重新开发或调整，则可视为重大。
• 对系统性能的影响：若预计会导致系统响应时间增加或减少超过 50%。
• 对开发和运维成本的影响：若架构调整使开发周期延长超过一个月或者运维复杂度提升一个等级（可自行定义等级）等情况。这些维度综合起来可以帮助更全面地评估架构调整的性质。

补充

• 需要记录入 ADR 文档的决策，都需要进行集体 review 才能进行实施
  • 可以提出修改意见改进 ADR
  • 也可以拒绝 ADR 提议
• 一旦 ADR 被采用或者拒绝，将视其为不可更改的。如果想要做调整，需要提出新的 ADR

参考

• https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html
• https://dev.to/koladev/how-senior-software-engineers-document-their-project-1nf4