作者：倪新明

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之旅吧！