Mermaid.js 序列圖語法指南

什麼是序列圖？

一個序列圖是一種重要的行為UML 圖用於在線性時間軸上可視化不同系統實體之間訊息、函數呼叫和資料載荷的時間順序流。被視為核心UML 圖類型，它通過沿 X 軸堆疊系統組件作為垂直生命線，並沿 Y 軸追蹤訊息交換來描繪運行時互動。此藍圖對開發人員調試分散式 API 握手、微服務編排路徑或即時使用者驗證流程極為珍貴。

使用Mermaid.js，您可以使用直觀的文本結構編寫複雜的時間過程。引擎會自動處理垂直間距，管理訊息箭頭對齊，並在您的畫布上乾淨地繪製運行時激活區塊。

核心語法指南：元素與構造

要在 Mermaid 中設計出精確且極易掃描的 UML 序列圖，您必須掌握參與者宣告、訊息箭頭變體、明確的生命線以及條件區塊結構。

1. 宣告參與者與角色

您使用participant關鍵字宣告標準系統實體。如果該實體代表人類終端使用者或外部操作員，請使用actor關鍵字在畫布上繪製標準的棒狀人形圖示：

sequenceDiagram
    actor 客戶端
    participant API 作為網關路由器

專業提示：使用as關鍵字將長的組件名稱映射為簡潔的內部別名，使您的訊息腳本簡潔且易讀。

2. 格式化訊息箭頭

您使用的線條類型和箭頭頭部決定了系統參與者之間的通訊風格：

• ->> **同步呼叫：** 一條實線，箭頭為實心。代表一個阻塞請求，會等待執行完成。
• --> **回應線：** 一條虛線，箭頭為空心。用於傳回資料載荷或確認令牌。
• -> **非同步呼叫：** 一條實線，箭頭為空心。表示非阻塞訊息或事件廣播。

序列圖
    App->>Server: 請求載荷
    Server-->App: 200 OK 回應

3. 管理生命線激活條

要精確顯示系統元件何時正在執行任務或佔用執行緒記憶體，請使用 activate 和 deactivate 指令。或者，您可以直接在訊息目標後面加上加號（+）或減號（-）符號，作為快速的視覺捷徑：

序列圖
    Client->>+Server: 處理資料
    %% 伺服器現在已視覺上激活
    Server-->-Client: 傳回結果

4. 結構化條件與替代方案（Alt、Opt、Loop）

為了處理分支執行時邏輯、權杖評估或重複的請求重試，請將您的訊息腳本包裝在標準的區塊片段中：

• alt / else — 評估條件路徑（類似於 if/else 程式碼區塊）。
• opt — 定義一個僅在特定條件下執行的選擇性步驟。
• 循環 — 重複執行一個執行序列，直到條件滿足為止。

序列圖
    循環 每30秒
        客戶端->>伺服器: 心跳偵測
    結束

建立清晰序列時間軸的最佳實務

• 保持生命線簡潔： 避免在 X 軸上列出數十個微小實體。如果一個流程與次要的輔助類別互動，應將它們抽象在高階系統邊界之後，例如[驗證工作程式] 或 [快取池].
• 明確標示狀態碼： 在撰寫回應回傳時（-->），不要只寫「回傳資料」。應以明確的 HTTP 狀態碼或事件類型標示路徑（例如，"201 已建立（JWT 憑證）"），以提供工程師精確的上下文資訊。
• 為複雜運算實作註解： 使用 Note over, Note left of，或 Note right of 指令來記錄非視覺化操作，例如內部加密步驟或資料庫資料雜湊。

現實世界中的 Mermaid.js 序列圖範例

範例 1：安全的 OAuth2 憑證交換流程（啟用與替代區塊）

此功能藍圖模擬了一個安全的使用者登入序列。它示範了如何使用 alt/else 區塊，結合人類參與者、明確的系統生命線與複雜的驗證路徑。

序列圖
    人物 User 代表終端使用者
    參與者 App 代表行動應用程式客戶端
    參與者 Auth 代表 Auth0 身份提供者

    User->>+App: 點擊「使用 OAuth 登入」
    App->>+Auth: 以 client_id 與 scope 重定向
    Auth-->>User: 渲染登入介面
    User->>Auth: 提交憑證
    
    Auth->>Auth: 驗證密碼雜湊值
    
    若憑證有效
        Auth-->>App: 以授權碼進行 302 重定向
        App->>Auth: 用授權碼交換存取權杖
        Auth-->>-App: 回傳 JWT 權杖 (IdToken)
        App-->>User: 渲染使用者帳戶首頁
    否則憑證無效
        Auth-->>App: 回傳 401 未授權錯誤
        App-->>-User: 顯示「無效的使用者名稱/密碼」警告
    結束

語法解析： 此時間軸記錄了多方之間的握手流程。alt / else 容器明確地呈現出二元驗證路徑，確保錯誤狀態與正常流程一同被完整記錄。

範例 2：分散式訂單庫存結帳（平行流程與註解）

此進階系統藍圖描繪出企業級電商結帳流程。它利用平行區塊（par）來展示並行的 API 發送流程，並在整體架構中處理資料庫鎖定的註解。

序列圖
    參與者 Web 代表網頁前端
    參與者 Ord 代表訂單協調器
    參與者 Inv 代表庫存服務
    參與者 Pay 代表付款網關

    Web->>+Ord: 提交結帳請求
    註解位於 Ord 上方：驗證商品庫存可用性
    
    平行 發送並行 API 請求
        Ord->>+Inv: 鎖定庫存項目
        Inv-->-Ord: 庫存已保留（庫存鎖定）
    且
        Ord->>+Pay: 授權信用卡扣款
        Pay-->-Ord: 成功捕獲（扣款已結算）
    結束
    
    選項 若處理分配失敗
        註解位於 Ord 右側：若任一呼叫失敗，執行回滾劇情
    結束
    
    Ord-->-Web: 200 成功，結帳確認

語法解析： 這par / and 容器指示引擎將並行執行整合在一起，記錄並行的後端操作。註解位於 與 位於右側的註解 標籤會直接將技術執行時說明注入到畫布網格中，幫助團隊理解背景交易，例如資料鎖定與回滾劇情，而不會使主要訊息箭頭變得混亂。