軟體架構通常是一項溝通上的挑戰。團隊在系統如何運作、資料如何流動以及邊界位於何處等問題上難以達成共識。若無標準化的做法，圖表便會變得雜亂、令人困惑或過於細節化。C4模型提供了一種結構化的層級架構，用於建立軟體架構圖。它讓團隊能夠以不同細節層級來視覺化系統結構。
本指南探討C4模型的四個層級。我們將分析何時應使用每一層級、目標受眾是誰，以及如何在技術文件中保持清晰度。透過遵循此框架，團隊可確保架構知識始終保持可取得且準確。
📊 C4模型概覽
C4模型代表上下文（Context）、容器（Containers）、組件（Components）與程式碼（Code）。它是一種由整體視角逐步深入至具體實作的層級結構。每一層級針對不同利害關係人回答不同的問題。該模型具有技術無關性，意指其著重於結構與責任，而非特定程式語言或平台。
使用單一圖表來解釋所有內容，通常會導致認知負荷過重。C4模型透過鼓勵為同一系統使用多張圖表，每張圖表以不同深度進行縮放，來解決此問題。
以下是四個層級的總結：
| 層級 | 名稱 | 焦點 | 典型受眾 | 細粒度 |
|---|---|---|---|---|
| 1 | 上下文 | 系統邊界 | 利害關係人、經理 | 低 |
| 2 | 容器 | 技術選擇 | 開發人員、架構師 | 中 |
| 3 | 組件 | 內部邏輯 | 開發人員 | 高 |
| 4 | 程式碼 | 實作細節 | 開發人員、代碼審查員 | 極高 |
🌍 第一級：系統背景
第一級提供整體概覽。它回答了這樣的問題：「這個系統如何融入更廣泛的世界？」此圖通常作為任何架構討論的起點。
🎯 目的與目標受眾
第一級圖示的主要目標是明確範圍。它針對廣泛的受眾設計，包括產品經理、業務利益相關者以及新團隊成員。這些人士需要理解價值主張與外部依賴關係，而不必陷入技術細節。
📝 應包含的內容
背景圖應包含以下元素：
- 系統本身：以中央方框表示。這是指正在記錄的軟體或服務。
- 人員：與系統互動的使用者或參與者。包括管理員、終端使用者或外部客戶。
- 其他系統：系統所溝通的外部服務。範例包括支付網關、電子郵件服務或舊有資料庫。
- 關係：連接系統與人員或其他系統的線條。這些線條代表資料流或互動。
🚫 應避免的內容
在此階段不要包含內部細節。避免顯示特定伺服器、資料庫表格或 API 端點。保持視圖抽象，可確保即使內部技術變更，圖示仍保持有效。
📦 第二級：容器
一旦邊界確定，第二級便會放大，揭示系統的組成部分。容器是一種高階構建模塊，代表一個獨立的執行環境。
🎯 目的與目標受眾
第二級圖示主要針對開發人員與架構師。他們需要了解系統如何部署以及使用了哪些技術。此級別彌補了業務需求與技術實現之間的差距。
📝 應包含的內容
容器圖將第一級的系統方框拆解為其組成部分。常見元素包括：
- 網頁應用程式：瀏覽器介面或單頁應用程式（SPAs）。
- 行動應用程式：iOS 或 Android 的原生應用程式。
- 伺服器端應用程式：在伺服器或雲端平台運行的後端服務。
- 資料庫：持久化儲存系統，無論是 SQL 或 NoSQL。
- 雲端服務：由第三方提供的管理服務，例如物件儲存或訊息佇列。
容器之間的連接應顯示它們如何通訊。這可能涉及 HTTP、TCP/IP 或資料庫查詢等協定。
🚫 避免事項
除非微服務是獨立的容器，否則避免顯示特定的微服務。不要列出容器內的每個函數或類別。如果容器包含許多服務，最好將它們拆分為獨立的圖表，而不是讓視圖混雜不清。
⚙️ 第三級：組件
第三級專注於單一容器的內部結構。它將容器分解為較小且可管理的單元，稱為組件。
🎯 目的與目標對象
此級別適用於系統內的開發人員。它幫助他們理解特定功能位於哪裡，以及程式碼庫的不同部分如何互動。這對於新工程師的入職培訓和功能規劃至關重要。
📝 應包含的內容
組件是功能的邏輯分組。它們可以代表：
- 軟體程式庫：可重用的程式碼區塊。
- 模組：應用程式邏輯的明確區段。
- 類別：特定的物件導向結構。
- 函數：獨立的程序或方法。
關鍵在於根據責任來分組組件。組件應具有明確的目的。例如，「付款處理」組件可能包含驗證信用卡和與閘道通訊的邏輯。
🚫 避免事項
不要繪製系統中的每一個類別。這會導致圖表無法閱讀。應專注於主要的架構決策和關鍵路徑。如果組件過於複雜，可能需要獨立的子圖表。
💻 第四級：程式碼
第四級是最細緻的層級。它處理實際的程式碼結構。然而，此層級通常是可選的。許多團隊發現第三級已足以應付大多數架構文件。
🎯 目的與目標對象
程式碼圖表是為需要理解特定實作細節的開發人員設計的。它們對於複雜的演算法、關鍵的安全流程或效能敏感的區段非常有用。
📝 應包含的內容
在此層級，您可能需要呈現：
- 序列圖： 顯示物件之間操作的順序。
- 類別圖： 顯示類別之間的繼承關係與關聯。
- 資料結構： 在記憶體中使用的特定資料模型。
此層級經常與標準的軟體工程文件重疊。C4模型建議謹慎使用，以避免維護上的負擔。
🚫 避免事項
除非變數名稱或特定方法簽章對架構至關重要，否則不要包含。若需記錄特定的程式碼邏輯，使用程式碼註解或專用的技術wiki頁面，通常比圖示更佳。
🛠️ 圖示維護的最佳實務
建立圖示僅是工作的一半。持續保持其準確性至關重要。過時的圖示可能誤導團隊，並造成技術負債。
🔄 與工作流程的整合
將圖示更新整合至您的開發流程中。將架構文件視為程式碼。當拉取請求變更系統結構時，也應同步更新相關圖示。這能確保文件隨著軟體一同演進。
👥 協作式所有權
將圖示的所有權指派給特定團隊成員。隨著團隊擴大，單一個人無法維護所有架構文件。應為每個容器或組件層級指定負責人。
🎨 視覺一致性
使用一致的風格指南。為不同類型的元素定義顏色（例如：藍色代表人員，綠色代表資料庫）。這有助於讀者快速瀏覽圖示，並在不閱讀每個標籤的情況下理解結構。
📉 應避免的常見陷阱
即使擁有良好的模型，團隊仍可能犯錯。了解常見錯誤有助於維持文件品質。
❌ 混合層級
最常見的問題之一是在單一圖示中混合不同層級。不要在情境圖中顯示程式碼類別。保持抽象層級分離。若圖示看起來令人困惑，請檢查是否縮放過度或不足。
❌ 過度設計
並非每個系統都需要第四層圖示。若系統較簡單，第二層可能已足夠。不要在無價值處強行套用模型。從小處著手，僅在必要時才增加細節。
❌ 忽略關係
只關注方框與線條，卻忽略了連接的意義。確保每條線都有標籤，說明所交換的資料或協定。未標示的箭頭對理解系統行為毫無幫助。
📈 C4模型的優勢
採用這種結構化方法為技術團隊帶來多項優勢。
- 共識理解： 每個人對於系統邊界與責任都使用相同的語言。
- 更快的上手： 新員工可以從第1層開始並逐步深入，快速理解系統結構。
- 降低複雜度： 將系統分解為層次結構，使其更容易進行推理。
- 彈性： 該模型適用於單體應用、微服務，或介於兩者之間的任何系統。
🔍 何時停止文件編寫
存在報酬遞減的點。如果你花在更新圖表上的時間比寫程式還多，很可能就是過度文件化了。請運用你的判斷力。
問問自己：
- 這張圖表是否幫助我理解系統？
- 這張圖表是否能幫助其他人理解系統？
- 更新這張圖表的成本是否太高？
如果最後一個問題的答案是肯定的，請簡化圖表或將其移除。目標是清晰，而非完整。
🚀 總結
C4模型提供了一種實用的方法來管理軟體架構文件。透過將關注點分為上下文、容器、組件和程式碼，團隊可以在堆疊的每一層進行有效溝通。它鼓勵採用分層方法，防止圖表變得令人不堪負荷。
從整體視角出發，定義邊界，然後僅根據受眾需求深入到必要的層級。將圖表與程式碼同步維護。這種有紀律的方法能帶來更好的軟體設計與更順暢的協作。