轻量级的架构决策记录机制

lsekfe

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进行评审