uml-modeling

UML 建模技能

何时使用此技能

在以下情况下使用此技能：

• UML 建模任务 - 处理 UML 图生成工作，包括类图、时序图、活动图、用例图和状态图
• 规划或设计 - 需要 UML 建模方法方面的指导
• 最佳实践 - 希望遵循既定模式和标准

概述

使用 PlantUML 和 Mermaid 表示法创建 UML 图，用于软件设计文档。

强制要求：文档优先的方法

创建 UML 图之前：

1. 调用 docs-management 技能，获取 UML 标准指导
2. 使用适当的表示法（PlantUML/Mermaid）验证图的语法
3. 所有指导均以 UML 2.5 规范为依据

UML 图类型

结构图

图	用途	使用时机
类图	显示类、属性、方法和关系	领域建模、设计
组件图	显示组件及其依赖关系	架构文档
部署图	显示物理部署	基础设施规划
对象图	显示对象实例	特定场景
包图	显示命名空间/模块	代码组织

行为图

图	用途	使用时机
用例图	显示参与者与系统的交互	需求
时序图	显示随时间变化的消息流	API 设计、协议
活动图	显示工作流和流程	业务流程
状态机图	显示状态转换	生命周期建模
通信图	显示对象交互	设计模式

类图

PlantUML 语法

@startuml
skinparam classAttributeIconSize 0

abstract class Entity {
  +Id: Guid
  +CreatedAt: DateTimeOffset
  +UpdatedAt: DateTimeOffset
}

class Order extends Entity {
  -_lineItems: List<LineItem>
  +CustomerId: Guid
  +Status: OrderStatus
  +Total: Money
  --
  +AddItem(product: Product, quantity: int): Result<LineItem>
  +RemoveItem(lineItemId: Guid): Result
  +Submit(): Result
  +Cancel(): Result
}

class LineItem extends Entity {
  +ProductId: Guid
  +ProductName: string
  +Quantity: int
  +UnitPrice: Money
  +LineTotal: Money
}

enum OrderStatus {
  Draft
  Submitted
  Paid
  Shipped
  Delivered
  Cancelled
}

class Money <<value object>> {
  +Amount: decimal
  +Currency: string
  +{static} Zero: Money
  +Add(other: Money): Money
  +Multiply(factor: decimal): Money
}

Order "1" *-- "0..*" LineItem : contains
Order --> OrderStatus
Order --> Money
LineItem --> Money

@enduml

Mermaid 类图

classDiagram
    class Entity {
        <<abstract>>
        +Guid Id
        +DateTimeOffset CreatedAt
        +DateTimeOffset UpdatedAt
    }

    class Order {
        -List~LineItem~ _lineItems
        +Guid CustomerId
        +OrderStatus Status
        +Money Total
        +AddItem(Product, int) Result~LineItem~
        +RemoveItem(Guid) Result
        +Submit() Result
        +Cancel() Result
    }

    class LineItem {
        +Guid ProductId
        +string ProductName
        +int Quantity
        +Money UnitPrice
        +Money LineTotal
    }

    class OrderStatus {
        <<enumeration>>
        Draft
        Submitted
        Paid
        Shipped
        Delivered
        Cancelled
    }

    Entity <|-- Order
    Entity <|-- LineItem
    Order "1" *-- "0..*" LineItem : contains
    Order --> OrderStatus

关系类型

// UML Relationship Reference
public static class UMLRelationships
{
    // Association: uses, knows about
    // Customer --> Order (Customer uses Order)

    // Aggregation: has-a (shared ownership)
    // Team o-- Player (Team has Players, Players can exist independently)

    // Composition: contains (exclusive ownership)
    // Order *-- LineItem (Order contains LineItems, LineItems cannot exist without Order)

    // Inheritance: is-a
    // Dog --|> Animal (Dog extends Animal)

    // Implementation: implements
    // UserService ..|> IUserService (UserService implements IUserService)

    // Dependency: depends on
    // Controller ..> Service (Controller depends on Service)
}

时序图

PlantUML 语法

@startuml
title Order Submission Flow

actor Customer
participant "API Gateway" as API
participant "Order Service" as Orders
participant "Payment Service" as Payment
participant "Notification Service" as Notify
database "Order DB" as DB
queue "Message Bus" as Bus

Customer -> API: POST /orders/{id}/submit
activate API

API -> Orders: SubmitOrder(orderId)
activate Orders

Orders -> DB: GetOrder(orderId)
activate DB
DB --> Orders: Order
deactivate DB

alt Order is valid
    Orders -> Payment: ProcessPayment(order)
    activate Payment

    Payment --> Orders: PaymentResult
    deactivate Payment

    alt Payment successful
        Orders -> DB: UpdateStatus(Paid)
        Orders -> Bus: Publish(OrderSubmitted)
        Bus -> Notify: OrderSubmitted
        activate Notify
        Notify -> Notify: SendConfirmation()
        deactivate Notify

        Orders --> API: Success
        API --> Customer: 200 OK
    else Payment failed
        Orders --> API: PaymentFailed
        API --> Customer: 402 Payment Required
    end
else Order invalid
    Orders --> API: ValidationError
    API --> Customer: 400 Bad Request
end

deactivate Orders
deactivate API

@enduml

Mermaid 时序图

sequenceDiagram
    participant C as Customer
    participant A as API Gateway
    participant O as Order Service
    participant P as Payment Service
    participant D as Database

    C->>A: POST /orders/{id}/submit
    activate A
    A->>O: SubmitOrder(orderId)
    activate O
    O->>D: GetOrder(orderId)
    D-->>O: Order

    alt Order valid
        O->>P: ProcessPayment(order)
        P-->>O: PaymentResult

        alt Payment successful
            O->>D: UpdateStatus(Paid)
            O-->>A: Success
            A-->>C: 200 OK
        else Payment failed
            O-->>A: PaymentFailed
            A-->>C: 402 Payment Required
        end
    else Order invalid
        O-->>A: ValidationError
        A-->>C: 400 Bad Request
    end

    deactivate O
    deactivate A

活动图

PlantUML 语法

@startuml
title Order Processing Workflow

start

:Customer submits order;

:Validate order;

if (Order valid?) then (yes)
  :Calculate totals;
  :Reserve inventory;

  fork
    :Process payment;
  fork again
    :Send confirmation email;
  end fork

  if (Payment successful?) then (yes)
    :Confirm inventory;
    :Create shipment;
    :Update order status;
    stop
  else (no)
    :Release inventory;
    :Notify customer;
    stop
  endif
else (no)
  :Return validation errors;
  stop
endif

@enduml

用例图

PlantUML 语法

@startuml
left to right direction

actor Customer
actor "Warehouse Staff" as Warehouse
actor Admin

rectangle "E-Commerce System" {
  usecase "Browse Products" as UC1
  usecase "Add to Cart" as UC2
  usecase "Checkout" as UC3
  usecase "Track Order" as UC4
  usecase "Process Refund" as UC5
  usecase "Manage Inventory" as UC6
  usecase "Fulfill Order" as UC7
  usecase "Generate Reports" as UC8

  Customer --> UC1
  Customer --> UC2
  Customer --> UC3
  Customer --> UC4
  Customer --> UC5

  Warehouse --> UC6
  Warehouse --> UC7

  Admin --> UC6
  Admin --> UC8

  UC3 ..> UC2 : <<include>>
  UC5 ..> UC4 : <<extend>>
}

@enduml

状态机图

PlantUML 语法

@startuml
title Order State Machine

[*] --> Draft : Create

Draft --> Submitted : Submit
Draft --> Cancelled : Cancel

Submitted --> Paid : PaymentReceived
Submitted --> Cancelled : Cancel
Submitted --> Draft : RequiresChanges

Paid --> Shipped : Ship
Paid --> Refunded : Refund

Shipped --> Delivered : Deliver
Shipped --> Returned : Return

Delivered --> Completed : Finalize
Delivered --> Returned : Return

Returned --> Refunded : ProcessReturn

Completed --> [*]
Refunded --> [*]
Cancelled --> [*]

@enduml

Mermaid 状态图

stateDiagram-v2
    [*] --> Draft : Create

    Draft --> Submitted : Submit
    Draft --> Cancelled : Cancel

    Submitted --> Paid : PaymentReceived
    Submitted --> Cancelled : Cancel
    Submitted --> Draft : RequiresChanges

    Paid --> Shipped : Ship
    Paid --> Refunded : Refund

    Shipped --> Delivered : Deliver
    Shipped --> Returned : Return

    Delivered --> Completed : Finalize
    Delivered --> Returned : Return

    Returned --> Refunded : ProcessReturn

    Completed --> [*]
    Refunded --> [*]
    Cancelled --> [*]

组件图

PlantUML 语法

@startuml
title System Components

package "Presentation Layer" {
  [Web Application] as Web
  [Mobile App] as Mobile
}

package "API Layer" {
  [API Gateway] as Gateway
  [GraphQL Server] as GraphQL
}

package "Business Layer" {
  [Order Service] as Orders
  [Payment Service] as Payment
  [Notification Service] as Notify
  [User Service] as Users
}

package "Data Layer" {
  database "Order DB" as OrderDB
  database "User DB" as UserDB
  queue "Message Bus" as Bus
}

package "External" {
  [Payment Provider] as PaymentExt
  [Email Service] as EmailExt
}

Web --> Gateway
Mobile --> Gateway
Gateway --> GraphQL
Gateway --> Orders
Gateway --> Users

Orders --> OrderDB
Orders --> Bus
Users --> UserDB

Payment --> PaymentExt
Notify --> EmailExt
Notify --> Bus

@enduml

最佳实践

通用指南

1. 让图聚焦：每张图表达一个概念
2. 使用一致的表示法：每个项目选择 PlantUML 或 Mermaid
3. 添加有意义的名称：使用清晰、描述性的标签
4. 包含图例：用于复杂图表
5. 版本控制：将图与代码一同存储在代码库中

图表选择指南

需求	图类型
数据结构、领域模型	类图
API 流程、协议	时序图
业务流程	活动图
参与者交互	用例图
生命周期、状态转换	状态机图
系统结构	组件图
基础设施	部署图

工作流

创建 UML 图时：

1. 明确目的：这张图要回答什么问题？
2. 选择图类型：选择最合适的类型
3. 使用文本起草：采用 PlantUML 或 Mermaid 表示法
4. 检查准确性：根据代码/需求进行验证
5. 补充上下文：按需添加标题、注释和图例
6. 渲染并验证：确保图表能正确渲染

参考资料

有关详细表示法指南：

---

最后更新： 2025-12-26