架構文件的用途與受眾#

架構文件必須服務於多元目的：對新進人員足夠透明易懂、對建構者足夠具體以作為藍圖、對分析者提供充足資訊以進行評估。架構文件可以同時是規範性的（prescriptive）和描述性的（descriptive）。

架構文件基本上有四個用途：

1. 教育手段（Education） — 向新加入團隊的成員、外部分析師、甚至新任架構師介紹系統。在許多場景中，「新人」是客戶，而你希望這次展示能帶來資金或核准
2. 利害關係人之間的溝通工具（Communication） — 最積極的消費者莫過於專案的未來架構師，可能是同一人或接任者，都需要了解前任如何處理難題及其決策原因
3. 系統分析與建構的基礎（Analysis & Construction） — 告知實作者該實作哪些模組、模組間如何連接、以及提供評估各品質屬性（安全性、效能、可用性、可修改性等）的必要資訊
4. 事件鑑識的基礎（Forensics） — 當事件發生時，追蹤立即原因與根本原因

為使文件持續提供價值，必須保持更新。

表示法（Notations）#

文件化視圖的表示法在形式化程度上差異甚大，大致分為三類：

• 非正式表示法（Informal） — 使用通用繪圖工具和視覺慣例的圖形描述（如 PowerPoint 或白板手繪），語意以自然語言描述，無法進行形式化分析
• 半正式表示法（Semiformal） — 使用標準化表示法，規定圖形元素與建構規則，但不提供完整語意處理。UML 和 SysML 屬於此類，大多數商用建模工具也採用此類表示法
• 正式表示法（Formal） — 具備精確（通常以數學為基礎）語意的表示法。一般稱為架構描述語言（ADLs），提供圖形詞彙和底層語意。實務上，正式表示法的使用相當罕見

更正式的表示法需要更多時間和精力來建立與理解，但透過減少歧義和更多分析機會來回報投入。不同的表示法適合表達不同類型的資訊 — UML 類別圖無法幫你推理排程性，序列圖也無法告訴你系統能否如期交付。

視圖（Views）#

軟體架構文件最重要的概念就是視圖（view）。軟體架構是複雜實體，無法以單一維度描述。視圖是系統元素及其關係的一種表示，只呈現特定類型的元素。

文件化架構就是文件化相關的視圖，再加上跨視圖的文件。

選擇哪些視圖取決於你的目標，而不同視圖以不同程度暴露不同品質屬性。文件化多少視圖是成本／效益的決策 — 每個視圖都有其成本與效益。

視圖的選擇由設計中所使用的模式驅動：module views、component-and-connector（C&C）views、allocation views，分別對應 Chapter 1 的三類架構結構，加上 quality views。

Module Views（模組視圖）#

**模組（module）**是提供一組連貫責任的實作單元，可以是 class、class 的集合、layer、aspect 或其他分解單位。

模組的關鍵屬性包括：

• 名稱（Name） — 主要識別手段，可能反映分解層級（如 A.B.C）
• 責任（Responsibilities） — 確立模組在整體系統中的角色
• 實作資訊 — 包括源碼檔案映射、測試資訊、管理資訊、實作限制、修訂歷史

模組視圖是靜態的功能分割，難以用來推理執行期行為。因此通常不適用於效能、可靠性等執行期品質的分析 — 這些需依賴 C&C 和 allocation views。

Component-and-Connector Views（C&C 視圖）#

C&C 視圖呈現具有執行期存在的元素，如 processes、services、objects、clients、servers 和 data stores，稱為元件（components）。交互路徑（如通訊連結、協定、資訊流、共享儲存存取）稱為連接器（connectors）。

連接器的範例：

• Service invocation
• Asynchronous message queues
• Event multicast（publish-subscribe）
• Pipes（非同步、保序的資料流）
• Transaction-oriented communication channel
• Enterprise service bus

C&C 視圖中的主要關係是 attachment：元件與連接器相連形成圖（graph）。相容性通常以資訊類型和協定定義。

元素的典型屬性：

• Reliability — 元件或連接器的故障可能性
• Performance — 回應時間、頻寬、延遲、抖動
• Resource requirements — 處理與儲存需求、能源消耗
• Functionality — 元素執行的功能
• Security — 加密、稽核追蹤、認證等安全功能
• Concurrency — 是否作為獨立行程或執行緒執行
• Runtime extensibility — 訊息結構是否支援演進中的資料交換

C&C 視圖常用於展示系統如何運作（可「動畫化」呈現端對端活動軌跡）以及推理執行期品質屬性（如效能和可用性）。

Allocation Views（配置視圖）#

配置視圖描述軟體單元到環境元素的映射，環境可以是硬體、作業系統環境、檔案系統或開發組織。

配置視圖的目標之一是比較軟體元素所需要的屬性與環境元素所提供的屬性，判斷配置是否成功。視圖可以是靜態的（固定資源配置）或動態的（條件觸發下配置變更，如負載平衡）。

Quality Views（品質視圖）#

當特定品質屬性特別重要且遍及多個結構時，結構性視圖未必是呈現架構解決方案的最佳方式。品質視圖透過擷取結構性視圖的相關片段並組合而成：

• Security view — 顯示所有安全相關的元件、通訊、資料儲存、安全協定及威脅回應
• Communications view — 元件間通道、網路通道、QoS 參數、併發區域
• Exception/Error-handling view — 錯誤偵測、報告與解決機制
• Reliability view — 複製、切換、時序議題與交易完整性
• Performance view — 網路流量模型、操作的最大延遲等

組合視圖（Combining Views）#

因為所有視圖描述的是同一個架構、為達共同目的而存在，許多視圖之間有強關聯。當兩個視圖之間的關聯特別緊密時，可將它們折疊為一個組合視圖（combined view）。最簡單的方式是建立疊加（overlay）。

常見的自然組合：

• C&C 視圖彼此 — 因為都呈現元件與連接器之間的執行期關係
• Deployment view 與顯示行程的 C&C view — 行程就是部署到處理器、VM 或容器上的元件
• Decomposition view 與 work assignment、implementation、uses 或 layered views — 分解的模組構成工作、開發和使用的單位

上圖展示了一個組合視圖範例，疊加了 client-server、multi-tier 和 deployment views。

文件化行為（Documenting Behavior）#

行為文件補充結構性視圖，描述架構元素之間如何互動。推理死鎖、任務完成時間、最大記憶體消耗等特性，需要行為資訊。兩種主要表示法：

Trace-Oriented（軌跡導向）#

描述系統在特定狀態下對特定刺激的回應序列。

• Use Cases — 描述 actors 如何使用系統達成目標，包含名稱、描述、主要/次要 actors、事件流、替代流、非成功案例
• Sequence Diagrams（序列圖） — 顯示元素實例之間的互動序列，兩個維度：垂直（時間）和水平（實例）。適合識別需要定義介面的地方

• Communication Diagrams — 顯示互動元素的圖形，每個互動標註順序編號。適用於驗證架構能否滿足功能需求，但不適合理解併發操作
• Activity Diagrams（活動圖） — 類似流程圖，顯示業務流程的步驟序列，支援條件分支與併發表達。Fork node 將流程分為多個併發流，Join node 同步併發流

Comprehensive（全面性表示法）#

呈現結構元素的完整行為，可從初始狀態推導所有可能路徑。

• State Machine Diagrams（狀態機圖） — 以方框表示狀態、箭頭表示轉換，每個轉換標註觸發事件。可選擇指定 guard condition（方括號內）和 action/effect（斜線後）

超越視圖（Beyond Views）#

除了視圖和行為，完整的架構文件還應包含：

• 視圖間的映射（Mapping Between Views） — 元素之間的關聯通常是多對多的，可用表格方便地捕捉，標註關聯類型如「is implemented by」、「implements」、「included in」
• 模式文件（Documenting Patterns） — 記錄所使用的模式、為何選擇此方案，以及模式實例化過程中的設計決策
• 情境圖（Context Diagrams） — 顯示系統或部分系統如何與環境互動。環境中的實體可以是人、其他系統或物理對象
• 變異指南（Variability Guide） — 說明如何運用架構中的變異點
• 設計理據（Rationale） — 解釋設計為何呈現目前形式，並提供其合理性的論證
• 術語表與縮寫清單（Glossary & Acronym List） — 確保所有利害關係人使用相同語言
• 文件控制資訊（Document Control Information） — 發行組織、版本號、發行日期、變更歷史

文件化設計理據（Documenting the Rationale）#

設計時你會做出重要的設計決策：

• 從多個替代方案中選擇設計概念
• 透過實例化所選概念來建立結構
• 建立元素間的關係與定義介面
• 分配資源（人員、硬體、運算）

當你檢視代表架構的圖表時，你看到的是思考過程的最終產物，卻未必能理解達成此結果的決策。記錄設計理據對於促進設計分析、實作、以及後續的架構理解至關重要。

記錄設計決策的最低限度可使用簡單表格：

更完整的記錄還可包含：產生了什麼證據？誰做了什麼？為何採取捷徑？為何做了權衡？做了什麼假設？

在識別元素時就應記錄設計決策 — 如果留到之後，你將不會記得當初為何這樣做。架構文件是你寫給未來自己的情書。

架構利害關係人（Architecture Stakeholders）#

不同利害關係人對架構文件有不同需求。以下列出主要利害關係人及其典型文件需求：

專案管理者（Project Managers）#

• 關注：排程、資源分配、可能的子集釋出
• 需要的視圖：Module views（Decomposition、Uses/Layered）、Allocation views（Deployment、Work assignment）、頂層 context diagrams

開發團隊成員（Development Team Members）#

• 需要了解：系統概念、被分配的元素詳細資訊、介面、可利用的程式碼資產、必須滿足的限制
• 需要的視圖：Module views（Decomposition、Uses/Layered、Generalization）、C&C views、Allocation views（Deployment、Implementation、Installation）、介面文件、variability guide、rationale

測試者與整合者（Testers & Integrators）#

• 需要：介面文件進行黑箱測試、介面集合與行為規格、uses view 進行增量子集測試
• 需要的視圖：Module views（Decomposition、Uses、Data model）、所有 C&C views、Allocation views（Deployment、Install、Implementation）

測試者與整合者值得特別關注，因為專案花費在測試上的精力通常佔整體的約一半。

其他系統設計者#

• 需要：互動元素的介面文件、資料模型、頂層 context diagrams

維護者（Maintainers）#

• 需要與開發者相同的資訊，加上 decomposition view（定位變更位置）、uses view（影響分析）、設計理據（了解架構師的原始思考、避免重複探索已棄用的替代方案）

終端使用者（End Users）#

• 雖然架構對使用者幾乎不可見，但檢視架構可揭露設計差異
• 可能感興趣的：顯示控制流和資料轉換的 C&C views、Deployment view、Context diagrams

分析師（Analysts）#

• 需要評估品質目標的資訊，可能需要存取文件的任何部分

基礎設施支援人員#

• 需要的視圖：Module views、C&C views、Allocation views、Variability guides

未來的架構師#

• 最熱衷的文件讀者，對所有內容都有興趣
• 特別渴望全面且坦誠的 rationale 和設計資訊

實務考量（Practical Considerations）#

建模工具#

許多商用建模工具支援以定義好的表示法指定架構構件；SysML 是廣泛使用的選擇。這些工具常提供：多使用者介面、版本控制、語法與語意一致性檢查、模型與需求/測試之間的追蹤連結，甚至自動產生可執行程式碼。

線上文件、超文本與 Wiki#

文件可結構化為連結的網頁，使用 wiki 等工具建立共享文件。組織需決定給各利害關係人的權限 — 允許指定的利害關係人評論和補充說明，但只有特定團隊人員能實際修改架構。

遵循發布策略#

專案開發計畫應規定保持重要文件（包括架構文件）更新的流程。文件產出物應受版本控制管理，架構師應計畫在支援主要專案里程碑時發布文件版本（例如，在每次迭代、衝刺或增量發布結束時）。

動態變化的架構文件化#

無論是執行期變化還是高頻率釋出-部署，所有動態架構的共同點是它們的變化速度遠快於文件化週期。應對策略：

• 文件化所有版本的不變量 — 如插件必須具備的特定屬性和介面，以及在架構中的預定位置
• 文件化架構允許的變更方式 — 通常是新增元件或以新實作替換元件
• 自動產生介面文件 — 若使用明確的介面機制（如 protocol buffers），總有最新的元件介面定義

可追蹤性（Traceability）#

架構存在於一個包含需求、程式碼、測試、預算與排程的資訊環境中。可追蹤性意味著將特定設計決策連結到促成它們的特定需求或商業目標。若所有 ASRs 都在追蹤連結中被涵蓋，我們就有信心架構部分是正確的。

本章總結#

• 撰寫架構文件如同其他寫作：黃金法則是認識你的讀者
• 架構是複雜的產出物，最好透過聚焦於特定視角的**視圖（views）**來表達
• 需選擇要文件化的視圖與表示法，可能需要組合重疊度高的視圖
• 除了結構，還必須文件化行為
• 補充文件包括：視圖間的關係、使用的模式、系統情境、變異機制、設計理據
• 實務上需考量發布策略、散佈工具（如 wiki）以及動態架構的文件化