作者：倪新明

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

(資料圖片僅供參考)

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

不論是在傳統(tǒng)的IT行業(yè)，還是互聯(lián)網(wǎng)行業(yè)，研發(fā)團(tuán)隊(duì)在架構(gòu)決策層面或多或少的都會(huì)面臨以下問(wèn)題或挑戰(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)決策的潛在問(wèn)題隨著時(shí)間推移暴露，但，如果決策時(shí)進(jìn)行充分分析這些問(wè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)沒(méi)有人能準(zhǔn)確的回答相似架構(gòu)決策場(chǎng)景在系統(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ì)成員無(wú)機(jī)會(huì)參與，但實(shí)際上團(tuán)隊(duì)成員有相應(yīng)訴求，至少能夠了解某項(xiàng)關(guān)鍵架構(gòu)設(shè)計(jì)的決策過(guò)程?即使團(tuán)隊(duì)內(nèi)部接手的項(xiàng)目，你能快速獲取系統(tǒng)關(guān)鍵架構(gòu)決策及其原因嗎？你可能會(huì)從代碼庫(kù)中尋找架構(gòu)決策的蛛絲馬跡，但很難獲取架構(gòu)決策背后的動(dòng)機(jī)以及決策的演進(jìn)過(guò)程

基于以上這些問(wèn)題，我們想：

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

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

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

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

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

新人引導(dǎo)，便于快速熟悉系統(tǒng)新的團(tuán)隊(duì)成員可以快速獲取系統(tǒng)的歷史架構(gòu)決策，理解決策背后的背景、決策過(guò)程以及相關(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)過(guò)程對(duì)齊認(rèn)知通過(guò)推動(dòng)落地ADRs，團(tuán)隊(duì)成員更容易對(duì)設(shè)計(jì)最佳實(shí)踐達(dá)成一致認(rèn)識(shí)和理解，進(jìn)一步避免后續(xù)建設(shè)過(guò)程中的“重復(fù)造輪子”，提升設(shè)計(jì)知識(shí)在團(tuán)隊(duì)間復(fù)用

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

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

??

標(biāo)題【必選】

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

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

狀態(tài)【必選】

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

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

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

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

可選方案【可選】

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

決策【必選】

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

影響【必選】

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

一致性【可選】

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

備注【必選】

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

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

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

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

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

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

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

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

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

缺點(diǎn)：

ADR的干系人不僅僅是研發(fā)人員，還有技術(shù)經(jīng)理、產(chǎn)品經(jīng)理、業(yè)務(wù)人員等其他角色的項(xiàng)目干系人?；谔夹g(shù)性的配置庫(kù)進(jìn)行存儲(chǔ)，顯然對(duì)除研發(fā)以外的角色不太友好。同時(shí)，還需要對(duì)非研發(fā)人員開(kāi)通倉(cāng)庫(kù)權(quán)限，代碼安全性也是須要考慮的因素。另外，基于配置庫(kù)存儲(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)：開(kāi)發(fā)人員不友好，離開(kāi)發(fā)庫(kù)較遠(yuǎn)

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

??

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

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

??

制定ADR活動(dòng)名稱：制定架構(gòu)決策記錄(ADRs)前置要求：無(wú)干系人職責(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í)踐過(guò)程中的常見(jiàn)疑問(wèn)問(wèn)題一：寫(xiě)ADR的 “時(shí)間成本較高” ，延長(zhǎng)了技術(shù)方案設(shè)計(jì)周期 ?

答：否！

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

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

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

問(wèn)題二：遺留系統(tǒng)沒(méi)有必要再寫(xiě)ADR ？

答：否！

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

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

答：否！

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

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

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

答：可能，但是有必要！

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

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

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

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

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

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

問(wèn)題六：什么時(shí)候需要寫(xiě)ADR沒(méi)有量化條件，所以很難落地？

答：否！

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

如何定義 "顯著影響" 沒(méi)有量化指標(biāo)，但如果存在以下場(chǎng)景可能是需要寫(xiě)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ā)人員改變開(kāi)發(fā)方式接受戰(zhàn)略性技術(shù)債：重構(gòu)影響較大的技術(shù)債往往對(duì)現(xiàn)有系統(tǒng)會(huì)有較大影響

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

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

6 ADR撰寫(xiě)中的常見(jiàn)誤區(qū)

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

【背景】部分

典型反例：

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

【決策】部分

典型反例：

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

【可選方案】部分

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

【一致性】部分

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

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

7結(jié)語(yǔ)

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)化檢查?

關(guān)鍵詞： 方式進(jìn)行 方案進(jìn)行 決策過(guò)程 技術(shù)方案