ADR 程序 - AWS 方案指引

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

ADR 程序

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

ADR 程序會輸出架構決策記錄的集合。此集合會建立決策日誌。決策日誌提供專案內容以及詳細的實作和設計資訊。專案成員瀏覽每個 ADR 的標題,以簡要了解專案內容。他們閱讀 ADR,以深入了解專案實作和設計選擇。

在團隊接受 ADR 時,它變得不可變。如果新的洞察需要不同的決策,團隊會提議新 ADR。在團隊接受新 ADR 時,它會取代先前的 ADR。

ADR 程序的範圍

專案成員應為影響軟體專案或產品的每個架構上重要的決策建立 ADR,包括下列項目 (Richards and Ford 2020):

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

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

  • 相依性 (元件的耦合)

  • 介面 (API 和已發佈的合約)

  • 建構技術 (程式庫、架構、工具和程序)

功能和非功能需求是 ADR 程序中最常見的輸入。

ADR 內容

在團隊確定需要 ADR 時,團隊成員開始根據專案範圍的範本編寫 ADR。(請參閱 ADR GitHub 組織以取得範例範本。) 此範本簡化了 ADR 建立並確保 ADR 擷取所有相關資訊。每個 ADR 至少應定義決策的內容、決策本身以及決策對專案及其可交付項目的影響。(如需這些小節的範例,請參閱附錄。) ADR 結構最強大的方面之一是它專注於決策的原因,而不是團隊如何實作決策。了解團隊做出決策的原因可以讓其他團隊成員更輕鬆地採用此決策,並防止未參與決策程序的其他架構師將來推翻該決策。

ADR 採用程序

每個團隊成員都可以建立 ADR,但團隊應為 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 擁有者會新增拒絕原因,以防止將來就相同主題進行討論。擁有者將 ADR 狀態變更為已拒絕

如果團隊核准 ADR,則擁有者會新增時間戳記、版本和利害關係人清單。然後,擁有者會將狀態更新為已接受

ADR 及其建立的決策日誌代表團隊所做的決策,並提供所有決策的歷史記錄。在可能的情況下,團隊在程式碼和架構審核期間使用 ADR 作為參考。除了執行程式碼審核、設計任務和實作任務之外,團隊成員還應諮詢 ADR 來做出產品的策略決策。

下圖顯示了套用 ADR 來驗證軟體元件中的變更是否符合協議決策的程序。


        使用 ADR 驗證軟體元件變更

作為一個良好的做法,每個軟體變更都應經過同行審核並至少需要一次核准。在程式碼審核期間,程式碼審核者可能會發現違反一或多個 ADR 的變更。在這種情況下,審核者會要求程式碼變更的作者更新程式碼,並共用 ADR 的連結。在作者更新程式碼時,它會得到同行審核者的核准並合併到主要程式碼庫中。

ADR 審核程序

在團隊接受或拒絕 ADR 後,團隊應將其視為不可變的文件。對現有 ADR 的變更需要建立新的 ADR、為新的 ADR 建立審核程序並核准此 ADR。如果團隊核准新 ADR,擁有者應將舊 ADR 的狀態變更為已取代。下圖說明更新程序。


        ADR 更新程序