循序圖：是什麼以及如何建立（2026 指南）
了解什麼是循序圖、UML 標記法如何運作，以及何時將其用於 API 設計、微服務和驗證流程。包含逐步建立指南。
當分散式系統中出現問題時，第一個問題通常是「什麼與什麼交談，以什麼順序？」這正是循序圖所回答的問題。它們顯示物件、服務或用戶如何隨時間相互互動——使不可見的溝通模式變得可見。
循序圖是軟體團隊最實用的 UML 圖表類型之一。它們彌合了高層次架構與實際程式碼之間的差距，對 API 設計、除錯微服務調用、記錄驗證流程和讓工程師熟悉不熟悉的系統都非常有價值。
什麼是循序圖？
循序圖是一種互動圖，顯示參與者（物件、服務、用戶或系統）在特定場景中如何相互溝通，按時間排序。垂直軸表示時間向下流動。水平軸列出參與者。
與專注於單一流程邏輯的流程圖不同，循序圖專注於多個參與者之間交換的訊息以及這些交換發生的順序。
基本結構：
Client Auth Service Database
| | |
|──── login() ────>| |
| |── findUser() ──>|
| |<── userData ────|
| |── verifyPwd() |
|<── JWT token ────| |
| | |
每條垂直線是一條生命線。每個水平箭頭是一條訊息。時間從上到下流動。
循序圖的 UML 標記法
生命線
生命線代表互動中的參與者。它由頂部的一個方塊（顯示參與者的名稱）和向下延伸的虛線組成。
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ Client │ │ API Server │ │ Database│
└────┬─────┘ └──────┬───────┘ └────┬─────┘
│ │ │
│ （虛線向下繼續） │
命名慣例：
- 系統/服務：駝峰命名法或帕斯卡命名法（
PaymentService、AuthAPI） - 參與者/用戶：普通名稱（
User、Admin、Customer） - 實例：
objectName:ClassName標記法（order:Order）
訊息
訊息是生命線之間的水平箭頭。四種類型：
| 訊息類型 | 箭頭樣式 | 含義 |
|---|---|---|
| 同步調用 | ────────> |
調用者等待回應 |
| 返回訊息 | - - - - -> |
對同步調用的回應 |
| 非同步訊息 | ────────> |
調用者不等待（通常帶有開放箭頭尖） |
| 自調用 | 箭頭循環回來 | 物件調用自己的方法 |
啟動條
啟動條（或執行事件）是生命線上的一個窄矩形，顯示該參與者何時處於活動狀態——處理請求或執行邏輯。
│ │
│──── call ───>│
│ ██ <- 啟動條（參與者正在處理）
│<── return ───│
│ │
組合片段
組合片段讓你在循序圖中顯示條件和重複邏輯。它們顯示為帶有左上角標籤的矩形框。
| 片段 | 標籤 | 用途 |
|---|---|---|
| 迴圈 | loop |
重複序列（指定條件或次數） |
| 替代 | alt |
替代路徑——類似於 if/else 區塊 |
| 可選 | opt |
可選序列——僅在條件為真時執行 |
| 並行 | par |
並行執行——序列同時發生 |
| 引用 | ref |
引用另一個循序圖 |
替代片段示例：
┌─ alt ─────────────────────────────────────┐
│ [credentials valid] │
│ AuthService ──── issue token ───> Client │
├────────────────────────────────────────────┤
│ [credentials invalid] │
│ AuthService ──── 401 error ────> Client │
└────────────────────────────────────────────┘
迴圈片段示例：
┌─ loop [for each item in cart] ─────────────┐
│ OrderService ── check stock ──> Inventory│
│ Inventory ─── available? ──> OrderService│
└────────────────────────────────────────────┘
循序圖 vs 流程圖
兩種圖表都對流程建模，但它們回答不同的問題。
| 面向 | 循序圖 | 流程圖 |
|---|---|---|
| 主要關注點 | 參與者之間的溝通 | 單一流程的邏輯流 |
| 軸 | 時間（垂直）+ 參與者（水平） | 由方向箭頭連接的步驟 |
| 顯示 | 訊息、順序、時間 | 決策、分支、迴圈 |
| 多個參與者 | 原生支援——每個人都有生命線 | 可能，但沒有泳道就顯得笨拙 |
| 最適合 | API、協議、分散式系統 | 演算法、業務流程 |
| 並行行為 | 透過 par 片段支援 |
較難表示 |
| 常見用戶 | 軟體工程師、架構師 | 業務分析師、產品團隊 |
當關鍵問題是「系統 A 對系統 B 說什麼，以及何時？」時，使用循序圖。當問題是「這個流程下一步做出什麼決策？」時，使用流程圖。
何時使用循序圖
API 設計和文件
在撰寫一行程式碼之前，循序圖讓你驗證 API 合約。為一個功能繪製調用序列，然後與團隊一起審查。你將在錯誤投入生產之前發現缺少的端點、不正確的資料依賴關係和模糊的回應格式。
微服務溝通
微服務架構難以推理，因為單個用戶動作的流程通常跨越五個或更多服務。循序圖使這一點可見：
User Gateway OrderSvc InventorySvc PaymentSvc NotifySvc
| | | | | |
|── POST /order ─────────>| | | |
| | |── check() ──>| | |
| | |<── ok ───────| | |
| | |── charge() ──────────────────>| |
| | |<── receipt ──────────────────| |
| | |── send() ──────────────────────────────────>|
|<── 201 Created ─────────| | | |
驗證流程
驗證流程涉及多個參與方（用戶、瀏覽器、身份提供商、資源伺服器）和嚴格的排序要求。循序圖是記錄 OAuth 流程、SAML 斷言和 JWT 驗證鏈的標準方式。
除錯生產事件
當事件發生時，重建發生的事情需要跨服務追蹤調用。從日誌和追蹤繪製的循序圖幫助團隊比閱讀原始日誌更快地理解故障序列並識別根本原因。
入職和知識轉移
加入團隊的新工程師可以閱讀循序圖，在幾分鐘內理解複雜的流程。這比閱讀程式碼或散文文件對互動密集的系統更有效率。
逐步建立指南
步驟一：定義場景
選擇一個特定的場景，而不是整個系統。好的範圍：
- 「用戶使用 Google OAuth 登入」
- 「客戶下訂單但信用卡被拒絕」
- 「服務 A 調用服務 B，後者超時」
避免：「驗證系統」（太廣泛）。每個圖表一個場景。
步驟二：識別參與者
列出此場景中涉及的每個參與者或系統。常見的參與者：
- 外部參與者：用戶、瀏覽器、行動應用程式
- 服務：API 閘道、驗證服務、訂單服務
- 資料儲存：資料庫、快取、訊息佇列
- 第三方：Stripe、Twilio、SendGrid
按照它們第一次出現的順序從左到右排列，發起者在最左邊。
步驟三：列出訊息
對於場景中的每個步驟，寫下：
- 誰發送訊息
- 誰接收它
- 訊息是什麼（方法名稱、事件名稱或描述）
- 它是同步的還是非同步的
步驟四：繪製序列
將參與者作為生命線放在頂部。按時間順序（從上到下）繪製訊息作為水平箭頭。添加啟動條以顯示處理時間。將條件或重複邏輯分組在組合片段中。
┌──────────┐ ┌──────────────┐ ┌──────────┐
│ Browser │ │ Auth Server │ │ UserDB │
└────┬─────┘ └──────┬───────┘ └────┬─────┘
│ │ │
│──── POST /login ─────>│ │
│ ██ │
│ │── SELECT user ───────>│
│ │<── user record ────────│
│ ██ │
│<── 200 + JWT ─────────│ │
│ │ │
步驟五：添加片段和備注
在序列有條件或重複邏輯的地方添加 alt、loop 或 opt 片段。添加備注（在 UML 中顯示為折疊矩形）用於不能整齊地放入訊息標籤中的重要約束或解釋。
步驟六：與利害關係人驗證
與擁有每個參與者的工程師或架構師一起走過圖表。驗證：
- 訊息順序正確嗎？
- 需要的地方包含了返回訊息嗎？
- 錯誤路徑有表示嗎？
- 缺少什麼嗎？
常見模式
請求-回應
最基本的模式。調用者發送同步訊息並等待返回。
Client Server
│ │
│──── request ──>│
│ ██
│<─── response ──│
│ │
帶佇列的非同步訊息
用於事件驅動架構。生產者不等待消費者處理訊息。
Producer Message Queue Consumer
│ │ │
│── publish() ──>│ │
│<── ack ────────│ │
│ │── deliver() ──>│
│ │ ██
│ │<── done ───────│
錯誤處理模式
始終在快樂路徑旁邊對失敗路徑建模。
┌─ alt ──────────────────────────────────────────┐
│ [success] │
│ Service ──── 200 OK ─────────────────> Client│
├─────────────────────────────────────────────────┤
│ [not found] │
│ Service ──── 404 Not Found ──────────> Client│
├─────────────────────────────────────────────────┤
│ [server error] │
│ Service ──── 500 Internal Error ─────> Client│
└─────────────────────────────────────────────────┘
超時和重試
┌─ loop [retry count < 3] ─────────────────────────┐
│ Client ──── request ───────────────> Service │
│ ┌─ opt [no response within 5s] ───────────────┐│
│ │ Client ──── timeout detected ││
│ └─────────────────────────────────────────────┘│
└───────────────────────────────────────────────────┘
最佳實踐
每個圖表一個場景。 試圖涵蓋所有可能路徑的循序圖變得不可讀。為快樂路徑、錯誤路徑和邊緣情況分別繪製圖表。
將參與者限制在 5-7 個。 超過七條生命線使水平空間成為問題。如果你有更多的參與者，將相關服務分組為單一參與者，並為該群組的內部建立單獨的圖表。
始終包含同步調用的返回訊息。 缺少返回箭頭意味著調用者從不收到回應。要明確。
精確標記訊息。 getMessage() 比「獲取資料」更好。包含方法名稱、HTTP 動詞和路徑，或事件名稱。避免模糊的標籤如「請求」或「回應」。
顯示發起的參與者。 從觸發序列的用戶或外部系統開始，而不是從流程中間開始。
謹慎使用備注。 備注對約束很有用（「必須在 200ms 以內完成」），但如果過度使用會使圖表混亂。
繪製錯誤路徑。 快樂路徑是顯而易見的。當圖表也顯示出錯時會發生什麼，它才變得有價值。
常見錯誤
在一個圖表中對整個系統建模。 這產生一個太複雜而無法閱讀或維護的圖表。將每個圖表範圍限定在一個特定的互動場景。
跳過返回訊息。 僅顯示出去的調用而不顯示返回會建立不完整的圖。為同步調用包含返回訊息。
混淆循序圖與流程圖。 添加決策菱形和分支箭頭使圖表變成流程圖混合體。使用 alt 和 opt 片段表示條件。
錯誤的時間排序。 圖表上位置較高的訊息被假定為較早發生。將回應放在其對應請求之上是常見的錯誤。
訊息標籤中太多細節。 訊息標籤中的完整 JSON 有效負載使圖表不可讀。使用訊息標籤表示名稱；如果有效負載細節重要，添加備注。
忽略非同步互動。 將每條訊息視為同步會隱藏重要的架構特性。明確標記非同步訊息。
使用 Flowova 建立循序圖
手動記錄 API 流程和服務互動很慢。Flowova 的循序圖製作工具讓你用純文字描述你的流程，並生成你可以與團隊一起視覺化編輯的結構化圖表。貼入描述，如「用戶提交登入表單，驗證服務根據資料庫驗證憑據，成功時返回 JWT」，即可獲得一個可以與你的團隊完善的工作圖表。
結語
當你需要理解或溝通多個參與者之間訊息的順序和方向時，循序圖是正確的工具。它們在 API 文件、微服務互動設計、驗證流程規格和事件事後回顧方面表現出色。關鍵是將每個圖表範圍限定在一個場景、包含快樂路徑和錯誤路徑，並與擁有每個參與者的人員驗證結果。從簡單的請求-回應模式開始，只有在場景要求時才增加複雜性。
