軟體架構經常被誤解為僅僅是在白板上畫方框。實際上，它是一門溝通學科，能夠彌合技術實現與商業理解之間的差距。C4 模型提供了一種結構化的方法，用於在不同抽象層次上可視化軟體架構。本指南探討每一層的內容，詳細說明何時應用它們、誰應該查看它們，以及它們如何相互結合，從而為你的系統呈現出一個連貫的圖像。
🌍 為何要標準化架構圖繪製？
若無標準，團隊經常會繪製出過於模糊而無用，或過於細節而難以維護的圖表。有些團隊在商業利益相關者需要流程概覽時，卻繪製網路圖；另一些團隊在開發人員僅需理解資料流時，卻創建類圖。C4 模型透過定義四個特定層級來解決此問題，每一層都有其獨特的目的與對象。
核心理念很簡單：一張圖無法呈現所有內容。相反，你應建立一組圖表，如同地圖般進行縮放。世界地圖顯示國家，城市地圖顯示街道，街道地圖顯示單棟建築。C4 模型將此邏輯應用於軟體。
📍 第一層：系統上下文
系統上下文圖是高階視圖。它回答的問題是：「這個系統做什麼，誰在使用它？」這通常是開始新專案或記錄現有系統時首先繪製的圖表。
🎯 主要觀眾
- 商業利益相關者：產品經理、高階主管與客戶，他們需要理解範圍，但不需技術術語。
- 新團隊成員：加入專案的開發人員，他們需要快速掌握生態系統的概況。
- 外部合作夥伴：第三方供應商，他們需要了解自己的系統如何與你的系統互動。
📦 圖中包含哪些內容？
系統上下文圖由三個明確的元素組成：
- 一個軟體系統：這是要描述的系統。它位於圖表的中心位置。
- 人員：與系統互動的使用者。這可能包括終端使用者、管理員或支援人員。
- 其他系統：與你的系統互動的外部軟體系統。這包括 API、資料庫或舊有平台。
🔗 關係與信任
線條將中心系統與人員及其他系統相連。這些線條代表關係與資料流。明確標示互動方向至關重要。例如，系統是將資料推送到外部系統，還是從外部系統拉取資料？
信任邊界也常在此處可視化。虛線可能將你的系統與外部合作夥伴分開，表示信任程度較低或屬於不同的安全領域。這有助於安全團隊理解邊界所在位置。
🏭 第二層：容器
一旦理解了上下文，我們便開始縮放。容器層回答的問題是：「這個系統的主要構建模塊是什麼？」容器是一種獨立的執行環境。它不是微服務，儘管微服務是容器。它也不是資料庫，儘管資料庫也是容器。它是一個自包含的部署單元。
🎯 主要觀眾
- 開發人員：需要理解技術堆疊與邊界的工程師。
- DevOps工程師：負責部署、擴展和監控的團隊。
- 架構師：設計系統不同部分之間整合模式的人。
📦 內部包含什麼？
容器圖將Level 1中的單一「軟體系統」分解為其組成部分。典型的容器包括：
- 網頁應用程式：瀏覽器為基礎的前端（例如：React、Angular應用程式）。
- 行動應用程式：iOS 或 Android 原生應用程式。
- API：REST、GraphQL 或 gRPC 端點。
- 資料庫系統：SQL 或 NoSQL 儲存。
- 命令列工具：用於維護的指令碼或工具。
🔗 互動
容器之間的連接顯示它們如何通訊。明確指出所使用的協定非常重要。是 HTTP 嗎？是像 RabbitMQ 這樣的訊息佇列嗎？還是直接的 TCP 連接？
與 Level 1 不同，Level 2 圖通常會包含容器之間的信任邊界。例如，網頁應用程式可能位於 DMZ（非軍事區），而資料庫則位於安全的內部網路中。可視化這種分離有助於在設計階段早期識別安全風險。
🧩 Level 3：組件
進一步放大，組件層次回答：「容器內部是什麼？」這正是系統邏輯所在之處。它將容器分解為更小且緊密結合的單元。一個容器可以包含許多組件，但一個組件僅屬於一個容器。
🎯 主要受眾
- 軟體工程師：撰寫實際程式碼的開發者。
- 系統設計師：定義應用程式內部結構的人。
- QA工程師：根據特定邏輯流程規劃測試案例的團隊。
📦 內部包含什麼？
組件代表功能的邏輯分組。它們不是實體檔案，而是概念模組。範例包括：
- 身份驗證服務： 處理登入和會話管理。
- 支付處理器： 與銀行 API 介接。
- 報表引擎： 產生 PDF 或資料視覺化圖表。
- 快取管理器： 處理記憶體中的資料儲存。
🔗 內部邏輯
在此層級，重點從部署轉移到邏輯。組件之間的連接顯示資料如何在應用程式中流動。你可能會從「使用者介面」組件畫一條線到「商業邏輯」組件，再連接到「資料存取」組件。
此層級對於理解耦合至關重要。如果兩個組件有許多依賴關係，可能需要重構。如果某個組件沒有任何依賴，它可能是獨立的工具類型，可移至其他容器中。
💻 第四層：程式碼
最後一層是程式碼層。它回答的問題是：「這個組件是如何實作的？」此圖顯示類別、介面和方法。這是細節最豐富的視圖，通常不會用於高階架構討論。
🎯 主要對象
- 初級開發人員： 學習程式碼庫結構的人。
- 程式碼審查者： 分析特定邏輯路徑的人。
📦 內容包含什麼？
程式碼圖形看起來像類別圖。它們顯示：
- 類別名稱。
- 屬性（變數）。
- 方法（函數）。
- 關係（繼承、組合、關聯）。
🔗 何時使用
第四層圖形可能變得極其複雜且難以維護。程式碼經常變動。如果圖形與程式碼不同步，就會變成雜訊。因此，此層級應謹慎使用。
它最適合用於複雜的演算法或特定設計模式，其中理解類別之間的互動至關重要。對於大多數架構討論，第三層已足夠。如果你發現自己需要為每項決策都使用第四層，那麼架構可能對於當前討論而言過於細節。
📊 C4 層級比較
為釐清差異，下表總結了各層級的範圍、目標對象與維護頻率。
| 層級 | 重點 | 主要受眾 | 細節程度 | 維護努力程度 |
|---|---|---|---|---|
| 等級 1 | 系統環境 | 利益相關者、新進人員 | 高 (1 個系統) | 低 (很少變動) |
| 等級 2 | 容器 | 開發人員、DevOps | 中等 (5-15 個容器) | 中等 (隨著部署而變動) |
| 等級 3 | 組件 | 工程師、設計師 | 低 (每個容器多個) | 高 (隨著功能變動) |
| 等級 4 | 程式碼 | 初階開發人員、審查者 | 極低 (類別/方法) | 極高 (隨著提交變動) |
🛠️ 文件編寫的最佳實務
建立圖表很容易；保持圖表實用卻很困難。以下是一些策略，可確保您的架構文件能長期保持價值。
📝 保持更新
過時的圖表比沒有圖表更糟糕，它會造成錯誤的信心。當系統發生變更時，請更新圖表。若有可能，將圖表更新整合至您的部署流程中，或將其列為合併請求的必要條件。
🎨 使用一致的符號
確保每張圖表都遵循相同的視覺規則。如果一個資料庫在某張圖表中是圓柱體，那麼在所有圖表中都應為圓柱體。如果使用者是小人圖，就一直保持這樣。一致性能降低讀者的認知負擔。
🚫 避免過度細節
不要在第二層圖中繪製每個 API 端點。專注於主要邊界。如果需要顯示所有端點，請建立獨立的 API 規格文件。圖表應提供地圖，而非每條街道的地址。
🔍 聚焦於「為什麼」
不要只展示現有的內容。解釋其存在的原因。在圖表中加入註解，說明設計決策。為什麼選擇了特定的資料庫？為什麼這兩個容器之間會有訊息佇列？這些註解提供了單靠圖畫無法傳達的背景資訊。
⚠️ 常見陷阱
即使經驗豐富的架構師在繪製圖表時也可能陷入陷阱。意識到這些常見錯誤有助於保持清晰。
❌ 「資料流」陷阱
許多團隊將架構與資料流混淆。圖表應呈現靜態結構：現有的元件及其連接方式。不應顯示事件的順序（例如：「使用者點擊按鈕 → API 呼叫資料庫 → 回應傳回」）。這屬於序列圖，而非 C4 圖。保持 C4 圖的靜態性，以避免混淆。
❌ 忽略信任邊界
安全性經常被視為事後補救。如果你有多個容器，應明確定義信任邊界。網頁應用程式是否直接信任資料庫？還是中間存在 API 層？錯誤地描述安全邊界可能導致生產環境出現漏洞。
❌ 使用錯誤的層級
向產品經理展示第三層細節會令人壓力過大。向開發人員展示第一層細節則不夠充分。應根據閱讀者的角色選擇合適的圖表層級。若無法確定，可提供概要視圖（第二層），並連結至詳細視圖（第三層）。
❌ 一圖定天下
試圖將整個系統塞入單一圖像會導致混亂。應接受層級結構。建立「系統上下文」頁面、「容器」頁面與「元件」頁面，並相互連結，讓使用者能依需求逐步深入檢視。
🔄 維護與演進
軟體並非靜態的。需求會變更，技術會演進，舊有程式碼也會被淘汰。C4 模型支援此演進過程，允許你僅更新特定層級，而無需重新繪製整個架構。
📅 圖表版本控制
與程式碼一樣，圖表也應具備版本控制。若發生重大架構變更，應建立圖表的新版本。這讓你能夠回溯並觀察系統如何隨時間演變。這對團隊而言是一份珍貴的歷史紀錄。
🤝 團隊協作
架構並非單人活動。鼓勵團隊成員參與圖表的建立。當開發人員更新程式碼時，他們通常是更新元件圖表的最佳人選。這能確保文件真實反映程式碼庫的實際狀況。
🏁 繼續前進
採用 C4 模型需要思維上的轉變。它將焦點從「繪製漂亮的圖畫」轉移到「創造實用的溝通工具」。透過理解每一層級的獨特目的，團隊能建立一套可隨著軟體複雜度增長而擴展的文件策略。
從第一層開始，以確保所有人對範圍達成共識。使用第二層定義技術邊界。使用第三層引導開發。僅在特定邏輯需要深入說明時才使用第四層。遵循這些原則，可確保你的架構文件始終是活躍的資產，而非被遺忘的陳舊資料。
目標是清晰。當新成員加入時，他們應能快速查看你的圖表並在數分鐘內理解系統。當利益相關者詢問變更的影響時，他們應能追蹤容器與元件之間的路徑。這才是 C4 模型的真正價值。
