如要說明基礎架構或應用程式團隊為何做出特定設計選擇，可以使用架構決策記錄 (ADR)。本文說明在Google Cloud上建構及執行應用程式時，何時及如何使用 ADR。
ADR 會記錄可用的主要選項、促成決策的主要需求，以及設計決策本身。您通常會將 ADR 儲存在與該決策相關的程式碼庫附近的 Markdown 檔案中。如果有人需要瞭解特定架構決策的背景資訊，例如您為何使用區域 Google Kubernetes Engine (GKE) 叢集，他們可以查看 ADR，然後查看相關聯的程式碼。
ADR 也能協助您執行更可靠的應用程式和服務。ADR 可協助您瞭解目前狀態，並在發生問題時進行疑難排解。ADR 也會建立工程決策的集合，協助未來的決策選擇和部署。
何時使用 ADR
您可以使用 ADR 追蹤認為對部署作業很重要的主要領域。ADR 可能包含下列類別：
- 具體產品選擇，例如選擇 Pub/Sub 和 Cloud Tasks。
- 特定產品選項和設定，例如使用地區 GKE 叢集搭配多叢集 Ingress，確保應用程式高可用性。
- 一般架構指南，例如 Dockerfile 資訊清單的最佳做法。
以下列舉幾個可能促使您建立 ADR 的具體例子：
- 您為何要為 Cloud SQL 執行個體設定高可用性 (HA)？
- 您如何確保 GKE 叢集的正常運作時間？您是否使用區域叢集？您是否使用初期測試版？原因為何？
評估要使用的產品時，ADR 有助於說明您的每個決定。隨著團隊發展，您會對堆疊有更多瞭解，並做出或調整其他決策，因此可以重新審視 ADR。如果進行調整，請附上先前的決定，以及變更的原因。這份記錄會隨著業務需求演變，或出現新的技術需求或可用解決方案，記錄架構的變更情形。
下列提示可協助您判斷何時應建立 ADR：
- 遇到技術難題或有疑問，但沒有現成的決策依據，例如建議的解決方案、標準作業程序、藍圖或程式碼集。
- 當您或您的團隊提供解決方案，但團隊無法在任何地方找到相關文件時。
- 當有兩個以上的工程選項，且您想記錄選擇背後的想法和原因。
撰寫 ADR 時，請考慮潛在讀者。主要讀者是負責 ADR 所涵蓋技術的團隊成員。ADR 的潛在讀者可能包括想瞭解您決策的鄰近團隊，例如架構和安全團隊。
此外，應用程式可能會變更擁有者或納入新的團隊成員。ADR 可協助新貢獻者瞭解所做的工程選擇背景。此外，ADR 也能讓您更輕鬆地規劃日後的變更。
ADR 的格式
典型的 ADR 包含一組章節。ADR 應有助於擷取您認為對應用程式和貴機構重要的內容。有些 ADR 可能只有一頁，有些則需要較長的說明。
以下 ADR 大綱範例說明如何設定 ADR 格式，納入環境的重要資訊：
- 作者和團隊
- 您想解決的脈絡和問題
- 您想解決的功能性和非功能性需求
- 這項決策可能影響的關鍵使用者歷程 (CUJ)
- 主要選項總覽
- 您的決定和接受所選選項的原因
為方便記錄決策，您可以在每個決策中加入時間戳記，顯示做出選擇的時間。
ADR 的運作方式
如果工程師、開發人員或應用程式擁有者可以輕鬆存取 ADR 包含的資訊，ADR 就能發揮最大效益。如果他們對某件事為何以特定方式完成有疑問，可以查看 ADR 尋找答案。
為了方便存取 ADR，部分團隊會將其放在中央 Wiki 中，而非來源控管存放區，讓業主也能存取。如果有人對特定工程決策有疑問，ADR 就能提供解答。
在下列情況下，ADR 效果良好：
- 新手上路：新團隊成員可以輕鬆瞭解專案，並在學習新程式碼集時，查看 ADR 解決疑問。
- 架構演變：如果團隊之間轉移技術堆疊，新擁有者可以查看過去的決策，瞭解目前的狀態。如果團隊有新的技術可用，也可以回顧過去的決策。ADR 可協助團隊避免重複討論相同的主題，並在團隊重新討論主題時提供歷史背景資訊。
- 分享最佳做法：如果 ADR 詳細說明瞭做出特定決策的原因，以及決定不採用的替代方案，團隊就能在整個機構中採用一致的最佳做法。
ADR 通常以 Markdown 格式撰寫，以保持輕量化和文字格式。Markdown 檔案可與應用程式程式碼一起納入來源控管存放區。
將 ADR 儲存在應用程式程式碼附近，最好是儲存在相同的版本控制系統中。變更 ADR 時，您可以視需要從來源控管中查看先前的版本。
您也可以使用其他媒介，例如共用的 Google 文件或內部 Wiki。這些替代位置可能更方便 ADR 團隊以外的使用者存取。您也可以在來源控制儲存空間中建立 ADR，但將重要決策鏡像到更容易存取的 Wiki。
後續步驟
- 如需其他指引和最佳做法，請參閱雲端架構中心和Google Cloud 架構完善架構。
- 如要瞭解 ADR 可能涵蓋的某些領域，請參閱「可擴充及具有韌性的應用程式模式」。