超越靜態圖像：利用 Mermaid 與 AI 工具解鎖圖形即程式碼的潛力
文件危機
每個工程團隊都深知這種痛苦。你花費數週時間設計優雅的微服務架構，精心編繪能令利害關係人讚嘆的 Visio 圖表。六個月後，系統已經演進——新增了新服務、遷移了資料庫、棄用了 API 端點，但圖表卻凝固在過去。它已成遺物，甚至是一種謊言。
這就是「文件腐蝕」，它是工程生產力的無聲殺手。當圖表失真，開發者便會忽視它們；當開發者忽視文件，部落知識便會取而代之；當唯一了解系統的人離職，你便只剩下一套複雜的程式碼庫，卻毫無地圖指引。
圖形即程式碼（DaC）是解決方案。而其核心正是Mermaid，這是一款基於 JavaScript 的圖形工具，能將純文字轉化為精美的視覺圖表。
核心理念：將圖形視為軟體
圖形即程式碼的根本轉變在於，以與應用程式程式碼相同的嚴謹度來處理圖形。這意味著：
1. 版本控制成為標準
當你的圖形是.mermaid檔案，它便與你的原始碼一同存放在你的 Git 儲存庫中。每一次變更都會被追蹤。你可以git blame來查看是誰新增了該服務，git diff來在合併前審查變更，並可回滾至任何先前狀態。
gitGraph
commit id: "初始架構"
commit id: "新增使用者服務"
branch feature/order-service
commit id: "訂單服務 v1"
commit id: "新增支付閘道"
checkout main
merge feature/order-service
commit id: "更新 API 閘道"
範例：使用 Mermaid 的 Git Graph 語法視覺化圖形本身的 Git 歷史
2. 圖形的程式碼審查
拉取請求（Pull Requests）不再僅限於程式碼。當開發者提出新服務或修改資料流程時，該變更會以可讀的差異（diff）形式出現在拉取請求中。審查者可以直接對圖形本身進行評論，確保架構決策在合併前經過討論與核准。
3. CI/CD 整合
你的圖形可在你的 CI/CD 流程中自動生成與驗證。想像一個 GitHub Action 能夠：
-
將所有 Mermaid 圖形渲染為 PNG/SVG 格式
-
將它們上傳至你的文件網站
-
若偵測到無效的 Mermaid 語法，則使建置失敗
flowchart LR
A[開發者推送程式碼] --> B[CI 流程執行]
B --> C[執行測試]
B --> D[渲染美人魚圖表]
D --> E{語法有效？}
E -->|是 | F[上傳至文件]
E -->|否 | G[建置失敗並通知團隊]
F --> H[部署應用程式]
G --> I[開發者修正語法]
I --> A
範例：用於圖表驗證與部署的 CI/CD 工作流程
美人魚實作：真實世界範例
讓我們透過實用且真實世界的範例，來探索美人魚支援的圖表類型。
範例 1：微服務架構（流程圖）
這是最常見的使用情境——視覺化您的服務如何進行溝通。
flowchart TB
subgraph "客戶層"
MobileApp[行動應用程式]
WebApp[網頁應用程式]
end
subgraph "API 閘道"
Gateway[API 閘道]
end
subgraph "微服務"
UserSvc[使用者服務]
OrderSvc[訂單服務]
ProductSvc[產品服務]
PaymentSvc[金流服務]
end
subgraph "資料層"
UserDB[(使用者資料庫)]
OrderDB[(訂單資料庫)]
ProductDB[(產品資料庫)]
Redis[(Redis 快取)]
end
subgraph "外部服務"
Stripe[Stripe 金流]
EmailAPI[電子郵件 API]
end
MobileApp --> Gateway
WebApp --> Gateway
Gateway --> UserSvc
Gateway --> OrderSvc
Gateway --> ProductSvc
Gateway --> PaymentSvc
UserSvc --> UserDB
UserSvc --> Redis
OrderSvc --> OrderDB
OrderSvc --> Redis
ProductSvc --> ProductDB
ProductSvc --> Redis
PaymentSvc --> Stripe
OrderSvc --> EmailAPI
PaymentSvc --> EmailAPI
範例：包含快取、資料庫與外部相依性的完整微服務架構
範例 2：使用者驗證流程（序列圖）
序列圖非常適合記錄服務之間複雜的互動。
sequenceDiagram
autonumber
participant 使用者
participant 前端
participant AuthSvc 驗證服務
participant UserDB 使用者資料庫
participant Cache Redis 快取
participant EmailSvc 電子郵件服務
使用者->>前端：輸入憑證
前端->>驗證服務：POST /login (電子郵件，密碼)
驗證服務->>使用者資料庫：依電子郵件查詢使用者
使用者資料庫-->>驗證服務：回傳加密後的密碼與使用者資料
驗證服務->>驗證服務：使用 bcrypt 驗證密碼
alt 有效憑證
驗證服務->>驗證服務：產生 JWT 權杖
驗證服務->>快取：儲存工作階段 (金鑰：user_id, 過期時間：1 小時)
驗證服務-->>前端：200 OK + JWT 權杖
前端-->>使用者：重新導向至主控台
else 無效憑證
驗證服務->>電子郵件服務：觸發登入失敗警示
驗證服務-->>前端：401 未授權
前端-->>使用者：顯示錯誤訊息
end
Note over 驗證服務，電子郵件服務：5 次失敗嘗試後，鎖定帳號 15 分鐘
範例：詳細的驗證流程，顯示成功與失敗路徑，包含快取與警示等副作用
範例 3：AWS 雲端基礎設施（類別圖）
類別圖不僅用於程式碼，也能建模雲端資源及其關係。
classDiagram
class VPC {
+string cidr_block
+string region
+createSubnet()
+deleteSubnet()
}
class Subnet {
+string availability_zone
+string cidr_block
+boolean is_public
+attachRouteTable()
}
class EC2Instance {
+string instance_type
+string ami_id
+int storage_gb
+start()
+stop()
+reboot()
}
class RDSDatabase {
+string engine
+string version
+int storage_gb
+boolean multi_az
+takeSnapshot()
+restoreFromSnapshot()
}
class S3Bucket {
+string bucket_name
+string region
+boolean versioning_enabled
+uploadFile()
+downloadFile()
}
class IAMRole {
+string role_name
+string policy_document
+attachPolicy()
+detachPolicy()
}
VPC "1" --> "*" Subnet
Subnet "1" --> "*" EC2Instance
Subnet "1" --> "0..1" RDSDatabase
VPC "1" --> "0..*" S3Bucket
EC2Instance --> IAMRole
RDSDatabase --> IAMRole
範例：將 AWS 基礎設施建模為具有屬性與方法的類別，適用於文件撰寫與基礎設施即程式碼規劃
範例 4：電子商務訂單處理（狀態圖）
狀態圖擅長展示實體如何在不同狀態之間轉換。
stateDiagram-v2
[*] --> Cart: 使用者新增商品
Cart --> Checkout: 使用者進入結帳
Checkout --> PaymentPending: 使用者提交訂單
PaymentPending --> PaymentProcessing: 啟動支付閘道
PaymentProcessing --> Paid: 支付成功
PaymentProcessing --> PaymentFailed: 支付遭拒
PaymentFailed --> Checkout: 使用者重試支付
PaymentFailed --> [*]: 使用者放棄購物車
Paid --> OrderConfirmed: 發送確認郵件
OrderConfirmed --> Preparing: 分配至倉庫
Preparing --> Shipped: 移交給運送商
Shipped --> InTransit: 運送商取件
InTransit --> Delivered: 送達確認
Delivered --> ReviewPrompted: 請求使用者評價
ReviewPrompted --> [*]: 使用者提交評價
Delivered --> RefundRequested: 使用者申請退費
RefundRequested --> RefundApproved: 客服審核通過
RefundApproved --> RefundProcessed: 款項退回
RefundProcessed --> [*]: 訂單結案
state "高風險詐欺檢查" as FraudCheck {
[*] --> CheckScore
CheckScore --> LowRisk: 分數 < 50
CheckScore --> HighRisk: 分數 >= 50
HighRisk --> ManualReview: 標記供團隊審查
ManualReview --> LowRisk: 核准
ManualReview --> PaymentFailed: 駁回
}
PaymentPending --> FraudCheck: 觸發風險評估
FraudCheck --> PaymentProcessing: 低風險範例：包含詐欺偵測巢狀狀態的完整電子商務訂單狀態機
範例 5：使用 GitHub 問題進行衝程規劃（Git 圖形）
Git 圖形可以表示超越 Git 本身的工作流程。
gitGraph
commit id: "衝程規劃" type: HIGHLIGHT
branch sprint-1
commit id: "使用者故事 #101: 登入頁面"
commit id: "使用者故事 #102: 使用者註冊"
branch bugfix/hotfix
commit id: "熱修復：驗證權杖過期"
checkout sprint-1
merge bugfix/hotfix
commit id: "使用者故事 #103: 密碼重設"
checkout main
merge sprint-1 tag: "v1.0.0"
branch sprint-2
commit id: "功能 #201: 購物車"
commit id: "功能 #202: 結帳流程"
branch experiment/ai-recommendations
commit id: "概念驗證：機器學習推薦引擎"
checkout sprint-2
commit id: "功能 #203: 訂單歷史"
checkout main
merge sprint-2 tag: "v2.0.0"
commit id: "發行說明：衝程 1 與 2 完成"範例：將專案管理、衝程與功能分支視覺化為 Git 圖形
圖形繪製的 AI 革命
儘管 Mermaid 優雅，但其語法可能成為障礙。當您試圖記錄系統時，誰還想除錯箭頭未對齊或括號遺漏的問題呢？
這就是 AI 驅動工具改變一切的地方。
AI 自動修復
像「VPasCode（Visual Paradigm 的圖形即程式碼平台）與「Mermaid Chart」已整合 AI 模型（如 Google Gemini 與 OpenAI），能夠：「
-
自動偵測語法錯誤
-
修復損毀的圖形，只需單擊一次
-
建議圖形結構的改進
讓我們看看實際運作：
損毀的 Mermaid 程式碼：
flowchart LR
A[前端] --> B(API 閘道
B --> C[使用者服務]
C --> D[(資料庫
D --> E[快取]
AI 修復的程式碼：
flowchart LR
A[前端] --> B(API 閘道)
B --> C[使用者服務]
C --> D[(資料庫)]
D --> E[快取]
AI 能識別缺失的閉合括號與方括號，並立即修復。
自然語言轉為圖表
或許最強大的功能是從自然語言描述生成圖表。透過像「OpenDocs」（VP 的文件平台），您只需描述您的需求：
「建立一個流程圖，顯示使用者登入。若憑證有效，則重新導向至主控台。若無效，則顯示錯誤並允許 3 次嘗試。失敗 3 次後，鎖定帳號。」
AI 生成的 Mermaid：
flowchart TD
Start([使用者嘗試登入]) --> EnterCreds[輸入電子郵件與密碼]
EnterCreds --> Validate{驗證憑證}
Validate -->|有效| Dashboard[重新導向至主控台]
Validate -->|無效| CheckAttempts{嘗試次數 < 3}
CheckAttempts -->|是| Increment[增加嘗試計數器]
Increment --> ShowError[顯示錯誤訊息]
ShowError --> EnterCreds
CheckAttempts -->|否| LockAccount[鎖定帳號 15 分鐘]
LockAccount --> SendAlert[發送安全警示電子郵件]
SendAlert --> End([處理結束])
Dashboard --> End
圖表類型間的轉換
AI 也能在不同圖表格式間進行轉換。需要將 PlantUML 圖表轉換為 Mermaid 嗎？AI 工具可以處理：
PlantUML 輸入：
@startuml
actor User
participant "前端" as FE
participant "後端" as BE
database "DB" as DB
User -> FE: 點擊登入
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: 使用者資料
BE --> FE: JWT token
FE --> User: 顯示主控台
@enduml
AI 轉換的 Mermaid：
sequenceDiagram
actor User
participant Frontend
participant Backend
participant Database
User->>Frontend: 點擊登入
Frontend->>Backend: POST /login
Backend->>Database: SELECT user
Database-->>Backend: 使用者資料
Backend-->>Frontend: JWT token
Frontend-->>User: 顯示主控台
互動式聊天機器人整合
部分平台現已提供用於建立圖表的聊天機器人介面。您可以進行對話：
使用者：「在我的架構圖中新增一個名為『庫存服務』的新服務。」
AI：「我將新增一個庫存服務，連接到您現有的產品與訂單服務。」
圖表會自動更新
使用者：「實際上，請讓它也連接到一個名為『InventoryDB』的新資料庫。」
AI：「完成。庫存服務現在已連接到產品服務、訂單服務以及新的 InventoryDB。」
將程式碼圖表整合到您的工作流程中
步驟 1：從小處著手
不要試圖一次將整個系統圖表化。從單一元件開始——例如您的驗證流程，或是您正在建構的新功能。
步驟 2：嵌入文件
將您的.mermaid檔案與您的文件並列存放（例如，放在/docs資料夾中）。使用如mermaid-cli等工具，在建置過程中將其渲染。
步驟 3：善用 VPasCode 的統一引擎
如果您在一個偏好各異的團隊中工作，VPasCode至關重要。它能在同一位置支援多種程式碼圖表語言：
# 在 VPasCode 中，您可以混合搭配：
diagrams/
├── architecture.mermaid
├── deployment.puml # PlantUML
├── database-erd.mermaid
└── workflow.d2 # D2 語言
步驟 4：透過 CI/CD 實現自動化
將步驟加入您的 GitHub Actions 或 GitLab CI：
- name: 渲染 Mermaid 圖表
run: |
for file in $(find docs -name "*.mermaid"); do
npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
done
- name: 上傳至文件網站
run: |
aws s3 sync docs/ s3://your-docs-bucket/
步驟 5：在拉取請求中進行審查
制定政策，規定所有架構變更都必須更新圖表。使用拉取請求評論來討論視覺變更：
審查者：「快取不應該位於訂單服務與資料庫之間嗎？目前它僅附加在用戶服務上。」
作者：「抓得真好。我會更新圖表。」
實際影響：案例研究
考慮一家採用 Mermaid 和 VPasCode 實施「圖表即程式碼」的金融科技初創公司：
-
之前：47 個靜態 Visio 檔案，大多數超過 6 個月未更新。新進員工花了 3 週才理解架構。
-
之後：12 個 Mermaid 圖表，全部儲存於 Git 中，隨每個功能更新。新進員工在第一週即能產出成果。
團隊的技術長指出：「我們已將圖表從合規檢查項目轉變為開發流程中活生生的部分。當我們辯論新架構時，我們會開啟 Mermaid 編輯器，直接用程式碼繪製草圖。這是一項革命性的改變。」
未來：持續性文件
最終目標是「持續性文件」，即圖表可從您的基礎設施或程式碼自動生成。相關工具已開始出現，能夠：
-
掃描您的 Kubernetes 清單並生成服務拓撲圖
-
解析 OpenAPI/Swagger 檔案並建立 API 流程圖
-
監控您的雲端資源並自動更新架構圖
Mermaid 處於這場運動的核心，提供一種簡單、基於文字的格式，機器可生成，人類也能理解。
今日開始
準備超越靜態圖片嗎？這是您的行動計畫：
-
安裝 Mermaid 擴充功能 在您喜愛的 IDE 中（VS Code、IntelliJ）
-
建立您的第一張圖表 在一個
.md檔案中，使用 Mermaid 語法 -
探索 VPasCode 的免費方案 體驗 AI 驅動的圖表繪製功能
-
建立一份活生生的文件儲存庫與您的程式碼庫並行
-
與您的團隊分享這篇文章並開啟對話
您的架構值得擁有比被遺忘資料夾中塵封圖表更好的待遇。是時候將您的圖表視為其應有的關鍵資產來對待了。
