PlantUML 示例：图表、语法与工作流

PlantUML 可以将简洁文本转换为图表，让架构与设计文档更容易检查、修改并保持一致。学习它最快的方法不是记住所有命令，而是从一个可运行的小示例开始，选择能够回答当前问题的图表类型，并且只在细节有助于读者做出决策时才添加细节。

本指南为最实用的图表类型提供可复制的 PlantUML 示例，包括时序图、类图、实体关系图、C4 架构图、活动图、组件图、部署图和状态图。它还介绍这些示例共用的语法、样式选择、布局行为和编辑器工作流。PlantUML 官方网站列出了 UML 与非 UML 图表类型，并说明支持 PNG、SVG、LaTeX、EPS，以及仅限时序图的文本输出，因此同一套文本工作流可以服务于多种发布环境（PlantUML，“Open-source tool that uses simple textual descriptions”，检索于 2026 年 7 月 24 日）。

本页的每个 PlantUML 源代码块都可以在可编辑源代码与渲染后的图表预览之间切换。找到合适的起点后，请打开 OnUML 编辑器，选择 PlantUML 模式，然后粘贴源代码进行调整。

OnUML 会将编码后的源代码发送到配置的 PlantUML 渲染服务，以生成 PlantUML 预览和导出文件。请勿在源代码中放入密码、API 密钥、访问令牌、私有端点或机密架构信息。

要点总结

每个完整的 PlantUML 源代码块都以 @startuml 开始，以 @enduml 结束。

根据问题选择图表：时序图用于随时间发生的交互，类图或 ER 图用于结构，C4 架构图或组件图用于架构，活动图用于流程，状态图用于生命周期。

将源代码作为可维护产物；需要便捷分享时导出 PNG，需要缩放和清晰文字时导出 SVG。

先让自动布局处理初稿。只有为了传达含义时，才添加方向、分组、颜色或主题。

下面的示例刻意保持小巧，便于粘贴到编辑器后立即扩展。

编辑前使用每个源代码块的预览控件，对比文本和渲染结果。

什么是 PlantUML 图表？

PlantUML 图表是根据元素及其关系的文本描述生成的图片。你不必手动定位每个形状，只需描述参与者、类、系统、活动或状态，渲染器就会计算它们的视觉排列。

最小的实用示例是：

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml

即使尚未渲染，源代码也易于阅读。在 OnUML 中，评审者可以检查文本、识别某条消息或关系发生的变化，并围绕生成预览的同一份源代码展开讨论。已保存的 OnUML 项目仍可编辑，PNG 和 SVG 则是渲染输出。

PlantUML 的范围比名称看起来更广。除时序图、类图、活动图、组件图、部署图、状态图、对象图、用例图和时序图等标准 UML 图表外，官方文档还包含实体关系图以及 JSON 或 YAML 可视化等格式（PlantUML 支持的图表）。你无需掌握所有类型；一组重点图表类型就足以覆盖大多数软件文档需求。

PlantUML 语法如何工作？

PlantUML 采用声明式语法：标识元素、描述连接，并按需添加标签或呈现规则。坐标由渲染器决定。

大多数源代码都包含四个共同概念：

@startuml 开始图表，@enduml 结束图表。
participant、class、entity、component 或 state 等关键字用于声明元素。
箭头表示消息、关系、转换或依赖。
title、note、skinparam 和 !theme 等命令用于优化呈现。

下面是一个混合组件示例：

@startuml
title Order Processing

actor Customer
component "Web App" as Web
component "Order API" as API
database "Orders" as DB

Customer --> Web: Place order
Web --> API: POST /orders
API --> DB: Save order
@enduml

Web、API 和 DB 等别名可以缩短关系定义，同时在输出中保留描述性标签。包含空格的标签适合使用引号。冒号通常用于引出关系上显示的文本。

箭头的含义取决于上下文。在时序图中，-> 表示按时间顺序出现的消息；在组件图中，它通常表示依赖或通信方向；在类图中，专用符号用于区分继承、实现、组合、聚合和依赖。请在具体图表类型的上下文中理解箭头，而不要假定它有一种通用含义。

源代码需要维护说明时，可以使用注释。单引号会开始一行 PlantUML 注释：

@startuml
' 该别名用于缩短后续关系定义
component "Payment Service" as Payment
database "Payment Records" as Records
Payment --> Records
@enduml

应该选择哪种 PlantUML 图表？

选择用最少表示法就能回答读者问题的图表。常见的文档错误是选择最熟悉的图表，而不是信息最充分的图表。

读者的问题	最佳起点	重点内容
发生了什么，顺序如何？	时序图	参与者、消息、时间
存在哪些对象或类型？	类图	属性、方法、关系
持久化数据如何关联？	ER 图	实体、键、基数
系统在其环境中处于什么位置？	C4 上下文图	人员和软件系统
存在哪些可部署应用？	C4 容器图或部署图	运行时边界和基础设施
流程包含哪些步骤和决策？	活动图	流程、分支、并行工作
模块之间如何依赖？	组件图	软件构建块
一个实体会如何随时间变化？	状态图	状态、事件、转换

一张图表应有一个主要用途。例如要展示订单工作流，可以用时序图表示运行时对话，用类图或 ER 图表示数据结构，用状态图表示订单生命周期。将三个问题合并到同一视图，通常只会得到技术上密集、实际作用却很弱的图表。

如果你要在基于文本的工具之间做选择，而不是选择图表类型，请参阅现有的 Mermaid 与 PlantUML 对比。本指南其余部分将专注于 PlantUML 本身。

PlantUML 时序图示例

时序图展示由谁通信、交换什么消息，以及交互以何种顺序发生。它非常适合登录流程、API 请求、后台任务、事件处理和服务间行为。

@startuml
title Sign-in Flow
autonumber

actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Store" as DB

User -> Web: Submit credentials
Web -> Auth: Authenticate
Auth -> DB: Find user
DB --> Auth: User record

alt Credentials are valid
  Auth --> Web: Access token
  Web --> User: Open dashboard
else Credentials are invalid
  Auth --> Web: Authentication error
  Web --> User: Show error
end
@enduml

这个示例引入显式参与者、同步消息、虚线返回箭头、自动编号以及 alt/else 条件分组。PlantUML 还支持 opt、loop、par、break、critical 和通用 group 块。官方时序图参考确认，参与者可以从消息中推断，但显式声明可以控制类型、标签、别名和显示顺序（PlantUML 时序图文档）。

让每条消息标签保持在一致的抽象层级。Authenticate 与 Find user 可以协调使用；如果在模糊的业务短语旁放置底层方法签名，时间线会更难理解。流程过高时，先拆分独立场景或使用引用块，再考虑分页。

如需深入了解身份验证、REST API 交互、激活和分组替代路径，请继续查看 PlantUML 时序图示例。

PlantUML 类图示例

类图描述软件的静态结构：类型、成员及其关系。它适合讨论领域模型、公共接口、所有权或拟议的代码组织方式。

@startuml
title Small E-commerce Domain
hide empty members

class Customer {
  +id: UUID
  +email: String
  +placeOrder(): Order
}

class Order {
  +number: String
  +status: OrderStatus
  +total(): Money
}

class OrderLine {
  +quantity: int
  +unitPrice: Money
}

enum OrderStatus {
  Draft
  Confirmed
  Shipped
}

Customer "1" --> "0..*" Order: places
Order "1" *-- "1..*" OrderLine
Order --> OrderStatus
@enduml

各端附近的引号值表示多重性。*-- 中的实心菱形表示组合：在该模型中，订单拥有其订单行。PlantUML 类图参考区分扩展（<|--）、接口实现（<|..）、组合（*--）、聚合（o--）以及 --> 或 ..> 等依赖（PlantUML 类图文档）。

不要仅仅因为 PlantUML 能够渲染，就使用所有可用关系。只有关系影响设计讨论时才添加。概念领域图可以省略方法；面向 API 的图表可以只显示公共操作；代码生成模型则可能需要准确的类型和可见性。

如需了解关系表示法、多重性、包、接口和更大的领域模型，请参阅 PlantUML 类图关系与示例。

PlantUML ER 图示例

实体关系图关注持久化数据、键和基数。它看起来类似类图，但所使用的词汇围绕表或概念实体，而不是运行时对象与行为。

@startuml
title Store Data Model

entity CUSTOMER {
  * customer_id : UUID <<PK>>
  --
  email : VARCHAR
}

entity PURCHASE_ORDER {
  * order_id : UUID <<PK>>
  --
  customer_id : UUID <<FK>>
  created_at : TIMESTAMP
}

entity ORDER_LINE {
  * order_line_id : UUID <<PK>>
  --
  order_id : UUID <<FK>>
  quantity : INTEGER
}

CUSTOMER ||--o{ PURCHASE_ORDER
PURCHASE_ORDER ||--|{ ORDER_LINE
@enduml

乌鸦脚样式端点可以简洁地传达基数。在这里，一个客户可以有零个或多个采购订单，而每个订单包含一条或多条订单行。显示主键与外键有助于数据库模式评审；省略实现专用字段则可以保持概念 ERD 易于阅读。

当主题是数据完整性和基数时使用 ER 图；当对象职责、方法、继承或领域行为更重要时使用类图。专门的 PlantUML ER 图与 ERD 指南介绍表示法选择，并构建更完整的数据库模型。

PlantUML C4 架构图示例

C4 架构图以逐级深入的层级描述软件架构：系统上下文、容器、组件，以及必要时的代码。PlantUML 可以通过 !include 使用标准库中的 C4 宏。

@startuml
!include <C4/C4_Context>

title Online Store — System Context

Person(customer, "Customer", "Browses products and places orders")
System(store, "Online Store", "Handles catalog, checkout, and order tracking")
System_Ext(payments, "Payment Provider", "Authorizes card payments")

Rel(customer, store, "Uses", "HTTPS")
Rel(store, payments, "Requests payment authorization", "HTTPS")
@enduml

该上下文视图有意避开数据库、队列、框架和内部服务，用于建立系统边界与外部关系。随后，容器视图可以揭示 Web 应用、API、数据存储和消息系统；组件视图可以深入某个容器。

PlantUML 发行版包含标准库，官方文档说明可以使用 <...> 引用语法访问这些库（PlantUML 标准库）。远程安装或特定渲染器安装可能有所不同，因此请确认团队所用环境支持 C4 库。

PlantUML C4 上下文、容器和组件示例在三个层级中沿用同一个系统，使视图之间的边界更容易理解。

如何设置 PlantUML 图表的样式和布局

样式应该用于阐明类别、重点或所有权，而不是弥补不清晰的模型。先从默认渲染开始，再做最小的呈现调整，帮助目标读者理解。

主题可以提供协调统一的基础：

@startuml
!theme plain

actor User
component "Web App" as Web
component "API" as API

User --> Web
Web --> API
@enduml

元素颜色可以区分角色：

@startuml
participant User #DCEBFF
participant "Order Service" as Order #FFF0C2
database Database #E3F7E8

User -> Order: Create order
Order -> Database: Insert order
@enduml

请让颜色与标签或构造型提供重复信号，避免含义完全依赖色彩感知。图表将嵌入带主题的网站时，应同时检查浅色和深色浏览环境中的对比度。

对于许多非时序图，left to right direction 可以生成更宽的视图：

@startuml
left to right direction

actor Customer
rectangle Store {
  component Catalog
  component Checkout
}
Customer --> Catalog
Catalog --> Checkout
@enduml

自动布局是约束求解器，而不是绘图画布。调整声明顺序、简化交叉链接、组合相关元素和改变方向，通常比强制精确位置更稳定。可复用配色和无障碍样式请参阅 PlantUML 颜色和主题；方向、间距、分组和复杂嵌套框请参阅 PlantUML 布局与嵌套框。

如何在 OnUML 中保存和导出 PlantUML 图表

简单的工作流是：

在 OnUML 的 PlantUML 编辑器中创建或粘贴源代码。
渲染预览并修复语法错误。
日后需要继续编辑时，登录并保存 OnUML 项目。
导出目标所需格式。

聊天、文档和议题跟踪器需要广泛兼容性时选择 PNG；响应式网页、缩放和清晰文本需要 SVG。在 OnUML 中，请检查当前预览，并使用编辑器工具栏中的 PNG 或 SVG 操作。

日后需要修改时，请保留 OnUML 项目。下载的图片是发布资源，无法作为 PlantUML 源代码编辑。

关于 OnUML 项目、浏览器草稿、PNG/SVG 下载和公开分享的完整说明，请参阅 PlantUML 导出指南。

PlantUML 常见问题及规避方法

大多数 PlantUML 问题可以归入四类：语法、渲染器能力、布局预期和输出处理。

有效源代码没有产生可见变化

确认正在编辑的是当前渲染的源代码，并且预览已刷新。如果涉及 !include，请确认渲染器可以解析它。将源代码精简为一个小型 @startuml/@enduml 示例，再逐段恢复，直到问题重现。

`newpage` 看似无效

newpage 在 PlantUML 语言层面描述分页，但 OnUML 目前每个图表标签页只预览和导出一张图片。请使用 PlantUML newpage 故障排查指南，将长时序图拆分为保持可见、可下载的标签页。

图表无法保持在精确位置

PlantUML 会优化自动计算的图结构。如果精确手动定位是核心需求，反复使用隐藏链接和布局技巧会让源代码变得脆弱。应先简化关系图，用包或矩形表达分组，并判断期望位置是否真的承载信息。

缺少拖放功能

PlantUML 本身采用文本优先方式。编辑器可以添加预览、模板、表单或其他视觉便利功能，但完全自由的所见即所得画布属于另一种交互模式。PlantUML 所见即所得编辑器与拖放指南介绍了应有的预期，以及如何在文本优先和可视化编辑之间做选择。

大型图表变得难以阅读

不要只通过缩小字体解决所有尺寸问题。应按受众和问题拆分视图：用上下文图表示范围，用容器图或组件图表示架构，用时序图表示一个场景，用类图或 ER 图表示一个有界领域。多个相互关联的视图，比一张“包罗万象的图表”更能保留有用细节。

可维护图表的实用工作流

每张图表都从一个单句问题开始。“结账流程如何处理授权失败？”可以验证，而“记录结账流程”则不行。问题决定图表类型和值得展示的元素。

然后遵循这个循环：

建立最小路径模型。 只添加核心参与者或元素及其必要关系。
尽早渲染。 源代码较小时，语法和视觉复杂度更容易修正。
每次只添加一种细节。 只在能够解决潜在歧义时，引入替代路径、基数、协议或注释。
与目标受众评审。 安全评审者、产品经理、数据库工程师和应用开发者需要不同细节。
为已保存项目指定明确负责人和标题。 没有清晰维护边界的文档会迅速老化。
只在团队已经维护外部自动化时使用它。 OnUML 提供交互式预览和 PNG/SVG 导出；CI 渲染是 OnUML 之外的独立工作流。

最易维护的 PlantUML 示例并不是最复杂的那个，而是能够可靠回答问题、并且无需逆向分析视觉画布就能修改的最小源代码。

常见问题解答

PlantUML 可以生成 SVG 吗？

可以。PlantUML 官方文档将 SVG 与 PNG 等其他输出一起列出。当图表需要缩放且文字保持清晰时，SVG 通常是更好的 Web 格式。

PlantUML 只用于 UML 图表吗？

不是。PlantUML 支持传统 UML 类型以及多种非 UML 格式。官方支持图表列表包含实体关系图、思维导图、工作分解结构、JSON、YAML、网络图等类型。

应该使用类图还是 ER 图？

用类图表示软件类型、行为和对象关系；用 ER 图表示持久化实体、键和基数。当领域模型与数据库模式不同时，维护独立视图比强行放进同一种表示法更清晰。

可以控制每个元素的精确位置吗？

不能像自由绘图工具一样操作。PlantUML 使用自动布局引擎。你可以影响方向、分组、顺序、间距和部分关系，但精确坐标并非常规创作模式。

`newpage` 会创建一张多页图片吗？

不会。newpage 描述的是独立渲染页面，而不是一张多页图片。OnUML 目前每个图表标签页只显示一张渲染图片，因此当每个部分都必须预览和导出时，请使用独立标签页。

继续学习

最佳下一步是选择最接近当前问题的指南，并调整其中的完整示例。

图表指南：

PlantUML 时序图语法与真实场景示例
PlantUML 类图关系与示例
PlantUML ER 图与 ERD 示例
PlantUML C4 上下文、容器和组件图

样式与布局：

PlantUML 颜色和主题指南
PlantUML 布局、方向、间距和嵌套框

编辑器与导出工作流：

在 OnUML 中将 PlantUML 导出为 PNG 或 SVG
修复 PlantUML newpage 和多输出问题
PlantUML 所见即所得与拖放编辑选项

当文本足够简单、可以评审，渲染视图也足够聚焦、能够支持决策时，PlantUML 的效果最好。复制最相关的最小示例，替换其中的领域术语，并且只在读者需要更多信息时扩展。

官方来源

PlantUML 首页和支持的图表类型
PlantUML 快速入门指南
PlantUML 时序图文档
PlantUML 类图文档
PlantUML 标准库文档

PlantUML 示例：图表、语法与工作流

目录

什么是 PlantUML 图表？

PlantUML 语法如何工作？

应该选择哪种 PlantUML 图表？

PlantUML 时序图示例

PlantUML 类图示例

PlantUML ER 图示例

PlantUML C4 架构图示例

更多实用 PlantUML 示例

用活动图表示决策驱动的流程

用组件图表示依赖

用部署图表示运行时位置

用状态图表示实体生命周期

如何设置 PlantUML 图表的样式和布局

如何在 OnUML 中保存和导出 PlantUML 图表

PlantUML 常见问题及规避方法

有效源代码没有产生可见变化

`newpage` 看似无效

图表无法保持在精确位置

缺少拖放功能

大型图表变得难以阅读

可维护图表的实用工作流

常见问题解答

PlantUML 可以生成 SVG 吗？

PlantUML 只用于 UML 图表吗？

应该使用类图还是 ER 图？

可以控制每个元素的精确位置吗？

`newpage` 会创建一张多页图片吗？

继续学习

官方来源

目录

什么是 PlantUML 图表？

PlantUML 语法如何工作？

应该选择哪种 PlantUML 图表？

PlantUML 时序图示例

PlantUML 类图示例

PlantUML ER 图示例

PlantUML C4 架构图示例

更多实用 PlantUML 示例

用活动图表示决策驱动的流程

用组件图表示依赖

用部署图表示运行时位置

用状态图表示实体生命周期

如何设置 PlantUML 图表的样式和布局

如何在 OnUML 中保存和导出 PlantUML 图表

PlantUML 常见问题及规避方法

有效源代码没有产生可见变化

newpage 看似无效

图表无法保持在精确位置

缺少拖放功能

大型图表变得难以阅读

可维护图表的实用工作流

常见问题解答

PlantUML 可以生成 SVG 吗？

PlantUML 只用于 UML 图表吗？

应该使用类图还是 ER 图？

可以控制每个元素的精确位置吗？

newpage 会创建一张多页图片吗？

继续学习

官方来源

`newpage` 看似无效

`newpage` 会创建一张多页图片吗？