C4 模型與 PlantUML 入門教程

軟件架構可視化的標準實踐，從理論到 AI 輔助落地

C4 模型是一種分層次、結構化的軟件架構描述方法，幫助團隊清晰地溝通複雜系統。本教程將帶你瞭解 C4 模型的核心理念，掌握用 PlantUML 繪製 C4 圖的方法，並推薦如何利用 Visual Paradigm 的 AI 工具提升效率。

1. 什麼是 C4 模型？

1.1 定義

C4 模型（Context、Containers、Components、Code）是由 Simon Brown 提出的軟件架構可視化框架，通過四個層次逐步細化系統架構：

• System Context（系統上下文）：展示系統與外部用户/系統的交互。
• Containers（容器）：拆解系統為獨立的部署單元（如微服務、數據庫、前端應用）。
• Components（組件）：深入單個容器內部，展示主要模塊及其關係。
• Code（代碼）：可選層，關注類/接口級別的設計（如 UML 類圖）。

此外，C4 模型還包括：

• System Landscape（系統全景圖）：展示企業級多系統間的關係。
• Dynamic Diagram（動態圖）：描述組件間的運行時交互。
• Deployment Diagram（部署圖）：映射軟件到硬件/雲資源。

1.2 為什麼使用 C4 模型？

1.3 適用場景

• 新項目設計：快速梳理系統架構，避免“先寫代碼後補文檔”。
• 遺留系統重構：通過 C4 圖理解現有系統，識別改進點。
• 團隊協作：統一語言，減少溝通誤差（如產品經理 vs 開發 vs 運維）。
• 技術分享：用 System Context 向非技術人員解釋系統。

2. 用 PlantUML 繪製 C4 模型

PlantUML 是一款文本化的圖形生成工具，支持 C4 模型語法，適合開發者快速繪圖。

2.1 準備工作

1. 安裝 PlantUML：

• 在線編輯器：PlantUML Web Server
• 本地安裝：需 Java 環境 + Graphviz（詳細教程）。

2. C4 PlantUML 庫： 引入官方 C4 庫（在 PlantUML 代碼中添加）：

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
' 可選：引入其他層次的庫（如 C4_Container、C4_Component）
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
@enduml
 

2.2 核心語法

System Context 圖

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

title System Context Diagram for "E-Commerce Platform"

Person(customer, "Customer", "End user browsing products")
System(ecommerce, "E-Commerce System", "Allows users to buy products online")

System_Ext(payment, "Payment Gateway", "Processes payments via credit card")
System_Ext(shipping, "Shipping Service", "Handles product delivery")

Rel(customer, ecommerce, "Browses products, places orders")
Rel(ecommerce, payment, "Processes payment")
Rel(ecommerce, shipping, "Arranges delivery")
@enduml

關鍵元素：

• Person()：用户/外部系統。
• System()：當前系統。
• System_Ext()：外部依賴系統。
• Rel()：關係描述。

Container 圖

@startuml
 !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.pumltitle Container Diagram for "E-Commerce System"
Person(customer, "Customer")
System_Boundary(ecommerce, "E-Commerce System") {
     Container(web_app, "Web Application", "Java/Spring Boot", "Handles user requests")
     Container(mobile_app, "Mobile App", "React Native", "Provides mobile UI")
     Container(api_gateway, "API Gateway", "Kong", "Routes requests to services")
     ContainerDb(database, "Database", "PostgreSQL", "Stores product/user data")
 }System_Ext(payment, "Payment Gateway")
Rel(customer, web_app, "Uses")
 Rel(customer, mobile_app, "Uses")
 Rel(web_app, api_gateway, "API Calls")
 Rel(mobile_app, api_gateway, "API Calls")
 Rel(api_gateway, database, "Reads/Writes")
 Rel(api_gateway, payment, "Processes payment")
 @enduml

關鍵元素：

• System_Boundary()：系統邊界。
• Container()：部署單元（如服務、數據庫）。
• ContainerDb()：數據庫容器。

Component 圖

2.3 AI 輔助生成 PlantUML

如果手寫 PlantUML 代碼繁瑣，可用 AI 工具（如 GitHub Copilot、Visual Paradigm AI）根據自然語言描述自動生成代碼： 示例提示詞：

“用 PlantUML C4 語法生成一個電商系統的 System Context 圖。系統名為‘在線商城’，外部用户是‘顧客’，外部系統包括‘支付網關’和‘物流服務’。顧客通過商城瀏覽商品並下單，商城調用支付網關處理支付，調用物流服務安排配送。”

AI 會返回可直接使用的 PlantUML 代碼。

3. Visual Paradigm AI 工具實戰

Visual Paradigm Desktop 2025.12 版本新增了原生 C4 模型支持，結合 AI 能力，讓繪圖更高效。

3.1 快速上手

1. 創建 C4 圖：

• 打開 Visual Paradigm → 新建圖表 → 選擇“C4 Model Diagram”。
• 選擇具體圖類型（如 System Context）。

2. 拖拽繪圖：

• 從左側工具欄拖動 Person、System、Container 等形狀到畫布。
• 雙擊形狀編輯名稱/描述。

3. AI 輔助生成：

• 點擊工具欄中的 AI Assistant 按鈕。
• 輸入自然語言描述（如“創建一個訂單管理系統的 Container 圖，包含 Web 前端、API 網關、訂單服務和 MySQL 數據庫”）。
• AI 會自動生成圖形草稿，供你微調。

3.2 最佳實踐

4. 實戰案例：微服務架構 C4 模型

場景：一個在線教育平台，包含用户服務、課程服務、支付服務和推薦系統。

4.1 System Context 圖

AI 生成提示詞：

“生成一個在線教育平台的 System Context 圖。外部用户是‘學生’和‘講師’，外部系統包括‘支付寶’和‘短信網關’。學生瀏覽課程並支付，講師上傳課程，平台發送短信通知。”

4.2 Container 圖

PlantUML 代碼：

4.3 Deployment 圖

Visual Paradigm AI 操作：

1. 打開 C4 Deployment Diagram。
2. 輸入提示詞：

“教育平台部署在 AWS 上，包含 2 個 EC2 實例（運行 API 網關和微服務）、1 個 RDS（PostgreSQL）、1 個 S3 存儲桶（存儲課程視頻）。使用 ALB 做負載均衡。”

1. AI 生成草圖後，手動調整細節。

5. 總結與建議

5.1 如何選擇？

• 快速繪圖 + 代碼集成：選擇 PlantUML。
• 團隊協作 + 文檔管理：選擇 Visual Paradigm。
• AI 輔助：兩者都支持，但 Visual Paradigm 的 AI 更智能（如自動佈局、標準檢查）。

5.2 下一步行動

1. 動手實踐：用 PlantUML 或 Visual Paradigm 繪製你當前項目的 System Context 圖。
2. 探索 AI：嘗試用 AI 生成一個 Container 圖，體驗效率提升。
3. 分享反饋：將繪製的 C4 圖分享給團隊，收集改進建議。

你是否已經在使用 C4 模型或 PlantUML？或者你更傾向於可視化工具如 Visual Paradigm？ 我很想了解你的選擇理由或遇到的挑戰！