一個UML 序列圖顯示參與者如何隨時間互動。它對於記錄一個使用案例、API 流程、業務流程或系統情境。時間通常由上而下流動；水平位置顯示參與者，而非時間經過的精確量度。
PlantUML讓您以文字描述圖形。Visual Paradigm 的 VPasCode 編輯器將程式碼編輯器與即時預覽及 AI 輔助功能結合，用於產生、修改與修正圖形程式碼。良好的工作流程是先用 AI 取得初稿，然後自行檢查並精修 PlantUML。
1. 基本結構
一個PlantUML 序列圖以@startuml開始，並以@enduml結束。參與者通常列於訊息之前，以便您控制其名稱與順序。
@startuml
actor Customer
participant Browser
participant "Order API" as API
database "Order DB" as DB
Customer -> Browser: Place order
Browser -> API: POST /orders
API -> DB: Save order
DB --> API: Order ID
API --> Browser: 201 Created
Browser --> Customer: Show confirmation
@enduml
參與者的顯示標籤可以加引號，並使用作為提供一個較短的別名以用於訊息。常見的參與者關鍵字包括actor, participant, boundary, control, entity, database，以及 集合。請使用最能傳達參與者角色的關鍵字；它並不強制採用特定架構。
2. 訊息與時間的閱讀
每個訊息均以發送者、箭頭、接收者與標籤的形式書寫。訊息列的順序決定了它們在圖表中的垂直順序。
-
->是實線訊息箭頭，常用於請求或呼叫。 -
-->是虛線箭頭，常用於回應或返回。 -
->>與-->>在常見的 PlantUML 樣式中採用開放式箭頭。 -
: 文字會新增訊息標籤。
請為呼叫與回應選擇一致的規範。UML 圖表用於傳達互動；它們並不會自動保證實作遵循所描繪的協定。
3. 活化與參與者生命週期
活化可用於顯示參與者何時正在執行工作。請使用 activate 與 停用，或縮寫++ 和 --在訊息箭頭上。
@startuml
actor User
participant "Login API" as API
database Users
User -> API: 提交憑證
activate API
API -> Users: 尋找帳號
activate Users
Users --> API: 帳號記錄
deactivate Users
API --> User: 登入結果
deactivate API
@enduml
活化（activations）在釐清巢狀呼叫或責任時最有用。若會使圖表變難讀，請避免機械式地將活化加入每個訊息。
4. 條件、替代方案與重複
使用組合片段來顯示控制流程。fragment 關鍵字開始區塊，else 在適用時分隔替代方案，而 end 將其關閉。保護條件應放在方括號內。
替代路徑：alt 和 else
@startuml
actor User
participant "Login API" as API
database Users
User -> API: 提交使用者名稱和密碼
API -> Users: 檢查憑證
Users --> API: 匹配結果
alt [憑證有效]
API --> User: 傳回工作階段權杖
else [憑證無效]
API --> User: 傳回驗證錯誤
end
@enduml
alt當路徑互斥時，此處為適當用法。請使用能讓條件清晰的標籤。
選擇性行為：opt
@startuml
actor Customer
participant Checkout
participant "Email Service" as Email
Customer -> Checkout: 完成購買
Checkout --> Customer: 訂單確認
opt [客戶已選擇接收電子郵件]
Checkout -> Email: 發送收據
Email --> Checkout: 已接受
end
@enduml
重複：迴圈
@startuml
參與者 "批次作業" 為 Job
參與者 "付款 API" 為 API
迴圈 [針對每個待處理付款]
Job -> API: 提交付款
API --> Job: 付款結果
end
@enduml
將重複的動作放入片段中，並清楚說明迴圈條件或範圍。
5. 平行與分組互動
使用 par 當互動同時發生或其順序不重要時。使用 group 來標記一組訊息，而不暗示特定的控制流程結構。
@startuml
participant "訂單服務" as Orders
participant "庫存服務" as Inventory
participant "通知服務" as Notify
Orders -> Orders: 訂單已接受
par 預留庫存
Orders -> Inventory: 預留商品
Inventory --> Orders: 預留結果
else 通知客戶
Orders -> Notify: 發送訂單更新
Notify --> Orders: 已接受
end
@enduml
使用 par僅在並發具有實際意義時使用。若某項動作必須在另一項動作開始前完成，則應以序列方式顯示訊息。
6. 註解、參考與視覺分組
註解可用於釐清假設、限制或決策。一個 ref片段可引導讀者參閱其他圖表或獨立記錄的互動。
@startuml
actor 客戶
participant "結帳介面" as UI
participant "付款服務" as Pay
participant "詐欺檢查" as Fraud
客戶 -> UI: 支付訂單
UI -> Pay: 授權付款
Pay -> Fraud: 評估交易
note right of Fraud
風險規則維持於
此互動之外。
end note
Fraud --> Pay: 風險結果
Pay --> UI: 授權結果
UI --> 客戶: 顯示結果
@enduml
註解應提供背景資訊，而非重複訊息標籤。若圖表變得擁擠，請將其拆分為專注的情境，並使用參考或文件連結加以串連。
7. 在 VPasCode 中建立與精修圖表
VPasCode支援以即時預覽方式編輯 PlantUML，以及AI 輔助圖表生成、程式碼修改與語法修正。其確切介面與功能可用性可能會變動，但一般工作流程如下：
-
開啟 VPasCode 並選擇或輸入 PlantUML。
-
描述互動流程，或將 PlantUML 草稿貼上至編輯器。
-
在精修原始碼時，檢查已渲染的預覽。
-
請 AI 進行特定變更，例如「使用「
alt.” -
檢視產生的程式碼與圖表，確認其語法與系統邏輯的正確性。
-
使用編輯器中提供的選項，匯出或分享完成的圖表。
一個有效的提示詞應提供圖表類型、參與者、系統邊界、主要成功路徑、重要替代路徑以及詳細程度。例如：
建立一個用於客戶登入網頁應用程式的 PlantUML 序列圖。包含瀏覽器、登入 API、身份提供者與使用者資料庫。顯示登入成功的路徑與密碼無效的替代路徑。使用簡潔的標籤，且不要編造超出上述範圍的服務。
將產生的程式碼視為草稿。檢查參與者、箭頭、條件與錯誤路徑是否反映實際系統，而不僅是看似合理的流程。
8. 更完整的範例：結帳時發生付款失敗
此範例結合了參與者別名、啟動動作與替代路徑。
@startuml
標題：結帳與付款授權
參與者：顧客
邊界：「結帳 UI」作為 UI
控制：「訂單服務」作為 Orders
參與者：「付款閘道」作為 Pay
資料庫：「訂單資料庫」作為 DB
顧客 -> UI：提交結帳
UI -> Orders：建立待處理訂單
啟動 Orders
Orders -> DB：儲存待處理訂單
DB --> Orders：訂單 ID
Orders -> Pay：授權付款
啟動 Pay
alt [付款已核准]
Pay --> Orders：授權碼
停用 Pay
Orders -> DB：標記訂單已確認
DB --> Orders：已更新
Orders --> UI：訂單已確認
UI --> 顧客：顯示確認訊息
else [付款遭拒絕]
Pay --> Orders：拒絕原因
停用 Pay
Orders -> DB：標記訂單失敗
DB --> Orders：已更新
Orders --> UI：付款遭拒絕
UI --> 顧客：顯示重試選項
end
停用 Orders
@enduml
檢查圖表的順序是否與實際行為相符。例如，若系統僅在授權成功後才持久化訂單，則應調整資料庫訊息以符合該設計。
9. 實用建模準則
-
保持圖表焦點明確。展示單一情境或一組緊密相關的路徑。將會干擾主要互動的深層細節拆分出來。
-
依職責命名參與者。優先使用如「
訂單服務」或「付款閘道」而非模糊標籤如「系統」. -
“展現有意義的邊界。在有助於讀者理解職責時，區分使用者、客戶端、內部服務、資料庫與外部系統。
-
使用清晰的訊息標籤。包含操作、事件或重要結果；避免僅標示為「處理」的標籤。
-
建模重要的失敗路徑。當超時、拒絕、重試或驗證失敗影響情境時，請納入相關內容。
-
準確使用片段。
alt表示替代路徑，opt表示可選行為，loop表示重複，而par表示平行行為。 -
避免實現雜訊。除非受眾需要，否則不要將每個 getter、內部方法或低層級細節都繪製成圖。
-
保持來源可維護。對長名稱使用別名，保持命名一致，並對重要假設使用簡短註解或備註。
10. 常見錯誤與審查清單
若圖表無法渲染，請檢查@startuml與@enduml存在，片段區塊具有對應的end陳述式，別名使用一致，且所有訊息端點均指向已定義的參與者。同時檢查是否有其他圖形語言的語法被意外貼入 PlantUML 原始碼中。
分享前，請檢視兩件事：
-
語法：它能否正確渲染？片段是否已正確閉合？參與者與別名是否一致？
-
語意：參與者與訊息方向是否正確？是否包含重要的錯誤路徑？外部系統與資料儲存是否準確呈現？
最強大的圖形即程式碼工作流程結合了可讀的原始碼、快速的視覺回饋與領域審查。PlantUML 提供對互動標記的明確控制，而VPasCode可加速草稿撰寫與迭代；圖形準確性的最終權威仍是其所要描述的系統行為。