作者：倪新明

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