以程式碼進行架構設計:PlantUML 與 Visual Paradigm 的 C4 建模完整指南

簡介

在現代軟體工程中,架構文件常遭受「文件腐蝕」的問題。在拖放式工具中建立的圖表,一旦匯出為靜態影像,便立即過時,逐漸偏離實際程式碼庫。解決方案在於將架構視為程式碼。

「C4 模型」提供了一種實用且具層級性的方法,以四個抽象層級來視覺化軟體架構:「系統情境, 容器, 元件」,以及「程式碼」。將 C4 方法論與「PlantUML」以及圖形即程式碼(Diagram-as-Code)工作流程,團隊可直接在原始程式碼旁維護具版本控制且高度同步的架構藍圖。

架構即程式碼:結合 PlantUML 的 C4 模型 " Visual Paradigm VPasCode

本指南探討如何運用 PlantUML 實作 C4 建模,並透過現代工具如「Visual Paradigm, VPasCode」,以及「AI 聊天機器人」,確保您的架構始終是開發過程中活生生、持續演進的產出物。


核心概念

在深入語法之前,必須先理解此方法的核心支柱:「

  • C4 層級結構:「」一種受數位地圖啟發的縮放隱喻。您從國家層級(情境)開始,縮放至城市層級(容器),接著是街道層級(元件),最後是建築藍圖層級(程式碼)。

  • 圖形即程式碼:「」以文字型領域特定語言(如 PlantUML)撰寫圖表,而非手動繪製。這使得差異比對、合併與 CI/CD 整合成為可能。

  • VPasCode:「Visual Paradigm 的腳本語言,填補了基於文字的 PlantUML 與 Visual Paradigm 豐富的元數據倉庫之間的差距,實現雙向同步。

  • AI 輔助建模:利用大型語言模型,根據自然語言需求生成初始的 C4 PlantUML 草稿,大幅減少模板化的摩擦。


1. 開始使用 C4-PlantUML

要在 PlantUML 中使用 C4 模型,您需要從 GitHub 倉庫引入官方的 C4 PlantUML 宏定義。這提供了專門的元素,例如:系統, 容器, 組件以及關係連接器(Rel).

基本設置與範本

VPasCode 編輯器顯示 PlantUML 程式碼以及為網際網路銀行系統生成的 C4 系統情境圖。

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

' 佈局指令
skinparam Linetype polyline

title 網際網路銀行系統之系統情境圖

Person(customer, "銀行客戶", "擁有個人銀行帳戶的銀行客戶。")
System(banking_system, "網際網路銀行系統", "允許客戶查詢帳戶、進行付款及管理個人資料。")
System_Ext(mail_system, "電子郵件系統", "用於發送確認郵件的內部 Microsoft Exchange 系統。")
System_Ext(mainframe, "大型主機銀行系統", "儲存核心銀行資訊與交易記錄。")

Rel(customer, banking_system, "使用", "HTTPS")
Rel(banking_system, mail_system, "發送電子郵件", "SMTP")
Rel(banking_system, mainframe, "從...獲取帳戶資訊", "儲存程序 / TCP/IP")

@enduml

💡 工具提示:雖然標準的 PlantUML 能完美渲染此內容,但將此程式碼匯入Visual Paradigm透過 VPasCode 編輯器,可將這些抽象元素連結至專案倉庫中的實際 UML 類別或資料庫結構。


2. 第一層:系統情境圖

「系統情境」圖表位於最高層級。它將您的軟體系統顯示為中央的方塊,周圍環繞著其使用者與它所互動的其他軟體系統。

  • 人員: 代表系統的人類使用者。

  • 系統: 您正在建構的軟體系統。

  • 系統_外部: 外部軟體系統(例如:金流閘道、舊式大型主機、電子郵件服務供應商)。

範例:電子商務平台情境

VPasCode 中的電子商務平台系統情境圖,顯示線上購物者、管理員與外部整合。

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

LAYOUT_WITH_LEGEND()

title 電子商務平台系統情境圖

Person(shopper, "線上購物者", "瀏覽並購買商品的顧客。")
Person(admin, "後台管理員", "管理庫存、訂單與客戶查詢。")

System(ecommerce, "電子商務平台", "允許使用者搜尋商品、下單並進行安全付款。")

System_Ext(payment_gateway, "金流閘道", "處理信用卡與數位錢包交易。")
System_Ext(shipping_provider, "全球運送 API", "計算運費並產生追蹤標籤。")
System_Ext(crm_system, "CRM 系統", "處理客戶服務工單與行銷活動。")

Rel(shopper, ecommerce, "瀏覽商品並購買項目", "HTTPS")
Rel(admin, ecommerce, "更新庫存並管理訂單", "HTTPS")
Rel(ecommerce, payment_gateway, "透過...處理付款", "REST API")
Rel(ecommerce, shipping_provider, "透過...預訂運送", "REST API")
Rel(ecommerce, crm_system, "同步客戶檔案並記錄服務請求", "Webhook")

@enduml

AI 聊天機器人整合

無需從頭撰寫上述內容,您可以向 AI 聊天機器人發出提示:

「為包含購物者、管理員、金流閘道與運送服務商的電子商務平台,產生一張 C4 系統情境 PlantUML 圖表。」

AI 將產生約 90% 正確的語法,您只需細化具體的關係標籤與技術協定。


3. 第二層:容器圖

「容器」容器圖表會縮放至軟體系統,以顯示高階技術建構模組。「容器」是指可獨立執行或部署的單位(例如:單頁應用程式、行動應用程式、微服務、資料庫、無伺服器函式)。

  • 容器: 應用程式或資料儲存庫。

  • ContainerDb: 代表資料庫或資料儲存庫的專用容器。

範例:電子商務容器

電子商務平台的 C4 模型容器圖,顯示線上購物者、單頁應用程式、API 閘道、資料庫、快取層與金流閘道。

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

LAYOUT_WITH_LEGEND()

title 電商平台容器圖

Person(shopper, "線上購物者", "線上購買商品。")

System_Boundary(ecommerce, "電商平台") {
    Container(spa, "單頁應用程式", "React, TypeScript", "透過瀏覽器為購物者提供所有功能。")
    Container(api, "API 閘道器 / 後端", "Node.js, Express", "處理業務邏輯、路由和身份驗證。")
    ContainerDb(db, "資料庫", "PostgreSQL", "儲存使用者資料、產品目錄和訂單資料。")
    Container(cache, "快取層", "Redis", "儲存工作階段資料和產品目錄快取。")
}

System_Ext(payment_gateway, "金流閘道器", "處理信用卡付款。")

Rel(shopper, spa, "造訪 shop.com", "HTTPS")
Rel(spa, api, "發出 API 呼叫", "JSON/HTTPS")
Rel(api, cache, "讀取/寫入工作階段狀態", "TCP")
Rel(api, db, "讀取/寫入訂單與使用者", "SQL/TCP")
Rel(api, payment_gateway, "扣款信用卡", "REST API")

@enduml


4. 第三層:元件圖

該元件圖會縮放至單一容器,以顯示內部元件(例如 Spring beans、模組、控制器、服務)及其互動關係。

範例:API 閘道器元件

VPasCode PlantUML 介面顯示 API 閘道後端服務架構的 C4 元件圖。

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

LAYOUT_WITH_LEGEND()

title API 閘道器 / 後端服務元件圖

Container(spa, "單頁應用程式", "React, TypeScript", "提供使用者介面功能。")
ContainerDb(db, "資料庫", "PostgreSQL", "儲存核心資料。")

Container_Boundary(api, "API 閘道器 / 後端") {
    Component(auth_controller, "驗證控制器", "Express Route", "處理使用者登入、Token 產生與 JWT 驗證。")
    Component(order_controller, "訂單控制器", "Express Route", "處理 incoming 訂單建立。")
    Component(order_service, "訂單服務", "Node.js Service", "包含核心結帳與驗證邏輯。")
    Component(order_repo, "訂單儲存庫", "Data Mapper", "對 PostgreSQL 執行 SQL 查詢。")
}

Rel(spa, auth_controller, "傳送憑證", "JSON/HTTPS")
Rel(spa, order_controller, "送出訂單載荷", "JSON/HTTPS")
Rel(order_controller, order_service, "呼叫業務邏輯")
Rel(order_service, order_repo, "查詢資料")
Rel(order_repo, db, "讀取/寫入資料列", "SQL/TCP")

@enduml

Visual Paradigm 與 VPasCode 的優勢

雖然 PlantUML 會自動處理版面配置,Visual Paradigm透過 VPasCode 為企業帶來價值。當您匯入上述的元件圖時:

  1. 儲存庫連結:VPasCode 可將order_service對應至您 VP 專案中的實際 Java 類別或 Node.js 模組。

  2. 影響分析:如果您變更訂單儲存庫在程式碼模型中的介面,VP 可將 C4 圖標記為過時。

  3. 一致樣式:使用組織官方企業架構/架構樣式範本(儲存於 VP 中)覆蓋 PlantUML 的預設 skinparams。


5. 維護 C4 PlantUML 的最佳實踐

  • 將程式碼保留在來源附近: 將您的.puml 圖形檔案直接存放在您的儲存庫中(例如,位於/docs/architecture 資料夾下),讓它們與您的程式碼庫同步演進。

  • 利用 AI 進行草稿撰寫: 使用自然語言提示立即生成初始的 PlantUML C4 區塊,然後手動調整邊界與關係。

  • 自動化渲染: 使用外掛程式或 CLI 工具將 PlantUML 生成整合到您的 CI/CD 流程中,自動輸出 SVG/PNG 圖形至您的內部維基。

  • 混合工具策略: 使用純 PlantUML 進行快速的 Pull Request 層級文件,但透過 VPasCode 將關鍵架構決策同步至 Visual Paradigm,以實現長期治理與利害關係人報告。

  • 標籤與元數據: 使用 C4 標籤($tags="...") 以啟用篩選功能。在 Visual Paradigm 中,這些標籤可驅動動態視圖與合規報告。


結論

採用結合 PlantUML 的 C4 建模,將架構從儀式性的交付成果轉變為持續的工程實踐。透過從 C4 的結構化抽象開始,並利用AI 聊天機器人 進行快速草稿撰寫、PlantUML 進行版本控制的渲染,以及Visual Paradigm/VPasCode 進行企業級儲存庫管理,團隊即可實現真正的架構對齊。

成功的關鍵不僅在於繪製方塊,更在於將這些方塊整合到您的開發生命週期中。從系統情境圖開始,在 CI 流程中自動化其渲染,並隨著團隊架構成熟度的提升逐步縮小範圍。未來的您——以及您的新進工程師——將會感謝您。