軟體架構文件經常面臨一個簡單的問題：不是完全沒有，就是細節過於繁雜，導致沒有人願意閱讀。團隊花上數週建立龐大的維基，但只要程式碼一變動，這些文件立刻過時。C4 模型提供了一個實用的解決方案。它提供了一種結構化的方式，可在不同抽象層次上呈現軟體架構。透過專注於系統脈絡, 容器, 組件，以及程式碼，您就能建立出對整個團隊都有用、易於維護且具價值的文件。
本指南將從基礎開始帶您了解 C4 模型。您將學會如何記錄複雜系統，而不會陷入技術細節的泥沼。無論您是協助新工程師入職，還是重構舊有應用程式，這種方法都能確保您的文件隨著軟體的發展而同步擴展。
🤔 什麼是 C4 模型？
C4 模型是一種層級式的軟體架構文件方法。它被設計來解決傳統 UML 圖表的限制，這些圖表往往會迅速變得過於複雜。與試圖在單一圖表中捕捉每個類別與介面不同，C4 將系統分解為可管理的層級。每一層都針對系統回答一個特定問題。
這種層級結構確保利害關係人能輕鬆找到所需資訊，而不會感到壓力過大。經理可能只需要看到系統脈絡圖。負責特定模組的開發者可能只需要查看組件圖。模型會適應觀眾的需求，而不是反過來。
抽象的四個層級
要有效實施 C4 模型，您必須理解這四個截然不同的層級。每一層代表不同的範圍與對象。
- 第一層：系統脈絡圖 – 宏觀視角。顯示您的系統及其使用者。
- 第二層：容器圖 – 技術堆疊。顯示高階的構建模組。
- 第三層：組件圖 – 內部邏輯。顯示容器內的各個部分。
- 第四層：程式碼圖 – 實作細節。顯示類別與關係。
大多數團隊發現，第一至第三層已涵蓋 95% 的文件需求。第四層是可選的，通常僅用於複雜的演算法或特定的架構模式。
🌍 第一層：系統脈絡圖
系統脈絡圖是您的起點。它回答了一個根本問題：這個系統做什麼，誰在使用它？。此圖表專為非技術相關的利害關係人設計，包括企業所有者、產品經理與新進員工。
在此視圖中，您的系統以中央的一個方框來表示。方框周圍是與其互動的外部實體。這些實體包括人員（如使用者或管理員）以及其他軟體系統（如付款網關或第三方 API）。
應包含的關鍵要素
- 人員： 哪些人與系統互動？（例如：顧客、管理員、支援人員）
- 系統： 您的系統與哪些其他軟體進行溝通？（例如：電子郵件服務、資料庫、客戶關係管理系統）
- 關係： 它們如何互動？使用箭頭來顯示資料流動方向。
- 標籤： 清楚標示資料交換的方向與類型。
保持此圖表簡潔。不要包含內部細節。如果你發現自己在加入內部組件，表示你已經進入第二層的範疇。目標是明確界定系統的邊界。
範例情境
想像一個電子商務平台。在系統上下文圖中，你會看到「電子商務平台」的方框。你會看到一個「顧客」方框連接到它以下訂單。你會看到一個「付款網關」方框連接到它以處理交易。你會看到一個「庫存系統」方框連接到它以進行庫存查詢。這就是第一層的全部範圍。
📦 第二層：容器圖
一旦邊界確定，你就可以進行細節探查。容器圖揭示了高階的技術架構。一個「容器」是可部署的軟體單元。範例包括網頁應用程式、行動應用程式、資料庫和微服務。
此圖表對開發人員至關重要。它顯示系統在實體或邏輯上的分離方式。它有助於回答諸如「後端是單體架構還是微服務？」或「我們使用哪種資料庫技術？」等問題。
定義容器
繪製此圖表時，請識別所使用的不同技術。每個容器應代表一個獨立的執行環境。
- 網頁應用程式： 通常在瀏覽器或伺服器上執行。
- 行動應用程式： 在使用者的裝置上執行。
- 資料庫： 儲存持久性資料。
- 微服務： 具有獨立部署能力的獨立服務。
使用箭頭連接這些容器，以顯示通訊路徑。以所使用的通訊協定（例如 HTTP、TCP 或 SQL）標示這些連接。
第二層的最佳實務
- 依技術分組：如果您有同一技術的多個執行個體，請邏輯性地將它們分組。
- 顯示邊界：明確指出哪個容器屬於您的系統，哪個屬於外部服務。
- 專注於通訊：箭頭與方框一樣重要，它們顯示資料流和依賴關係。
⚙️ 第3級：組件圖
現在您需要更深入。組件圖將單一容器分解為其內部組件。一個組件是容器內功能的邏輯分組。它不是實體檔案，而是一個行為上一致的單元。
此層級適用於系統內部的開發人員。它幫助他們理解內部架構，而無需閱讀原始碼。它回答的問題是：「這個應用程式內部是如何組織的？」
識別組件
組件應為類別或函數的邏輯分組。範例包括：
- 驗證服務：處理使用者登入與會話管理。
- 訂單處理器：處理建立訂單的邏輯。
- 報表引擎：產生資料摘要。
不要列出每個類別。僅列出對架構理解重要的組件。如果某個組件過於微小，此層級可能更適合忽略它。
映射關係
與前幾層相同，顯示組件之間如何互動。使用箭頭表示依賴關係，並以所使用的方法呼叫或介面標示箭頭。
| 圖表層級 | 受眾 | 重點 | 細節層級 |
|---|---|---|---|
| 第1級：系統上下文 | 利害關係人、經理 | 邊界與使用者 | 高 |
| 第2級：容器 | 開發人員、DevOps | 技術堆疊 | 中等 |
| 第3級：組件 | 開發人員 | 內部邏輯 | 低 |
| 第4級：程式碼 | 資深開發人員 | 類別與介面 | 極低 |
💻 第4級：程式碼圖
最後一級深入探討實作細節。此圖顯示類別、介面及其關係。基本上就是類別圖。
對於大多數專案而言，此級別並非必要。它變動過於頻繁，難以維護。若要理解程式碼，應直接閱讀程式碼。然而，對於複雜的演算法或關鍵的安全模組，此級別可能有所幫助。
何時使用第4級
- 複雜演算法： 當邏輯非顯而易見，需要視覺化說明時。
- 安全關鍵路徑： 當理解資料流程對安全審計至關重要時。
- 舊系統： 當文件遺失，程式碼是唯一真實來源時。
如果你發現自己花在繪製第4級圖表的時間比寫程式碼還多，很可能就是過度文件化了。應謹慎使用此級別。
🛠️ 繪製圖表
你不需要昂貴的工具來製作這些圖表。C4模型與工具無關。你可以使用文字編輯器、通用圖表軟體，或以程式碼為基礎的定義語言。關鍵在於一致性。
流程
- 從第1級開始： 定義你的系統邊界。
- 轉至第2級： 識別你的容器與技術。
- 深入到第3級： 將您的容器分解為組件。
- 審查： 檢查圖表是否與程式碼一致。
- 更新： 當架構變更時，隨時更新圖表。
工具考量
- 基於文字： 將您的圖表寫在文字檔案中。這允許進行版本控制。
- 視覺編輯器： 使用拖放工具進行快速草圖繪製。
- 基於程式碼： 在程式碼中定義圖表。這可確保它們與程式庫保持同步。
無論您選擇哪一種，都請確保團隊同意標準。一致性比特定工具更重要。
🔄 維護與演進
如果不加以維護，文件就會死亡。一個常見的陷阱是只建立一次圖表卻從不更新。為避免此情況，請將文件整合到您的工作流程中。
文件即程式碼
將您的圖表儲存在與原始碼相同的程式庫中。這可確保它們一同進行版本控制。當您合併拉取請求時，理想情況下也應更新圖表。
自動化更新
如果您使用基於程式碼的定義，可以自動產生圖像。這能減少保持圖表更新的阻力。然而，仍需手動審查以確保邏輯正確。
排程審查
- 每季： 計畫一次審查會議以檢查圖表的準確性。
- 重構期間： 將更新圖表作為重構任務的一部分。
- 新功能： 在引入重大新功能時更新圖表。
🚫 常見陷阱
即使有結構化的模型，團隊仍會犯錯。了解這些陷阱將節省您的時間與煩惱。
1. 過度細節化
不要試圖顯示第三層中的每個類別。這會導致混亂與困惑。應專注於高階組件。若開發人員需要細節，他們可直接查看程式碼。
2. 忽略觀眾
不要向產品經理展示第3級圖表。他們不關心組件。展示第1級圖表給他們。根據閱讀對象來調整圖表。
3. 舊資料
不要讓圖表過時。如果圖表與程式碼不符，那比沒有圖表更糟糕。這會造成錯誤的信心。
4. 混合層級
不要在同一頁上混合使用第1級和第2級圖表。保持層級結構清晰。如果需要顯示更多細節，請建立新的圖表。
💡 成功的最佳實務
為了充分發揮C4模型的效益，請遵循這些指南。它們將幫助你維持健康的文件文化。
- 保持簡單： 使用簡單的形狀和標籤。避免使用複雜的符號。
- 使用一致的顏色： 使用顏色來表示狀態或類型，但請在所有圖表中保持一致。
- 著重於流程： 強調資料如何在系統中流動，而不僅僅是儲存方式。
- 迭代： 從粗略草圖開始。隨著時間推移不斷完善。
- 分享： 將圖表放在你的維基或程式碼庫中。讓所有人都能輕鬆取得。
🤝 與開發流程整合
文件不應是獨立的任務。它應該是開發流程的一部分。這樣才能確保從一開始就考慮架構。
設計審查
在撰寫程式碼之前進行設計審查。使用C4圖表作為主要溝通工具。這有助於早期發現架構問題。
入職訓練
為新進人員使用第1級和第2級圖表。這能幫助他們快速理解系統，而無需閱讀數千行程式碼。
重構
在重構之前，先更新圖表。這能幫助你理解變更的影響。重構後，確認圖表與新的結構相符。
🌟 結論
C4模型是管理軟體架構文件的強大工具。它提供了一個清晰的結構，能隨著你的系統擴展。透過針對正確的觀眾，聚焦於適當的細節層級，你可以建立真正被使用的文件。
從系統背景開始。定義你的邊界。然後依需求逐步深入。保持圖表更新。記住，目標是溝通，而非完美。只要遵循這些實務，你就能在幾小時內完成系統文件，而不是幾週。
