最小有效 UML：軟體系統建模實用指南

UML 在促進溝通與決策時最具實用價值，而非淪為文件編寫的工具。團隊通常不需要所有類型的 UML 圖表。在大多數專案中，七種圖表類型即可奠定堅實基礎：

1. 使用案例圖

2. 活動圖

3. 序列圖

4. 類別圖

5. 元件圖

6. 部署圖

7. 狀態機圖

這些圖表共同從互補的視角描述系統：

• 目標：使用者與外部系統的需求

• 行為：工作如何在系統中流動

• 互動：物件與服務如何協作

• 結構：存在哪些實體與關係

• 架構：主要軟體組件如何組織

• 運作：系統執行的位置

• 生命週期：重要物件如何隨時間演變

目標並非為每個可能的關注點建立一張圖表，而是建立最小且連貫的模型集合，以回應利害關係人真正提出的問題。

1. 「最小有效 UML」的意義

最小有效 UML 是一種基於四項原則的建模策略：

• 為決策而建模：建立圖表是為了釐清需求、設計選擇、風險或實作細節。

• 使用最簡潔且足夠的表示法：避免不必要的符號、裝飾和細節。

• 保持可追溯性：在可行情況下，將需求與行為、結構、程式碼、測試和部署進行關聯。

• 保持圖表易於理解：包含一切內容的圖表往往無法傳達任何資訊。

一個有用的模型應有助於回答以下類型的問題：

• 誰與系統互動？

• 系統必須提供哪些功能？

• 哪些步驟構成了一個業務流程？

• 哪個物件或服務負責每個動作？

• 必須表示哪些資料和領域概念？

• 子系統如何劃分？

• 應用程式、資料庫和外部服務部署在哪裡？

• 重要實體如何在其生命週期中轉換？

如果圖表無助於回答其中任何一個問題，則可能沒有必要。

2. 七圖核心

這些圖表並非獨立存在。它們形成一個鏈條：

狀態機圖透過描述具有有意義狀態的物件的生命週期，橫跨此鏈。

例如，線上訂單可表示如下：

• 使用案例：下訂單

• 活動：驗證購物車、授權付款、保留庫存、確認訂單

• 序列：客戶介面呼叫訂單服務、付款服務與庫存服務

• 類別： 訂單, 訂單明細, 付款、以及 產品

• 元件：網頁應用程式、訂單服務、付款配接器、庫存服務

• 部署：瀏覽器、應用程式叢集、資料庫、付款提供者

• 狀態機：草稿 → 待付款 → 已付款 → 已出貨 → 已送達

3. 使用案例圖：定義系統目標

使用案例圖從外部呈現系統。它識別與系統互動的參與者及其追求的目标。

3.1 使用案例圖包含的內容

主要元素包括：

• 系統邊界：定義被建模系統內部的內容

• 參與者：人員、組織、裝置或外部系統

• 使用案例：系統所提供的目標或服務

• 關聯：參與者與使用案例之間的連結

• 包含關聯：另一個使用案例所需的可重現行為

• 擴展關聯：選取性或條件式行為

範例：

@startuml
left to right direction

actor Customer
actor "Payment Provider" as PaymentProvider
actor "Warehouse System" as Warehouse

rectangle "Online Store" {
  usecase "Browse Products" as UC1
  usecase "Place Order" as UC2
  usecase "Authorize Payment" as UC3
  usecase "Fulfill Order" as UC4
}

Customer --> UC1
Customer --> UC2
UC2 ..> UC3 : <<include>>
PaymentProvider --> UC3
Warehouse --> UC4
@enduml

3.2 正確識別參與者

參與者不一定是人類角色；它是任何與系統互動的外部實體。

可能的參與者包括：

• 客戶

• 支援代理

• 管理員

• 金流閘道

• 身分提供者

• 倉儲管理系統

• 排程工作

• 行動應用程式

• 物聯網裝置

避免根據內部實現細節來命名參與者。「REST 控制器」通常不是參與者。「合作夥伴應用程式」則可能是。

3.3 將使用案例命名為目標

良好的使用案例名稱描述結果：

• 提交費用報表

• 核准採購申請

• 註冊新病患

• 產生發票

• 重設密碼

薄弱的名稱描述實現機制：

• 呼叫 API

• 執行 SQL 查詢

• 開啟表單

• 呼叫控制器

使用案例應回答：

參與者希望透過系統達成什麼有意義的結果？

3.4 何時使用 include 和 extend

使用<<include>>當一個行為總是作為另一個行為的一部分而被需要時。

例如：

• 「下訂單」包含「計算總額」

• 「註冊帳戶」包含「驗證電子郵件」

使用<<extend>>當行為是選填或具條件性時。

例如：

• 「下訂單」可能由「套用促銷折扣」延伸

• 「登入」可能由「完成多因素驗證」延伸

不要僅為了讓圖表看起來更複雜而使用這些關係。通常，簡短的書面情境或活動圖會更清晰。

3.5 使用案例圖無法顯示的內容

用例圖並非用於描述：

• 詳細的用戶介面佈局

• 確切的實現類別

• 資料庫資料表

• 訊息順序

• 演算法邏輯

• 基礎設施拓撲結構

它們定義範圍與目標，其他圖則提供細節。

4. 活動圖：建模工作流程與流程

活動圖顯示工作如何推進。它們特別適用於業務流程、工作流程、分支邏輯、平行工作及例外處理。

4.1 核心元素

活動圖通常使用：

• 起始節點

• 動作

• 決策節點

• 合併節點

• 分叉與匯合

• 泳道

• 終止節點

• 保護條件，例如：[已核准]或 [已拒絕]

範例：

@startuml
|客戶|
start
:提交訂單;

|訂單服務|
:驗證訂單;

if (訂單有效？) then (是)
  :計算總額;

  fork
    |付款服務|
    :授權付款;
  fork again
    |庫存服務|
    :預留庫存;
  end fork

  |訂單服務|
  :確認訂單;
  stop
else (否)
  :回傳驗證錯誤;
  stop
endif
@enduml

4.2 使用泳道來顯示職責

泳道可釐清哪個角色、系統或組件執行每個動作。

實用的泳道可能代表：

• 客戶

• 客服專員

• 訂單服務

• 支付服務提供者

• 倉庫

• 自動排程器

當流程跨越組織或系統界線時，泳道尤為寶貴。

4.3 明確建模決策

決策應具備有意義的條件：

[付款核准]
[付款拒絕]

避免使用模糊的標籤，例如：

[是]
[否]

除非決策問題本身已一目了然。

4.4 在重要時顯示並行性

當活動同時發生時，分叉與匯合十分有用。例如，訂單驗證後：

• 可能進行付款授權

• 可能保留庫存

• 可能執行詐欺檢查

然而，僅在並行性影響時序、一致性、失敗處理或系統設計時才進行建模。切勿僅為了使圖表更複雜而使用並行分支。

4.5 活動圖與需求

活動圖可揭露缺失的需求。例如，在建模核准流程時，團隊可能會發現未解答的問題：

• 如果核准者無法使用會發生什麼事？

• 請求是否可以被拒絕並重新提交？

• 升級時間為何？

• 是否可以由兩人同時核准？

• 如果下游系統無法使用會發生什麼事？

這使得活動圖在實施開始前非常有用。

5. 序列圖：解釋隨時間推移的協作

序列圖顯示參與者如何在按時間順序的互動中交換訊息。它們非常適合詳細描述重要情境。

5.1 主要元素

序列圖通常包含：

• 參與者

• 物件或服務

• 生命線

• 訊息

• 回覆訊息

• 活化條

• 條件

• 迴圈

• 替代路徑

• 非同步訊息

範例：

@startuml
actor Customer
boundary "Web App" as Web
control "Order Service" as Order
control "Payment Service" as Payment
database "Order DB" as DB

Customer -> Web : 提交訂單
Web -> Order : createOrder(cart)

Order -> DB : save(order)
DB --> Order : orderId

Order -> Payment : authorize(amount)

alt 付款已核准
  Payment --> Order : 已核准
  Order -> DB : updateStatus(PAID)
  Order --> Web : 確認
  Web --> Customer : 顯示確認
else 付款遭拒
  Payment --> Order : 遭拒
  Order -> DB : updateStatus(PAYMENT_FAILED)
  Order --> Web : 付款錯誤
  Web --> Customer : 顯示錯誤
end
@enduml

5.2 策略性地選擇情境

不要為每個使用案例建立序列圖。從以下情境開始：

• 業務關鍵

• 技術風險高

• 整合密集

• 安全敏感

• 交易相關

• 難以理解

• 可能暴露架構問題

典型範例包括：

• 使用者驗證

• 金流處理

• 檔案上傳

• 訂單提交

• 密碼重設

• 事件發布

• 失敗復原

• 背景作業執行

5.3 區分同步與非同步互動

同步呼叫表示發送方會等待回應；非同步訊息則允許發送方繼續執行。

此區分會影響：

• 使用者體驗

• 交易邊界

• 錯誤處理

• 可擴展性

• 重試行為

• 可觀測性

請一致地使用不同的標記法，並在註解或附帶文字中說明重要的非同步行為。

5.4 建立失敗路徑模型

僅顯示成功路徑的序列圖可能隱藏重大設計風險。請使用alt, opt、以及loop片段來顯示：

• 驗證失敗

• 授權失敗

• 逾時

• 重試

• 部分失敗

• 重複請求

• 服務不可用

• 補償或回滾

例如：

@startuml
客戶端 -> API : 提交請求

API -> 服務 : 處理請求

alt 服務回應
  服務 --> API : 結果
  API --> 客戶端 : 成功
else 逾時
  API -> 服務 : 重試請求
  alt 重試成功
    服務 --> API : 結果
    API --> 客戶端 : 成功
  else 重試失敗
    API --> 客戶端 : 暫時失敗
  end
end
@enduml

5.5 避免過於詳細的序列圖

當序列圖包含每個內部方法呼叫時，將變得難以維護。應聚焦於有意義的職責與邊界：

• 使用者介面

• 應用程式服務

• 領域物件

• 儲存庫

• 外部服務

• 訊息中介軟體

• 資料庫

詳細的實作圖可能在除錯時有幫助，但不應成為主要的架構文件。

6. 類別圖：描述結構與領域概念

類別圖顯示靜態結構。它們可以描述以下任一項：

• 概念領域模型

• 設計層級的物件模型

• 以實作為導向的類別結構

這些是不同層次的抽象，不應隨意混用。

6.1 概念式與實作式類別圖

概念式模型可能包含：

• 客戶

• 訂單

• 產品

• 付款

實作式模型可能包含：

• 訂單控制器

• 訂單應用程式服務

• 訂單儲存庫

• 付款閘道配接器

兩者皆有效，但它們回答的是不同的問題。

6.2 核心關聯

常見關聯包括：

• 關聯

• 聚合

• 組合

• 泛化

• 相依性

• 實現

請謹慎使用關聯。在許多情況下，簡單的關聯比在聚合與組合之間做細微區分更為清晰。

範例：

@startuml
class Customer {
  +id: CustomerId
  +name: String
  +email: EmailAddress
}

class Order {
  +id: OrderId
  +status: OrderStatus
  +total(): Money
  +submit()
}

class OrderLine {
  +quantity: int
  +unitPrice: Money
  +lineTotal(): Money
}

class Product {
  +sku: String
  +name: String
}

Customer "1" -- "0..*" Order : places
Order "1" *-- "1..*" OrderLine : contains
OrderLine "*" --> "1" Product : refers to
@enduml

6.3 多重性至關重要

多重性表達約束：

• 1 — 恰好一個

• 0..1 — 可選

• * — 多個

• 1..* — 一個或多個

例如：

客戶 "1" -- "0..*" 訂單

表示每個訂單屬於一位客戶，而一位客戶可能擁有零個或多個訂單。

6.4 建模職責，而不僅是資料欄位

類別圖應有助於說明行為應歸屬於何處。具有有意義操作的領域物件，通常比僅包含 getter 和 setter 的一組類別更具資訊性。

例如：

Order.submit()
Order.cancel()
Order.calculateTotal()
Payment.authorize()

具體操作取決於設計方法，但原則是一致的：

將重要的業務職責置於擁有它們的概念附近。

6.5 避免將類別圖轉化為資料庫結構

類別圖並非自動等同於關聯式結構。除非目的是專門進行持久化設計，否則不要加入所有資料庫欄位。

一個有用的區分是：

• 領域模型：業務概念與規則

• 設計模型：軟體類別與職責

• 資料模型：資料表、金鑰、索引與約束

這些可能相互關聯，但不可混淆。

7. 元件圖：顯示架構邊界

元件圖描述系統中主要可替換或可部署的組件，以及它們互動的介面。

它們有助於回答以下問題：

• 主要的子系統有哪些？

• 哪個元件負責某項職責？

• 每個元件提供什麼功能？

• 每個元件需要什麼？

• 整合邊界位於何處？

• 哪些相依關係是穩定的或具有風險的？

範例：

@startuml
component "Web Application" as Web
component "Order Service" as Order
component "Payment Adapter" as Payment
component "Inventory Service" as Inventory
database "Order Database" as DB
cloud "External Payment Provider" as Provider

Web --> Order : REST API
Order --> Payment : Payment interface
Order --> Inventory : Inventory API
Order --> DB : Persistence
Payment --> Provider : Provider API
@enduml

7.1 元件圖不是套件圖

套件圖將模型元素分組，通常用於組織目的。元件圖則描述提供與消耗功能的架構單元。

一個元件可能是：

• 一個可部署的服務

• 一個網頁應用程式

• 一個行動應用程式

• 一個函式庫

• 一個訊息中介軟體

• 一個外部平台

• 一個資料庫

• 一個第三方整合

適當的層級取決於架構。

7.2 在能釐清契約處顯示介面

介面使相依關係更加明確：

@startuml
介面 PaymentGateway

元件「訂單服務」作為 Order
元件「付款配接器」作為 Adapter

Order ..> PaymentGateway
Adapter - PaymentGateway
@enduml

這表示訂單服務依賴於抽象層，而非特定提供者。

7.3 使用元件圖以支援架構決策

當元件圖搭配簡短的設計註解時，其價值會更高：

• 為何存在此邊界？

• 誰擁有這些資料？

• 互動是同步還是非同步？

• 當依賴關係失敗時會發生什麼事？

• 該元件是否可獨立部署？

• 它代表什麼安全邊界？

• 存在哪些一致性保證？

圖表不需包含所有答案，但應將注意力引導至重要問題。

8. 部署圖：將軟體與基礎設施連接

部署圖顯示軟體構建成果執行的實體或虛擬環境。

它們有助於回答：

• 每個應用程式在何處執行？

• 哪些節點進行通訊？

• 資料庫位於何處？

• 哪些服務可從外部存取？

• 存在哪些網路邊界？

• 系統如何分佈？

• 哪些基礎設施選擇會影響可靠性或效能？

範例：

@startuml
node "使用者裝置" as Device {
  artifact "瀏覽器" as Browser
}

node "雲端區域" as Cloud {
  node "Web 層" as WebTier {
    artifact "Web 應用程式" as WebApp
  }

  node "應用程式層" as AppTier {
    artifact "訂單服務" as OrderSvc
    artifact "付款配接器" as PaymentSvc
  }

  database "訂單資料庫" as DB
}

cloud "付款提供者" as Provider

Browser --> WebApp : HTTPS
WebApp --> OrderSvc : HTTPS
OrderSvc --> DB : TLS
OrderSvc --> PaymentSvc
PaymentSvc --> Provider : HTTPS
@enduml

8.1 區分節點、工件與環境

• 一個「節點」是一種執行環境，例如伺服器、容器、裝置、虛擬機器或受管理平台。

• 一個「工件」是一種可部署的軟體單元，例如二進位檔案、容器映像、套件或應用程式。

• 一個「環境」可代表開發、測試、預先上線或生產環境。

8.2 納入運作上重要的細節

視目的而定，部署圖可能顯示：

• 負載平衡器

• 防火牆

• 網路區域

• 容器叢集

• 可用性區域

• 資料庫與複本

• 快取

• 訊息中介軟體

• 物件儲存

• 外部服務

• 監控與記錄系統

請勿加入對所記錄決策無影響的基礎設施細節。

8.3 使用部署圖進行風險分析

部署建模可以揭示：

• 單點故障

• 暴露的資料庫

• 缺失的網路邊界

• 過度的跨區域流量

• 缺乏故障轉移策略的依賴關係

• 環境之間分隔不足

• 未加密的連線

• 不切實際的擴展假設

9. 狀態機圖：建模生命週期

狀態機圖描述實體如何透過在不同狀態間轉換來回應事件。

當物件的行為強烈依賴其當前狀態時，它們尤為寶貴。

常見範例包括：

• 訂單

• 付款

• 出貨

• 支援工單

• 使用者帳戶

• 工作流程請求

• 訂閱

• 文件

• 裝置

• 工作執行

範例：

@startuml
[*] --> Draft

Draft --> PendingPayment : submit
PendingPayment --> Paid : payment approved
PendingPayment --> PaymentFailed : payment declined
PaymentFailed --> PendingPayment : retry payment
Paid --> Processing : begin fulfillment
Processing --> Shipped : dispatch
Shipped --> Delivered : confirm delivery
Paid --> Cancelled : cancel
Processing --> Cancelled : cancel if allowed
Delivered --> [*]
Cancelled --> [*]
@enduml

9.1 仔細定義狀態

狀態應代表有意義的條件，而不僅僅是動作。

良好的狀態：

• 待審批

• 已核准

• 已拒絕

• 付款失敗

• 已出貨

薄弱的狀態：

• 點擊按鈕

• 呼叫服務

• 執行方法

動作是事件或轉換。狀態是持續存在的條件。

9.2 包含轉換規則

轉換可包含：

• 事件

• 保護條件

• 動作

例如：

待審批 -- 核准 [經理授權] / 記錄核准 --> 已核准

這使業務規則可見且可測試。

9.3 使用狀態機推導測試

每個轉換都暗示了測試案例：

• 有效轉換

• 無效轉換

• 保護條件失敗

• 重複事件

• 超時

• 重試

• 取消

• 復原

對於訂單生命週期，測試可能驗證：

• 草稿訂單可以提交

• 已送達的訂單無法取消

• 付款失敗允許重試

• 已取消的訂單無法恢復為已付款狀態

10. 七張圖表如何協同運作

這些圖表應構成一個一致的模型，而非七張彼此孤立的插圖。

考慮「提交費用報表」的功能。

使用情境

• 員工提交費用報表

• 經理核准費用報表

• 財務人員處理報銷

活動

• 輸入費用

• 附上收據

• 驗證資料

• 提交報表

• 轉發至經理

• 核准或拒絕

• 送交財務部門

序列

• 員工介面呼叫費用服務

• 費用服務驗證報表

• 收據服務儲存附件

• 工作流服務指派經理

• 通知服務發送警報

類別

• 員工

• 費用報表

• 費用項目

• 收據

• 核准

• 報銷

元件

• 網頁應用程式

• 費用服務

• 收據儲存

• 工作流程服務

• 通知服務

• 財務整合

部署

• 瀏覽器

• 網頁層

• 應用程式叢集

• 物件儲存

• 關聯式資料庫

• 財務平台

狀態機

草稿 → 已提交 → 審查中 → 已核准 → 已報銷
                         ↓
                      遭駁回

每個圖表都提供不同的視角，且不會重複其他所有圖表。

11. 選擇要建立的圖表

一個實用的選擇流程是詢問團隊面臨哪種類型的疑慮。

並非每個功能都需要對應的圖表。

輕量級決策規則

當以下任一條件成立時，請建立圖表：

• 多位利害關係人對需求有不同的詮釋。

• 某個流程具有重要的分支或平行行為。

• 某個情境跨越多個系統邊界。

• 某個領域物件具有非平凡的規則。

• 需要溝通某項架構決策。

• 部署拓撲會影響可靠性、安全性或效能。

• 生命週期規則難以用文字敘述清楚。

• 該圖表將用於實作、審查、測試或營運的複用。

避免僅因範本要求而建立圖表。

12. 詳細程度層級

良好的建模實踐會運用多個抽象層級。

情境層級

顯示系統與主要的外部參與者或系統。

適用於：

• 範圍

• 利害關係人溝通

• 系統邊界

容器或子系統層級

顯示應用程式、服務、資料庫及主要整合。

適用於：

• 架構

• 所有權

• 部署規劃

元件層級

顯示內部架構組件與介面。

適用於：

• 詳細設計

• 相依性審查

• 團隊邊界

程式碼層級

顯示類別、方法與實作相依性。

適用於：

• 開發人員工作

• 重構

• 除錯

請勿將所有層級置於同一張圖中。情境圖不應包含所有類別，而類別圖也不應嘗試呈現整個生產網路。

13. Visual Paradigm UML

Visual Paradigm 非常適合偏好圖形建模與整合文件化的團隊。

它可用於：

• 互動式繪製 UML 圖

• 維護模型儲存庫

• 將圖表與需求連結

• 建立可追蹤性關聯

• 產出文件

• 透過共用建模環境進行協作

• 產生或逆向工程選定產出物

• 使用導航與組織功能來管理較大的模型

13.1 優勢

圖形化 UML 工具在以下情況特別有幫助：

• 分析師與非開發人員需要編輯圖表

• 利害關係人偏好視覺化操作

• 專案需要正式的模型組織

• 可追溯性至關重要

• 團隊維護中央儲存庫

• 文件必須一致地產生

13.2 建議用法

對於能從以下功能受益的模型視圖，請使用 Visual Paradigm：

• 互動式版面配置

• 豐富的註解

• 跨圖表導航

• 正式的儲存庫管理

• 可追溯性

• 利害關係人工作坊

不要讓工具決定建模策略。首先請決定：

• 該圖表支援哪項決策

• 誰將閱讀它

• 何種詳細程度是適當的

• 它將如何維護

• 模型是否需要連接到需求或程式碼

13.3 儲存庫規範

共用模型儲存庫可從與原始碼控制相同的實踐中受益：

• 建立命名慣例

• 指派主要模型領域的負責人

• 審查重大變更

• 避免不必要的重複圖表

• 封存過時的視圖

• 記錄重要圖表的目的

• 保持模型元素名稱的一致性

14. VPasCode 與基於文字的建模

VPasCode 在 Visual Paradigm 生態系統中支援以文字為導向的建模方法。這種風格對於希望圖表更像原始程式碼產物的團隊非常有用。

基於文字的圖表可提供：

• 版本控制相容性

• 程式碼審查

• 分支與合併

• 自動生成

• 可重複的建置

• 更輕鬆的批次更新

• 與原始程式碼和文件更緊密結合

基於文字的模型可能如下所示：

actor Customer
usecase "Place Order" as PlaceOrder
Customer --> PlaceOrder

確切的語法取決於所使用的工具和工作流程，但更廣泛的優勢在於圖表以可編輯的文字形式呈現，而不僅是圖形檔案。

14.1 基於文字的建模何時效果良好

在以下情況使用基於文字的圖表：

• 開發人員維護模型

• 圖表經常變更

• 團隊使用 Git 或其他版本控制系統

• 審查人員希望檢視文字變更

• 圖表作為文件的一部分生成

• 多個分支需要獨立演進

14.2 潛在限制

在以下情況，基於文字的建模可能較不便利：

• 業務利害關係人需要直接編輯圖表

• 版面配置必須手動最佳化

• 模型包含豐富的視覺註解

• 團隊不熟悉圖表語法

• 儲存庫需要複雜的視覺導航功能

混合方法通常行之有效：針對程式碼導向的架構使用文字式圖表，針對利益相關者導向的分析則使用圖形化工具。

15. PlantUML

PlantUML 是一種廣為流行的文字式圖表方法，可從純文字生成 UML 及相關的架構圖表。

範例：

@startuml
actor User
participant "Web App" as Web
participant "Application Service" as App
database Database

User -> Web : Request
Web -> App : Execute operation
App -> Database : Read/write data
Database --> App : Result
App --> Web : Response
Web --> User : Display result
@enduml

15.1 優點

PlantUML 具有價值，因為圖表可以：

• 儲存於原始程式碼旁

• 在拉取請求中進行審查

• 自動生成

• 透過簡單的文字編輯進行更新

• 納入 Markdown 或文件管線中

• 在不同環境中一致產出

15.2 組織 PlantUML 檔案

一個實用的儲存庫結構可能如下：

docs/
  architecture/
    system-context.puml
    components.puml
    deployment.puml
  workflows/
    place-order.puml
    refund-payment.puml
  domain/
    order-model.puml
    order-lifecycle.puml

使用具描述性的名稱，並按目的而非工具來組織圖表。

15.3 將生成的影像排除在單一真相來源之外

在可能的情況下：

• 儲存 .puml 檔案作為權威來源

• 在文件建置期間生成 PNG、SVG 或 PDF 檔案

• 避免手動編輯生成的影像

• 驗證圖表在自動化環境中能否成功呈現

15.4 使用一致的樣式

定義一套簡潔的視覺詞彙：

• 外部系統使用一種顏色

• 內部服務使用一種顏色

• 資料庫使用一種顏色

• 非同步訊息傳遞使用一種標記法

• 介面使用一種命名慣例

• 表示安全邊界使用一種方式

一致性比裝飾更為重要。

16. 人工智慧輔助的 UML 建模

人工智慧可以加速建模過程，但應將其視為建模助手，而非權威來源。

人工智慧適用於以下用途：

• 將需求轉換為候選用例

• 提取參與者與目標

• 提出活動流程

• 生成 PlantUML 程式碼

• 建議序列圖中的參與者

• 識別領域實體

• 偵測遺漏的替代路徑

• 審查圖表的一致性

• 從圖表生成文件

• 在圖形表示與文字表示之間進行轉換

• 從狀態轉換生成測試構想

16.1 高效的人工智慧工作流程

可靠的工作流程如下：

1. 提供需求、限制與系統情境。

2. 請人工智慧識別假設與模糊之處。

3. 生成候選圖表。

4. 根據實際需求審查圖表。

5. 將其與實作和基礎設施進行比較。

6. 修正不準確或虛構的細節。

7. 視覺化呈現並檢查結果。

8. 取得相關利害關係人的審查。

9. 將核准的模型儲存至專案儲存庫。

10. 當系統變更時進行更新。

16.2 以限制條件提示 AI

弱提示：

為訂單系統建立 UML 圖表。

更強的提示：

建立用於提交訂單的 PlantUML 序列圖。

參與者：
- 客戶
- Web 應用程式
- 訂單服務
- 付款提供者
- 庫存服務
- 訂單資料庫

限制條件：
- 訂單確認前必須先完成付款授權。
- 庫存保留可與付款授權並行發生。
- 付款被拒絕時，訂單狀態必須維持為「付款失敗」。
- 超時應重試一次。
- 顯示成功、被拒絕和超時的路徑。
- 不得編造此處未列出的服務。

限制條件陳述得越清楚，輸出包含不支援架構的可能性就越低。

16.3 請 AI 進行批判性評估，而不僅是生成

有用的審查提示包括：

• 哪些需求未被呈現？

• 缺少哪些分支？

• 此序列圖是否與狀態機矛盾？

• 是否有任何相依關係未加說明？

• 是否有職責被分配給錯誤的元件？

• 部署模型是否支援可用性需求？

• 哪些轉換應成為測試案例？

• 哪些假設需要確認？

16.4 常見的 AI 建模失敗

AI 生成的模型可能：

• 虛構參與者或服務

• 混淆業務角色與技術元件

• 加入不支援的資料庫資料表

• 假設為同步通訊

• 省略失敗路徑

• 誤導所有權歸屬

• 錯誤地使用 UML 關聯

• 產生語法正確但語義錯誤的圖表

• 混用抽象層級

• 將猜測視為需求

關鍵原則如下：

AI 可以快速生成草稿，但只有領域與技術審查才能確認草稿是否正確。

17. 驗證 UML 是否符合現實

圖表僅在與系統保持一致時才具有價值。

17.1 依據需求進行驗證

檢查：

• 每個重要需求是否都出現在一個或多個模型中？

• 參與者與目標是否正確？

• 是否已呈現業務規則？

• 是否已包含例外情況？

• 在相關處是否已反映非功能性需求？

17.2 依據實作進行驗證

檢查：

• 元件邊界是否與程式碼相符？

• 序列參與者是否存在？

• 介面與訊息是否準確？

• 類別職責是否合理？

• 非同步操作是否正確呈現？

• 狀態轉換是否由實作強制執行？

17.3 依據作業進行驗證

檢查：

• 部署圖是否實際上可進行部署？

• 網路連線是否合理？

• 是否已呈現外部系統？

• 在重要處是否已包含資料庫、佇列、快取與儲存空間？

• 失敗與伸縮的假設是否合理？

17.4 跨圖表驗證

尋找以下類型的矛盾：

• 一個使用案例命名了系統情境中不存在的參與者

• 一個序列圖表調用了架構中未顯示的元件

• 一個狀態機允許了業務規則不支援的轉換

• 一個類別圖表顯示一對多關係，而資料庫強制執行一對一關係

• 一個部署圖表遺漏了序列圖表所需的服務

• 一個活動圖表顯示平行操作，而實現嚴格為順序執行

跨圖表的一致性通常比任何單一圖表的藝術品質更重要。

18. 可追蹤性

可追蹤性將模型與需求、程式碼、測試及操作產出物連結起來。

一個簡單的可追蹤性鏈結可能如下：

需求
  → 使用案例
    → 活動流程
      → 序列情境
        → 元件
          → 實現
            → 自動化測試

對於具狀態的領域物件：

業務規則
  → 狀態轉換
    → 保護條件
      → 測試案例

可追蹤性並不要求將每個元素連結到所有其他元素。應專注於高價值關係：

• 安全關鍵行為

• 法規要求

• 安全控制

• 重要整合

• 複雜的業務規則

• 高風險的架構決策

19. 版本控制與模型維護

圖表是一種文件，若未加以維護，文件將變得不可靠。

19.1 將模型儲存在其描述的工作附近

可能的做法包括：

• 原始碼儲存庫中的 UML 檔案

• 架構文件儲存庫

• 共用模型儲存庫

• 與技術文件一併發布的產生圖表

• 需求與模型元素之間的關聯

19.2 將圖表與程式碼一併審查

對於架構或行為的變更，在可行的情況下，應將相關的圖表更新納入與實作相同的變更中。

審查人員隨後可評估：

• 實作是否符合預期設計

• 設計變更是否已完整完成

• 相依性是否已變更

• 是否存在新的失敗路徑

• 是否已考量部署影響

19.3 優先採用較少的權威圖表

多份相互矛盾的圖表比一份不完整的圖表更糟。應確立每項關注事項的權威圖表。

例如：

• 元件圖：作為主要服務邊界的權威圖表

• 部署圖：作為生產拓撲的權威圖表

• 狀態機：作為訂單生命週期的權威圖表

• 類別圖：作為領域關聯的權威圖表

20. 常見建模錯誤

建模所有事物

圖表較多並不會自動帶來更多理解。應針對重要的風險與決策進行建模。

混用抽象層級

切勿將業務角色、程式類別、雲端基礎架構與資料庫欄位置於同一張未加區分的圖表中。

使用模糊的名稱

「處理資料」或「處理請求」等名稱會掩蓋意圖。應優先使用能識別目標、職責或有意義事件的名稱。

省略失敗行為

僅包含成功情境的模型會產生不切實際的期望。應納入重要的例外情況、重試機制、逾時與拒絕狀態。

將圖表視為永久不變

架構會演進。圖表應有負責人，並應有維護的預期。

過度使用 UML 關聯

簡單的關聯通常優於技術上精確但令人困惑的關聯類型集合。

使圖表難以閱讀

使用多個專注的視圖，而非單一龐大的圖表。按情境、子系統、生命週期或部署邊界將大型模型進行拆解。

讓工具驅動設計

工具可以讓圖表更易於繪製，但無法決定哪些內容應被建模，也無法判斷模型是否正確。

21. 實用的建模工作流程

團隊可針對某個功能或系統採用以下工作流程。

步驟 1：確立範圍

建立輕量級的上下文視圖，並識別：

• 系統邊界

• 主要使用者

• 外部系統

• 主要目標

步驟 2：識別使用情境

將使用情境寫為參與者的目標。將相關功能分組，並識別最重要的情境。

步驟 3：建模主要工作流程

使用活動圖來顯示：

• 正常流程

• 決策點

• 職責

• 平行工作

• 例外情況

步驟 4：選擇關鍵情境

為那些重要、複雜、具風險或高度整合的互動建立序列圖。

步驟 5：定義領域結構

為這些情境中涉及的概念建立概念層級或設計層級的類別圖。

步驟 6：確立架構邊界

使用元件圖來顯示：

• 主要模組或服務

• 介面

• 相依性

• 歸屬權

• 整合點

步驟 7：模型部署

當基礎設施、安全性、擴展性、可用性或營運成為重要考量時，請建立部署圖。

步驟 8：模型生命週期

為行為取決於狀態或允許轉換的實體建立狀態機圖。

步驟 9：驗證

將模型與以下項目進行比較：

• 需求

• 現有程式碼

• 測試

• 資料結構

• 基礎設施

• 營運限制

步驟 10：維護

當行為、介面、所有權或部署發生變更時，請更新受影響的圖表。

22. 一般系統的最小交付成果

對於中型應用程式，實用的基準可能如下：

• 一個系統情境或使用案例視圖

• 兩至五個重要業務流程的活動圖

• 兩至五個關鍵情境的序列圖

• 一個領域類別圖

• 一個元件圖

• 一個生產環境部署圖

• 關鍵生命週期實體的狀態機圖

這並非強制性配額。某些系統可能需要較少的圖表，而其他系統則可能需要更多。適當的數量取決於複雜度、風險、團隊規模、法規以及誤解的代價。

23. 工具選擇策略

不同的工具滿足不同的建模需求。

團隊無需為每種情況選擇單一工具。若真相來源與維護責任明確，混合方法也能運作良好。

結論

實用的 UML 策略並非使用所有圖表類型，而是選擇能讓人理解系統的最小視圖集合。

七圖核心提供廣泛覆蓋：

• 用例圖說明目標與範圍。

• 活動圖說明工作流程與職責。

• 序列圖說明協作與時序。

• 類別圖說明結構與領域概念。

• 組件圖說明架構邊界。

• 部署圖說明執行時配置與基礎設施。

• 狀態機圖說明生命週期規則。

Visual Paradigm 可支援圖形化建模、追蹤性與基於儲存庫的協作。VPasCode 與 PlantUML 使圖表更易於與原始碼一起進行版本控制、審查、生成與維護。AI 可加速草稿、轉換與審查，但其輸出必須與實際需求、真實實現及運作限制進行比對驗證。

最強的建模實踐是講究紀律而非 exhaustive：

1. 建模關鍵的決策、風險與行為。

2. 選擇最能回答問題的那種圖表類型。

3. 讓每個圖表專注於單一抽象層級。

4. 透過一致的命名與追蹤性，連結相關的圖表。

5. 根據需求、程式碼、測試與部署來驗證模型。

6. 將圖表儲存並審查為可維護的專案產出物。

7. 移除不再提供價值的圖表。

有效的 UML 並非以產出的圖表數量來衡量，而是取決於模型是否能協助人們以更確信的方式建置、測試、運作與變更系統。

參考資料

1. VPasCode：結合 PlantUML、Mermaid 與 Graphviz 的 AI 輔助圖表即程式碼解決方案: 官方指南，涵蓋 VPasCode 的文字轉圖表引擎、語法最佳實踐，以及 AI 輔助的修改工作流程。
2. 從「繪圖雜務」到「表達溝通」：AI 聊天機器人概覽: 說明 Visual Paradigm 的 AI 聊天機器人如何將自然語言轉換為符合標準的 UML 及其他圖表。
3. 以 NotesKeep 知識庫驅動 Visual Paradigm AI 聊天機器人: 展示如何將 NotesKeep 儲存庫連接為知識來源，以支援 AI 驅動的圖表生成與需求綜合。
4. 以 Visual Paradigm 革新您的 Mac UML 建模體驗: 概述 Visual Paradigm 在 macOS 上對 UML 2.x 的支援、程式碼工程與模型追蹤能力。
5. Visual Paradigm 18.1 推出 AI VPP 聊天機器人: 發布公告，介紹 AI VPP 聊天機器人，讓使用者能透過自然語言查詢 .vpp 專案檔案。
6. VPasCode 方案與價格: VPasCode 免費層級的價格與功能比較，以及與 Visual Paradigm Online/桌面版的整合說明。
7. 歡迎使用 Visual Paradigm VPasCode：圖表即程式碼的轉型: 介紹圖表即程式碼工作流程，以及 PlantUML、Mermaid 與 Graphviz 的統一渲染環境。
8. Visual Paradigm VPasCode 中的原生 AI 圖表生成: 詳述 VPasCode 內建的 AI，可直接在編輯器中生成與修改 PlantUML/Mermaid/Graphviz 圖表。