Mermaid.js 架構圖語法與佈局指南

架構圖提供了一種結構化的藍圖，供系統架構師和 DevOps 團隊用來視覺化基礎設施設置、雲端微服務以及結構佈局配置。基於 architecture-beta 引擎，此文字導向工具透過自動排列結構性服務群組、資料庫叢集、閘道器與邊緣路徑，取代手動拖曳功能，將其整理成清晰且可預測的系統佈局。

基本語法結構

每個圖表都以 architecture-beta 聲明標頭開始。您可透過使用 service 關鍵字定義單獨的節點元素，並透過指定精確的方向座標埠（T頂端、B底端、L左側、R右側）以冒號和雙破折號分隔。

Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  service gateway(internet)[閘道器標籤]
  service server(server)[應用伺服器]
  
  gateway:B -- T:server
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

語法參考

下表分解了在 Mermaid.js 中構建架構工作區地圖所使用的主數據元件、格式化關鍵字和連接器屬性。

語法元件 類型需求 描述與使用規則
宣告 關鍵字識別符 初始化基礎設施地圖工作區畫布。必須使用精確的 架構-beta區塊。
服務節點 關鍵字 + 識別區塊 宣告一個架構實體。使用語法：服務 id(圖示)[顯示標籤].
群組包裝 容器關鍵字 將相關服務群組於視覺容器內。使用語法：群組 id(圖示)[群組標籤].
在…內關鍵字 指派修飾符 明確指派一個服務節點位於特定宣告的群組包裝內：服務 id(圖示)[標籤] 在 groupId 內.
連接節點 關鍵字識別符 建立一個結構對齊的中心點，用於整齊地導引複雜的多方向連結路徑：連接點 id.
連接邊 埠方向運算子 透過將連結固定於特定節點側邊（T、B、L、R）來設定方向追蹤路徑：來源:側邊 -- 側邊:目標。支援方向性箭頭尾端（-->).

進階群組與埠邊緣路由

為了精確控制連結在元件之間傳輸的方式，而不會顯得雜亂，架構引擎需要明確的埠點綁定。相關節點可以組織在結構群組內，以釐清系統邊界。

1. 精確埠點綁定規則

您透過在相應節點識別碼後附加冒號和邊緣方向旗標（”T, B, L, R) 來定義連接線離開和進入元件的位置：

  • db:R -- L:server：連線從資料庫的**右側**離開，並以直線水平方式進入伺服器的**左側**。
  • db:T -- L:server：連線從資料庫的**頂端**離開，並以乾淨的90°彎角自動彎曲進入伺服器的**左側**。
  • src:B --> T:proc：連線從來源節點的**底端**離開，並向下延伸進入處理器的**頂端**，末端帶有方向箭頭。

2. 使用群組來組織系統

要宣告一個視覺群組（例如虛擬私人雲端或資料庫叢集），請使用 group關鍵字，並透過 in修飾符指派節點到該群組：

Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  group cloudNetwork(cloud)[私人雲端]
    service auth(server)[驗證節點] in cloudNetwork
    service api(server)[API 端點] in cloudNetwork
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

對齊同級元素（v11.16.0+）

當多個不同的服務共用相同的邊緣路由路徑時（例如，三個解耦的資料來源同時傳輸至單一訊息工作節點），佈局演算法有時會將它們聚集在一起。使用 align row 和 對齊欄位指令會強制引擎將這些同級元素均勻地分布在特定的軸線上。

Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  服務 src1(server)[來源 1]
  服務 src2(server)[來源 2]
  服務 proc(server)[處理器中心]

  src1:B --> T:proc
  src2:B --> T:proc

  對齊列 src1 src2
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

現實世界藍圖：微服務叢集藍圖

此藍圖展示了高度彈性、企業級的雲端架構。透過將主要 API 引擎置於中心，並水平向兩側分支認證與非同步任務，此佈局運用對稱設計原則以避免線條重疊。整個資料流程可預測地從公開網關向下流動至整齊對齊的資料儲存層，並利用雙重對齊列指令，將元件鎖定在清晰且可預測的水平軌道上。

Mermaid 在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  標題 "高可用性微服務架構"

  %% 外部入口層
  服務 cloudflare(internet)[Cloudflare WAF]
  服務 alb(server)[AWS 應用程式負載平衡器]

  %% 核心應用叢集
  群組 appCluster(cloud)[受管理的 EKS 微服務]
    服務 authService(server)[認證服務] 在 appCluster
    服務 apiService(server)[核心 API 引擎] 在 appCluster
    服務 workerNode(server)[非同步任務工作節點] 在 appCluster

  %% 受保護的儲存層
  群組 dataCluster(database)[受保護的資料層]
    服務 redis(disk)[Redis 快取叢集] 在 dataCluster
    服務 postgres(database)[PostgreSQL 主節點] 在 dataCluster

  %% 1. 垂直流程：流量從公開端點向下進入運算核心
  cloudflare:B --> T:alb
  alb:B --> T:apiService

  %% 2. 水平流程：核心 API 向左右兩側對稱分支
  apiService:L --> R:authService
  apiService:R --> L:workerNode

  %% 3. 基準流程：應用程式工作節點直接下落到對應的資料槽位
  authService:B --> T:redis
  workerNode:B --> T:postgres

  %% 為完美網格佈局設定軸線對齊
  對齊列 authService apiService workerNode
  對齊列 redis postgres
Edit Mermaid in VPasCode
在 VPasCode 中編輯 Mermaid

常見語法陷阱與系統限制

撰寫基礎設施程式碼時，請記住這些特定的設定驗證規則，以避免解析錯誤：

  • 標籤方括號序列：顯示的文字字串必須使用方括號[標籤文字]並直接跟隨圖示括號，中間不得有空格：服務 id(server)[文字]是正確的。在括號內使用引號將導致解析器失效。
  • 埠點大小寫敏感：連接邊緣埠點錨點必須以大寫字母書寫（T, B, L, R). 小寫字母（t, b, l, r) 無法識別，將導致佈局生成崩潰。
  • 預宣告規則： 邊路徑語句中使用的每個節點或節點識別符，都必須在它上方的獨立行中明確宣告。連接到隱式節點名稱將無法成功建構。
  • 對齊成員限制： 使用 對齊列 或 對齊欄 對齊定位指令時，必須在命令列中提供至少兩個或更多有效且先前宣告過的服務或節點識別符。
返回頂端