Architecture Decision Recordarc42 的決策記錄範本
1. 引言與目標
簡要描述需求、驅動力量,以及需求的摘錄(或摘要)。對主要利益相關者而言優先順序最高的、前三項(最多五項)架構品質目標。一張列出重要利益相關者及其對架構的期望的表格。
1.1 需求概覽
內容
簡要描述功能需求、驅動力量,以及需求的摘錄(或摘要)。提供指向(但願已存在的)需求文件的連結,並說明可以在哪裡找到它們。
動機
從終端使用者的角度來看,建立或修改系統是為了更好地支援某項業務活動和/或提高品質。
形式
簡短的文字描述,可能採用表格形式的用例格式。如果存在需求文件,此概覽應引用這些文件。
請儘可能保持這些摘錄簡短。在本文件的可讀性與相對於需求文件可能產生的冗餘之間取得平衡。
1.2 品質目標
內容
對主要利益相關者而言,實現起來最重要的前三項(最多五項)架構品質目標。我們真正指的是架構的品質目標。不要將它們與專案目標混淆,兩者未必相同。ISO 25010 標準很好地概述了可能值得關注的主題。
動機
你應該瞭解最重要的利益相關者的品質目標,因為它們會影響基本的架構決策。請務必把這些品質說得非常具體,避免使用流行術語。如果你作為架構師不知道自己的工作品質將如何被評判……
形式
一張按優先順序排序的表格,列出最重要的品質目標和具體場景。
1.3 利益相關者
內容
對系統利益相關者的明確概覽,即所有符合以下情形的人員、角色或組織:
應當瞭解該架構
必須被說服接受該架構
必須使用該架構或程式碼開展工作
工作中需要該架構的文件
必須就係統或其開發做出決策
動機
你應該瞭解參與系統開發或受系統影響的所有各方。否則,你可能會在開發過程的後期遇到令人不快的意外。這些利益相關者決定了你的工作及其成果的範圍和詳細程度。
形式
一張表格,包含角色名稱、人員姓名,以及他們對架構及其文件的期望。
2. 約束
任何約束團隊在設計與實現決策或相關流程決策方面的因素。有時可能超出單個系統的範圍,對整個組織和公司有效。
內容
任何約束軟體架構師在設計和實現決策或開發流程決策方面自由度的需求。這些約束有時超出單個系統的範圍,對整個組織和公司有效。
動機
架構師應當確切地知道,在設計決策中哪些地方是自由的,哪些地方必須遵守約束。約束必須始終加以處理,不過它們有時是可以協商的。
形式
帶有說明的簡單約束表格。如有需要,可以將其細分為技術約束、組織與政治約束,以及約定(例如程式設計或版本管理指南、文件或命名約定)。
3. 背景與範圍
劃定你的系統與其(外部)通訊夥伴(相鄰系統和使用者)之間的邊界。規定外部介面。從業務/領域的視角(必須)或技術的視角(可選)呈現。
內容
系統範圍與背景——顧名思義——將你的系統(即你的範圍)與它所有的通訊夥伴(相鄰系統和使用者,即系統的背景)劃分開來,從而規定外部介面。
如有必要,請區分業務背景(特定領域的輸入和輸出)與技術背景(通道、通訊協定、硬體)。
動機
與通訊夥伴之間的領域介面和技術介面,是系統最關鍵的方面之一。請確保你完全理解它們。
形式
各種背景圖
通訊夥伴及其介面的列表。
3.1 業務背景
內容
規定所有通訊夥伴(使用者、IT 系統……),並說明特定領域的輸入和輸出或介面。你還可以選擇性地新增特定領域的格式或通訊通訊協定。
動機
所有利益相關者都應當瞭解與系統環境交換了哪些資料。
形式
各類將系統視為黑盒、並規定與通訊夥伴之間領域介面的圖。
或者(或另外)你可以使用表格。表格的標題是你的系統名稱,三列分別包含通訊夥伴的名稱、輸入和輸出。
3.2 技術背景
內容
將你的系統與其環境連線起來的技術介面(通道和傳輸介質)。此外,還有特定領域的輸入/輸出到通道的對映,即說明哪種輸入/輸出使用哪個通道。
動機
許多利益相關者根據系統與其背景之間的技術介面做出架構決策。尤其是基礎設施或硬體設計人員會決定這些技術介面。
形式
例如,用 UML 部署圖描述與相鄰系統之間的通道,並配以一張對映表,顯示通道與輸入/輸出之間的關係。
4. 解決方案策略
對塑造架構的基本決策和解決方案策略的總結。可以包括技術、頂層分解、實現最高品質目標的方法,以及相關的組織決策。
內容
對塑造系統架構的基本決策和解決方案策略的簡要總結與說明。這些包括:
技術決策
關於系統頂層分解的決策,例如使用某種架構模式或設計模式
關於如何實現關鍵品質目標的決策
相關的組織決策,例如選擇開發流程,或將某些任務委託給第三方。
動機
這些決策構成了你的架構的基石。它們是許多其他詳細決策或實現規則的基礎。
形式
請保持對這些關鍵決策的說明簡短。
根據你的問題陳述、品質目標和關鍵約束,說明你做了什麼決定以及為什麼這樣決定。詳細內容請參閱後續章節(結構細節見第 5 章,橫切關注點見第 8 章)。
你可以使用解決方案方法的列表或表格。
5. 構建塊檢視
系統的靜態分解,是對原始碼的抽象,以白盒(其中包含黑盒)的層級結構呈現,直至適當的詳細程度。
內容
構建塊檢視展示了系統到構建塊(模組、元件、子系統、類、介面、包、庫、框架、層、分割槽、層級、函式、宏、操作、資料結構……)的靜態分解,以及它們的依賴關係(關係、關聯……)。
每份架構文件都必須包含此檢視。以房屋作類比,這相當於平面圖。
動機
透過抽象使原始碼的結構易於理解,從而保持對原始碼的整體把握。
這使你能夠在抽象層面上與利益相關者溝通,而無需披露實現細節。
形式
構建塊檢視是黑盒和白盒(見下圖)及其描述的層級集合。
5.1 整體系統白盒
在這裡,你使用以下白盒範本描述整個系統的分解。它包含:
一張概覽圖
分解的動機
所含構建塊的黑盒描述。對此我們為你提供了幾種選擇:
使用一張表格,簡短而務實地概覽所有包含的構建塊及其介面
按照黑盒範本(見下文),列出各構建塊的黑盒描述。根據你所選的工具,這份列表可以是子章節(在文字檔案中)、子頁面(在維基中)或巢狀元素(在建模工具中)。
(可選:)重要的介面,它們沒有在構建塊的黑盒範本中說明,但對於理解白盒非常重要。
由於指定介面的方式太多,我們沒有為它們提供專門的範本。
在最好的情況下,範例或簡單的簽名就足夠了。
5.2 第 2 層
在這裡,你可以將第 1 層中(部分)構建塊的內部結構指定為白盒。
你必須決定系統中哪些構建塊足夠重要,值得做如此詳細的描述。請優先考慮相關性而不是完整性。請詳細說明重要的、出人意料的、有風險的、複雜的或易變的構建塊。省略系統中普通的、簡單的、乏味的或標準化的部分。
5.2.1 構建塊 1 的白盒
規定構建塊 1 的內部結構。
使用白盒範本(見上文)。
6. 執行時檢視
以場景的形式描述構建塊的行為,涵蓋重要的用例或功能、關鍵外部介面處的互動、執行與管理,以及錯誤和異常行為。
內容
執行時檢視以下列領域的場景的形式,描述系統構建塊的具體行為和互動:
重要的用例或功能:構建塊如何執行它們?
關鍵外部介面處的互動:構建塊如何與使用者和相鄰系統協作?
執行與管理:啟動、啟動完成、停止
錯誤和異常場景
備註:選擇可能的場景(序列、工作流)的主要標準是它們的架構相關性。描述大量場景並不重要,而應記錄具有代表性的一組場景。
動機
你應該瞭解系統構建塊(的例項)在執行時如何完成工作並相互通訊。你在文件中主要會記錄場景,以便向那些不太願意或沒有能力閱讀和理解靜態模型(構建塊檢視、部署檢視)的利益相關者傳達你的架構。
形式
描述場景的表示法有很多,例如:
帶編號的步驟列表(用自然語言)
活動圖或流程圖
序列圖
BPMN 或 EPC(事件過程鏈)
狀態機
等等
6.n 執行時場景 n(1、2、3 等)
插入執行時圖或該場景的文字描述。
插入對此圖中所示構建塊例項之間互動的值得注意的方面的描述。
7. 部署檢視
包含環境、計算機、處理器、拓撲的技術基礎設施。(軟體)構建塊到基礎設施元素的對映。
內容
部署檢視描述:
用於執行你的系統的技術基礎設施,其基礎設施元素包括地理位置、環境、計算機、處理器、通道和網路拓撲,以及其他基礎設施元素,以及
(軟體)構建塊到這些基礎設施元素的對映。
系統通常在不同的環境中執行,例如開發環境、測試環境、生產環境。在這種情況下,你應當記錄所有相關的環境。
當你的軟體作為分散式系統在多於一臺計算機、處理器、伺服器或容器上執行時,或者當你設計和製造自己的硬體處理器和晶片時,尤其要記錄部署檢視。
從軟體的角度來看,只需記錄展示構建塊部署所需的那些基礎設施元素即可。硬體架構師可以做得更多,按照他們需要記錄的任何詳細程度來描述基礎設施。
動機
軟體離開硬體就無法執行。這一底層基礎設施可以而且將會影響你的系統和/或某些橫切概念。因此,你需要了解基礎設施。
形式
最高層級的部署圖也許已經包含在第 3.2 節的技術背景中,其中你自己的基礎設施是一個黑盒。在本節中,你將使用額外的部署圖放大這個黑盒。
UML 提供了部署圖來表達該檢視。當你的基礎設施較為複雜時,請使用它,可能需要使用巢狀的圖。
當你的(硬體)利益相關者更喜歡使用 UML 部署圖以外的其他型別的圖時,請讓他們使用任何能夠展示基礎設施節點和通道的圖。
7.1 基礎設施第 1 層
描述(通常結合使用圖、表格和文字):
你的系統在多個位置、環境、計算機、處理器等之間的分佈,以及它們之間的物理連線
這種部署結構的重要理由或動機
基礎設施的品質和/或效能特徵
軟體製品(構建塊)到基礎設施元素的對映
對於多個環境或替代部署,請為所有相關環境複製 arc42 的這一部分。 **
7.2 基礎設施第 2 層
在這裡,你可以包含基礎設施第 1 層中(部分)基礎設施元素的內部結構。
請為每個選定的元素複製第 1 層的結構。
8. 橫切概念
在系統多個部分(→ 橫切)中相關的總體性、原則性的規定和解決方案方法。概念通常與多個構建塊相關。包含領域模型、架構模式和風格、使用特定技術的規則和實現規則等不同主題。
內容
本節描述橫切概念(實踐、模式、規定或解決方案思路)。這些概念通常與多個構建塊相關。它們可能涵蓋許多不同的主題。
動機
概念構成了架構概念完整性(一致性、同質性)的基礎。因此,它們對於實現系統的內在品質是一項重要貢獻。
這是我們在範本中為這類概念的統一規範所提供的位置。
這些概念中有許多與你的多個構建塊相關或對其產生影響。
形式
形式可以多種多樣:
結構任意的概念文件
範例實現,尤其適用於技術概念
使用架構檢視表示法的橫切模型摘錄或場景
本節的結構
只選擇你的系統最需要的主題,並在本節中為每個主題分配一個二級標題(例如 8.1、8.2 等)。
- 不要試圖涵蓋上述圖中的所有主題。
背景
系統中的某些主題通常涉及多個構建塊、硬體元素或開發流程。在一個集中的位置溝通或記錄這類橫切主題,可能比在相關構建塊、硬體元素或開發流程的描述中重複它們更容易。
某些概念可能涉及系統的所有元素,另一些則可能只與少數元素相關。
9. 架構決策
重要的、代價高昂的、關鍵的、大規模的或有風險的架構決策,包括其理由。
內容
重要的、代價高昂的、大規模的或有風險的架構決策,包括其理由。這裡的「決策」指的是根據給定標準選擇一個備選方案。
請自行判斷,一項架構決策應該記錄在這個集中的章節中,還是更適合在區域性記錄(例如在某個構建塊的白盒範本中)。避免重複的文字。請參閱第 4 章,你已經在那裡記錄了架構中最重要的決策。
動機
系統的利益相關者應當能夠理解並回溯你的決策。
形式
為每項重要決策編寫 ADR(架構決策記錄)
按重要性和後果排序的列表或表格,或者
以每項決策單獨成節的形式提供更詳細的記錄
背景(關於 ADR)
較小的文件片段更容易閱讀、建立和維護。談到架構決策時,開發團隊往往:
知道這項決策,因為它在例如原始碼中是可見的,但是
不清楚這項決策背後的動機(參見 Nygard 2011)
因此,你應該記錄少數重要決策及其動機和推理
我們關於決策的建議
保留一份具有架構意義的決策集合,即那些影響結構、品質特性、重要(尤其是外部)依賴和介面,或構建技術的決策(感謝 Michael Nygard 的這一建議)。
10. 品質需求
以場景形式表達的品質需求,配以品質樹以提供高層概覽。最重要的品質目標應已在第 1.2 節(品質目標)中描述。
內容
本節包含所有相關的品質需求。
其中最重要的需求已經在第 1.2 節(品質目標)中描述過,因此在此處只需引用。在本第 10 章中,你還應當記錄重要性較低的品質需求,這些需求即使沒有完全實現也不會帶來高風險(但最好能有)。
動機
由於品質需求會對架構決策產生很大影響,你應該以具體且可衡量的方式瞭解哪些品質對你的利益相關者真正重要。
更多資訊
請參閱 https://quality.arc42.org 上內容全面的 Q42 品質模型。
10.1 品質需求概覽
內容
品質需求的概覽或摘要。
動機
我們經常遇到數十個(甚至數百個)詳細的品質需求。在這一概覽部分,你應該嘗試進行總結,例如透過描述類別或主題(如 ISO 25010:2023 或 Q42 所建議的)。
如果這些摘要描述已經足夠精確、具體且可衡量,你可以跳過第 10.2 節。
形式
使用一張簡單的表格,每行包含一個類別或主題以及對品質需求的簡短描述。或者,你也可以使用思維導圖來組織這些品質需求。
文獻中還描述過品質屬性樹的概念,它將通用術語「品質」作為根,並對「品質」一詞進行樹狀細化。[Bass+21] 為此引入了「品質屬性效用樹」(Quality Attribute Utility Tree)這一術語。
10.2 品質場景
內容
品質場景使品質需求具體化,並使人們能夠判斷它們是否得到滿足(就驗收標準而言)。請確保你的場景具體且可衡量。
有兩類場景尤其有用:
使用場景(也稱為應用場景或用例場景)描述系統在執行時對某種刺激的反應。這也包括描述系統效率或效能的場景。範例:系統在一秒內對使用者的請求做出反應。
變更場景描述對系統或其直接環境進行修改或擴充套件所期望的效果。範例:實現了額外的功能,或者對某個品質屬性的需求發生了變化,並測量變更所需的工作量或持續時間。
形式
詳細場景的典型資訊包括以下內容:
簡短形式(Q42 模型所傾向的形式):
背景/上下文:什麼型別的系統或元件,環境或情況如何?
來源/刺激:誰或什麼發起或觸發某種行為、反應或動作。
度量/驗收標準:包含度量或指標的響應
場景的長形式(SEI 和 [Bass+21] 所傾向的形式)更為詳細,包含以下資訊:
場景 ID:場景的唯一識別符號。
場景名稱:場景的簡短描述性名稱。
來源:發起該場景的實體(使用者、系統或事件)。
刺激:系統必須應對的觸發事件或條件。
環境:系統遇到該刺激時的執行背景或條件。
製品:受該刺激影響的構建塊或系統的其他元素。
響應:系統針對該刺激所表現出的結果或行為。
響應度量:用於評估系統響應的標準或指標。
另請參閱
自 2023 年 1 月起,arc42 提供了一個務實的品質模型,建議使用 #flexible、#efficient、#usable、#operable、#testable、#secure、#safe、#reliable 等標籤或標記來標註品質需求。
11. 風險與技術債務
已知的技術風險或技術債務。系統內部或周圍存在哪些潛在問題?開發團隊對哪些方面感到苦惱?
內容
按優先順序排序的已識別技術風險或技術債務列表。
動機
「風險管理是成年人的專案管理」(Tim Lister,Atlantic Systems Guild)。
這應當成為你系統性地發現和評估架構中風險與技術債務的座右銘,管理層利益相關者(例如專案經理、產品負責人)在整體風險分析和度量規劃中將需要這些資訊。
形式
風險和/或技術債務的列表,可能還包括用於最小化、緩解或規避風險或減少技術債務的建議措施。