輕量級的架構決策記錄機制

作者：倪新明

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