Mermaid vs PlantUML 泳道图：当前 OnUML 默认选 PlantUML

当前 OnUML 版本下，泳道图优先 PlantUML；Mermaid 11.6.0 只能用 subgraph 近似，官方 beta 语法也不作为稳定生产默认。截至 2026-07-22，OnUML 锁定 Mermaid 11.6.0；Mermaid 官网为 11.16.0，该版本新增 swimlane-beta，官方同时提示其语法未来可能演变（11.16.0 发布记录，Swimlanes Diagram Syntax）。

本文只比较角色职责、泳道切换、跨泳道可读性和版本兼容。需要从工具与图表目的整体选择时，请看总览中的系统边界；需要讨论动作控制而非职责归属时，请看活动图中的动作控制。

核心结论

• 当前 11.6.0 没有 Mermaid 独立泳道图类型，subgraph 只是流程图视觉分组。
• PlantUML 以 |Lane| 切换当前活动所属角色，职责归属写在流程文本中。
• Mermaid 11.16.0 的 swimlane-beta 不等于 OnUML 已支持，也不应作为稳定生产默认。
• 当讨论服务、组件和外部依赖的边界时，应使用软件架构图的系统边界。

版本前提决定当前选择

Mermaid 的独立泳道图从 11.16.0 起以 swimlane-beta 提供，使用顶层 subgraph 定义泳道，并允许跨泳道边；官方说明该新图类型的语法可能继续演变。OnUML 当前锁定的 11.6.0 低于该版本门槛，因此本文只把 subgraph 视为近似分组，当前默认选择 PlantUML（Mermaid Swimlanes，11.16.0 发布记录）。

这一区分要写清楚：官网 11.16.0 的能力描述可以帮助评估未来版本，但不能反推当前 OnUML 已能渲染 swimlane-beta。本文所有 Mermaid 示例都使用项目当前可用的 Flowchart subgraph。

谁负责活动，谁更清楚？

PlantUML 活动图用 |Lane| 切换泳道，后续活动归属当前泳道，并支持颜色和别名；这使职责在源码阅读时保持连续。Mermaid Flowchart 的节点可被放入 subgraph，但该结构的本质是图形分组，而非当前 11.6.0 的独立泳道类型（PlantUML Swimlanes，Mermaid Flowcharts）。

下面的退货流程保留了相同业务步骤。Mermaid 通过 Customer、Support、Warehouse 和 Finance 四个分组放置节点；PlantUML 则在每次职责交接处显式切换泳道，因此每个活动的归属能从代码顺序直接确认。

Mermaid 代码和图

flowchart LR
  subgraph Customer
    C1[Submit return request]
    C2[Ship item back]
    C3[Receive refund]
  end

  subgraph Support
    S1[Review request]
    S2[Send return label]
    S3[Notify result]
  end

  subgraph Warehouse
    W1[Receive item]
    W2[Inspect item]
  end

  subgraph Finance
    F1[Issue refund]
  end

  C1 --> S1
  S1 --> S2
  S2 --> C2
  C2 --> W1
  W1 --> W2
  W2 --> S3
  S3 --> F1
  F1 --> C3

PlantUML 代码和图

@startuml
|Customer|
start
:Submit return request;

|Support|
:Review request;
:Send return label;

|Customer|
:Ship item back;

|Warehouse|
:Receive item;
:Inspect item;

|Support|
:Notify result;

|Finance|
:Issue refund;

|Customer|
:Receive refund;
stop
@enduml

如何阅读跨泳道交接？

PlantUML 在活动之间切换 |Lane|，交接点随流程文字出现；这使读者先看到动作和归属，再理解图上的流转。Mermaid subgraph 之间可用普通连线连接节点，但跨分组图的可读性更依赖布局；官方还说明，子图节点与外部相连时，子图自己的方向可能继承父图方向（PlantUML Swimlanes，Mermaid subgraph 方向说明）。

当交接次数增加，职责边界不应只靠节点所在区域猜测。PlantUML 的每次泳道切换是可审查的文本标记；Mermaid 则适合把少量角色作为视觉分组，且应为跨组连线预留足够清晰的布局。

Mermaid 11.6.0 为什么只能用 subgraph？

因为独立 swimlane-beta 的官方版本门槛是 Mermaid 11.16.0+，而 OnUML 当前锁定 11.6.0。在当前版本中，Flowchart 的 subgraph 和普通边是可用的组合，但不能把它称为 Mermaid 的原生泳道图，也不能承诺新版 beta 语法已经稳定可用（Mermaid Swimlanes，Mermaid Flowcharts）。

下面的采购流程展示了 subgraph 的边界：角色区域可以分开，跨区域交接由边连接。它能呈现职责分组，但职责和交接的阅读成本会随着分组数与跨组边数增加。

Mermaid 代码和图

flowchart LR
  subgraph Requester
    R1[Create purchase request]
    R2[Revise request]
    R3[Receive goods]
  end

  subgraph Manager
    M1[Review request]
    M2{Approved?}
  end

  subgraph Procurement
    P1[Create purchase order]
    P2[Confirm supplier]
  end

  subgraph Warehouse
    W1[Prepare receiving plan]
  end

  subgraph Finance
    F1[Reserve budget]
  end

  R1 --> M1 --> M2
  M2 -- No --> R2 --> M1
  M2 -- Yes --> P1 --> P2
  P2 --> W1
  P2 --> F1
  W1 --> R3
  F1 --> R3

PlantUML 代码和图

@startuml
|Requester|
start
:Create purchase request;

|Manager|
:Review request;

if (Approved?) then (yes)
  |Procurement|
  :Create purchase order;
  :Confirm supplier;

  fork
    |Warehouse|
    :Prepare receiving plan;
  fork again
    |Finance|
    :Reserve budget;
  end fork

  |Requester|
  :Receive goods;
  stop
else (no)
  |Requester|
  :Revise request;
  |Manager|
  :Review request again;
  stop
endif
@enduml

为什么 PlantUML 更适合作为当前默认？

在 OnUML 的 11.6.0 基线下，PlantUML 已有可用的 |Lane| 活动泳道语法，而 Mermaid 只能将角色放入 Flowchart subgraph。当图的主要问题是“这个动作属于谁、何时交给谁”时，PlantUML 将归属和切换写成源码的一部分，因此应优先采用它（PlantUML Swimlanes，Mermaid Flowcharts）。

这个简短示例适合 subgraph：职责边界少，回到 QA 的路径也很容易追踪。它仍是流程图分组，而不是当前版本中的独立泳道类型。

Mermaid 代码和图

flowchart TD
  subgraph Product
    P1[Define requirement]
    P2[Accept result]
  end

  subgraph Engineering
    E1[Design solution]
    E2[Implement change]
    E3[Fix feedback]
  end

  subgraph QA
    Q1[Test change]
    Q2{Passed?}
  end

  P1 --> E1 --> E2 --> Q1 --> Q2
  Q2 -- No --> E3 --> Q1
  Q2 -- Yes --> P2

当前 OnUML 中，若只需少量角色分组和清楚的跨组边，Mermaid Flowchart subgraph 可以满足说明需求。若职责归属、泳道切换和交接记录本身需要被评审，使用 PlantUML。

不要用泳道图替代系统边界图。服务、组件、外部系统及它们的关系应放到软件架构图的系统边界；动作执行顺序与终止条件应放到活动图的动作控制。

常见问题

OnUML 当前支持 Mermaid 的 swimlane-beta 吗？

不支持。OnUML 锁定 Mermaid 11.6.0，而官方 Swimlanes 文档标注独立 swimlane-beta 需要 11.16.0+；该文档也提示新语法可能演变。因此它不能被当作当前项目或稳定生产环境的默认方案（Mermaid Swimlanes）。

Mermaid 的 subgraph 能表达什么？

它能把流程节点放在不同视觉分组，并用普通边连接分组内外的节点。对少量角色和少量交接，这足以展示职责区域；但它是 Flowchart 分组，不应描述成当前 11.6.0 的独立泳道语义（Mermaid Flowcharts）。

PlantUML 如何切换活动所属泳道？

在 PlantUML 活动图中写入 |Lane| 即可切换后续活动所在泳道，官方还支持泳道颜色和别名。这让职责交接紧跟在动作文本前，适合需要逐步确认归属的跨角色流程（PlantUML Swimlanes）。

何时应该改用软件架构图？

当读者的问题变成“哪个服务调用哪个系统、边界在哪里”，泳道已不是最佳视图，应使用软件架构图的系统边界。泳道图保持在“谁执行哪一步、何时交接”的层次，能避免职责流程和系统结构混在一张图里。