如何使用 PlantUML 建立循序圖

難以解釋系統流程？PlantUML 幫助您快速繪製循序圖。只需輸入文字，無需設計技能。

學習 API、微服務和錯誤處理的關鍵模式。查看可立即使用的實際範例。 立即試用，在幾分鐘內建立您的第一個圖表！

什麼是循序圖？

在軟體工程中，一切都與清晰的溝通有關，特別是在理解系統的行為方面。循序圖是記錄系統行為最有效的方法之一；它們按時間順序呈現物件、系統或使用者之間的互動。

循序圖是 UML (統一塑模語言）圖表的子集，在呈現依時間排序的訊息流程方面最為成功。與靜態圖表（如類別圖或元件圖）相比，循序圖有助於突顯動態流程，即在交易或工作期間的實際通訊（元件交換）。

這類圖表可協助回答以下問題：

• 此操作中有哪些服務？
• 呼叫如何發生？
• 每個步驟預期會有什麼回應？
• 故障或延遲會在哪裡發生？

循序圖常用於對應互動，而且相當容易解讀和說明。這使得它們在複雜架構、系統和 API 設計中非常重要。當您定義或考慮微服務中的互動、記錄目前舊有流程的執行方式，或系統在各種情況下的行為時，它們特別有用。

當團隊在設計流程早期使用循序圖時，可避免溝通不良問題、減少整合問題，並使每個人（包括後端工程師和產品經理）在系統行為上達成一致。

什麼是 PlantUML

圖表是軟體工程語言的視覺輔助工具。從類別結構設計到工作流程對應和 API 文件，有效的視覺化溝通可節省時間並減少混淆。在眾多可用工具中，沒有比 PlantUML 更以開發人員為中心或更完美整合現代軟體實踐的了，它是一種基於文字的圖表語言。

PlantUML 不僅是 UML 工具；它也是一個強大的通用圖表引擎；您可以用它建立循序圖、類別圖、活動流程、使用案例圖、ER 圖、線框圖等。全部都是從純文字建立。

無論您是架構師、開發人員、業務分析師還是產品負責人，將您解讀的抽象邏輯精簡並闡明為視覺化內容，都有助於改善您的理解和協作。

不幸的是，Visio 或 Lucidchart 等傳統工具並不總是能輕鬆做到這一點，而且笨重、緩慢，或只是不適合 DevOps 的節奏和流程。PlantUML 可輕鬆整合到您的開發生命週期中。

本手冊是您掌握 PlantUML 的全方位指南，涵蓋語法、進階樣式、自動化和實際情境。它針對希望在版本控制下清理文件並具備自動化能力的工程師、分析師、架構師和技術文件撰寫人員。

為何使用 PlantUML？

• 基於文字：更簡單的版本控制，在差異比對中更容易審查，語法易於學習。
• 工具友善：支援 Markdown、HTML、Doxygen、Confluence、GitHub 和 CI 工具。輕鬆與 IDE、CI/CD 流程整合。
• 可自動化：可透過命令列或 Docker 輕鬆呈現。
• 可擴充：巨集、匯入和外觀支援複雜的模組化組態。
• 低佔用空間：輕量且開源。支援 Mermaid、Markdown 呈現器等。

如何在 PlantUML 中製作循序圖

要深入了解如何透過 PlantUML 製作循序圖，以下是其基本形式。

@startuml Alice -> Bob: Hello Bob!@enduml

分解

• @startuml 和 @enduml 定義圖表的開始和結束。
• Alice -> Bob 表示從 Alice 發送訊息給 Bob。
• 冒號：它表示或添加標籤以指示任何訊息，例如在此案例中是「Hello Bob!」
• 結果：帶有時間軸和兩個參與者的視覺化圖表，顯示單向通訊。

了解循序圖元件

PlantUML 提供豐富的語法來表達各種真實世界的互動。

參與者

參與者是圖表中的實體——使用者、服務或元件。

@startumlparticipant "Web Client" as WCparticipant "Auth API" as AA@enduml

使用 participant 關鍵字為它們命名。別名（as WC）使標籤更簡短。

訊息

• 同步：實線箭頭 ->
• 非同步：虛線箭頭 -->
• 回傳：反向箭頭 <-- or <-

User -> Server: RequestServer --> User: Acknowledgement

啟用方塊

啟用列顯示參與者何時正在主動執行某項操作。

@startumlAlice -> Bob: Start Processactivate BobBob --> Alice: Donedeactivate Bob@enduml

這使時間軸更精確並指示處理時間。

自我呼叫

物件可以呼叫自己——對於內部處理或遞迴很有用。

@startumlparticipant "Service""Service" -> "Service": Internal Check@enduml

完整範例：使用者登入流程

@startumlactor Userparticipant "Frontend" as FEparticipant "Auth Service" as ASparticipant "Database" as DBUser -> FE: Enters credentialsFE -> AS: Authenticate()AS -> DB: Validate credentialsDB --> AS: ValidAS --> FE: Auth tokenFE --> User: Welcome Page@enduml

這顯示了什麼：

• 從 UI 到後端的登入互動流程
• 透過資料庫進行內部驗證
• 回傳工作階段權杖和對使用者的回應
• 這是網頁應用程式和微服務中的常見模式。

進階循序圖功能

一旦您熟悉基礎知識，以下是 PlantUML 提供的更進階工具。

迴圈和條件

條件流程：

@startumlparticipant Clientparticipant ServerClient -> Server: Requestalt Valid Request Server --> Client: Successelse Invalid Request Server --> Client: Errorend@enduml

迴圈：

@startumlparticipant Workerloop Every 5 seconds Worker -> Worker: Poll Queueend@enduml

這些有助於模擬具有重試、條件和分支行為的真實系統。

註解和標註

註解為文件或簡報目的增加清晰度。

@startumlAlice -> Bob: Pingnote right of Bob This service must respond within 100ms.end noteBob --> Alice: Pong@enduml

群組和片段

@startumlgroup Login Flow User -> AuthService: Submit Credentials AuthService --> User: Tokenend@enduml

群組區塊有助於邏輯上分離互動（例如註冊、付款等）。

自動編號

您可以為每個互動添加序號：

@startumlautonumberClient -> API: GET /dataAPI --> Client: 200 OK@enduml

循序圖中的樣式與版面配置

雖然 PlantUML 的預設輸出是可讀的，但應用一致的樣式和版面配置改進可使您的圖表更易於理解，尤其是隨著複雜度增加時。PlantUML 提供多種自訂選項，可控制循序圖的視覺外觀而不改變其邏輯流程。

Skin 參數

使用 skinparam 為您的圖表進行全域樣式設定。您可以控制箭頭顏色、字型、背景顏色、間距等等。

@startumlskinparam backgroundColor #F5F5F5skinparam sequenceArrowColor DarkBlueskinparam sequenceParticipantUnderline falseskinparam participantPadding 20@enduml

這些參數讓您的圖表更易於閱讀，並且更符合您組織的品牌形象或文件樣式。

主題

PlantUML 也包含內建主題。這些主題會影響字型、顏色和參與者形狀。若要套用主題：

@startuml!theme sketchy-outlineparticipant Userparticipant ServiceUser -> Service: Send Request@enduml

熱門主題包括：

• sketchy-outline：手繪風格，適合非正式圖表
• mars：深色、極簡外觀
• cerulean：類似 Bootstrap 的 UI 風格

您可以在 plantuml.com/theme 探索可用的主題。

版面配置控制

PlantUML 允許細微的版面配置調整以提升清晰度：

控制訊息順序：

您可以在訊息之間插入 ... 來控制垂直間距：

Alice -> Bob: Init...Bob -> Charlie: Delegate

控制方向和間距：

雖然時序圖自然由上而下流動，您可以使用 order 手動調整參與者位置：

participant A order 10participant B order 20participant C order 30

這在您想要重新排序生命線而不更改程式碼順序時很有幫助。

使用註記以提升清晰度

大量使用註記來說明步驟之間發生的事情，特別是當受眾較不具技術背景時。

@startumlAlice -> Bob: Authenticatenote right of Bob Bob verifies the credentials and returns a session token.end noteBob --> Alice: Token@enduml

隱藏未使用的生命線

如果您想要讓圖表保持專注，您可以宣告參與者但避免呈現其生命線：

hide lifelineparticipant "Cache Service" as Cache

最佳實務：

• 每個圖表維持 4-6 個參與者以確保可讀性。
• 將相關訊息垂直對齊。
• 為不同類型的參與者使用一致的顏色（例如：使用者 = 灰色、服務 = 藍色、資料庫 = 綠色）。
• 始終包含箭頭和回應線以避免模稜兩可。
• 使用 group、alt 或 loop 區塊將相關動作分組以實現邏輯組織。

更明智地使用樣式和版面配置功能，您的圖表不僅能正常運作，還能以更專業的方式傳達改善的溝通效果。乾淨的視覺呈現也能讓您的文件在不同團隊或利害關係人之間更易於維護和發展。

使用 PlantUML 的免費循序圖範例

時序圖不僅是理論性的東西，在真實世界的系統中是必需的，特別是在分散式和事件驅動系統中。以下提供三個實際範例，說明如何使用時序圖來建模各種軟體系統的互動。

電子商務中的訂單處理

這模擬了線上商店在使用者結帳後如何處理訂單。

@startumlactor Customerparticipant "Web Store" as UIparticipant "Order Service" as Orderparticipant "Inventory System" as Stockparticipant "Payment Gateway" as PaymentCustomer -> UI: Place OrderUI -> Order: Create OrderOrder -> Stock: Reserve itemsStock --> Order: Confirm availabilityOrder -> Payment: Process paymentPayment --> Order: Payment SuccessOrder --> UI: Order Confirmed@enduml

它展示了：

• 跨系統的元件協調
• 同步和非同步流程
• 庫存驗證和付款之間的依賴關係

具有重試邏輯的微服務 API 請求

這模擬了後端 API 在失敗時使用重試邏輯請求外部第三方 API。

@startumlparticipant "App Backend" as Appparticipant "External API" as APIApp -> API: Request Dataalt API Fails API --> App: Error 500 App -> API: Retry Request API --> App: Successelse API Success API --> App: Successend@enduml

它展示了：

• 使用 alt 區塊處理條件式回應
• 重試邏輯清楚地視覺化
• 外部依賴處理

事件驅動通知系統

這模擬了系統在使用者觸發動作（如完成購買）後如何使用訊息佇列發送通知。

@startumlactor Userparticipant "E-Commerce App" as Appparticipant "Message Queue" as MQparticipant "Notification Service" as Notifyparticipant "Email Server" as EmailUser -> App: Complete PurchaseApp -> MQ: Publish event (OrderPlaced)MQ -> Notify: Consume eventNotify -> Email: Send confirmation email@enduml

它展示了：

• 使用訊息佇列在服務之間解耦
• 非同步事件消費
• 從一端到另一端，包含使用者動作和系統通知

這是微服務和無伺服器系統的典型特徵，服務會引發和回應事件，而不是服務之間的通訊。這些只是序列圖在實際開發情境中非常有用的一些範例，無論是開發系統、撰寫 API 規格、引導新使用者或診斷災難。

使用 PlantUML 製作時序圖時的錯誤

使用 PlantUML 製作時序圖時要考慮的限制

PlantUML 是一個強大且非常靈活的工具，特別是對開發人員而言，但它確實有以下需要注意的限制：

• 樣式限制：與 GUI 工具相比，自訂功能相當有限。除了最基本的 skin 參數外，您無法對文字位置、間距或線條曲線進行太多操作。
• 複雜邏輯的學習曲線陡峭：雖然基本語法相當簡單，但要保持純文字邏輯合理簡潔可能非常困難，因為複雜邏輯的流程包含迴圈、條件和註記等內容。
• 沒有即時協作：雖然應用程式，例如 Miro 或 Lucidchart 具有輕鬆的即時共同編輯和內建註解功能，PlantUML 完全缺乏類似功能。
• 視覺預覽非常有限：如果 PlantUML 尚未整合到您的 IDE 或 CI 管線中，呈現和預覽圖表通常需要您在工作流程中使用其他工具。
• 對視覺優先的利害關係人不友善：商務使用者會發現基於文字的圖表是最不友善的方法，特別是在面對客戶時。

可以說 PlantUML 非常適合重視自動化控制、版本控制和 markdown 功能的開發團隊。然而，如果您追求高度精緻的視覺效果或即時圖表體驗，GUI 替代方案可能更適合您。

製作循序圖的更多方法

雖然 PlantUML 是一個非常強大且便利的工具，支援版本控制和基於文字的圖表，但它並不總是團隊和使用案例的正確選擇。以下是一些應考慮替代方案的情況：

在以下情況考慮替代方案：

• 您需要進階視覺設計：PlantUML 允許的樣式或設計有限，無法與 Lucidchart、Visio 或 Draw.io 等拖放工具競爭，這些工具具有像素級和自訂視覺控制能力。您還希望在文件中嵌入視覺化和圖片。
• 您的受眾非技術人員：當利害關係人更偏好即時編輯方式的視覺優先工具時，節點結構可能不是可用性或可訪問性的最佳選擇。
• 您需要即時協作：雖然 PlantUML 在 git 工作流程中運作良好，但它不允許像 Miro 或 FigJam 那樣的即時共同編輯或即時註解進行有效協作。
• 您正在協作處理歷史性或複雜的圖表：雖然 Structurizr 和 Archimate 等工具可以支援您使用圖表工具協作處理大型系統或概覽的標準視覺方式。而 Diagrams.net 等工具可以分層複製，但巨大的圖表同樣可能導致人們錯過上下文資訊或缺乏效能。

製作時序圖的 PlantUML 替代方案

Mermaid:

（語法、支援）更簡單的語法，用於協作和即時文件。非常適合以 markdown 為主的工作流程，以及從 GitHub 或 Obsidian 中的圖表儲存庫快速繪製圖表。

Draw.io / Diagrams.net:

完全免費的 GUI 工具，可與 Google Drive 或 Confluence 順暢整合。

Lucidchart /

Visio：一款熟悉且適合企業使用的圖表工具，適合職場中重視完善格式和智慧整合的使用者。

EdrawMax:

Visio 的桌面替代方案，提供豐富的範本支援。

根據您的使用情境選擇合適的工具——PlantUML 非常適合文件即程式碼的工作流程，但對於交付給客戶的工作，有更好的工具能提供更佳的使用者體驗或視覺呈現。

GUI 工具選項（中立參考）

如果您的團隊偏好所見即所得編輯而非程式碼圖表，GUI（圖形使用者介面）工具如 EdrawMax、Lucidchart 或 Draw.io 具有以下優勢：

• 範本和現成的模板
• 非常簡單的拖放介面
• 即時協作功能
• 匯出為 PDF、PNG 或 SVG

這些工具非常適合非開發人員使用者、快速模擬製作，以及需要視覺精緻度但不需要使用文字格式的客戶導向文件。

總結

循序圖對於視覺化系統的行為方式而非僅僅是系統本身非常有價值。使用 PlantUML 建立循序圖可為您的文件增加速度、清晰度和版本控制。

純文字格式意味著 PlantUML 可以完美整合到 CI 流程、Git 儲存庫和團隊文件工具中。它為開發人員和架構師提供了更清晰的協作方式，同時讓他們能夠將圖表與所記錄的程式碼緊密結合。

無論您是在記錄單一 API 呼叫還是整個分散式系統，PlantUML 都能讓您將想法轉化為可靠且可維護的圖表，無需啟動任何拖放式 UI。