ADR 程序 - AWS規範指導

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

ADR 程序

體繫結構決策記錄 (ADR) 是一份文檔,描述了團隊對他們計劃構建的軟件體繫結構的一個重要方面所做的選擇。每個 ADR 都描述了體繫結構決策、其上下文及其後果。ADR 具有狀態,因此遵循生命週期。如需 ADR 的範例,請參附錄

ADR 流程輸出一系列體繫結構決策記錄。此集合將創建決策日誌。決策日誌提供項目上下文以及詳細的實施和設計信息。項目成員瀏覽每個 ADR 的頭條新聞,以獲取項目上下文的概述。他們閲讀 ADR,深入瞭解項目實施和設計選擇。

當團隊接受 ADR 時,它將變得不可變。如果新見解需要不同的決策,團隊將提出一個新的 ADR。當團隊接受新的 ADR 時,它將取代之前的 ADR。

發展成果解決進程的範圍

項目成員應為影響軟件項目或產品的每個具有體繫結構意義的決策創建 ADR,包括以下內容(理查茲和福特 2020):

  • 結構(例如,微服務等模式)

  • 無功能要求(安全性、高可用性和容錯能力)

  • 依賴關係(組件耦合)

  • 接口(API 和已發佈的合同)

  • 構造技術(庫、框架、工具和流程)

功能性和非功能性要求是 ADR 過程中最常見的投入。

ADR 內容

當團隊確定需要 ADR 時,團隊成員開始根據項目範圍的模板編寫 ADR。(請參《》中的ADR GitHub 組織,例如模板。) 該模板簡化了 ADR 的創建,並確保 ADR 捕獲所有相關信息。每個發展成果評估至少應確定決定的背景、決定本身以及決定對項目及其交付成果的影響。(有關這些部分的示例,請參閲附錄。) ADR 結構最強大的一個方面是,它側重於作出決定的原因,而不是團隊如何執行決定。瞭解團隊作出決策的原因可使其他團隊成員更容易採納決策,並防止未參與決策過程的其他建築師在 future 推翻該決策。

ADR 採用程序

每個團隊成員都可以創建一個 ADR,但團隊應該為 ADR 確定所有權的定義。作為 ADR 所有者的每位作者都應積極維護和傳達 ADR 內容。為了澄清此所有權,本指南將 ADR 作者稱為ADR 擁有者下列各節會詳細説明。其他團隊成員可以隨時為 ADR 做出貢獻。如果 ADR 的內容在團隊接受 ADR 之前發生了變化,則所有者應批準這些更改。

下方圖表説明 ADR 的創建、擁有權和採用程序。


        ADR 的創建、所有權和採用流程

團隊確定了體繫結構決策及其所有者之後,ADR 所有者在提議的狀態在進程的開始。中的 ADR提議的狀態準備進行審查。

隨後,ADR 所有者啟動 ADR 的審核流程。ADR 審核流程的目標是決定團隊是否接受 ADR、確定需要返工或拒絕 ADR。項目團隊(包括所有者)審查 ADR。審查會議應從專門的時間段開始,閲讀發展成果評估。平均而言,10 到 15 分鐘就足夠了。在此期間,每個團隊成員都會閲讀文檔,並添加評論和問題來標記不清楚的主題。審核階段結束後,ADR 所有者將讀出並與團隊討論每個評論。

如果團隊找到改進 ADR 的行動點,ADR 的狀態將保持提議的。ADR 所有者制定操作,並與團隊協作,為每個操作添加一個受讓人。每個團隊成員都可以貢獻和解決行動要點。ADR 所有者有責任重新安排審閲流程。

團隊還可以決定拒絕 ADR。在這種情況下,ADR 所有者會添加拒絕的原因,以防止將 future 討論同一主題。所有者將 ADR 狀態更改為已拒絕

如果團隊批準 ADR,則所有者會添加時間戳、版本和利益相關者列表。然後,所有者將狀態更新為已接受

ADR 和他們創建的決策日誌代表團隊做出的決策,並提供所有決策的歷史記錄。團隊在代碼和體繫結構審查期間儘可能使用 ADR 作為參考。除了執行代碼審查、設計任務和實施任務之外,團隊成員還應諮詢 ADR 以瞭解產品的戰略決策。

下圖顯示了應用 ADR 以驗證軟件組件的更改是否符合商定決策的過程。


        使用 ADR 驗證軟件組件更改

作為一種良好做法,每個軟件更改都應經過同行審查,並至少需要一次批準。代碼審閲期間,代碼審閲者可能會發現違反一個或多個 ADR 的更改。在這種情況下,審閲者要求代碼更改的作者更新代碼,並共享一個指向 ADR 的鏈接。當作者更新代碼時,代碼將獲得同行審閲者的批準,並將其合併到主代碼庫中。

ADR 審核程序

團隊應在團隊接受或拒絕 ADR 後將其視為不可變文檔。對現有 ADR 的更改需要創建一個新的 ADR,為新的 ADR 建立審核流程,並批準 ADR。如果團隊批準了新的 ADR,則所有者應將舊 ADR 的狀態更改為已取代。下方圖表説明更新程序。


        ADR 更新過程