VPasCode：使用 PlantUML 绘制 UML 活动图——实用教程

UML 活动图用于建模工作的流动方式通过一个过程：执行的操作、做出的决策、并行工作以及完成路径。PlantUML 允许您将模型以文本形式描述，然后将其渲染为图表——当您希望图表易于修订、审查并与项目文档一起保存时，这是一种很有用的方法。PlantUML 当前的活动语法使用可读的关键字，例如start, if, repeat，以及fork；其旧的活动语法仍受支持，但建议在新图表中使用新语法。

1. 建模内容

使用活动图来解释流程或算法，例如：

• 客户结账流程

• 审批流程

• 数据导入管道

• 用例中的步骤

• 分配给人员、团队或系统组件的工作

活动是工作单元，例如“验证订单”。一个控制流连接活动并指示其顺序。一个决策在替代路径中进行选择；并行流显示可以并发进行的工作。图表应阐明行为，而不应试图记录每个实现细节。

一个实用的经验法则：如果主要问题是“接下来会发生什么，以及在什么条件下？”，那么活动图是一个很好的选择。

2. PlantUML 基础

PlantUML 图表以@startuml并以”结尾@enduml.在当前活动语法中：

• start表示初始节点。

• :Action;定义一个动作。

• if (...) then (...)根据条件进行分支。

• endif结束条件语句。

• stop结束一个流程。

• repeat和repeat while表示重复。

• fork, fork again，以及end fork表示并行工作。

动作按顺序书写并隐式连接。您可以为分支添加标签，并使用partition按职责或角色对工作进行分组。

这是一个最小示例：

@startuml
start
:接收请求;
:验证请求;
stop
@enduml

3. 决策与替代路径

使用if当流程做出选择时使用。分支标签应传达条件的结果，而不仅仅是重复条件。

@startuml
start
:接收订单;
:检查库存;

if (所有商品是否可用？) then (是)
  :预留商品;
  :请求付款;
else (否)
  :通知客户;
  stop
endif

:确认订单;
stop
@enduml

此处，if引入一个决策，而endif将其关闭。是和否标签使替代方案可见。当路径在endif之后继续到共享操作时，它们将重新汇入流程。

建模提示：明确说明每种有意义结果所发生的情况。如果错误、超时或拒绝路径对利益相关者很重要，请将其展示出来，而不是隐含处理。

4. 循环与重试

当某个操作或一组操作可以重复时，请使用循环。此示例会持续请求输入，直到通过验证：

@startuml
start
:读取已提交的数据;

repeat
  :验证数据;
  if (有效？) then (是)
    :保存数据;
    break
  else (否)
    :显示验证错误;
    :请用户修正数据;
  endif
repeat while (用户是否继续？) 为 (是) 不为 (否)

stop
@enduml

如果循环的退出条件模糊，阅读起来可能会很困难。应明确说明什么会导致再次尝试，以及什么会结束重复——特别是在重试次数有限或可取消的情况下。

5. 并行工作与同步

使用fork 表示独立操作可以并发执行，而end fork 表示路径必须在流程继续之前进行同步。

@startuml
start
:订单已确认;

fork
  :发送确认邮件;
fork again
  :准备仓库拣货清单;
fork again
  :更新销售仪表板;
end fork

:将订单标记为处理中;
stop
@enduml

fork 不一定代表不同的人；它可以表示并发的系统行为。仅在操作确实可以并行发生时才使用它。如果一个任务必须在另一个任务开始前完成，则应将其建模为顺序执行。

6. 带分区的泳道

分区按负责的角色、团队或系统对操作进行分组。这可以在不改变流程本身的情况下使交接更加清晰。PlantUML 支持使用partition.

@startuml
start

partition Customer {
  :提交订单;
}

partition "订单服务" {
  :验证订单;
  if (订单有效？) then (是)
    :创建订单记录;
  else (否)
    :返回验证错误;
    stop
  endif
}

partition 仓库 {
  :准备发货;
}

partition "订单服务" {
  :发送确认;
}

stop
@enduml

选择与实际职责划分相匹配的泳道标签。避免为每个小组件创建新的分区；过多的泳道会使图表更难扫描。

7. 数据对象和注释

某些工作流通过显示重要输入或输出会受益。PlantUML 活动图支持对象节点构造型；注释也可以添加上下文，而无需将每个操作标签变成一段文字。

@startuml
start
:接收付款请求;

:授权付款;
note right
  使用付款提供商的
  授权响应。
end note

:记录付款结果;
stop
@enduml

保持主要活动标签简短。当读者需要业务规则、假设或说明，但它们本身不是流程中的步骤时，请将它们放在注释中。

8. 完整示例：在线结账

这个较大的示例结合了分区、决策、替代路径和并行工作。

@startuml
标题 在线结账

start

partition Customer {
  :查看购物车;
  :提交结账;
}

partition "订单服务" {
  :验证购物车和地址;

  if (购物车和地址有效？) then (是)
    :计算总额;
  else (否)
    :显示验证错误;
    stop
  endif
}

partition "支付服务" {
  :授权付款;

  if (付款已批准？) then (已批准)
    :扣款;
  else (已拒绝)
    :返回付款失败;
    stop
  endif
}

partition "订单服务" {
  :创建订单;
}

fork
  partition "通知服务" {
    :发送订单确认;
  }
fork again
  partition 仓库 {
    :将订单排入拣货队列;
  }
end fork

partition "订单服务" {
  :显示订单确认;
}

stop
@enduml

从上到下阅读：客户提交结账，订单服务进行验证，授权付款，然后创建订单。之后，确认和仓库准备并行运行。如果验证或付款失败，流程将通过相应的失败路径结束。

9. 图表即代码工作流

一个实用的工作流是：

图表即代码工作流

一个实用的工作流是：

1. 用通俗的语言描述该流程。识别其起点、终点、主要操作、决策、异常、并行任务和负责角色。

2. 编写第一个 PlantUML 草稿。在注重样式之前，先关注逻辑。

3. 渲染并检查它。检查结果是否阅读自然，且分支和循环是否易于理解。

4. 与利益相关者一起审查逻辑。渲染仅检查语法，而非流程是否正确。

5. 修订源代码并将其与项目一起保存。基于文本的图表易于与其他文档一起进行差异比较和审查。

对于本地渲染，PlantUML 命令行工具可以生成图表文件；基于浏览器的编辑器适合快速起草和预览。PlantUML 还提供浏览器编辑器，而 VPasCode 提供带有实时预览和 PlantUML 活动图支持的基于浏览器的编辑器。

1. 用通俗语言描述该流程。识别其起点、终点、主要操作、决策点、异常处理、并行任务以及负责角色。

2. 编写第一个 PlantUML 草稿。在注重样式之前，先关注逻辑。

3. 渲染并检查它。检查结果是否阅读自然，且分支和循环是否易于理解。

4. 与利益相关者一起审查逻辑。渲染仅检查语法，而非流程是否正确。

5. 修订源代码并将其与项目一起保存。基于文本的图表易于与其他文档一起进行差异比较和审查。

对于本地渲染，PlantUML 命令行工具可以生成图表文件；基于浏览器的编辑器适合快速起草和预览。PlantUML 还提供浏览器编辑器，而 VPasCode 提供带有实时预览和 PlantUML 活动图支持的基于浏览器的编辑器。

10. 使用 Visual Paradigm VPasCode 和 AI 辅助

VPasCode 是 Visual Paradigm 的基于浏览器的文本到图表编辑器。其 PlantUML 支持包括活动图，且编辑器提供实时渲染。Visual Paradigm 还介绍了内置的自然语言图表生成功能，以及用于修改或修正图表代码的 AI 辅助功能。

一个有用的 AI 辅助工作流程：

1. 提示应针对行为，而不仅仅是图表类型。例如：
   “为在线结账创建一个 PlantUML 活动图。包括购物车验证、地址验证、支付授权、失败路径、订单创建，以及并行的确认邮件和仓库准备。为‘客户’、‘订单服务’、‘支付服务’、‘通知服务’和‘仓库’使用分区。使用当前的 PlantUML 活动语法。”

2. 检查生成的源代码。检查它是否使用了 @startuml/@enduml，每个分支都代表一个真实条件，并且已处理失败或替代路径。

3. 在 VPasCode 中渲染它。使用预览功能发现语法错误、令人困惑的标签或过于复杂的布局。

4. 自行或通过有针对性的 AI 编辑来优化 PlantUML。请求具体变更，例如“添加支付超时路径”或“使订单创建后的仓库准备变为顺序执行”。

5. 请熟悉该流程的人员进行验证。AI 可以草拟一个看似合理的图表，但它无法确认贵组织的实际流程是否正确。

VPasCode 的具体控件和功能可用性可能因产品版本而异；请确认您所用编辑器中的当前选项。

11. Visual Paradigm 建模工作流

当您希望直接处理图表源代码和预览时，请使用 VPasCode。当任务需要图形编辑或更广泛的模型工作时，请使用 Visual Paradigm 的建模环境。Visual Paradigm 的指南描述了一个生成或导入图表，然后在可视化编辑器中进行优化的工作流；具体的导入路径可能因产品和版本而异。

合理的交接方式如下：

1. 在 PlantUML 中起草并迭代。

2. 分享渲染后的图表和源代码以供审查。

3. 如果您需要可视化编辑或其他建模功能，请将其打开或导入到相应的 Visual Paradigm 编辑器中。

4. 如果 PlantUML 源代码是团队选定的唯一真实来源，请将其作为维护版本；避免在两个位置静默地进行冲突编辑。

12. 常见错误与质量检查清单

在分享图表之前，请检查：

• 它是否有清晰的起点和有意义的终点？

• 每个动作是否描述了一个可识别的工作项？

• 决策结果是否标注清晰？

• 在关键位置是否包含了拒绝、错误、超时或取消路径？

• 循环条件是否使重复和退出行为清晰明确？

• 并行动作是否真正独立，并在需要时显示了同步？

• 分区是否代表了有用的所有权边界？

• 读者是否无需阅读冗长的动作标签就能理解流程？

• 渲染后的图表是否与实际情况相符？

优秀的活动图并非最长或最详细的那一个。它是最小的能够清晰展示工作流、决策、职责和重要异常情况的图表。

快速语法参考

示例使用 PlantUML 当前的活动图语法。对于不常见的构造或特定版本的渲染行为，请查阅 PlantUML 活动图参考文档。