作者：倪新明

ADR是一種性價(jià)比非常高的架構(gòu)決策文檔化實(shí)踐，團(tuán)隊(duì)引入和實(shí)踐成本很低，卻能為團(tuán)隊(duì)帶來極大收益！

1 團(tuán)隊(duì)研發(fā)面臨的問題

不論是在傳統(tǒng)的IT行業(yè)，還是互聯(lián)網(wǎng)行業(yè)，研發(fā)團(tuán)隊(duì)在架構(gòu)決策層面或多或少的都會(huì)面臨以下問題或挑戰(zhàn)：

• 新成員加入團(tuán)隊(duì)，對(duì)系統(tǒng)現(xiàn)有的架構(gòu)決策可能會(huì)盲目遵守，只知其然，不知其所以然；或者挑戰(zhàn)或違反約束，持續(xù)挑戰(zhàn)當(dāng)前決策，“質(zhì)疑”決策的合理性和正確性，負(fù)責(zé)人需要不間斷的解釋、同步、推動(dòng)達(dá)成共識(shí)
• 架構(gòu)決策的潛在問題隨著時(shí)間推移暴露，但，如果決策時(shí)進(jìn)行充分分析這些問題可能會(huì)提前發(fā)現(xiàn)和規(guī)避
• 現(xiàn)有系統(tǒng)架構(gòu)決策是如何演進(jìn)？當(dāng)前決策背后的動(dòng)機(jī)是什么？有可能團(tuán)隊(duì)內(nèi)已經(jīng)沒有人能準(zhǔn)確的回答
• 相似架構(gòu)決策場景在系統(tǒng)中重復(fù)出現(xiàn)，由于遺忘決策原因，或團(tuán)隊(duì)成員變化等因素，仍要花時(shí)間去分析、設(shè)計(jì)和推動(dòng)干系人達(dá)成共識(shí)
• 團(tuán)隊(duì)內(nèi)只有少部分人負(fù)責(zé)架構(gòu)設(shè)計(jì)，其他團(tuán)隊(duì)成員無機(jī)會(huì)參與，但實(shí)際上團(tuán)隊(duì)成員有相應(yīng)訴求，至少能夠了解某項(xiàng)關(guān)鍵架構(gòu)設(shè)計(jì)的決策過程?即使團(tuán)隊(duì)內(nèi)部接手的項(xiàng)目，你能快速獲取系統(tǒng)關(guān)鍵架構(gòu)決策及其原因嗎？你可能會(huì)從代碼庫中尋找架構(gòu)決策的蛛絲馬跡，但很難獲取架構(gòu)決策背后的動(dòng)機(jī)以及決策的演進(jìn)過程

基于以上這些問題，我們想：

• 通過最小但依然高效的方式記錄系統(tǒng)的架構(gòu)決策
• 能夠識(shí)別系統(tǒng)關(guān)鍵決策的演進(jìn)過程
• 架構(gòu)決策以及設(shè)計(jì)最佳實(shí)踐能夠在團(tuán)隊(duì)間高效同步
• 團(tuán)隊(duì)成員都有機(jī)會(huì)參與到架構(gòu)設(shè)計(jì)決策過程中
• 通過文檔形式記錄架構(gòu)決策首當(dāng)其沖的問題是：文檔過期??！

確實(shí)，過期問題是文檔化必然面臨的問題。無論通過什么機(jī)制，比如強(qiáng)流程、自動(dòng)化更新等都存在過期風(fēng)險(xiǎn)。那為什么還要選擇記錄架構(gòu)決策呢?基于以下兩個(gè)原因：

• 性價(jià)比：架構(gòu)決策文檔化的收益遠(yuǎn)大于維護(hù)過期帶來的成本
• 輕量級(jí)：保持ADR的簡短、輕量，規(guī)模越小的文檔越容易保持與實(shí)際的同步。

2 ADR剖析

Architecture Decision Record，縮寫ADR，即架構(gòu)決策記錄，該實(shí)踐最先由Michael Nygard發(fā)起，是記錄架構(gòu)決策最有效的方式之一。簡單來說，ADR是一種對(duì)架構(gòu)決策的文檔化記錄，其目的是通過文檔化的形式記錄系統(tǒng)的架構(gòu)決策、原因以及決策過程。

通過對(duì)系統(tǒng)架構(gòu)決策進(jìn)行有效記錄，團(tuán)隊(duì)可以從以下幾個(gè)層面獲得收益：

• 新人引導(dǎo)，便于快速熟悉系統(tǒng)新的團(tuán)隊(duì)成員可以快速獲取系統(tǒng)的歷史架構(gòu)決策，理解決策背后的背景、決策過程以及相關(guān)影響
• 項(xiàng)目交接，對(duì)已有決策進(jìn)行文檔化積累敏捷環(huán)境強(qiáng)調(diào)團(tuán)隊(duì)對(duì)知識(shí)的快速學(xué)習(xí)，基于ADRs團(tuán)隊(duì)可以快速熟悉已有系統(tǒng)的架構(gòu)演進(jìn)過程
• 對(duì)齊認(rèn)知通過推動(dòng)落地ADRs，團(tuán)隊(duì)成員更容易對(duì)設(shè)計(jì)最佳實(shí)踐達(dá)成一致認(rèn)識(shí)和理解，進(jìn)一步避免后續(xù)建設(shè)過程中的“重復(fù)造輪子”，提升設(shè)計(jì)知識(shí)在團(tuán)隊(duì)間復(fù)用

建議的ADR的基本結(jié)構(gòu)包括標(biāo)題、狀態(tài)、背景、決策、影響共五個(gè)部分，一般情況下，推薦增加一致性和備注兩個(gè)極具價(jià)值的額外章節(jié)作為補(bǔ)充。

需要說明的是，團(tuán)隊(duì)可以按需增加其他章節(jié)以增強(qiáng)ADR的表現(xiàn)能力，比如增加可選方案章節(jié)對(duì)可選方案進(jìn)行詳細(xì)描述。

??

標(biāo)題【必選】

ADR的 “標(biāo)題” 部分主要包括兩部分，其一是順序編號(hào)，其二是對(duì)架構(gòu)決策的簡短描述。標(biāo)題的描述需要確保對(duì)架構(gòu)決策進(jìn)行準(zhǔn)確描述、清晰無歧義，同時(shí)，也要保持簡短明了。

例如：ADR 01. 訂單服務(wù)和履約服務(wù)之間采用異步消息機(jī)制

狀態(tài)【必選】

ADR的 "狀態(tài)" 限定為 待審核 , 審核通過，被取代 三種狀態(tài)之一。

• 待審核：決策必須被高級(jí)別決策者或ARB審核
• 審核通過：架構(gòu)決策已經(jīng)被審核，并已準(zhǔn)備就緒進(jìn)行實(shí)現(xiàn)
• 被取代：架構(gòu)決策已發(fā)生變更，并被另一個(gè)ADR取代。該狀態(tài)表明，之前的ADR一定是被審核通過的，處于提議狀態(tài)未審核通過的ADR是不允許流向該狀態(tài)。處于提議狀態(tài)的ADR只能持續(xù)修改直到審核通過。被取代狀態(tài)提供了一種有效的架構(gòu)決策追溯機(jī)制，能夠幫助團(tuán)隊(duì)識(shí)別架構(gòu)決策的演進(jìn)過程。

背景【必選】

推動(dòng)架構(gòu)師對(duì)此項(xiàng)架構(gòu)決策的具體背景或問題進(jìn)行描述，以及簡潔扼要地表述可能的可選方案。決策背景在一定程度上也是對(duì)系統(tǒng)架構(gòu)的一種描述。

說明：不建議在此章節(jié)進(jìn)行詳細(xì)的替代方案分析和說明，如果確實(shí)需要進(jìn)行詳細(xì)闡述，則建議增加額外的章節(jié)進(jìn)行說明。

可選方案【可選】

對(duì)可選的替代方案進(jìn)行詳細(xì)描述，對(duì)比不同方案的優(yōu)劣勢

決策【必選】

該部分包含了具體的架構(gòu)決策以及相應(yīng)的決策依據(jù)，原則上要使用肯定式、命令式的描述方式表述具體的架構(gòu)決策，不要存在主觀的、消極的、模棱兩可的、可能存在歧義的措辭。說明：關(guān)注Why 而非 How，理解架構(gòu)決策的原因比理解怎么實(shí)現(xiàn)更加重要

影響【必選】

該部分描述此項(xiàng)架構(gòu)決策的整體影響。每項(xiàng)決策都會(huì)或多或少的對(duì)現(xiàn)有系統(tǒng)產(chǎn)生影響，包括好的影響和壞的影響，通過該章節(jié)推動(dòng)架構(gòu)師思考這些影響是否超過架構(gòu)決策的收益。

一致性【可選】

該部分并不是標(biāo)準(zhǔn)ADR元素，但同樣頗具價(jià)值，其作用在于推動(dòng)架構(gòu)師從架構(gòu)一致性的視角思考所作架構(gòu)決策如何進(jìn)行度量和治理。架構(gòu)師必須確定該項(xiàng)架構(gòu)決策的一致性保證是通過人工方式還是通過自動(dòng)化方式實(shí)現(xiàn)。如果可以通過自動(dòng)化方式進(jìn)行，則在該章節(jié)明確說明自動(dòng)化的執(zhí)行方案。

備注【必選】

備注部分并不是標(biāo)準(zhǔn)ADR的結(jié)構(gòu)，但是強(qiáng)烈推薦增加該章節(jié)。備注部分主要包含的ADR的各種元數(shù)據(jù)，例如：

原作者、審核日期、審核人、替代日期、最后修改日期、修改人、最后修改內(nèi)容

說明：有些團(tuán)隊(duì)認(rèn)為備注部分的元數(shù)據(jù)信息沒有太大價(jià)值，特別是，當(dāng)團(tuán)隊(duì)將ADRs與代碼一同存儲(chǔ)在配置庫時(shí)(并不推薦該種存儲(chǔ)方式)。但實(shí)際上，將元信息作為ADR的一部分比依賴配置庫更具價(jià)值和優(yōu)勢。

3 ADR的組織和存儲(chǔ)

ADR文檔具體存放在什么位置，比如FTP服務(wù)器、WIKI或者同項(xiàng)目代碼配置庫，不同的團(tuán)隊(duì)可以根據(jù)情況進(jìn)行靈活選擇。原則：ADR能夠被干系人便捷地獲取。

方式一：基于類似Git的配置庫存儲(chǔ)

優(yōu)點(diǎn)：

?架構(gòu)決策離代碼很近，方便研發(fā)人員獲取

?通過配置庫的版本管理能力輕松的實(shí)現(xiàn)ADR的變更管理

缺點(diǎn)：

ADR的干系人不僅僅是研發(fā)人員，還有技術(shù)經(jīng)理、產(chǎn)品經(jīng)理、業(yè)務(wù)人員等其他角色的項(xiàng)目干系人?；谔夹g(shù)性的配置庫進(jìn)行存儲(chǔ)，顯然對(duì)除研發(fā)以外的角色不太友好。同時(shí)，還需要對(duì)非研發(fā)人員開通倉庫權(quán)限，代碼安全性也是須要考慮的因素。另外，基于配置庫存儲(chǔ)不太方便存放同一系統(tǒng)不同應(yīng)用下通用的架構(gòu)決策以及應(yīng)用間的集成架構(gòu)決策。

方式二：類似WIKI的在線協(xié)同編輯共享系統(tǒng)內(nèi)

優(yōu)點(diǎn)：干系人友好在線協(xié)作方便處理跨應(yīng)用的架構(gòu)決策

缺點(diǎn)：開發(fā)人員不友好，離開發(fā)庫較遠(yuǎn)

基于對(duì)跨應(yīng)用架構(gòu)決策的存儲(chǔ)，團(tuán)隊(duì)選擇將ADR存儲(chǔ)在在線協(xié)同文檔平臺(tái)，并通過合理的文件夾結(jié)構(gòu)進(jìn)行組織，參考以下組織形式：

??

4 ADR融入研發(fā)流程

如果要落地ADR，則須要將其融入到現(xiàn)有的研發(fā)過程中。ADR涵蓋的流程活動(dòng)主要是：

??

制定ADR

• 活動(dòng)名稱：制定架構(gòu)決策記錄(ADRs)
• 前置要求：無
• 干系人職責(zé)： 子系統(tǒng)負(fù)責(zé)人負(fù)責(zé)制定子系統(tǒng)作用域內(nèi)的ADR，系統(tǒng)架構(gòu)師負(fù)責(zé)跨系統(tǒng)架構(gòu)決策制定
• 活動(dòng)輸入：PRD活動(dòng)輸出：《架構(gòu)決策記錄》
• 執(zhí)行形式：線下，或非正式的頭腦風(fēng)暴
• 執(zhí)行時(shí)間：屬于系統(tǒng)設(shè)計(jì)的一個(gè)子活動(dòng)，在系統(tǒng)設(shè)計(jì)階段進(jìn)行
• 評(píng)審ADR

活動(dòng)名稱：評(píng)審ADR

• 活動(dòng)目的：評(píng)審ADR的完整性和正確性，確保架構(gòu)決策的合理性
• 前置要求：已完成ADR制定
• 干系人職責(zé)：ADR指定人發(fā)起評(píng)審，系統(tǒng)架構(gòu)師及核心研發(fā)參與評(píng)審活動(dòng)
• 活動(dòng)輸入：ADRs
• 活動(dòng)輸出：ADR評(píng)審記錄（在ADR文檔上更新評(píng)審信息）
• 執(zhí)行形式：正式或非正式的評(píng)審會(huì)
• 執(zhí)行時(shí)間：技術(shù)方案內(nèi)部評(píng)審時(shí)，對(duì)該方案相關(guān)的ADR進(jìn)行評(píng)審

5 ADR實(shí)踐過程中的常見疑問

問題一：寫ADR的 “時(shí)間成本較高” ，延長了技術(shù)方案設(shè)計(jì)周期 ?

答：否！

該疑問可能主要來自于以下幾個(gè)原因：

• 寫文檔 = 費(fèi)時(shí)間？大多數(shù)研發(fā)人員排斥文檔，且沒有寫文檔的習(xí)慣。
• 對(duì)ADR模板理解不夠深入和準(zhǔn)確，撰寫過程中無從下手
• 決策缺少必要的分析習(xí)慣，對(duì)架構(gòu)決策缺少必要的對(duì)比、分析，在撰寫ADR時(shí)，缺少必要的依據(jù)，不得不額外查找資料，所以寫的“很慢”

但實(shí)際上，如果作為架構(gòu)決策者具備決策分析的習(xí)慣，特別是在技術(shù)方案設(shè)計(jì)時(shí)，進(jìn)行過充分的決策分析，1-2頁的ADR文檔撰寫不會(huì)超過 1 個(gè)小時(shí)，甚至在半個(gè)小時(shí)內(nèi)完成。即使制定和評(píng)審ADR影響了一小部分設(shè)計(jì)時(shí)間，通過對(duì)關(guān)鍵決策的充分分析和審重決策所帶來的價(jià)值遠(yuǎn)勝過返工造成額外成本

問題二：遺留系統(tǒng)沒有必要再寫ADR ？

答：否！

價(jià)值是決定是否寫ADR的因素之一，切忌ADR只對(duì)當(dāng)前架構(gòu)決策進(jìn)行記錄。對(duì)于遺留系統(tǒng)，在團(tuán)隊(duì)遺忘之前，記錄其關(guān)鍵架構(gòu)決策依然具有較大價(jià)值。

問題三：ADR這種文檔化機(jī)制與敏捷沖突 ？

答：否！

敏捷宣言中指出：可以工作的軟件勝過面面俱到的文檔。其強(qiáng)調(diào)左側(cè)更有價(jià)值，但不否定右側(cè)的價(jià)值。

因此，文檔化并不一定與敏捷理念發(fā)生沖突。通過采用輕量級(jí)的文檔機(jī)制，記錄具有核心價(jià)值的東西，確保文檔機(jī)制不會(huì)成為團(tuán)隊(duì)負(fù)擔(dān)，本身與敏捷文化相互契合。

問題四：ADR評(píng)審是不是流程太重 ？

答：可能，但是有必要！

ADR評(píng)審是引入ADR機(jī)制的重要活動(dòng)之一，不可忽略！正是通過多干系人參與下的評(píng)審活動(dòng)，才能產(chǎn)生ADR的諸多重要價(jià)值。通過這種正式或非正式的評(píng)審活動(dòng)：

• 提升架構(gòu)決策的合理性和正確性
• 提升團(tuán)隊(duì)的技術(shù)氛圍
• 提升團(tuán)隊(duì)成員的技術(shù)思考能力、技術(shù)水平、架構(gòu)決策的參與感，實(shí)現(xiàn)架構(gòu)決策在團(tuán)隊(duì)成員間的高效同步......

因此，ADR的評(píng)審活動(dòng)是必要的，從效率考慮，團(tuán)隊(duì)可以優(yōu)化評(píng)審過程。

問題五：ADR模板很多，團(tuán)隊(duì)?wèi)?yīng)該如何選擇？

答：沒有標(biāo)準(zhǔn)的，只有最適合的 ！

ADR沒有統(tǒng)一的模板，選擇適合團(tuán)隊(duì)的，建議：

模板保持輕量，不要試圖覆蓋所有的場景，否則，ADR會(huì)成為團(tuán)隊(duì)成員的負(fù)擔(dān)

更重要的是，ADR模板和模板元素的含義一定要在團(tuán)隊(duì)成員間達(dá)成一致

問題六：什么時(shí)候需要寫ADR沒有量化條件，所以很難落地？

答：否！

原則上：對(duì)系統(tǒng)產(chǎn)生顯著影響的架構(gòu)決策需要寫ADR。

如何定義 "顯著影響" 沒有量化指標(biāo)，但如果存在以下場景可能是需要寫ADR的信號(hào)：

• 直接影響高優(yōu)先級(jí)的架構(gòu)屬性
• 修改對(duì)外接口：對(duì)外提供的接口修改往往需要進(jìn)行充分影響分析
• 引入或者移除依賴：依賴的加入和移除往往標(biāo)示著組件能力的引進(jìn)和廢棄
• 改變系統(tǒng)的通用結(jié)構(gòu)：工程結(jié)構(gòu)是應(yīng)用架構(gòu)的重要維度之一
• 迫使研發(fā)人員改變開發(fā)方式接受戰(zhàn)略性技術(shù)債：重構(gòu)影響較大的技術(shù)債往往對(duì)現(xiàn)有系統(tǒng)會(huì)有較大影響

以上場景只是可能需要寫ADR的一些信號(hào)，但并不是強(qiáng)制約定。

是否需要寫ADR的終極實(shí)踐準(zhǔn)則是：具體情況，具體分析

6 ADR撰寫中的常見誤區(qū)

ADR的結(jié)構(gòu)雖然非常簡單，但團(tuán)隊(duì)在開始實(shí)踐過程時(shí)對(duì)于每個(gè)章節(jié)的內(nèi)容表述極易出現(xiàn)偏差，在撰寫ADR文檔時(shí)常見的問題如下：

【背景】部分

典型反例：

未直接說明推動(dòng)進(jìn)行決策的原因：正確的方式是要明確說明進(jìn)行此次架構(gòu)決策的背景或動(dòng)機(jī)是什么，明確 WHY對(duì)可選方案進(jìn)行詳細(xì)說明：ADR實(shí)踐初期，團(tuán)隊(duì)常犯的錯(cuò)誤式在 “背景” 部分對(duì)方案進(jìn)行詳細(xì)的大篇幅論述

【決策】部分

典型反例：

缺少?zèng)Q策依據(jù)說明：決策依據(jù)過于簡單，不充分，不能推到選擇當(dāng)前決策的論據(jù)決策結(jié)果表述措辭不夠明確、模棱兩可

【可選方案】部分

典型反例：分析角度存在明顯傾向性，不夠客觀

【一致性】部分

該章節(jié)的目的是推動(dòng)架構(gòu)師對(duì)如何確保決策被團(tuán)隊(duì)遵守進(jìn)行深入思考，特別是考慮是否可以通過自動(dòng)化方式進(jìn)行。典型的反例詞匯是：系統(tǒng)落地、開發(fā)實(shí)現(xiàn)......

如果不能不同自動(dòng)化方式進(jìn)行檢查，可能 設(shè)計(jì)評(píng)審、同行代碼評(píng)審、專家代碼評(píng)審是可能的方式如果可以通過自動(dòng)化方式進(jìn)行，則要說明如何進(jìn)行自動(dòng)化方式進(jìn)行約束校驗(yàn)。例如，如果工程實(shí)踐通過Archunit進(jìn)行單測，則可以表述基于Archunit的規(guī)則代碼。

7結(jié)語

ADR不僅僅是一份文檔，團(tuán)隊(duì)將獲得以下收益：

• 系統(tǒng)關(guān)鍵決策知識(shí)留存有助于新團(tuán)隊(duì)成員快速融入，知其然也知其所以然
• 提升團(tuán)隊(duì)技術(shù)氛圍提升團(tuán)隊(duì)技術(shù)思考力和技術(shù)能力，同步最佳實(shí)踐
• 提升架構(gòu)決策的合理性和正確性
• 管理技術(shù)債的能力
• 更高效的架構(gòu)決策溝通機(jī)制
• 減少重復(fù)性的決策討論和分析
• 架構(gòu)決策一致性推動(dòng)系統(tǒng)架構(gòu)約束自動(dòng)化檢查?