PlantUML 时序图：语法与真实场景示例
PlantUML 时序图可以将按时间顺序发生的交互转换为可评审的文本。声明涉及的人员和系统，用消息连接它们，再使用 alt、loop 和 par 等分组关键字表示决策或重复。它尤其适合记录身份验证、API 调用、后台任务和服务间通信。
本教程将构建两张完整图表：登录流程和 REST API 请求。如果你仍在确定哪种图表适合当前问题，请先查看更全面的 PlantUML 示例指南。
要点总结
- 时序图描述随时间发生的行为；参与者从左到右排列，消息从上到下排列。
- 显式声明参与者可以使名称、类型和顺序更可预测。
alt、opt、loop、par和critical无需绘制多张图就能表达控制流。- 激活条表示参与者正在执行工作，但不衡量经过的时间。
- PlantUML 渲染你所描述的交互，但不会验证 API 或安全性是否正确。
前置条件
打开 OnUML 编辑器，选择 PlantUML 模式，然后将每个示例粘贴到源代码编辑器中。OnUML 会为你渲染预览，因此无需在本地安装 PlantUML。需要日后继续编辑时，请登录并保存 OnUML 项目。
标准的源代码边界是：
@startuml
' 这里放置图表定义
Alice -> Bob: Hello
@enduml
PlantUML 也能在参与者首次出现在消息中时识别它们，但对于长期维护的文档，显式声明更好，因为它可以控制标签和显示顺序。本指南的语法遵循官方时序图文档（检索于 2026 年 7 月 24 日）。
如何阅读 PlantUML 时序图？
从上到下阅读图表。每条垂直生命线代表一个参与者，每个水平箭头表示一条晚于上方消息发送的消息。水平位置主要表示参与者，而不是持续时间：较长的箭头不代表较慢的请求。
PlantUML 支持专用的参与者形状：
@startuml
actor User
boundary WebApp
control AuthService
entity Account
database UserDatabase
queue AuditQueue
User -> WebApp: Submit credentials
WebApp -> AuthService: Authenticate
AuthService -> UserDatabase: Find account
AuthService -> AuditQueue: Record attempt
@enduml
这些类型向读者传达角色，但不会改变底层系统。请保持一致使用，而不是试图为每个实现细节分配独特形状。
第 1 步：声明参与者和消息
从成功路径开始。-> 等实线箭头通常表示请求，--> 等虚线箭头适合表示响应。这是视觉约定，并非 PlantUML 强制规定的协议规则。
@startuml
title Successful login
actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Database" as DB
User -> Web: Enter email and password
Web -> Auth: POST /sessions
Auth -> DB: Find user by email
DB --> Auth: User record
Auth --> Web: Session token
Web --> User: Show dashboard
@enduml
Web 等别名让后续消息保持简短，同时保留易读标签。请按照希望的显示顺序声明参与者。PlantUML 仍可能调整间距，但声明顺序提供了稳定起点。
第 2 步：用激活条展示处理过程
激活条表示参与者正在处理交互的某个部分。当工作区间对说明很重要时，使用 activate 和 deactivate。
@startuml
title Login with activation
actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Database" as DB
User -> Web: Submit login form
activate Web
Web -> Auth: Authenticate(credentials)
activate Auth
Auth -> DB: Load account
activate DB
DB --> Auth: Account
deactivate DB
Auth --> Web: Access token
deactivate Auth
Web --> User: Redirect to dashboard
deactivate Web
@enduml
每次激活都应对应一次停用。即使源代码可以渲染，未闭合的激活条也可能让输出产生误导。参与者生命线确实结束时可以使用 destroy；return label 则能以简洁方式绘制并标记返回消息。在大型图表中混用简写与显式激活前，请先查阅官方文档。
第 3 步：添加成功与失败分支
只展示成功的身份验证流程并不完整。使用 alt 组表示互斥结果，并用 else 表示另一个分支。
@startuml
title Login success and failure
autonumber
actor User
participant "Web App" as Web
participant "Auth Service" as Auth
database "User Database" as DB
User -> Web: Submit credentials
Web -> Auth: Authenticate(credentials)
Auth -> DB: Find user and password hash
DB --> Auth: Account data
alt Credentials are valid
Auth -> Auth: Create session token
Auth --> Web: 201 Created + token
Web --> User: Show dashboard
else Credentials are invalid
Auth --> Web: 401 Unauthorized
Web --> User: Show generic error
end
@enduml
autonumber 便于讨论，因为评审者可以引用消息编号。PlantUML 还支持自定义起始值、增量、暂停和恢复。不要在公开图表中编码敏感实现细节：流程应解释职责，而不应暴露机密或防御阈值。
第 4 步：建立可选、重复和并行工作模型
PlantUML 为常见控制流提供了多种分组结构：
opt表示可选交互。loop表示重复。par表示可以并行执行的工作。break表示提前退出。critical标记必须作为临界区处理的交互。group创建自定义命名分区。
下面是一份完整的 REST API 示例，结合可选缓存与并行后续工作：
@startuml
title Product API request
autonumber
actor Client
participant "API Gateway" as Gateway
participant "Product Service" as Product
database Cache
database "Product DB" as DB
queue "Analytics Queue" as Events
Client -> Gateway: GET /products/42
Gateway -> Product: getProduct(42)
activate Product
Product -> Cache: read("product:42")
alt Cache hit
Cache --> Product: Cached product
else Cache miss
Cache --> Product: Not found
Product -> DB: SELECT product 42
DB --> Product: Product row
Product -> Cache: write("product:42", product)
end
par Return response
Product --> Gateway: Product DTO
Gateway --> Client: 200 OK
else Publish analytics
Product -> Events: ProductViewed(42)
end
deactivate Product
@enduml
par 块表示两条路径足够独立，可以作为并行行为来讨论。它并不能证明实现使用了独立线程，也不能保证响应绝不会等待分析任务。请在周边文档中定义具体含义。
第 5 步：让大型图表易于评审
一张有用的时序图应有一个明确问题。如果标题中多次出现“以及”，应将源代码拆分为更小的视图。保持参与者别名稳定，用业务含义标记消息，并且只对无法通过交互本身表达的信息使用注释。
@startuml
title Resilient inventory reservation
actor Customer
participant Checkout
participant Inventory
Customer -> Checkout: Confirm order
Checkout -> Inventory: Reserve items
loop Up to 3 attempts
alt Inventory service responds
Inventory --> Checkout: Reservation result
break Reservation completed
Checkout --> Customer: Continue checkout
end
else Temporary timeout
Checkout -> Checkout: Apply retry policy
end
end
note right of Checkout
Retry limits belong to the
application policy, not PlantUML.
end note
@enduml
如需了解类型和关系的静态视图，请继续查看 PlantUML 类图关系。要将 API 行为与存储实体联系起来，请使用 PlantUML ER 图。
时序图常见错误
| 问题 | 原因 | 更好的做法 |
|---|---|---|
| 图表读起来像源代码 | 包含了每个函数调用 | 展示跨越有意义边界的交互 |
| 虚线和实线箭头使用不一致 | 没有图例或约定 | 统一定义请求和响应样式 |
| 缺少失败路径 | 作者从理想路径演示开始 | 为重要结果添加 alt 分支 |
| 激活条从不结束 | 遗漏了 deactivate | 显式平衡激活和停用 |
| 单张图表极高 | 组合了多个场景 | 拆分为独立 OnUML 图表标签页，或用 ref 概括次要工作 |
| 图表暗示协议正确 | 渲染输出看起来具有权威性 | 另请领域专家评审模型 |
完整的身份验证示例
下面的源代码可以直接复制，其中包含令牌刷新路径、身份验证失败和审计事件。
@startuml
title Web authentication flow
autonumber
actor User
boundary Browser
control "Auth API" as Auth
entity "Session Store" as Sessions
database "User DB" as Users
queue "Audit Events" as Audit
User -> Browser: Submit login form
Browser -> Auth: POST /sessions
activate Auth
Auth -> Users: Find account
Users --> Auth: Account and password hash
alt Valid credentials
Auth -> Sessions: Create session
Sessions --> Auth: Session ID
Auth -> Audit: LoginSucceeded
Auth --> Browser: 201 Created + secure cookie
Browser --> User: Show account
else Invalid credentials
Auth -> Audit: LoginFailed
Auth --> Browser: 401 Unauthorized
Browser --> User: Show generic error
end
deactivate Auth
@enduml
常见问题解答
PlantUML 要求先声明参与者吗？
不要求。PlantUML 可以从消息中自动发现参与者。如果需要别名、专用参与者形状或受控顺序，则应显式声明。
alt 和 opt 有什么区别？
alt 用于两个或多个互斥路径，opt 用于一个可能不会发生的条件交互。两种分组都以 end 结束。
时序图能证明 API 正确吗？
不能。PlantUML 只渲染源代码中的消息和分组，不验证身份验证安全性、HTTP 语义、竞态条件或失败处理。
可以在哪里比较 PlantUML 与 Mermaid 时序图？
如果主要问题是选择工具，而不是学习 PlantUML 语法，请参阅现有的 Mermaid 与 PlantUML 时序图对比。
后续步骤
从团队目前用文字说明的一项交互开始。声明外部参与者、系统边界和成功消息，再只添加影响当前评审决策的失败与并发路径。
接下来可浏览 PlantUML 示例中心、使用 PlantUML ERD 语法建立持久化结构模型，或查阅官方时序图参考中的消息延迟、分隔符和参与者创建等少见语法。官方 Creole 格式参考介绍了如何格式化较长的参与者标签、注释和消息文本，而不改变交互语义。
当多张图表需要相同视觉约定时，请使用官方 PlantUML 主题参考，不要在每张时序图中复制互不相关的样式指令。