Mermaid vs PlantUML 状态图：正式状态机默认选 PlantUML

只比较状态机表达能力，PlantUML 更强，应优先用于正式状态机设计；Mermaid 适合普通状态流。 官方资料核验于 2026-07-22，整体工具差异请看系列总览。

两者都能表达开始与结束状态、带标签的转换、复合状态、choice、fork/join 和并行区域。正式状态机的分水岭不在并行区域，而在恢复历史、专用进入/退出点，以及跨复合状态内部转换的表达边界。

核心结论

• Mermaid 适合订单、工单和界面等普通状态流，PlantUML 应优先用于正式状态机设计。
• PlantUML 官方状态图支持浅历史 [H]、深历史 [H*] 和 <<entryPoint>>、<<exitPoint>>（PlantUML State Diagram syntax and features）。
• 截至 2026-07-22，Mermaid 11.16.0 官方状态图文档未提供 history、history*、entryPoint 或 exitPoint 专用语法（Mermaid State diagrams）；这不是对底层实现永久能力的断言。本项目锁定 Mermaid 11.6.0。
• 状态迁移顺序请结合时序图对比，步骤与决策请结合活动图对比。

本文基于两份官方语法文档：

• Mermaid State Diagram 官方文档
• PlantUML State Diagram 官方文档

Mermaid vs PlantUML 状态图核心差异

重点不是谁“能不能画状态”，而是这张图需要明确表达哪些状态机概念。

普通状态流两者有明显差距吗？

对订单、工单和界面生命周期，两者差距不大。Mermaid 官方文档支持基本状态、带标签转换和 [*] 起止状态；PlantUML 也提供同类基础表达。若读者只需理解下一步可能发生什么，Mermaid 足够清楚。

Mermaid 代码和图

stateDiagram-v2
  [*] --> Draft
  Draft --> AwaitingPayment: submit order
  AwaitingPayment --> Paid: payment approved
  AwaitingPayment --> Cancelled: payment expired
  Paid --> Fulfilled: ship order
  Paid --> Cancelled: cancel before shipping
  Fulfilled --> [*]
  Cancelled --> [*]

PlantUML 代码和图

@startuml
[*] --> Draft
Draft --> AwaitingPayment : submit order
AwaitingPayment --> Paid : payment approved
AwaitingPayment --> Cancelled : payment expired
Paid --> Fulfilled : ship order
Paid --> Cancelled : cancel before shipping
Fulfilled --> [*]
Cancelled --> [*]
@enduml

这个场景没有明确的表达能力胜负。普通生命周期图不需要历史恢复或专用端点时，选择 Mermaid 可以保持状态流直观；正式状态机仍应以 PlantUML 为默认。

复合状态的边界如何影响建模？

两者都支持复合状态和多层嵌套，也能在复合状态之间转换。Mermaid 官方文档同时规定：不能直接连接分别属于不同复合状态的内部状态（Mermaid State diagrams）；当业务规则依赖这类跨边界内部迁移时，PlantUML 的表达更稳妥。

Mermaid 代码和图

stateDiagram-v2
  [*] --> Processing

  state Processing {
    [*] --> Validating
    Validating --> ReservingInventory: valid
    Validating --> Rejected: invalid
    ReservingInventory --> Confirming: reserved
    Confirming --> [*]
  }

  Processing --> Completed
  Processing --> Failed
  Completed --> [*]
  Failed --> [*]

PlantUML 代码和图

@startuml
[*] --> Processing

state Processing {
  [*] --> Validating
  Validating --> ReservingInventory : valid
  Validating --> Rejected : invalid
  ReservingInventory --> Confirming : reserved
  Confirming --> [*]
}

Processing --> Completed
Processing --> Failed
Completed --> [*]
Failed --> [*]
@enduml

一到两层嵌套的普通流程仍可使用 Mermaid。需要跨复合状态内部转换、历史恢复或专用端点时，PlantUML 的已文档化语法才会产生决定性差异。

并行区域是主要分水岭吗？

不是。Mermaid 和 PlantUML 都支持 fork、join 和复合状态内的 -- 并行区域；PlantUML 还支持 || 作为另一种区域排列方向。因此，并行区域本身不能证明高级状态机能力相同或不同。

Mermaid 代码和图

stateDiagram-v2
  [*] --> Active

  state Active {
    [*] --> Unverified
    Unverified --> Verified: identity approved

    --

    [*] --> EmailOff
    EmailOff --> EmailOn: enable email
    EmailOn --> EmailOff: disable email
  }

  Active --> Suspended: policy violation
  Suspended --> Active: review passed

PlantUML 代码和图

@startuml
[*] --> Active

state Active {
  [*] --> Unverified
  Unverified --> Verified : identity approved

  --

  [*] --> EmailOff
  EmailOff --> EmailOn : enable email
  EmailOn --> EmailOff : disable email
}

Active --> Suspended : policy violation
Suspended --> Active : review passed
@enduml

这里的基础语法依旧接近。账号解除暂停后若必须恢复此前内部状态，PlantUML 的浅历史 [H] 和深历史 [H*] 才是有官方依据的差异。

正式状态机为什么应优先用 PlantUML？

当图需要记录更完整的状态机表示法，而不只是解释状态流时，PlantUML 更有优势。例如：

• 需要恢复上次运行模式的设备控制器。
• 有明确进入/退出点的工作流引擎。
• 存在跨复合状态内部转换的复杂生命周期。
• 需要使用 UML 专用状态表示法评审的领域模型。
• 使用统一主题和 stereotype 的长期架构文档。

以下场景通常用 Mermaid 就够了：

• 读者主要需要理解合法状态转换。
• 嵌套较浅，且没有历史恢复或专用端点。

如果问题重点是服务调用顺序，可以看时序图对比；如果重点是步骤、决策和责任分工，而不是对象状态，可以看活动图对比。

官方核验与版本边界

截至 2026-07-22，官网导航显示 Mermaid 11.16.0，State diagrams 页面没有列出 history、history*、entryPoint 或 exitPoint 专用语法；这只能说明该文档未提供这些写法。PlantUML 对浅/深历史和进入/退出点的专用表示法见State Diagram syntax and features。OnUML 当前锁定 11.6.0，文档结论不能把官网版本与项目版本混为一谈。

状态图选择结论

状态图的选择先看是否需要正式状态机表达，再看是否只是解释普通状态流。并行区域两者都能画；真正应触发 PlantUML 的是 [H]、[H*]、进入/退出点和更复杂的复合状态边界。

状态图有哪些常见问题？

Mermaid 能画嵌套状态图吗？

可以。Mermaid 支持复合状态和多层嵌套，普通功能生命周期通常已经够用。涉及跨复合状态内部状态转换、历史恢复或专用进入/退出点时，PlantUML 更合适。

Mermaid 支持并行状态吗？

支持。Mermaid 可以在复合状态中使用 -- 分隔并行区域。PlantUML 支持 -- 和 ||，多提供一种区域排列方向。

Mermaid 和 PlantUML 状态图语法可以直接转换吗？

两者共享 [*]、-->、复合状态和并行分隔符等概念，Mermaid 官方也说明其语法尝试与 PlantUML 保持兼容以便共享图表。高级 stereotype、样式和工具专用语法仍不能假定可以无损转换。

生产系统的状态机应该选哪个？

如果图只是解释实现，Mermaid 可胜任。若文档必须表达历史状态、专用进入/退出点或跨复合状态内部迁移，优先使用 PlantUML。图表语法表达的是设计，不能替代对实际状态机实现的测试。

最后总结：

只比较状态机表达能力，PlantUML 更强，应优先用于正式状态机设计；Mermaid 适合普通状态流。 用时序图说明调用顺序，用活动图说明决策和责任，可让状态图保持专注。