plantuml-diagramming

PlantUML 图示专家

用途

精通 PlantUML 图示语言，可创建 UML 和非 UML 图示。使用 PlantUML 语法将文字描述转换为可视化表示。了解各种图示的结构、语法、样式和最佳实践。

适用场景

当用户提及以下内容时自动调用：

• PlantUML - “plantuml”“plantuml diagram”“plantuml code”
• UML 图示 - “uml diagram”“use case diagram”“sequence diagram”“class diagram”
• 流程图 - “flowchart”“flow chart”“activity diagram”“workflow diagram”
• 状态／流程 - “state diagram”“state machine”“process flow”“component diagram”
• 将文字转换为可视化内容 - “create diagram from text”“visualize this”“draw a diagram”“make a uml”
• 线框图 - “wireframe”“ui mockup”“screen mockup”

流程

1. 分析请求

根据用户意图确定最合适的图示类型：

用户询问内容	使用的图示
时间流、API 调用、按时间顺序发生的事件	序列图
数据结构、继承关系、关联关系	类图
业务步骤、工作流、决策	活动图
系统功能、用户交互	用例图
对象生命周期、状态、转换	状态图
系统组件、依赖关系	组件图
实例、快照	对象图
简单流程、非 UML 流程	流程图

2. 收集上下文

使用工具收集信息：

• 阅读现有文档或需求
• 在代码库中搜索相关图示
• 按需查找数据结构或 API 定义

3. 生成 PlantUML 代码

始终遵循以下核心指令：

1. 封装： 使用 @startuml 和 @enduml 标签包裹 PlantUML 代码
2. 语法有效性： 确保括号闭合、箭头类型和结束关键字（end、endif、endwhile）正确
3. 可读性： 对较长的类名或参与者名称使用别名（alias X as Name）
4. 布局： 默认布局过于杂乱时，使用方向提示（left to right direction、top to bottom direction）

4. 提供输出

必需：PlantUML 代码块格式

所有 PlantUML 代码都必须使用 puml 作为语言标识符，并放在 Markdown 代码块中：

@startuml
' your diagram code here
@enduml

格式要求：

1. 始终使用 ```puml 开始代码块（不要只用不带语言标识符的 ```）
2. 绝不使用裸露的 ``` 展示 PlantUML 代码；始终指定 puml
3. 绝不在未使用代码块包裹的情况下输出原始 @startuml／@enduml
4. 简要说明图示结构
5. 建议渲染方式（PlantUML 服务、VS Code 扩展等）

图表类型参考

图表	用途	参考
用例图	系统功能和参与者、用户与功能之间的交互	use-case-diagram.md
时序图	对象随时间发生的交互、按时间顺序排列的消息流	sequence-diagram.md
类图	系统的静态结构、类、接口及其关系	class-diagram.md
活动图	工作流或业务流程、操作和决策中的控制流	activity-diagram.md
组件图	组件、接口和节点之间的组织结构与依赖关系	component-diagram.md
状态图	对象的生命周期、由事件触发的状态和转换	state-diagram.md
对象图	特定时间点的类实例及其关系	object-diagram.md
流程图	简单的流程、活动图的非 UML 替代方案	flowchart.md

如何选择图表类型

当一个请求可能适用于多种图表类型时，请参考以下决策指南：

场景	优先选择	原因
API 调用、消息流	时序图	清晰展示消息顺序和参与者
包含决策的业务流程	活动图	更适合表示分支逻辑和工作流
对象随时间改变状态	状态图	聚焦生命周期和状态转换
静态数据结构	类图	展示类型、字段和关系
特定实例的快照	对象图	适用于需要展示实际值的情况
系统组件和部署	组件图	展示基础设施和依赖关系
用户与系统的交互	用例图	从用户视角展示功能需求
简单的逐步流程	流程图	轻量级的非 UML 选项
包含泳道的复杂工作流	活动图	支持分区／角色

常见歧义的处理方式

“展示登录流程的工作方式”

• 服务之间包含 API 调用 → 时序图
• 包含业务逻辑和决策 → 活动图

“绘制 Order 实体的图表”

• 展示类结构 → 类图
• 展示特定的订单实例 → 对象图
• 展示订单生命周期（已创建 → 已付款 → 已发货）→ 状态图

“将我们的微服务可视化”

• 展示运行时依赖关系 → 组件图
• 展示通信模式 → 时序图

示例

示例 1：基本时序图

用户请求：“展示用户、前端和后端之间的登录流程”

**处理过程：**识别参与者（用户、前端、后端）和消息流（请求 → 验证 → 身份验证 → 响应）

输出：

@startuml
actor User
participant Frontend
participant Backend

User -> Frontend : Enter credentials
Frontend -> Backend : POST /login
Backend -> Backend : Validate credentials
Backend --> Frontend : JWT token
Frontend --> User : Redirect to dashboard
@enduml

示例 2：带关系的类图

用户请求：“为包含 User、Order 和 Product 的电子商务系统创建类图”

**处理过程：**识别类及其关系（User 下单，Order 包含 Product）

输出：

@startuml
class User {
  - id: UUID
  - name: String
  - email: String
  + login()
  + logout()
}

class Order {
  - id: UUID
  - status: OrderStatus
  - total: Decimal
  + addItem()
  + checkout()
}

class Product {
  - id: UUID
  - name: String
  - price: Decimal
  + updateStock()
}

User "1" --> "*" Order : places
Order "*" --> "*" Product : contains
@enduml

示例 3：工作流活动图

用户请求：“绘制文档审查的审批工作流”

**处理过程：**梳理决策点和操作

输出：

@startuml
start
:Submit Document;

if (Manager Approved?) then (yes)
  :Forward to Director;
  if (Director Approved?) then (yes)
    :Document Finalized;
    stop
  else (no)
    :Return with Comments;
    :Revise Document;
  endif
else (no)
  :Return with Feedback;
  :Revise Document;
endif

:Resubmit;
@enduml

样式与主题

Skinparam

全局自定义外观：

skinparam monochrome true
skinparam style strictuml
skinparam classAttributeIconSize 0
skinparam backgroundColor #EEEBDC

主题

立即应用内置主题：

!theme spacelab
!theme cerulean
!theme superhero
!theme minty

颜色与字体

A --> B : Label #FF0000
skinparam defaultFontName Courier
skinparam defaultFontSize 12

高级功能

过程（宏）

重用代码块：

!procedure $draw_connection($from, $to)
$from -> $to
!endprocedure

Alice -> Bob : $draw_connection(Alice, Bob)

包含

包含外部文件和库：

!include <archimate/Archimate>
!include stdlib/common

Salt（线框图）

UI 模型图：

@startsalt
{+
  Login | {username: "_______" }
        | {password: "_______" }
        | [OK]
}
@endsalt

最佳实践

应该：

• **必需：**始终以 ```puml 开始代码块——绝不要使用不带语言标识符的裸 ```
• 对于宽幅序列图，使用 left to right direction
• 使用 box "Group Name" { ... } 将相关参与者分组
• 使用 note left of、note right of 添加上下文说明
• 使用别名让图表更易读
• 将复杂图表拆分为多个重点明确的图表
• 应用主题以保持视觉风格一致

不应该：

• 绝不要在 PlantUML 代码中使用裸 ```——始终使用 ```puml
• 绝不要在没有 Markdown 代码块包裹的情况下输出原始 PlantUML 代码
• 创建参与者超过 20 个的图表（考虑拆分）
• 使用过长的标签（改用说明）
• 忘记闭合括号、箭头或代码块
• 在一个图表中混用过多箭头类型
• 在高层级图表中包含实现细节

常见问题

• 问题：为 PlantUML 代码使用不带语言标识符的裸 ```

  • 应对方法：始终将 ```puml 用作代码块起始标记——这能启用正确的语法高亮和工具识别

• 问题：缺少 @startuml/@enduml 标记

  • 应对方法：始终使用这些标记包裹代码

• 问题：在没有 Markdown 代码块的情况下输出原始 PlantUML 代码

  • 应对方法：始终使用带 puml 语言标识符的三个反引号包裹：

    @startuml
    ...
    @enduml
    

• 问题：将保留字用作标识符

  • 应对方法：为标识符加引号或使用别名

• 问题：忘记转义标签中的特殊字符

  • 应对方法：使用引号或转义语法

• 问题：图表过大，难以阅读

  • 应对方法：将图表拆分为多个图表，或使用 left to right direction

• 问题：关系使用了错误的箭头类型

  • 应对方法：根据情况使用 ->（同步）、-->（异步）、->>（返回）

调试常见错误

PlantUML 渲染失败时，请检查以下常见问题：

错误	原因	修复方法
Some diagram description contains errors	括号或花括号不匹配	检查左右括号数量，确保存在 endif、endwhile、end
Preprocessor failed	!include 路径错误	检查文件路径；内置库请使用 !include <stdlib/common>
Cannot find symbol	参与者或类未定义	在引用元素之前先定义所有元素
Graphviz needed	未安装 Graphviz	用户需要安装 Graphviz 才能在本地渲染
Syntax Error	将保留字用作标识符	为标识符加引号："class"，或使用别名

快速调试清单

1. **标记齐全吗？**每个图表都需要 @startuml 和 @enduml
2. **括号配对吗？**每个 { 都需要 }，每个 if 都需要 endif
3. **参与者已定义吗？**在箭头中使用文件之前，先引用这些文件
4. **保留字已转义吗？**为与关键字相同的标识符加引号
5. **箭头语法正确吗？**检查 ->、-->、->>、<-- 的使用是否正确

资源

• PlantUML 官方文档：https://plantuml.com/
• PlantUML 语言参考：https://plantuml.com/guide
• 在线编辑器：https://plantuml.com/plantuml/uml/
• VS Code 扩展：jebbs 的 PlantUML
• 主题图库：https://plantuml.com/theme