一个UML 序列图展示了参与者随时间推移的交互方式。它适用于记录一个用例、API 流程、业务流程或系统场景。时间通常从上到下流动；水平位置表示参与者是谁，而非经过时间的精确度量。
PlantUML允许您将图表描述为文本。Visual Paradigm 的 VPasCode 编辑器将代码编辑器与实时预览及 AI 辅助功能相结合，用于生成、修改和修正图表代码。良好的工作流程是：先用 AI 生成初稿，然后自行检查并优化 PlantUML 代码。
1. 基本结构
一个PlantUML 序列图以@startuml开始，并以@enduml结束。参与者通常列在消息之前，以便您可以控制它们的名称和顺序。
@startuml
actor Customer
participant Browser
participant "Order API" as API
database "Order DB" as DB
Customer -> Browser: Place order
Browser -> API: POST /orders
API -> DB: Save order
DB --> API: Order ID
API --> Browser: 201 Created
Browser --> Customer: Show confirmation
@enduml
参与者的显示标签可以加引号，使用作为提供用于消息中的更短别名。常见的参与者关键字包括actor, participant, boundary, control, entity, database，和集合。使用最能传达参与者角色的关键字；它不强制特定的架构。
2. 读取消息和时间
每条消息都写作发送者、箭头、接收者和标签。消息行的顺序决定了它们在图中的垂直顺序。
-
->是实线消息箭头，通常用于请求或调用。 -
-->是虚线箭头，通常用于响应或返回。 -
->>和-->>在常见的 PlantUML 样式中使用开放式箭头头。 -
: 文本添加消息标签。
为调用和响应选择一致的约定。UML 图用于传达交互；它们不能自动保证实现遵循所描绘的协议。
3. 激活和参与者生命周期
激活可以显示参与者何时在工作。使用activate 和 停用，或简写++ 和 --在消息箭头上。
@startuml
actor User
participant "Login API" as API
database Users
User -> API: 提交凭据
activate API
API -> Users: 查找账户
activate Users
Users --> API: 账户记录
deactivate Users
API --> User: 登录结果
deactivate API
@enduml
激活状态在阐明嵌套调用或职责时最为有用。如果机械地为每条消息添加激活状态会使图表更难阅读，则应避免这样做。
4. 条件、替代方案和重复
使用组合片段来表示控制流。fragment 关键字开始该块，else 在适用时分隔替代方案，而 end 结束它。守卫条件应放在方括号中。
替代路径：alt 和 else
@startuml
actor User
participant "Login API" as API
database Users
User -> API: 提交用户名和密码
API -> Users: 检查凭据
Users --> API: 匹配结果
alt [凭据有效]
API --> User: 返回会话令牌
else [凭据无效]
API --> User: 返回认证错误
end
@enduml
alt当路径互斥时，使用此结构是合适的。请使用能清晰表达条件的标签。
可选行为：opt
@startuml
actor Customer
participant Checkout
participant "Email Service" as Email
Customer -> Checkout: 完成购买
Checkout --> Customer: 订单确认
opt [客户已选择接收电子邮件]
Checkout -> Email: 发送收据
Email --> Checkout: 已接受
end
@enduml
重复：循环
@startuml
participant "Batch Job" as Job
participant "Payment API" as API
loop [for each pending payment]
Job -> API: Submit payment
API --> Job: Payment result
end
@enduml
将重复的操作放入片段中，并清楚地说明循环条件或作用域。
5. 并行和分组交互
使用par 当交互并发发生或其顺序不重要时。使用group 来标记一组消息，而不暗示特定的控制流结构。
@startuml
参与者“订单服务”为 Orders
参与者“库存服务”为 Inventory
参与者“通知服务”为 Notify
Orders -> Orders: 订单已接受
par 预留库存
Orders -> Inventory: 预留商品
Inventory --> Orders: 预留结果
else 通知客户
Orders -> Notify: 发送订单更新
Notify --> Orders: 已接受
end
@enduml使用 par仅在并发具有实际意义时使用。如果一个动作必须在另一个动作开始之前完成，则应以顺序方式显示消息。
6. 注释、引用和视觉分组
注释可以阐明假设、约束或决策。一个 ref片段可以将读者指向另一个图表或单独文档化的交互。
@startuml
参与者 Customer
参与者“结账界面”为 UI
参与者“支付服务”为 Pay
参与者“欺诈检查”为 Fraud
Customer -> UI: 支付订单
UI -> Pay: 授权支付
Pay -> Fraud: 评估交易
note right of Fraud
风险规则在此交互之外维护。
end note
Fraud --> Pay: 风险结果
Pay --> UI: 授权结果
UI --> Customer: 显示结果
@enduml注释应提供上下文，而非重复消息标签。如果图表变得拥挤，请将其拆分为专注的场景，并使用引用或文档链接将它们连接起来。
7. 在 VPasCode 中创建和细化图表
VPasCode支持带实时渲染的 PlantUML 编辑，以及AI 辅助图表生成、代码修改和语法修正。其确切界面和功能可用性可能会发生变化，但一般工作流程如下：
-
打开 VPasCode 并选择或输入 PlantUML。
-
描述交互过程，或将 PlantUML 草稿粘贴到编辑器中。
-
在细化源代码时，检查渲染后的预览效果。
-
请 AI 进行特定修改，例如“使用
alt.” -
审查生成的代码和图表，确保语法正确且系统逻辑无误。
-
使用编辑器中提供的选项导出或分享完成的图表。
一个有效的提示词应向 AI 提供图表类型、参与者、系统边界、主要成功路径、重要备选路径以及详细程度。例如：
为 Web 应用用户登录场景创建一个 PlantUML 序列图。包含浏览器、登录 API、身份提供商和用户数据库。展示成功登录路径和无效密码的备选路径。使用简洁的标签，不要虚构超出上述范围的服务。
将生成的代码视为草稿。检查参与者、箭头、条件和错误路径是否真实反映实际系统，而不仅仅是看起来合理的流程。
8. 更完整的示例：带支付失败的结账流程
此示例结合了参与者别名、激活状态和备选路径。
@startuml
标题：结账与支付授权
参与者 客户
边界 "结账界面" 作为 UI
控制 "订单服务" 作为 Orders
参与者 "支付网关" 作为 Pay
数据库 "订单数据库" 作为 DB
客户 -> UI: 提交结账
UI -> Orders: 创建待处理订单
激活 Orders
Orders -> DB: 保存待处理订单
DB --> Orders: 订单 ID
Orders -> Pay: 授权支付
激活 Pay
alt [支付已批准]
Pay --> Orders: 授权码
取消激活 Pay
Orders -> DB: 标记订单已确认
DB --> Orders: 已更新
Orders --> UI: 订单已确认
UI --> 客户: 显示确认信息
else [支付被拒绝]
Pay --> Orders: 拒绝原因
取消激活 Pay
Orders -> DB: 标记订单失败
DB --> Orders: 已更新
Orders --> UI: 支付被拒绝
UI --> 客户: 显示重试选项
end
取消激活 Orders
@enduml检查图表中的顺序是否与真实行为一致。例如，如果系统仅在授权成功后才持久化订单，请将数据库消息移至与该设计相匹配的位置。
9. 实用建模指南
-
保持图表聚焦。展示一个场景或一组紧密相关的流程。将分散注意力的深层细节拆分出来。
-
按职责命名参与者。优先使用诸如“
订单服务”或“支付网关”而非模糊的标签，如“系统”. -
“展示有意义的边界。当有助于读者理解职责时，区分用户、客户端、内部服务、数据库和外部系统。
-
使用清晰的消息标签。包含操作、事件或重要结果；避免仅标注“流程”的标签。
-
建模关键失败路径。当超时、拒绝、重试或验证失败影响场景时，应包含相关内容。
-
准确使用片段。
alt表示替代路径，opt表示可选行为，loop表示重复，以及par表示并行行为。 -
避免实现噪声。除非受众需要，否则不要为每个 getter、内部方法或底层细节绘制图表。
-
保持源码可维护性。对长名称使用别名，保持命名一致，并对重要假设使用简短注释或说明。
10. 常见错误与审查清单
如果图表无法渲染，请检查@startuml和@enduml存在时，片段块具有匹配的end语句，别名使用一致，且所有消息端点均指向已定义的参与者。同时检查是否意外将其他图表语言的语法粘贴到了 PlantUML 源代码中。
在分享之前，请检查以下两点：
-
语法：能否正常渲染？片段是否已正确闭合？参与者和别名是否一致？
-
含义：参与者和消息方向是否正确？是否包含了重要的错误路径？外部系统和数据存储是否准确表示？
最强大的图表即代码工作流结合了可读的源代码、快速的视觉反馈和领域审查。PlantUML 提供了对交互符号的明确控制，而VPasCode可以加快草稿和迭代的速度；图表准确性的最终权威仍是其所要描述的系统行为。