Mermaid.js C4 圖表語法與架構指南

C4 圖表是一種標準化的架構視覺化方法，旨在於多個結構抽象層次上模擬軟體系統。內建於 Mermaid.js 中的c4引擎遵循 C4 模型的四個核心層級：上下文（宏生態系統），容器（應用程式、服務與資料庫），組件（內部結構模組），以及動態互動。此工具透過根據您的文字宣告應用一致且可直接展示的架構模組，免除自訂 CSS 樣式的麻煩。

理解 C4 圖表抽象概念與關鍵字

Mermaid 支援四種專用的圖表初始化標頭，取決於您的系統佈局所需的細節層級：

  • C4Context：專注於整體視圖，顯示使用者、核心軟體生態系統以及高階外部依賴關係。
  • C4Container：向下一層縮放，拆解獨立應用程式、前端介面、微服務、資料庫儲存系統與佇列。
  • C4Component：深入容器內部，展示內部程式碼層級的模組，例如控制器（Controllers）、服務（Services）與儲存庫（Repositories）。
  • C4Dynamic：專注於追蹤執行時期的資料互動，或基礎設施模組之間的逐步交易序列。

基本語法結構

每個 C4 圖表均以特定層級標頭開始，後接可選的標題陳述與以逗號分隔的巨集元件。參數置於括號中，字串以雙引號包圍。

Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
C4Context
  title "互聯網核心系統上下文藍圖"
  Person(customer, "銀行客戶", "擁有個人帳戶的銀行客戶。")
  System(banking_system, "網上銀行系統", "讓客戶查看帳戶資訊。")
  Rel(customer, banking_system, "使用", "HTTPS")
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

完整的 C4 元素巨集分類

Mermaid C4 庫提供廣泛的專用巨集，以明確區分所有抽象層級中的內部組件、外部系統與資料庫層級。

1. 人物與使用者巨集

  • Person(別名, 標籤, [描述], [角色圖示], [標籤]): 模擬內部的人類使用者或利益相關者。
  • Person_Ext(別名, 標籤, [描述], [角色圖示], [標籤]): 模擬位於核心組織邊界之外的外部使用者（例如第三方供應商或審計師）。

2. 系統與軟體生態巨集

  • System(別名, 標籤, [描述], [角色圖示], [標籤]): 代表位於您直接管理範圍內的內部、在範圍內的軟體系統群組。
  • System_Ext(別名, 標籤, [描述], [角色圖示], [標籤]): 模擬由第三方管理的重要外部軟體系統（例如身分識別提供者、核心銀行帳本）。
  • SystemDb(別名, 標籤, [描述], [角色圖示], [標籤]): 呈現一個呈圓柱形的系統層級資料儲存庫方框。
  • SystemDb_Ext(別名, 標籤, [描述], [角色圖示], [標籤]): 呈現一個外部的第三方資料庫層級。

3. 容器層巨集（C4Container 層）

  • Container(別名, 標籤, 技術, [描述], [角色圖示], [標籤]): 模擬一個獨立的可執行應用程式、API 伺服器或前端介面。
  • ContainerDb(別名, 標籤, 技術, [描述], [角色圖示], [標籤]): 呈現一個容器層級的關聯式或非關聯式資料庫引擎包裝。
  • Container_Ext(別名, 標籤, 技術, [描述], [角色圖示], [標籤]): 代表外部雲端容器或應用程式服務。
  • ContainerDb_Ext(別名, 標籤, 技術, [描述], [角色圖示], [標籤]): 代表外部的、受管理的雲端資料庫儲存層級。

4. 元件層巨集（C4Component 層）

  • Component(別名, 標籤, 技術, [描述], [角色圖示], [標籤]): 對應內部程式碼層級的模組、層級或類別控制器。
  • ComponentDb(別名, 標籤, 技術, [描述], [角色圖示], [標籤]): 模擬內部的微元件儲存系統或底層檔案快取系統。

邊界容器與結構包裝

為了表示安全範圍、企業防火牆或邏輯應用程式邊界，Mermaid 提供了三個專用的方括號封閉容器包裝。嵌套在其中的元素會以視覺方式分組。

  • Enterprise_Boundary(別名, 標籤) { ... }: 將高階系統包圍在一個廣闊的視覺邊界內，代表整體企業或公司基礎設施的邊界。
  • System_Boundary(別名, 標籤) { ... }: 將密切相關的應用容器或微服務群組在一個統一的軟體生態系統框內。
  • Container_Boundary(別名, 標籤) { ... }: 在單一應用模組的上下文層中，將程式碼層級的元件隔離。

進階關係方向運算子

在C4圖中連接模塊依賴於Rel巨集或其明確指向的變體。與傳遞原始流程圖線條不同，您可透過在邏輯模塊內直接宣告技術向量來語義化地追蹤連接。

關係語法標記 視覺箭頭方向 使用對齊上下文
Rel(來源, 目標, 標籤, [技術]) 動態 / 自動化 預設關係。讓佈局演算法決定最佳的線路路徑。
BiRel(來源, 目標, 標籤, [技術]) 雙向 (<–>) 表示雙向互動式握手、雙工協議或同步流程。
Rel_Back(來源, 目標, 標籤, [技術]) 反向箭頭頂端 (<–) 在程式碼邏輯中向前繪製關係，但將可見的視覺箭頭反向翻轉。
Rel_Neighbor(來源, 目標, 標籤, [技術]) 水平佈局偏好 強制目標節點與來源節點保持在同一水平列上，緊鄰其旁。
Rel_Down(來源, 目標, 標籤, [技術]) / Rel_D(...) 直線向下 (v) 強制垂直資料流向下傳遞至資料庫層或後續的背景流程。
Rel_Up(來源, 目標, 標籤, [技術]) / Rel_U(...) 直上 (^) 強制關係路徑直接向上延伸至客戶端 UI 元件。
Rel_Left(來源, 目標, 標籤, [技術]) / Rel_L(...) 直左 (<-) 將路徑水平導向畫布元素的左側。
Rel_Right(來源, 目標, 標籤, [技術]) / Rel_R(...) 直右 (->) 將路徑水平導向畫布元素的右側。

自訂動態樣式與標籤 (C4 圖形覆寫)

為了標示舊系統應用程式、突出顯示高階系統，或強調安全的資料流程，您可以使用元件標籤引擎建立自訂樣式。您可在文件頂端定義標籤屬性矩陣，然後將該標籤標籤附加至您的元件定義中。

樣式修改關鍵字：

  • UpdateElementStyle(元件名稱, 背景色, 字體色, [邊框色], [陰影]): 直接覆寫明確元件框的預設背景調色盤。
  • UpdateRelStyle(來源, 目標, 線條色, 文字色): 明確針對連接路徑，以重新著色線路路徑或連接描述。
Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
C4Context
  title "自訂色彩編碼的全球架構地圖"
  
  System(legacy_api, "舊版計費核心", "處理訂閱續期。")
  System(modern_portal, "客戶儀表板入口", "現代化的使用者網頁檢視引擎。")
  
  %% 直接色彩自訂
  UpdateElementStyle(legacy_api, "#d9534f", "#ffffff", "#c9302c")
  UpdateElementStyle(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

現實世界藍圖：企業電商系統邊界容器地圖

此全面且多層級的容器藍圖追蹤線上電商生態系。它使用一個System_Boundary 範圍容器來隔離內部核心伺服器，並透過System_Ext，將內部關聯式資料庫儲存空間與外部追蹤微服務並列映射，並使用明確的技術堆疊參數鎖定通訊管道。

Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
C4Container
  title "企業級電子商務平台的容器藍圖"

  Person(customer, "線上購物者", "瀏覽目錄項目並將商品加入其數位購物車。")
  System_Ext(payment_gateway, "Stripe API 服務", "第三方信用卡保險庫與處理引擎。")

  System_Boundary(ecommerce_scope, "電子商務核心範圍") {
    Container(frontend_app, "前端應用程式", "Next.js, React", "提供靜態資源並處理使用者購物車會話。")
    Container(checkout_service, "結帳微服務", "Node.js, Express", "處理購物車工作流程並計算稅額。")
    ContainerDb(order_db, "訂單總帳資料庫", "PostgreSQL", "儲存歷史交易明細與安全總帳記錄。")
  }

  %% 架構互動路徑
  Rel(customer, frontend_app, "使用", "HTTPS/瀏覽器")
  Rel_Down(frontend_app, checkout_service, "透過", "JSON/REST API")
  
  Rel_Right(checkout_service, order_db, "將交易狀態持久化於", "SQL/JDBC 連接")
  Rel_Left(checkout_service, payment_gateway, "使用", "安全 TLS/HTTPS API")
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

常見語法陷阱與系統限制

在為軟體框架編譯乾淨的 C4 圖時，請留意這些執行參數，以避免圖表崩潰：

  • 逗號分隔格式： 與幾乎所有其他 Mermaid 模式不同，C4 宏要求參數之間必須使用嚴格的逗號：Person(id, "標籤", "描述")。遺漏分隔逗號將導致佈局建構器完全崩潰。
  • 保留的標籤引號： 宏內的顯示欄位、技術標籤與描述區塊 *必須* 使用明確的雙引號包覆。若未使用引號包覆直接插入原始文字，將引發導致解析中斷的錯誤。
  • 邊界嵌套順序： 當將元素包覆於 System_Boundary 或 Enterprise_Boundary 區塊中時，您必須使用標準的大括號明確清除其工作區內容{ }。若遺留邊界括號未關閉或配對錯誤，將導致渲染佈局中斷。
  • 動態別名實例化： 您無法繪製關係（Rel）至一個未由其上方的元素宏區塊明確初始化的別名識別符。請確保您的宣告流程從上至下順序進行。
返回頂端