序列圖作為一種基本工具，用於可視化系統內物件或組件之間隨時間變化的互動。它們描繪訊息、資料和控制信號的流動，提供系統行為的時間視圖。正確執行時，這些圖表能減少歧義，統一團隊理解，並以技術與非技術利益相關者均可理解的格式記錄複雜邏輯。然而，若圖表雜亂無章或結構不佳，反而會導致混淆而非清晰。本指南概述了構建能有效傳達意圖的序列圖的必要標準。
🧩 理解核心組件
在深入布局與流程之前，必須使用標準元素建立穩固的基礎。每個序列圖都依賴於特定的構建模塊。一致地使用這些元素，可確保任何審閱文件的人都能理解邏輯，而無需依賴圖例。
- 生命線：代表互動中的參與者。通常以從圖表頂部延伸至底部的垂直虛線表示。每條生命線代表一個物件、角色或子系統。
- 參與者：代表流程的啟動者。通常以左側的簡筆人像或簡單圖示表示，用以標示外部使用者或系統觸發序列。
- 訊息：連接生命線的水平箭頭。它們表示從一個參與者發送到另一個參與者的請求、調用或信號。
- 激活條：放置在生命線上的矩形條。它們顯示參與者正在積極執行操作的期間。
- 回傳訊息：指向發送者的虛線箭頭。它們表示請求已完成或資料已返回。
確保所有參與者名稱清晰明確。避免使用「Object1」或「System」等通用名稱。應使用如「UserSession」、「PaymentProcessor」或「OrderRepository」等描述性名稱。這種情境化命名能讓讀者立即理解每個組件的角色，而無需交叉參考其他文件。
📩 結構化訊息流
序列圖的核心在於訊息流。您繪製和標記這些箭頭的方式，決定了讀者對互動時間與性質的理解。遵循標準符號可避免誤解。
1. 同步與非同步呼叫
區分阻塞與非阻塞操作。實心箭頭頭通常表示同步訊息，發送者在繼續前會等待回應。棒狀箭頭頭（開放箭頭）通常代表非同步訊息，發送者在發送信號後立即繼續執行。
- 同步：當後續邏輯依賴於呼叫結果時使用。
- 非同步：用於發送後不管的操作，例如記錄或通知，其流程不依賴於立即回應。
2. 處理回傳值
不要用每個回傳值來使圖表雜亂。僅回傳對邏輯或資料流具有重要意義的訊息。若方法回傳布林狀態，可在標籤中標示（例如「回傳：true」）。若回傳大型物件，則以概念性方式描述（例如「回傳：OrderData」）。
確保回傳箭頭以虛線繪製。這種視覺區別能將請求與回應分開，使時間軸更易閱讀。除非為調試流程所必需，否則避免為不跨越組件邊界的內部操作繪製回傳訊息。
🔄 使用控制框管理複雜性
隨著系統擴展，互動序列變得非線性。您將遇到包含條件、迴圈和可選行為的場景。控制框可讓您封裝這些行為，而不會破壞圖表的線性閱讀流程。
1. 選項（Alt）框
使用Alt使用框架來表示條件邏輯（if-else 情境）。根據條件將框架拆分為不同的片段。
- 頂部片段： 主要條件（例如：「使用者已驗證」）。
- 否則片段： 預設條件（例如：「使用者未驗證」）。
清楚標示每個片段。避免過度嵌套 Alt 框架，否則會產生難以追蹤的「意大利麵式」效果。若邏輯分支過深，建議將序列圖拆分為多個獨立圖表，分別呈現每個主要情境。
2. 選擇性（Opt）框架
使用Opt針對可能根據特定條件出現或不出現的行為，使用 Opt 框架。這與 Alt 不同，Alt 暗示在路徑之間必須做出選擇。例如，「忘記密碼」連結可能僅出現在登入畫面上。將此邏輯置於 Opt 框架中，以顯示其為標準流程的例外。
3. 迴圈框架
當某個流程重複時，使用Loop框架。不必繪製每一輪迭代，只需繪製一個具代表性的互動，並以條件（例如：「針對購物車中的每個項目」）包覆於迴圈框架中。
- 在框架標題中明確標示迭代條件。
- 確保迴圈內容準確反映單次迭代。
- 避免將迴圈用於每輪迭代行為會變化的複雜邏輯；應改用迴圈搭配註解，說明變異情形。
🎨 視覺清晰度與佈局
序列圖是一種視覺化成果。其有效性高度取決於外觀呈現。雜亂的圖表暗示程式碼或設計過程混亂。應嚴格遵循格式規則，以維持專業性。
1. 對齊與間距
將所有生命線垂直對齊。確保訊息的水平位置符合時間邏輯流程。參與者應根據互動頻率或邏輯層級，由左至右排列。發起者通常應位於最左側。
訊息之間應保持一致的垂直間距。不要將互動過於緊密堆疊。留白是一種降低認知負荷的工具。若兩個互動快速相繼發生，應稍作分隔，以區分事件。
2. 活動條管理
活動條表示正在進行的處理。若處理時間可忽略不計，無需為每則訊息繪製活動條。應專注於跨越多則訊息或跨系統邊界的活動條，以突顯計算資源集中的位置。
3. 顏色使用
雖然圖表在文件中通常為單色，但適度使用顏色可提升可讀性。然而，確保顏色不是意義的唯一指示。使用顏色來分組相關參與者或強調特定錯誤路徑。務必確保圖表在灰階下仍可清晰閱讀，以利列印文件。
👥 為不同受眾進行調整
並非每位讀者都需要相同層級的細節。針對資深架構師設計的圖表，與針對資淺開發者設計的圖表有所不同。應根據受眾調整細節程度。
| 受眾 | 關注領域 | 細節層級 | 排除 |
|---|---|---|---|
| 業務利益相關者 | 高階工作流程 | 低 | 資料庫呼叫、API 標頭 |
| 系統架構師 | 元件整合 | 中 | 變數名稱、特定邏輯 |
| 開發人員 | 邏輯實作 | 高 | 無（專注於流程） |
針對業務利益相關者，抽象技術步驟。例如不要使用「POST /api/v1/orders」，而應標示為「建立訂單請求」。如此可讓焦點集中在業務價值，而非端點語法。
針對開發人員，於有幫助之處包含方法簽章。明確標示錯誤處理路徑。若交易需要回滾，請顯示回滾訊息傳回呼叫者。
⚠️ 常見錯誤與修正
避免常見陷阱，與遵循最佳實務同等重要。在完成文件前，請根據此檢查清單審查您的工作。
- 抽象層級混雜：請勿在同一張圖表中混雜高階業務動作與低階資料庫查詢。這會混淆時間軸。應將資料庫持久化邏輯與編排邏輯分開。
- 遺漏回應訊息： 若發送訊息，通常會有回應訊息表示完成。若遺漏此訊息，會讓流程顯得不完整。
- 生命線過於擁擠： 若生命線互動過多，會變成「毛球」。應將圖表拆分成子流程，或使用註解來引用外部邏輯。
- 時間進展不清晰： 確保時間嚴格由上而下流動。除非是回應訊息，否則不要畫向上箭頭。非訊息的斜向箭頭會造成混淆。
- 命名不一致： 確保不會以不同名稱指稱同一參與者（例如「User」與「Client」）。一致性能建立文件的可信度。
🔄 維護與演進
軟體很少是靜態的。需求會變更，功能也會被棄用。若未維護的序列圖會成為負擔，當開發人員假設圖表與程式碼相符時，可能會導致錯誤。
1. 版本控制
將圖表視為程式碼。將它們與應用程式一起儲存在相同的版本控制系統中。使用有意義的提交訊息來解釋圖表變更的原因。若圖表已更新，請在標題中註明版本號。
2. 與程式碼連結
盡可能將圖表元素連結到實際的實作檔案。這讓開發人員能從視覺化表示導航至原始碼。這能減少文件與現實之間的摩擦。
3. 定期審查
安排定期審查您的圖表。在程式碼重構或迭代規劃期間，確認圖表仍反映系統的當前狀態。若某項功能已被移除，應立即更新圖表，以避免新成員產生混淆。
📝 關鍵指南摘要
總結而言，有效的序列圖需要在設計與維護上都具備紀律。它們不只是繪圖；而是系統與建構或維護它的人之間的合約。遵循以下原則，可確保您的文件增加價值，而非產生雜訊。
- 從參與者開始：始終明確誰是流程的起始者。
- 保持線性：時間應垂直流動，不應反向回溯，除非是回傳。
- 限制深度：避免 Alt 和 Loop 框架的過深嵌套。將複雜邏輯拆分為多個圖表。
- 清楚標示：每個箭頭與方框都應有描述性標籤。
- 審查清晰度：請同事在無上下文的情況下閱讀圖表。若他們無法理解流程，則應簡化之。
投入時間創建高品質的序列圖，能帶來減少除錯時間、新開發人員更快上手，以及減少架構誤解的回報。一張清晰的圖表，是一種無聲的共識，代表所有人都以相同方式理解系統。
