Architecture Decision RecordAWS 架構決策記錄流程
架構決策記錄(ADR)是一份文件,用於描述團隊就其計劃構建的軟體架構的某個重要方面所做出的選擇。每個 ADR 描述架構決策、其背景及其後果。ADR 具有狀態,因此遵循一個生命週期。有關 ADR 的範例,請參閱附錄。
ADR 流程會輸出一組架構決策記錄。這組記錄構成決策日誌。決策日誌提供專案背景以及詳細的實施和設計資訊。專案成員瀏覽每個 ADR 的標題即可概覽專案背景,閱讀 ADR 則可深入瞭解專案的實施和設計選擇。
團隊接受某個 ADR 後,它就變為不可變。如果新的見解要求做出不同的決策,團隊會提出新的 ADR。團隊接受新的 ADR 後,它將取代之前的 ADR。
ADR 流程的範圍
專案成員應為每一項影響軟體專案或產品、具有架構意義的決策建立 ADR,包括以下方面(Richards 和 Ford 2020):
結構(例如微服務等模式)
非功能性需求(安全性、高可用性和容錯性)
依賴關係(元件的耦合)
介面(API 和已釋出的契約)
構建技術(庫、框架、工具和流程)
功能性和非功能性需求是 ADR 流程最常見的輸入。
ADR 的內容
當團隊發現需要 ADR 時,一名團隊成員會根據專案統一的範本開始撰寫 ADR。(有關範本範例,請參閱 ADR GitHub 組織。)範本簡化了 ADR 的建立,並確保 ADR 涵蓋所有相關資訊。每個 ADR 至少應定義決策的背景、決策本身,以及該決策對專案及其交付物的後果。(有關這些部分的範例,請參閱附錄。)ADR 結構最強大的特點之一是,它關注決策的原因,而不是團隊如何實施。理解團隊為何做出該決策,會讓其他團隊成員更容易採納它,並防止未參與決策過程的其他架構師在將來推翻該決策。
ADR 採納流程
每位團隊成員都可以建立 ADR,但團隊應當確立 ADR 所有權的定義。作為 ADR 所有者的每位作者都應積極維護並傳達 ADR 的內容。為明確這種所有權,本指南在以下各節中將 ADR 作者稱為 ADR 所有者。其他團隊成員始終可以為 ADR 做出貢獻。如果在團隊接受 ADR 之前其內容發生變化,所有者應批准這些變化。
團隊識別出某項架構決策及其所有者後,ADR 所有者在流程開始時提交處於已提議(Proposed)狀態的 ADR。處於已提議狀態的 ADR 已準備好接受評審。
隨後,ADR 所有者啟動該 ADR 的評審流程。ADR 評審流程的目標是決定團隊是接受該 ADR、認定其需要返工,還是拒絕該 ADR。包括所有者在內的專案團隊對 ADR 進行評審。評審會議應以一段專門用於閱讀 ADR 的時間開始。平均而言,10 到 15 分鐘就足夠了。在此期間,每位團隊成員閱讀文件,並新增評論和問題以標記不清楚的主題。評審階段結束後,ADR 所有者逐條宣讀並與團隊討論每條評論。
如果團隊發現了可改進 ADR 的行動項,ADR 的狀態保持為已提議。ADR 所有者擬定這些行動項,並與團隊協作為每項行動指派負責人。每位團隊成員都可以為行動項做出貢獻並解決它們。重新安排評審流程是 ADR 所有者的責任。
團隊也可以決定拒絕該 ADR。在這種情況下,ADR 所有者會補充拒絕的理由,以避免將來就同一主題再次討論。所有者將 ADR 狀態更改為已拒絕(Rejected)。
如果團隊批准該 ADR,所有者會新增時間戳、版本和利益相關者列表。然後所有者將狀態更新為已接受(Accepted)。
ADR 以及它們所形成的決策日誌代表團隊做出的決策,並提供所有決策的歷史記錄。團隊在可能的情況下,將 ADR 用作程式碼評審和架構評審的參考。除了執行程式碼評審、設計任務和實施任務之外,團隊成員還應查閱 ADR,瞭解產品的戰略性決策。
作為一項良好實踐,每項軟體變更都應經過同行評審,並且至少需要一人批准。在程式碼評審期間,程式碼評審者可能會發現違反一個或多個 ADR 的變更。在這種情況下,評審者會要求程式碼變更的作者更新程式碼,並分享指向該 ADR 的連結。作者更新程式碼後,經同行評審者批准併合併到主程式碼庫中。
ADR 評審流程
在團隊接受或拒絕 ADR 之後,應將其視為不可變的文件。更改現有 ADR 需要建立新的 ADR,為新的 ADR 建立評審流程,並批准該 ADR。如果團隊批准新的 ADR,所有者應將舊 ADR 的狀態更改為已取代(Superseded)。