name: UML 建模 description: UML 图生成，包括类图、序列图、活动图、用例图和状态图 allowed-tools: Read, Glob, Grep, Write, Edit

UML 建模技能

何时使用此技能

使用此技能时：

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

概述

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

强制要求：文档优先方法

创建 UML 图之前：

调用 docs-management 技能 获取 UML 标准指导
验证图语法 使用适当的符号（PlantUML/Mermaid）
基于 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 关系参考
public static class UMLRelationships
{
    // 关联：使用，知道
    // Customer --> Order (Customer 使用 Order)

    // 聚合：拥有（共享所有权）
    // Team o-- Player (Team 拥有 Players, Players 可以独立存在)

    // 组合：包含（独占所有权）
    // Order *-- LineItem (Order 包含 LineItems, LineItems 不能没有 Order 存在)

    // 继承：是
    // Dog --|> Animal (Dog 继承 Animal)

    // 实现：实现
    // UserService ..|> IUserService (UserService 实现 IUserService)

    // 依赖：依赖于
    // Controller ..> Service (Controller 依赖于 Service)
}

序列图

PlantUML 语法

@startuml
title 订单提交流程

actor Customer
participant "API 网关" as API
participant "订单服务" as Orders
participant "支付服务" as Payment
participant "通知服务" as Notify
database "订单数据库" as DB
queue "消息总线" 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 订单有效
    Orders -> Payment: ProcessPayment(order)
    activate Payment

    Payment --> Orders: PaymentResult
    deactivate Payment

    alt 支付成功
        Orders -> DB: UpdateStatus(Paid)
        Orders -> Bus: Publish(OrderSubmitted)
        Bus -> Notify: OrderSubmitted
        activate Notify
        Notify -> Notify: SendConfirmation()
        deactivate Notify

        Orders --> API: 成功
        API --> Customer: 200 OK
    else 支付失败
        Orders --> API: PaymentFailed
        API --> Customer: 402 支付要求
    end
else 订单无效
    Orders --> API: ValidationError
    API --> Customer: 400 错误请求
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 订单处理工作流

start

:客户提交订单;

:验证订单;

if (订单有效?) then (是)
  :计算总额;
  :预留库存;

  fork
    :处理支付;
  fork again
    :发送确认邮件;
  end fork

  if (支付成功?) then (是)
    :确认库存;
    :创建发货;
    :更新订单状态;
    stop
  else (否)
    :释放库存;
    :通知客户;
    stop
  endif
else (否)
  :返回验证错误;
  stop
endif

@enduml

用例图

PlantUML 语法

@startuml
left to right direction

actor Customer
actor "仓库员工" as Warehouse
actor Admin

rectangle "电子商务系统" {
  usecase "浏览产品" as UC1
  usecase "添加到购物车" as UC2
  usecase "结账" as UC3
  usecase "跟踪订单" as UC4
  usecase "处理退款" as UC5
  usecase "管理库存" as UC6
  usecase "履行订单" as UC7
  usecase "生成报告" 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 订单状态机

[*] --> Draft : 创建

Draft --> Submitted : 提交
Draft --> Cancelled : 取消

Submitted --> Paid : 收到支付
Submitted --> Cancelled : 取消
Submitted --> Draft : 需要更改

Paid --> Shipped : 发货
Paid --> Refunded : 退款

Shipped --> Delivered : 送达
Shipped --> Returned : 退回

Delivered --> Completed : 完成
Delivered --> Returned : 退回

Returned --> Refunded : 处理退回

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 系统组件

package "表示层" {
  [Web 应用] as Web
  [移动应用] as Mobile
}

package "API 层" {
  [API 网关] as Gateway
  [GraphQL 服务器] as GraphQL
}

package "业务层" {
  [订单服务] as Orders
  [支付服务] as Payment
  [通知服务] as Notify
  [用户服务] as Users
}

package "数据层" {
  database "订单数据库" as OrderDB
  database "用户数据库" as UserDB
  queue "消息总线" as Bus
}

package "外部" {
  [支付提供商] as PaymentExt
  [邮件服务] 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

最佳实践

一般指南

保持图专注：每个图一个概念
使用一致符号：按项目选择 PlantUML 或 Mermaid
添加有意义的名称：清晰、描述性标签
包括图例：用于复杂图
版本控制：与代码一起存储在仓库中

图选择指南

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

工作流

创建 UML 图时：

识别目的：图回答什么问题？
选择图类型：选择最合适的类型
文本草稿：使用 PlantUML 或 Mermaid 语法
审查准确性：对照代码/需求验证
添加上下文：根据需要添加标题、注释、图例
渲染和验证：确保图正确渲染

参考资料

详细语法指南：

最后更新： 2025-12-26