Mermaid 時序圖：API 與服務呼叫

時序圖用來說明互動順序。當核心問題是「誰在什麼時候把什麼發給誰」時，它比流程圖更合適。常見場景包括瀏覽器到 API 的呼叫、驗證握手、Webhook 投遞、佇列處理以及服務之間的重試。

用有意義的名稱宣告參與者

sequenceDiagram
  actor User
  participant Web as Web application
  participant API as Orders API
  participant DB as Database

  User->>Web: Submit order
  Web->>API: POST /orders
  API->>DB: Insert order
  DB-->>API: Order ID
  API-->>Web: 201 Created
  Web-->>User: Show confirmation

別名可以讓訊息語句更短，同時保留可讀標籤。人類角色用 actor，軟體元件用 participant。參與者的順序要讓主路徑更容易閱讀。

區分呼叫和回應

實線箭頭通常表示請求或呼叫，虛線箭頭通常表示回傳。這是一種溝通慣例，不代表一定是同步執行。如果阻塞和非同步的差別很重要，應該寫進標籤或正文裡。

用一張圖表達分支

當兩個結果共享同一個上下文時，可以使用 alt 區塊：

sequenceDiagram
  Client->>API: GET /profile
  alt token is valid
    API-->>Client: 200 Profile
  else token expired
    API-->>Client: 401 Unauthorized
  end

opt 適合可選分支，loop 適合重複互動。區塊標籤應該描述條件，而不是實作細節。token is valid 比 if checkToken() returns true 更清楚。

保持時間和責任真實

時序圖雖然由上而下閱讀，但它並不自動代表效能時間線。不要把縱向間距當成精確耗時。如果需要延遲數據，應該把實際數值寫進訊息標籤，或者單獨放一個效能圖。

也不要把時序圖畫成所有內部函式呼叫的總帳。只建模跨越有意義邊界的互動。聚焦後的圖更容易與 API 合約和失敗行為保持同步。

把範例貼到 Mermaid 圖表編輯器 裡，再把參與者逐個替換成你系統裡的元件。文件裡建議匯出 SVG，這樣不同寬度下文字和線條都更清晰。