作者：倪新明ADR是一种性价比非常高的架构决策记录实践。团队引进和实践的成本很低，却能给团队带来很大的收益！1研发团队面临的问题无论在传统IT行业还是互联网行业，研发团队在架构决策层面或多或少都会面临以下问题或挑战：系统的架构决策可能会受到影响。盲从，只知道是什么，不知道为什么；或挑战或违反约束，不断挑战当前决策，“质疑”决策的合理性和正确性，负责人需要不断解释、同步、推动共识架构的决策潜在问题随着时间的推移会暴露出来，但是，如果在决策时进行充分分析，这些问题可能会被发现并提前规避现有系统架构决策如何演变？当前决定背后的动机是什么？很可能团队中没有人能给出准确的答案。类似的架构决策场景在系统中反复出现。由于忘记决策原因或团队成员变动等因素，仍然需要花时间分析、设计和推动利益相关者达成共识。一小部分人负责架构设计，其他团队成员没有机会参与，但实际上团队成员有相应的诉求，至少能了解一个关键架构设计的决策过程，即使团队拿在项目内部，你可以快速获得系统的关键架构决策，为什么？你可以从代码库中寻找架构决策的蛛丝马迹，但很难获得架构决策背后的动机和决策的演进过程。基于以上问题，我们希望：以最小但仍然有效的方式记录系统的架构决策，以识别系统关键决策的演进过程架构决策和设计最佳实践可以在团队之间高效同步团队成员拥有参与架构设计决策过程的机会以文档的形式记录架构决策第一个问题是：文档过期！！确实，过期问题是文档无法避免的问题。无论采用何种机制，如强流程、自动更新等，都存在过期风险。那为什么选择记录架构决策呢？基于以下两个原因：高性价比：记录架构决策的好处远大于维护到期的成本轻量级：保持ADR简短轻量级，文档越小越好容易与现实保持同步。2ADRAnalysisArchitectureDecisionRecord，简称ADR，即架构决策记录。这种做法首先由MichaelNygard发起，是记录架构决策的最有效方式之一。简而言之，ADR是架构决策的书面记录。其目的是以文件化的形式记录系统的架构决策、原因和决策过程。通过有效记录系统架构决策，团队可以从以下几个方面受益：新人引导，有利于快速熟悉系统新团队成员可以快速获取系统的历史架构决策，了解决策背后的背景，决策-制定流程和相关影响项目移交、记录和积累现有决策。敏捷环境强调团队对知识的快速学习。基于ADR，团队可以快速熟悉现有系统架构的演进过程。对齐认知通过推动ADR的实施，团队成员更容易在设计最佳实践上达成共识和理解，进一步避免后续施工过程中的“重新发明轮子”，提高设计知识并在团队间复用在这种情况下，建议增加两个有价值的额外章节Consistency和Remarks，作为补充。需要注意的是，团队可以根据需要增加其他章节来提升ADR的性能，比如增加options的章节，对options进行详细的描述。Title【必填】ADR的“Title”部分主要包括两部分，一个是序列号，另一个是架构决策的简短描述。标题的描述需要保证对架构决策的描述准确、清晰、不含糊，同时要简短明了。例如：ADR01。订单服务和履行服务之间使用异步消息机制。Status【必填】ADR的“状态”仅限于pendingreview、approved、replaced三种状态之一。待定：该决定必须由高级决策者或ARB审查。已批准：体系结构决策已经过审查并准备好实施已取代：体系结构决策已更改并被另一个ADR取代。该状态表示之前的ADR一定已经获得批准，未获得批准的拟议状态的ADR不允许流向该状态。处于拟议状态的ADR只能继续修改，直到获得批准。被取代状态为架构决策提供了一个有效的追溯机制，可以帮助团队识别架构决策的演变。背景【必填】促使架构师描述本次架构决策的具体背景或问题，并简要表达可能的备选方案。决策背景在一定程度上也是对系统架构的描述。说明：本章不建议对备选方案进行详细的分析和描述。如果确实需要详细阐述，建议另加章节进行说明。备选方案[可选]详细描述备选方案，并比较不同方案的优缺点。决策[必填]这部分包含具体的架构决策和相应的决策依据。原则上，应该使用肯定式和命令式，以描述性的方式表达具体的架构决策，不使用主观的、否定的、模棱两可的、有潜在歧义的术语。解释：关注为什么而不是如何。理解架构决策的原因比理解如何实现它们更重要。[必需]本节描述此架构决策的总体影响。每个决策都会对现有系统产生或多或少的影响，包括好的影响和坏的影响。通过本章，我们鼓励架构师思考这些影响是否超过了架构决策的好处。一致性[可选]这部分不是标准的ADR要素，但也很有价值。它的作用是促使架构师从架构一致性的角度思考如何衡量和管理架构决策。架构师必须确定此架构决策的一致性保证是手动实现还是通过自动化实现。如果可以自动化完成，则在本节中明确说明自动化执行方案。备注[必填]备注部分不是标准的ADR结构，但强烈建议添加此部分。remark部分主要包含ADR的各种元数据，如：原作者、审稿日期、审稿人、替换日期、最后修改日期、修改人、最后修改说明：有团队认为remark部分的元数据信息不会太大值，尤其是当团队将ADR与代码一起存储在配置存储库中时（不推荐）。但实际上，将元信息作为ADR的一部分比依赖配置库具有更多的价值和优势。3ADR的组织和存储ADR文档存放在哪里，比如FTP服务器，WIKI或者同一个项目代码配置库，不同的团队可以根据情况灵活选择。原则：利益相关者可以很容易地获得ADR。方式一：基于类Git的配置库存储优点：架构决策非常贴近代码，方便研发人员获取ADR变更管理很容易通过配置库的版本管理能力实现缺点：利益相关者ADR不仅是研发人员，还有技术经理、产品经理、业务人员等其他角色的项目干系人。基于过于技术化的配置仓库存储，显然对研发以外的角色并不友好。同时，也需要为非研发人员开放仓库权限，代码安全也是需要考虑的因素。另外，基于配置库存储，不方便存储同一系统不同应用下的公共架构决策，以及应用之间集成的架构决策。方法二：在系统内进行类似WIKI的在线协同编辑和分享。优点：利益相关者是友好的。在线协作便于处理跨应用架构决策。缺点：开发者不友好，离开发库较远。基于跨应用架构的存储决策，团队选择将ADR存储在在线协作文档平台上，并通过合理的文件夹结构进行组织。参考以下组织形式：4ADR融入研发流程如果要实施ADR，必须将其整合到现有的研发流程中。ADR涵盖的过程活动主要有：ADR的开发活动名称：架构决策记录（ADRs）的开发先决条件：无涉众责任：子系统的负责人负责制定子系统范围内的ADR，系统架构师负责跨系统架构决策活动输入：PRD活动输出：《架构决策记录》执行形式：线下，或非正式头脑风暴执行时间：属于系统设计的一个子活动，在系统设计阶段ADR活动名称：审核ADR活动目的：审核ADR的完整性和正确性，确保架构决策的合理性ADR审核记录（更新ADR文件审核信息）执行形式：正式或非正式审核会议执行时间：期间技术方案内部审核，审核与方案相关的ADR5ADR实践过程中的常见问题问题一：写ADR的“时间成本高”延长了技术方案设计周期？答：不！这个疑问可能主要来自以下几个原因：写文档=耗时？大多数开发人员拒绝文档并且没有编写文档的习惯。对ADR模板的理解不够深入和准确，在编写过程中无法做出决策，缺乏必要的分析习惯，对架构决策缺乏必要的比较和分析，在编写时缺乏必要的依据写ADR，所以要搜索额外的资料，所以写了“Veryslow”但其实如果你作为架构决策者有决策分析的习惯，尤其是在技术方案的设计上，如果你进行了充分的决策分析，1-2页的ADR文档的编写不会超过1小时，甚至半小时就可以完成。即使开发和审查ADR只占用一小部分设计时间，对关键决策进行全面分析和审查所带来的价值也远远超过返工的额外成本。问题二：遗留系统有必要写ADR吗？答：不！Value是决定是否写ADR的因素之一，ADR不应该只记录当前的架构决策。对于遗留系统，在团队忘记关键架构决策之前记录它们仍然具有很大的价值。问题三：ADR的文档机制与敏捷有冲突吗？答：不！敏捷宣言指出：可工作的软件胜于全面的文档。它强调左侧更有价值，但并不否定右侧的价值。因此，文档并不一定与敏捷哲学相冲突。通过采用轻量级的文档机制来记录具有核心价值的事物，保证了文档机制不会成为团队的负担，并且与敏捷文化相兼容。问题四：ADR审核流程是否过于繁重？答：有可能，但有必要！ADR审核是引入ADR机制的重要活动之一，不容忽视！正是通过多方利益相关者的审查活动，才能产生ADR的许多重要价值。通过这样正式或非正式的评审活动：提高架构决策的合理性和正确性，改善团队的技术氛围，提高团队成员的技术思维能力、技术水平和参与架构决策的意识，实现架构决策-团队成员之间的交流。高效同步……因此，ADR审查活动必不可少。从效率的角度，团队可以优化审核流程。问题五：ADR模板很多，团队该如何选择？答：没有标准，只有最合适的！ADR没有统一的模板，选择适合团队的。建议：保持模板轻量化，不要试图覆盖所有场景，否则ADR会成为团队成员的负担。更重要的是，ADR模板和模板元素的含义必须是团队成员之间的共识问题6：什么时候需要写一个没有量化条件的ADR，执行起来有难度？答：不！原则上：对系统有重大影响的架构决策需要编写ADR。如何定义“重大影响”没有量化指标，但如果有以下场景，可能是需要写ADR的信号：直接影响高优先级架构属性，修改对外接口：外部提供接口修改引入或移除往往需要全影响分析依赖：依赖的添加和移除往往标志着组件能力的引入和放弃改变系统的总体结构：工程结构是应用架构的重要维度之一迫使开发者改变开发方法接受战略性技术债：重构影响较大技术债往往对现有系统的影响较大。以上场景只是一些可能需要写ADR的信号，但并不是强制性的约定。写不写ADR的最终实践标准是：具体情况，具体分析ADR写作中的6个常见错误ADR的结构虽然很简单，但是团队在开始写ADR的时候很容易偏离每章的内容表达实践过程。ADR文档中常见的问题如下：【背景】一些典型的反例：没有直接说明决策的原因：正确的做法是清楚地说明做出这个架构决策的背景或动机，并阐明替代方案的原因。详细说明：在ADR实践初期，团队经常在“背景”部分对方案进行详尽详尽的讨论而犯错误【决策】一些典型的反例：缺乏决策依据说明：决策依据过于简单不足，无法推向选择当前决策的论据和决策结果表述不清，含糊不清[选项]一些典型的反例：分析视角有明显的倾向性，不够客观[一致性]本章的目的是促进架构师对如何确保团队遵循决策进行深入思考，尤其是如果可以以自动化方式完成。典型的反例词是：系统落地、开发、实施……如果不能通过不同的自动化方式进行检查，也许设计审查、同行代码审查、专家代码审查是可能的方式。如果可以用自动化的方式完成，那么就必须说明Howtoperformconstraintverificationinaautomatedmanner.例如工程实践通过Archunit单测，就可以制定基于Archunit的规则代码。7结语ADR不仅仅是一份文件，团队将获得以下好处：系统中关键决策知识的保留将有助于新的团队成员快速融入，了解正在发生的事情和原因将改善团队的技术氛围并提高团队的技术思维和技术能力，同步最佳实践，提高架构决策的合理性和正确性管理技术债务的能力更高效的架构决策沟通机制减少重复的决策讨论和分析架构决策的一致性促进系统架构约束的自动化检查
