掌握使用 PlantUML 的 UML 活動圖（程式碼即圖形方法）：全面指南

簡介

在軟體架構與業務流程建模的複雜世界中，清晰至關重要。雖然像類別圖 這樣的靜態圖表向我們展示系統由什麼組成，活動圖 則揭示系統如何運作。它們是 UML（統一建模語言）的動態核心，捕捉從啟動到完成的控制流與資料流。

請將活動圖視為一種進階的流程圖，專為企業邏輯設計。它不僅僅列出步驟，還能視覺化決策點、平行處理、迴圈以及不同參與者或系統之間的交接。無論您是在記錄用戶的登入旅程、規劃訂單履行流程，還是設計複雜演算法，活動圖都提供了一種通用語言，填補了業務利害關係人與技術團隊之間的鴻溝。

本指南專注於使用PlantUML，一種基於文字的圖形工具，支援版本控制、易於維護且視覺化一致。透過掌握以下所述語法與最佳實踐，您將能把抽象流程轉化為清晰、可執行的視覺模型。

1. 核心概念與建構模組

每個穩健的活動圖都是由一組特定的核心元素構建而成。在編寫任何程式碼之前，理解這些建構模組至關重要。

關鍵術語

• 動作: 流程中的原子步驟，例如：: 驗證付款；.
• 控制流程: 連接各個動作的箭頭，指示執行的順序。
• 決策節點: 評估保護條件，以決定下一步採取哪條路徑。
• 分叉/匯合: 一個分叉 會啟動並行流程（平行處理），而一個匯合 則將它們同步回單一執行緒。
• 泳道: 按職責將圖表劃分。這非常適合展示部門、使用者或微服務之間的交接。

2. 圖表示例

以下是兩個綜合示例，展示如何將這些元素組合成功能圖表。

示例 A：功能完整的「訂單處理」

功能：泳道、決策、迴圈與分叉

此圖表模擬完整的電子商務訂單生命週期，涉及客戶、訂單系統與倉庫。

@startuml
<style>
  element { MaximumWidth 150 }
  start   { Backgroundcolor #00695C }
  stop    { Backgroundcolor #C2185B }
  activity{ Backgroundcolor #81D4FA; MaximumWidth 150 }
  diamond { Backgroundcolor #FFB74D; MaximumWidth 80 }
  arrow   { LineColor #424242; Fontcolor #000000 }
  swimlane{ Fontcolor #000000; FontSize 14 }
</style>
title 訂單處理活動圖

|#F0F8FF|客戶|
start
:下訂單;

|#FFF8E1|訂單系統|
:接收訂單;
:驗證付款;

if (付款已核准？) then (是)
  :確認訂單;
else (否)
  :通知客戶;
  stop
endif

|#F0F8FF|客戶|
:檢視確認;

repeat
  :檢查訂單狀態;
repeat while (有變更請求？) 為 (是) 非 (否)

|#FFF8E1|訂單系統|
if (庫存有貨？) then (是)
  :發貨;
else (否)
  :通知客戶延遲;
endif

|#E8F5E9|倉庫|
fork
  :包裝商品 A;
fork again
  :包裝商品 B;
end fork
:發送包裹;

|#F0F8FF|客戶|
:接收訂單;
stop
@enduml

示例 B：專注於「登入嘗試」

功能：決策、迴圈與提前終止

此圖表專注於安全邏輯，處理有效憑證、失敗嘗試、重試與帳號鎖定。

@startuml
<style>
  element { MaximumWidth 150 }
  start   { Backgroundcolor #00695C }
  stop    { Backgroundcolor #C2185B }
  activity{ Backgroundcolor #81D4FA; MaximumWidth 150 }
  diamond { Backgroundcolor #FFB74D; MaximumWidth 80 }
  arrow   { LineColor #424242; Fontcolor #000000 }
  swimlane{ Fontcolor #000000; FontSize 14 }
</style>
title 登入嘗試活動圖

|#F0F8FF|使用者|
start
:輸入憑證;

|#FFF8E1|驗證服務|
:檢查憑證;

if (有效？) then (是)
  :發行會話權杖;
else (否)
  :記錄失敗嘗試;

  repeat
    :提示重新輸入;
  repeat while (剩餘嘗試次數？) 為 (是) 非 (否)

  if (已鎖定？) then (是)
    :通知管理員;
    stop
  endif
endif

:授予存取權限;
stop
@enduml

3. PlantUML 語法速查表

使用此參考指南，高效地建立您自己的圖表。

' 開始 / 結束（必要）
start
stop

' 簡單動作（冒號語法 — 務必包含 ; ）
:執行某動作;

' 判斷（唯一有效形式）
if (條件？) then (是)
  :執行動作 A;
else (否)
  :執行動作 B;
endif

' 迴圈
repeat
  :可重複動作;
repeat while (繼續？) 為 (是) 非 (否)

' 平行分支 / 合併
fork
  :平行路徑 A;
fork again
  :平行路徑 B;
end fork
:合併並繼續;

' 泳道（定義泳道，然後切換回來）
|#F0F8FF|銷售|
:銷售部門活動;
|#FFF8E1|資訊技術|
:資訊技術部門活動;

4. 指導原則與內部規範

為確保您的圖表可渲染、易讀且專業，請遵守以下十項規則：

1. 必要開始/結束: 務必以「start」開始，並確保所有可能路徑皆能抵達「stop」。缺乏終點的圖表是不完整的。
2. 關閉判斷: 務必以「endif」結束判斷區塊。否則圖表將無法正確渲染。
3. 配對迴圈: 每個「repeat 必須有對應的 repeat while。它們是無法拆分的語法配對。
4. 冒號語法：使用 :action; 格式。請勿使用舊式簡寫，例如 -> action ->.
5. 動詞 – 名詞命名：使用動詞 – 名詞配對清晰地命名動作（例如，使用「驗證付款」而非僅「付款」），以提升可讀性。
6. 樣式置放：將 <style> 區塊緊接在 @startuml，接著是 title.
7. 使用泳道：對於涉及多個參與者、系統或部門的任何流程，請使用泳道來清晰映射責任。
8. 限制寬度：將活動寬度保持在約 150 像素以下（使用 MaximumWidth）以防止標籤變得無法閱讀。
9. 避免使用註解：除非明確要求，否則避免使用註解元素，以維持圖表整潔並專注於流程。
10. 有意義的標籤：選擇描述性的分支標籤。雖然 yes/否是可接受的，標籤如已核准/已拒絕或有庫存/無庫存可提供即時的上下文。

5. 技巧與秘訣

• 以顏色編碼泳道: 為每個泳道使用不同的背景色調（如範例所示）。這可提升可掃描性，並幫助觀眾立即識別誰負責哪一步驟。
• 僅在需要平行處理時使用分支: 使用分支僅在任務真正獨立且可同時進行時使用（例如：包裝兩種不同的物品）。請勿將分支用於順序步驟。
• 明確模擬重試機制: 將迴圈放置於失敗情況之後以清楚模擬重試邏輯。這能讓開發人員與測試人員一眼看出錯誤處理路徑。
• 自然閱讀流程: 將動作由上至下排列。根據流程順序，保持泳道由左至右的一致性（例如：客戶 → 系統 → 倉庫）。
• 複雜分支: 若需要多路分支，可使用elseif，但請保持可讀性。對於複雜邏輯，嵌套if語句通常更為清晰。

6. 常見使用情境

活動圖是適用於多個領域的通用工具：

• 業務流程建模: 記錄訂單履行、員工入職或審批工作流。
• 用例細化: 將高層級用例擴展為逐步行為模型。
• 演算法設計: 記錄複雜函數、服務或數據處理流水線的控製流程。
• 工作流分析: 可視化團隊間交接流程，以識別瓶頸或職責不清之處。
• 錯誤處理: 規劃回退機制、重試循環及失敗退出路徑。
• 並發分析: 識別並行路徑何時需要同步（分叉/匯合），以避免競態條件。
• 模式合規性: 將實際實施的流程與目標標準或法規要求進行比較。

7. 誰應該使用它？

✅ 分享圖表前的快速檢查清單

在定稿圖表前，請依序檢查此品質保證清單：

• 是否有開始，且每條路徑是否都連接到結束?
• 所有決策是否都以endif?
• 迴圈是否以配對的repeat / repeat while配對構成？
• 分支是否以fork / fork again開啟，並以end fork?
• 每個動作是否都以分號;?
• 當涉及多個參與者時，是否使用了泳道？
• 「<style>」區塊與「標題」是否正確放置在頂部？

結論

UML 活動圖不僅僅是美觀的圖示；它們是溝通、分析與設計的關鍵工具。透過運用「PlantUML」，您便能以程式碼形式建立這些圖表，使其可進行版本控制、輕鬆更新，並在整個組織中保持一致。

無論您是在繪製簡單的用戶登入流程，還是複雜的分散式供應鏈，其原則皆相同：定義起始點與終點、釐清決策點、尊重並行處理，並透過「泳道」來分配責任。本指南提供了語法速查表與最佳實踐，讓您現在便能以精準與清晰的方式建模任何流程。今天就開始繪製圖表，將複雜的邏輯轉化為可理解的作業流程。