arc42 嘅決策記錄範本

https://arc42.org/overview

1. 簡介同目標

簡單描述需求、驅動因素，以及需求嘅摘錄（或者摘要）。列出架構最重要嘅三個（最多五個）質素目標，呢啲目標對主要持份者嚟講優先次序最高。再加一個列出重要持份者同佢哋對架構有咩期望嘅表格。

1.1 需求概覽

內容

簡單描述功能性需求、驅動因素，以及需求嘅摘錄（或者摘要）。提供連結去（但願已經存在嘅）需求文件，並且講明喺邊度可以搵到。

動機

從最終用戶嘅角度嚟睇，建立或者修改一個系統，係為咗加強對某項業務活動嘅支援，及／或者提升質素。

形式

簡短嘅文字描述，可能用表格式嘅用例格式。如果已經有需求文件，呢個概覽應該引用嗰啲文件。

呢啲摘錄要盡量精簡。喺本文件嘅可讀性同同需求文件可能出現嘅重複之間取得平衡。

1.2 質素目標

內容

架構最重要嘅三個（最多五個）質素目標，達成呢啲目標對主要持份者最為重要。我哋真係指架構嘅質素目標，唔好同項目目標混淆，兩者未必相同。ISO 25010 標準對可能感興趣嘅課題提供咗一個好好嘅概覽。

動機

你應該知道最重要嘅持份者有咩質素目標，因為佢哋會影響根本性嘅架構決策。要非常具體咁講明呢啲質素，避免用流行術語。如果作為架構師嘅你都唔知道你嘅工作質素會點樣被評價……

形式

一個列出最重要質素目標同具體情境嘅表格，按優先次序排列。

1.3 持份者

內容

明確列出系統嘅持份者概覽，即係所有符合以下條件嘅人、角色或者組織：

應該知道架構
需要被說服接受架構
必須使用架構或者程式碼工作
工作上需要架構文件
必須就系統或者系統開發作出決定

動機

你應該知道所有參與系統開發、或者受系統影響嘅各方。否則，你可能喺開發過程後期遇到令人不快嘅意外。呢啲持份者決定你工作同工作成果嘅範圍同詳細程度。

形式

一個表格，列出角色名稱、人名，以及佢哋對架構同架構文件嘅期望。

2. 限制

任何限制團隊喺設計同實施決策上，或者喺相關流程決策上嘅因素。有時可以超出個別系統，適用於整個組織同公司。

內容

任何限制軟件架構師喺設計同實施決策、或者開發流程決策上嘅自由度嘅需求。呢啲限制有時超出個別系統，適用於整個組織同公司。

動機

架構師應該清楚知道喺設計決策上邊度有自由，邊度必須遵守限制。限制必須處理，不過亦可能可以磋商。

形式

簡單嘅限制表格，附帶解釋。如有需要，可以細分為技術限制、組織同政治限制，以及慣例（例如編程或者版本管理指引、文件或者命名慣例）。

3. 背景同範圍

將你嘅系統同（外部）溝通夥伴（鄰近系統同用戶）劃分開，並指明外部介面。從業務／領域角度（必須）或者技術角度（可選）展示。

內容

系統範圍同背景，顧名思義，就係將你嘅系統（即你嘅範圍）同所有溝通夥伴（鄰近系統同用戶，即你系統嘅背景）劃分開，從而指明外部介面。

如有需要，應該區分業務背景（特定領域嘅輸入同輸出）同技術背景（通道、協定、硬件）。

動機

同溝通夥伴之間嘅領域介面同技術介面，係系統最關鍵嘅方面之一。務必完全明白佢哋。

形式

各種背景圖
溝通夥伴及其介面嘅清單。

3.1 業務背景

內容

指明所有溝通夥伴（用戶、IT 系統等），並解釋特定領域嘅輸入、輸出或者介面。亦可以選擇性咁加入特定領域嘅格式或者通訊協定。

動機

所有持份者都應該明白系統同外部環境之間交換咗咩數據。

形式

各種將系統當作黑盒、並指明同溝通夥伴之間領域介面嘅圖。

另外（或者額外）亦可以用表格。表格嘅標題係你系統嘅名稱，三個欄分別載有溝通夥伴嘅名稱、輸入同輸出。

3.2 技術背景

內容

將你嘅系統連接到外部環境嘅技術介面（通道同傳輸媒介）。另外，將特定領域嘅輸入／輸出對應到通道，即係解釋邊個輸入／輸出用邊條通道。

動機

好多持份者會根據系統同其背景之間嘅技術介面作出架構決策，尤其係基礎設施或者硬件設計師會決定呢啲技術介面。

形式

例如用 UML 部署圖描述同鄰近系統之間嘅通道，再配合一個對應表，顯示通道同輸入／輸出之間嘅關係。

4. 解決方案策略

總結塑造架構嘅根本決策同解決方案策略。可以包括技術、頂層分解、達成最高質素目標嘅方法，以及相關嘅組織決策。

內容

簡短總結同解釋塑造系統架構嘅根本決策同解決方案策略，包括：

技術決策
關於系統頂層分解嘅決策，例如使用某個架構模式或者設計模式
關於點樣達成關鍵質素目標嘅決策
相關嘅組織決策，例如揀選開發流程，或者將某啲工作交畀第三方

動機

呢啲決策係你架構嘅基石，亦係好多其他詳細決策或者實施規則嘅基礎。

形式

對呢啲關鍵決策嘅解釋要簡短。

根據你嘅問題陳述、質素目標同關鍵限制，說明你決定咗咩、點解咁決定。並引用以下章節嘅詳細內容（第 5 節講結構細節，第 8 節講橫切關注點概念）。

你可以用解決方案做法嘅清單或者表格。

5. 構建塊視圖

系統嘅靜態分解，即原始碼嘅抽象，以白盒（內含黑盒）嘅層級結構展示，直至適當嘅詳細程度。

內容

構建塊視圖展示系統靜態分解成各個構建塊（模組、組件、子系統、類別、介面、套件、程式庫、框架、層、分區、層級、函數、巨集、操作、數據結構等），以及佢哋之間嘅依賴關係（關係、關聯等）。

每份架構文件都必須有呢個視圖。用屋嚟比喻，呢個就係平面圖。

動機

透過抽象令結構容易理解，從而掌握原始碼嘅概覽。

咁樣你就可以喺抽象層面同持份者溝通，而唔使披露實施細節。

形式

構建塊視圖係黑盒同白盒（見下圖）嘅層級集合，連同佢哋嘅描述。

5.1 整體系統白盒

喺呢度你用以下白盒範本描述整個系統嘅分解。範本包含：

一幅概覽圖
分解嘅動機
所含構建塊嘅黑盒描述。對於呢部分，我哋提供以下選擇：
- 用一個表格，簡短而務實咁概覽所有所含構建塊同佢哋嘅介面
- 按照黑盒範本（見下文），用一系列構建塊嘅黑盒描述。視乎你揀選嘅工具，呢個清單可以係子章節（文字檔案）、子頁面（Wiki）或者嵌套元素（建模工具）。
- （可選：）重要嘅介面。呢啲介面喺構建塊嘅黑盒範本入面冇解釋，但對於理解白盒非常重要。

由於指明介面嘅方式太多，所以我哋冇為佢哋提供特定範本。

最好嘅情況下，用例子或者簡單嘅簽名就已經足夠。

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. 橫切關注點概念

喺系統多個部分（→ 橫切）都相關嘅整體性、原則性規定同解決方案做法。概念通常同多個構建塊有關。包括不同課題，例如領域模型、架構模式同風格、使用特定技術嘅規則，以及實施規則。

內容

本節描述橫切關注點概念（實踐、模式、規定或者解決方案構想）。呢類概念通常同多個構建塊有關，亦可能涵蓋好多不同課題。

動機

概念係架構概念完整性（一致性、同質性）嘅基礎。因此，佢哋對達成系統嘅內在質素有重要貢獻。

呢個係我哋喺範本入面提供嘅位置，用嚟連貫地指明此類概念。

好多呢類概念同你嘅幾個構建塊有關或者會影響佢哋。

形式

形式可以多樣：

結構不拘嘅概念文件
範例實施，特別係技術概念
用架構視圖記法表達嘅橫切模型摘錄或者情境

本節嘅結構

只揀你系統最需要嘅課題，並為每個課題喺本節指派一個第 2 層標題（例如 8.1、8.2 等）。

唔好嘗試涵蓋上述圖入面所有課題。

背景

系統入面有啲課題，往往涉及多個構建塊、硬件元素或者開發流程。喺一個中央位置傳達或者記錄呢類橫切課題，可能比喺相關構建塊、硬件元素或者開發流程嘅描述入面重複記錄更容易。

某啲概念可能涉及系統嘅所有元素，另一啲就可能只同少數元素有關。

9. 架構決策

重要、昂貴、關鍵、大規模或者有風險嘅架構決策，連同理據。

內容

重要、昂貴、大規模或者有風險嘅架構決策，連同理據。我哋講嘅「決策」，係指根據既定準則喺多個選項之中揀選其一。

請自行判斷，一項架構決策應該記錄喺呢個中央章節，定係記錄喺本地更好（例如喺某個構建塊嘅白盒範本入面）。避免重複文字。請參閱第 4 節，你已經喺嗰度記錄咗架構最重要嘅決策。

動機

系統嘅持份者應該能夠理解同追溯你嘅決策。

形式

每項重要決策都有一份 ADR（架構決策記錄）
按重要性同後果排序嘅清單或者表格，或者
以更詳細嘅形式，為每項決策設獨立章節

背景（關於 ADR）

較細嘅文件更容易閱讀、建立同維護。講到架構決策，開發團隊經常會：

知道該決策，因為例如喺原始碼入面睇得到，但係
欠缺該決策背後嘅動機（見 Nygard 2011）

因此，你應該記錄少量重要嘅決策，連同佢哋嘅動機同推理

我哋對決策嘅建議

保存一批具架構意義嘅決策，即係影響結構、質素特性、重要（尤其係外部）依賴關係同介面，或者建構技術嘅決策（多謝 Michael Nygard 提出呢個建議）。

10. 質素需求

以情境形式表達質素需求，並配合質素樹提供高層次概覽。最重要嘅質素目標應該已經喺第 1.2 節（質素目標）入面描述。

內容

本節載有所有相關嘅質素需求。

其中最重要嘅需求已經喺第 1.2 節（質素目標）描述，所以喺呢度只應該引用。喺本第 10 節，你亦應該記錄重要性較低嘅質素需求，即使冇完全達成都唔會造成高風險（但可能係錦上添花）。

動機

由於質素需求會對架構決策有好大影響，你應該以具體同可衡量嘅方式，知道對持份者嚟講邊啲質素真正重要。

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。）

呢句應該成為你系統性咁發現同評估架構入面風險同技術債嘅座右銘。管理層持份者（例如項目經理、產品負責人）喺整體風險分析同措施規劃時會需要呢啲資料。

形式

風險及／或者技術債嘅清單，可能包括建議嘅措施，用嚟減少、緩解或者避免風險，或者減少技術債。