关于架构设计:轻量级的架构决策记录机制

作者：倪新明

ADR是一种性价比十分高的 架构决策文档化实际，团队引入和实际老本很低，却能为团队带来极大收益！

1 团队研发面临的问题

不论是在传统的 IT 行业，还是互联网行业，研发团队在架构决策层面或多或少的都会 面临以下问题或挑战：

•新成员退出团队，对系统现有的架构决策可能会 自觉恪守 ，只知其然，不知其所以然；或者 挑战或违反 束缚，继续挑战以后决策，“质疑”决策的合理性和正确性，负责人须要不间断的解释、同步、推动达成共识

•架构决策的潜在问题随着时间推移裸露，但，如果决策时进行充沛剖析这些问题可能会提前发现和躲避

•现有零碎架构决策是 如何演进 ？以后决策背地的 动机是什么？有可能团队内曾经没有人能精确的答复

•类似架构决策场景在零碎中 反复呈现，因为忘记决策起因，或团队成员变动等因素，仍要花工夫去剖析、设计和推动干系人达成共识

•团队内 只有少部分人负责架构设计 ，其余团队成员无机会参加，但实际上 团队成员有相应诉求，至多可能理解某项要害架构设计的决策过程

•即便团队外部接手的我的项目，你能疾速获取零碎要害架构决策及其起因吗？你可能会从代码库中寻找架构决策的蛛丝马迹，但很难获取架构决策背地的动机以及决策的演进过程

基于以上这些问题，咱们想：

•通过 最小但仍然高效 的形式记录零碎的架构决策

•可能 识别系统要害决策的演进过程

•架构决策以及设计最佳实际可能在团队间 高效同步

•团队成员都有机会参加到架构设计决策过程中

通过文档模式记录架构决策首当其冲的问题是：文档过期！！

的确，过期问题是文档化必然面临的问题。无论通过什么机制，比方强流程、自动化更新等都存在过期危险。那为什么还要抉择记录架构决策呢? 基于以下两个起因：

•性价比：架构决策文档化的收益远大于保护过期带来的老本

•轻量级 ：放弃 ADR 的简短、轻量， 规模越小的文档越容易放弃与理论的同步。

2 ADR 分析

Architecture Decision Record，缩写 ADR，即架构决策记录，该实际最先由 Michael Nygard 发动，是记录架构决策最无效的形式之一。简略来说，ADR 是一种对架构决策的文档化记录，其 目标是通过文档化的模式记录零碎的架构决策、起因以及决策过程。

通过对系统架构决策进行无效记录，团队能够从以下几个层面取得收益：

•新人疏导，便于疾速相熟零碎新的团队成员能够疾速获取零碎的历史架构决策，了解决策背地的背景、决策过程以及相干影响

•我的项目交接，对已有决策进行文档化积攒麻利环境强调团队对常识的疾速学习，基于 ADRs 团队能够疾速相熟已有零碎的架构演进过程

•对齐认知通过推动落地 ADRs，团队成员更容易对设计最佳实际达成统一意识和了解，进一步防止后续建设过程中的“反复造轮子”，晋升设计常识在团队间复用

倡议 的 ADR 的根本构造包含 题目、状态、背景、决策、影响 共五个局部，个别状况下，举荐减少 一致性和备注 两个极具价值的额定章节作为补充。

须要阐明的是，团队能够按需减少其余章节以加强 ADR 的体现能力，比方减少可选计划章节对可选计划进行详细描述。





题目【必选】

ADR 的“题目”局部次要包含两局部，其一是程序编号，其二是对架构决策的简短形容。题目的形容须要确保对架构决策进行精确形容、清晰无歧义，同时，也要 放弃简短明了。

例如：ADR 01. 订单服务和履约服务之间采纳异步音讯机制

状态【必选】

ADR 的 “ 状态 ” 限定为 待审核 , 审核通过，被取代 三种状态之一。

•待审核：决策必须被高级别决策者或 ARB 审核

•审核通过：架构决策曾经被审核，并已准备就绪进行实现

•被取代：架构决策已产生变更，并被另一个 ADR 取代。该状态表明，之前的 ADR 肯定是被审核通过的，处于提议状态未审核通过的 ADR 是不容许流向该状态。处于提议状态的 ADR 只能继续批改直到审核通过。被取代状态提供了一种无效的架构决策追溯机制，可能帮忙团队辨认架构决策的演进过程。

背景【必选】

推动架构师对此项 架构决策的具体背景或问题进行形容，以及简洁简要地表述可能的可选计划。决策背景在肯定水平上也是对系统架构的一种形容。

阐明：不倡议 在此章节进行具体的代替计划剖析和阐明，如果的确须要进行具体论述，则倡议减少额定的章节进行阐明。

可选计划【可选】

对可选的代替计划进行详细描述，比照不同计划的优劣势

决策【必选】

该局部蕴含了 具体的架构决策以及相应的决策依据，原则上要应用必定式、命令式的形容形式表述具体的架构决策，不要存在主观的、消极的、不置可否的、可能存在歧义的措辞。阐明：关注 Why 而非 How，了解架构决策的起因比了解怎么实现更加重要

影响【必选】

该局部形容此项架构决策的整体影响。每项决策都会或多或少的对现有零碎产生影响，包含好的影响和坏的影响 ，通过该章节推动架构师思考这些影响 是否超过架构决策的收益。

一致性【可选】

该局部并不是规范 ADR 元素，但同样颇具价值，其作用在于推动架构师从架构一致性的视角思考所作架构决策如何进行度量和治理 。 架构师必须确定该项架构决策的一致性保障是通过人工形式还是通过自动化形式实现。如果能够通过自动化形式进行，则在该章节明确阐明自动化的执行计划。

备注【必选】

备注局部并不是规范 ADR 的构造，然而强烈推荐减少该章节。备注局部次要蕴含的 ADR 的各种元数据，例如：

原作者、审核日期、审核人、代替日期、最初批改日期、批改人、最初批改内容

阐明：有些团队认为备注局部的元数据信息没有太大价值，特地是，当团队将 ADRs 与代码一起存储在配置库时 (并不举荐该种存储形式)。但实际上， 将元信息作为 ADR 的一部分比依赖配置库更具价值和劣势。

3 ADR 的组织和存储

ADR 文档具体寄存在什么地位，比方 FTP 服务器、WIKI 或者同我的项目代码配置库，不同的团队能够依据状况进行灵便抉择。准则：ADR 可能被干系人便捷地获取。

形式一：基于相似 Git 的配置库存储

长处：

•架构决策离代码很近，不便研发人员获取

•通过配置库的版本治理能力轻松的实现 ADR 的变更治理

毛病：

ADR 的干系人不仅仅是研发人员，还有技术经理、产品经理、业务人员等其余角色的我的项目干系人。基于太技术性的配置库进行存储，显然对除研发以外的角色不太敌对。同时，还须要对非研发人员开明仓库权限，代码安全性也是须要思考的因素。另外，基于配置库存储不太不便寄存同一零碎不同利用下通用的架构决策以及利用间的集成架构决策。

形式二：相似 WIKI 的在线协同编辑共享零碎内

长处：干系人敌对在线合作不便解决跨利用的架构决策

毛病：开发人员不敌对，来到发库较远

基于对跨利用架构决策的存储，团队抉择将 ADR 存储在在线协同文档平台，并通过正当的文件夹构造进行组织，参考以下组织模式：





4 ADR 融入研发流程

如果要落地 ADR，则须要将其融入到现有的研发过程中。ADR 涵盖的流程流动次要是：





制订 ADR

•流动名称：制订架构决策记录(ADRs)

•前置要求：无

•干系人职责：子系统负责人负责制订子系统作用域内的 ADR，零碎架构师负责跨零碎架构决策制定

•流动输出：PRD 流动输入：《架构决策记录》

•执行模式：线下，或非正式的头脑风暴

•执行工夫：属于零碎设计的一个子流动，在零碎设计阶段进行

评审 ADR

•流动名称：评审 ADR

•流动目标：评审 ADR 的完整性和正确性，确保架构决策的合理性

•前置要求：已实现 ADR 制订

•干系人职责：ADR 指定人发动评审，零碎架构师及外围研发参加评审流动

•流动输出：ADRs

•流动输入：ADR 评审记录（在 ADR 文档上更新评审信息）

•执行模式：正式或非正式的评审会

•执行工夫：技术计划外部评审时，对该计划相干的 ADR 进行评审

5 ADR 实际过程中的常见疑难

问题一：写 ADR 的“工夫老本较高”，缩短了技术方案设计周期 ?

答：否！

该疑难可能次要来自于以下几个起因：

•写文档 = 费时间？大多数研发人员排挤文档，且没有写文档的习惯。

•对 ADR 模板了解不够深刻和精确，撰写过程中无从下手

•决策短少必要的剖析习惯，对架构决策短少必要的比照、剖析，在撰写 ADR 时，短少必要的根据，不得不额定查找材料，所以写的“很慢”

但实际上，如果作为架构决策者具备决策分析的习惯，特地是在技术方案设计时，进行过充沛的决策分析，1- 2 页的 ADR 文档撰写不会超过 1 个小时，甚至在半个小时内实现。即便制订和评审 ADR 影响了一小部分设计工夫，通过对要害决策的充沛剖析和审重决策所带来的价值远胜过返工造成额定老本

问题二：遗留零碎没有必要再写 ADR？

答：否！

价值是决定是否写 ADR 的因素之一，切忌 ADR 只对以后架构决策进行记录。对于遗留零碎，在团队忘记之前，记录其要害架构决策仍然具备较大价值。

问题三：ADR 这种文档化机制与麻利抵触？

答：否！

麻利宣言中指出：能够工作的软件胜过八面玲珑的文档。其强调左侧更有价值，但不否定右侧的价值。

因而，文档化并不一定与麻利理念发生冲突 。 通过采纳轻量级的文档机制，记录具备外围价值的货色，确保文档机制不会成为团队累赘，自身与麻利文化互相符合。

问题四：ADR 评审是不是流程太重？

答：可能，然而有必要！

ADR 评审是引入 ADR 机制的重要流动之一，不可疏忽！正是通过多干系人参加下的评审流动，能力产生 ADR 的诸多重要价值。通过这种正式或非正式的评审流动：

•晋升架构决策的合理性和正确性

•晋升团队的技术气氛

•晋升团队成员的技术思考能力、技术水平、架构决策的参与感，实现架构决策在团队成员间的高效同步 ……

因而，ADR 的评审流动是必要的，从效率思考，团队能够优化评审过程。

问题五：ADR 模板很多，团队应该如何抉择？

答：没有规范的，只有最适宜的！

ADR 没有对立的模板，抉择适宜团队的，倡议：

模板放弃轻量，不要试图笼罩所有的场景，否则，ADR 会成为团队成员的累赘

更重要的是，ADR 模板和模板元素的含意肯定要在团队成员间达成统一

问题六：什么时候须要写 ADR 没有量化条件，所以很难落地？

答：否！

原则上：对系统产生显著影响的架构决策须要写 ADR。

如何定义 “ 显著影响 ” 没有量化指标，但如果存在以下场景可能是须要写 ADR 的信号：

•间接影响高优先级的架构属性

•批改对外接口：对外提供的接口批改往往须要进行充沛影响剖析

•引入或者移除依赖：依赖的退出和移除往往标示着组件能力的引进和废除

•扭转零碎的通用构造：工程构造是利用架构的重要维度之一

•迫使研发人员扭转开发方式承受战略性技术债：重构影响较大的技术债往往对现有零碎会有较大影响

以上场景只是可能须要写 ADR 的一些信号，但并不是强制约定。

是否须要写 ADR 的终极实际准则是：具体情况，具体分析

6 ADR 撰写中的常见误区

ADR 的构造尽管非常简单，但团队在开始实际过程时对于每个章节的内容表述极易呈现偏差，在撰写 ADR 文档时常见的问题如下：

【背景】局部

典型反例：

未间接阐明推动进行决策的起因：正确的形式是要明确阐明进行此次架构决策的背景或动机是什么，明确 WHY 对可选计划进行具体阐明：ADR 实际初期，团队常犯的谬误式在“背景”局部对计划进行具体的大篇幅阐述

【决策】局部

典型反例：

短少决策依据阐明：决策依据过于简略，不充沛，不能推到抉择以后决策的论据决策后果表述措辞不够明确、不置可否

【可选计划】局部

典型反例：剖析角度存在显著倾向性，不够主观

【一致性】局部

该章节的目标是 推动架构师对如何确保决策被团队恪守进行深刻思考，特地是思考是否能够通过自动化形式进行。典型的反例词汇是：零碎落地、开发实现 ……

如果不能不同自动化形式进行查看，可能 设计评审、同行代码评审、专家代码评审是可能的形式如果能够通过自动化形式进行，则要阐明如何进行自动化形式进行束缚校验。例如，如果工程实际通过 Archunit 进行单测，则能够表述基于 Archunit 的规定代码。

7 结语

ADR 不仅仅是一份文档，团队将取得以下收益：

•零碎要害决策常识留存有助于新团队成员疾速融入，知其然也知其所以然

•晋升团队技术气氛晋升团队技术思考力和技术能力，同步最佳实际

•晋升架构决策的 合理性和正确性

•治理技术债的能力

•更高效的 架构决策沟通机制

•缩小重复性的决策探讨和剖析

•架构决策一致性 推动零碎架构束缚自动化查看

开始 团队的 ADR 之旅吧！