VPasCode：使用 PlantUML 的 UML 活動圖表——實用教程

UML 活動圖表用於模擬工作流程透過一個流程：執行的動作、做出的決策、平行工作以及完成路徑。PlantUML 允許您將該模型以文字描述，然後將其渲染為圖表——這是一種實用的方法，特別適合需要輕鬆修訂、審查並與專案文件並存維護的圖表。PlantUML 目前的活動語法使用易讀的關鍵字，例如start, if, repeat，以及fork；其舊版活動語法仍受支援，但建議在新圖表中採用新版語法。

1. 應模擬什麼

使用活動圖表來解釋流程或演算法，例如：

• 客戶結帳工作流程

• 核准流程

• 資料匯入管線

• 使用案例中的步驟

• 分配給人員、團隊或系統組件的工作

活動是工作單位，例如「驗證訂單」。一個控制流程連接活動並指示其順序。一個決策在替代路徑中進行選擇；平行流程顯示可並行執行的工作。圖表應釐清行為，而非嘗試記錄所有實作細節。

一個實用的經驗法則：如果主要問題是「接下來會發生什麼？在什麼條件下？」，那麼活動圖表非常適合。

2. PlantUML 基礎

PlantUML 圖表以@startuml 並以 ” 結尾@enduml。在目前的活動語法中：

• start 標示初始節點。

• :Action; 定義一個動作。

• if (...) then (...) 根據條件進行分支。

• endif 結束條件判斷。

• stop 終止流程。

• repeat 和 repeat while 模擬重複。

• fork, fork again，以及 end fork 模擬平行工作。

動作依順序書寫並隱含連接。您可以為分支添加標籤，並使用 partition 來依職責或角色分組工作。

這是一個最小範例：

@startuml
start
:接收請求;
:驗證請求;
stop
@enduml

3. 決策與替代路徑

使用if當流程進行選擇時使用。分支標籤應傳達條件的結果，而不僅僅是重複條件。

@startuml
start
:接收訂單;
:檢查庫存;

if (所有項目是否可用？) then (是)
  :保留項目;
  :請求付款;
else (否)
  :通知客戶;
  stop
endif

:確認訂單;
stop
@enduml

在此，if引入決策，而endif將其關閉。是與否標籤使替代方案可見。當路徑在endif後繼續至共用動作時，它們會重新匯入流程。

建模提示：明確說明每個有意義的結果會發生什麼。如果錯誤、超時或拒絕路徑對利害關係人重要，請將其顯示出來，而非將其隱含。

4. 迴圈與重試

當某個動作或一組動作可以重複時，請使用迴圈。此範例會持續要求輸入，直到通過驗證為止：

@startuml
start
:讀取已提交的資料；

repeat
  :驗證資料；
  if (有效？) then (是)
    :儲存資料；
    break
  else (否)
    :顯示驗證錯誤；
    :請使用者修正資料；
  endif
repeat while (使用者是否繼續？) 為 (是) 非 (否)

stop
@enduml

若迴圈的終止條件模糊，則難以閱讀。應清楚說明觸發再次嘗試的原因，以及終止重複的條件——特別是當重試次數有限或可被取消時。

5. 平行作業與同步

使用fork 當獨立動作可同時執行時，以及end fork 當各路徑必須在流程繼續前進行同步時。

@startuml
start
:訂單已確認；

fork
  :發送確認電子郵件；
fork again
  :準備倉庫揀貨清單；
fork again
  :更新銷售儀表板；
end fork

:將訂單標記為處理中；
stop
@enduml

fork 不一定代表不同的人；它可表示並行的系統行為。僅在動作確實可平行執行時才使用它。若某任務必須在另一任務開始前完成，則應以序列方式建模。

6. 帶有分區的泳道

分區可根據負責的角色、團隊或系統將動作分組。這可在不改變流程本身的情況下使交接更清晰。PlantUML 支援使用partition.

@startuml
start

partition Customer {
  :提交訂單；
}

partition "訂單服務" {
  :驗證訂單；
  if (訂單有效？) then (是)
    :建立訂單記錄；
  else (否)
    :回傳驗證錯誤；
    stop
  endif
}

partition 倉庫 {
  :準備出貨；
}

partition "訂單服務" {
  :發送確認；
}

stop
@enduml

選擇與實際職責劃分相符的泳道標籤。避免為每個小型元件建立新的區段；過多的泳道會使圖表難以掃描。

7. 資料物件與註解

某些工作流程透過顯示重要輸入或輸出會更有益。PlantUML 活動圖支援物件節點標記；註解也能補充背景資訊，而無需將每個動作標籤變成一段文字。

@startuml
start
:接收付款請求；

:授權付款；
note right
  使用付款供應商的
  授權回應。
end note

:記錄付款結果；
stop
@enduml

保持主要活動標籤簡短。當讀者需要業務規則、假設或說明，但這些內容本身並非流程中的步驟時，請將其放入註解中。

8. 完整範例：線上結帳

此較大範例結合了區段、決策、替代路徑與平行工作。

@startuml
title 線上結帳

start

partition Customer {
  :檢視購物車；
  :提交結帳；
}

partition "訂單服務" {
  :驗證購物車與地址；

  if (購物車與地址有效？) then (是)
    :計算總額；
  else (否)
    :顯示驗證錯誤；
    stop
  endif
}

partition "付款服務" {
  :授權付款；

  if (付款已核准？) then (已核准)
    :扣款；
  else (遭拒)
    :回傳付款失敗；
    stop
  endif
}

partition "訂單服務" {
  :建立訂單；
}

fork
  partition "通知服務" {
    :發送訂單確認；
  }
fork again
  partition 倉庫 {
    :將訂單排入揀貨佇列；
  }
end fork

partition "訂單服務" {
  :顯示訂單確認；
}

stop
@enduml

由上至下閱讀：客戶提交結帳，訂單服務進行驗證，付款獲得授權，並建立訂單。隨後，確認與倉庫準備工作平行執行。若驗證或付款失敗，流程將透過相關失敗路徑結束。

9. 圖形即程式碼工作流程

一個實用的工作流程如下：

圖形即程式碼工作流程

一個實用的工作流程如下：

1. 以通俗語言描述該流程。識別其起始點、終點、主要動作、決策、例外情況、平行任務及負責角色。

2. 撰寫第一份 PlantUML 草稿。在美化之前，先專注於邏輯。

3. 渲染並檢查它。檢查結果是否讀起來自然，且分支與迴圈是否清晰易懂。

4. 與利害關係人檢視邏輯。渲染僅檢查語法，而非流程是否正確。

5. 修訂原始碼並將其與專案一併儲存。文字式圖表容易與其他文件進行比對與審查。

對於本機渲染，PlantUML 命令列工具可產生圖表檔案；基於瀏覽器的編輯器則適合快速撰寫草稿與預覽。PlantUML 也提供瀏覽器編輯器，而 VPasCode 則提供具備即時預覽與 PlantUML 活動圖支援的瀏覽器編輯器。

1. 以通俗語言描述流程。識別其起始點、終點、主要動作、決策點、例外情況、平行任務及負責角色。

2. 撰寫第一份 PlantUML 草稿。在美化之前，先專注於邏輯。

3. 渲染並檢查它。檢查結果是否讀起來自然，且分支與迴圈是否清晰易懂。

4. 與利害關係人檢視邏輯。渲染僅檢查語法，而非流程是否正確。

5. 修訂原始碼並將其與專案一併儲存。文字式圖表容易與其他文件進行比對與審查。

對於本機渲染，PlantUML 命令列工具可產生圖表檔案；基於瀏覽器的編輯器則適合快速撰寫草稿與預覽。PlantUML 也提供瀏覽器編輯器，而 VPasCode 則提供具備即時預覽與 PlantUML 活動圖支援的瀏覽器編輯器。

10. 使用 Visual Paradigm VPasCode 與 AI 輔助

VPasCode 是 Visual Paradigm 的基於瀏覽器的文字轉圖表編輯器。其 PlantUML 支援包含活動圖，且編輯器提供即時渲染。Visual Paradigm 亦說明內建的自然語言圖表產生功能，以及用於修改或修正圖表程式碼的 AI 輔助。

一個實用的 AI 輔助工作流程：

1. 提示應針對行為，而不僅是圖表類型。例如：
   「建立一個用於線上結帳的 PlantUML 活動圖。包含購物車驗證、地址驗證、付款授權、失敗路徑、訂單建立，以及並行的確認電子郵件與倉儲準備。使用區隔區分別代表客戶、訂單服務、付款服務、通知服務與倉儲。使用現行的 PlantUML 活動語法。」

2. 檢查產生的原始碼。檢查它是否使用「@startuml/@enduml，每個分支都代表一個真實的條件，且失敗或替代路徑已得到處理。

3. 在 VPasCode 中渲染它。使用預覽功能來發現語法錯誤、令人困惑的標籤或過於複雜的佈局。

4. 自行或使用針對性的 AI 編輯來優化 PlantUML。提出具體的變更要求，例如「新增付款超時路徑」或「讓倉儲準備在訂單建立後依序進行」。

5. 請熟悉該流程的人員進行驗證。AI 可以草擬一個看似合理的圖表，但無法確認貴組織的實際流程是否正確。

VPasCode 的確切控制項與功能可用性可能因產品版本而異；請確認您所使用的編輯器中的當前選項。

11. Visual Paradigm 建模工作流程

當您需要直接處理圖表原始碼與預覽時，請使用 VPasCode；當任務需要圖形編輯或更廣泛的模型工作時，請使用 Visual Paradigm 的建模環境。Visual Paradigm 的指引描述了一個工作流程：生成或匯入圖表，然後在視覺編輯器中進行優化；具體的匯入路徑可能因產品與版本而異。

合理的交接方式如下：

1. 在 PlantUML 中草擬並進行迭代。

2. 分享已渲染的圖表與原始碼以供審查。

3. 如果您需要視覺編輯或其他建模功能，請將其開啟或匯入相關的 Visual Paradigm 編輯器。

4. 如果 PlantUML 原始碼是團隊選定的唯一真實來源，請將其作為維護版本；避免在兩個地方靜默地進行衝突編輯。

12. 常見錯誤與品質檢查清單

在分享圖表前，請檢查：

• 它是否有明確的起始點與有意義的結束點？

• 每個動作是否描述了一個可辨識的工作項目？

• 決策結果的標籤是否清晰？

• 在關鍵位置是否已包含拒絕、錯誤、超時或取消路徑？

• 迴圈條件是否讓重複與退出行為清晰明確？

• 平行動作是否真正獨立，且在需要時是否已顯示同步機制？

• 區隔是否代表了有意義的權責邊界？

• 讀者是否能在不閱讀冗長動作標籤的情況下理解流程？

• 已渲染的圖表是否與實際流程相符？

良好的活動圖表並非最長或最詳細的那個；它應是最小的圖表，能清楚呈現工作流程、決策、責任與重要例外情況。

快速語法參考

範例使用 PlantUML 目前的活動圖語法。對於不常見的結構或特定版本的渲染行為，請參閱 PlantUML 活動圖參考文檔。