Mermaid vs PlantUML 时序图：复杂交互该选谁？
PlantUML 更强，应该优先选择 PlantUML。 只比较时序图表达能力时，Mermaid 已能处理常见分支、并行、激活和参与者类型，但 PlantUML 对返回语义、深调用栈、片段引用和长图分页的支持更完整。前者能完成多数基础时序图，后者更适合需要持续维护的正式设计图。
本文引用的官方资料统一核验于 2026-07-22。
本文只比较时序图本身。需要完整选型背景，可以先看系列总览中的整体决策框架。
比较依据是两套工具当前的官方语法。Mermaid 已明确支持 alt、opt、loop、par、critical、break、activation 和参与者创建/销毁；PlantUML 除了这些基础能力，还提供 return、autoactivate、ref over 与 newpage 等更适合复杂调用链的语法。截至 2026-07-22，Mermaid 当前官方文档未提供这四类能力的等价专用语法。具体能力可分别查看 Mermaid Sequence Diagram 官方文档 和 PlantUML Sequence Diagram 官方文档。
核心结论
- 两者都能表达常见控制流程，条件分支不是决定性差异。
- 参与者类型也不再是 PlantUML 独占能力，但 PlantUML 的关键字更直接。
- 一旦需要精确返回、自动激活、正式片段引用或分页，PlantUML 明显更完整。
- 如果暂时无法判断图以后会不会变复杂，优先使用 PlantUML。
Mermaid 与 PlantUML 时序图的核心差异是什么？
核心差异不在基础消息或条件分支，而在复杂调用关系能否被直接、精确地写进源码。根据两套官方时序图语法的能力清单，Mermaid 已覆盖 6 类常用控制片段；PlantUML 则进一步覆盖返回、自动激活、引用片段和分页，因此整体表达上限更高。
| 对比点 | Mermaid | PlantUML | 结论 |
|---|---|---|---|
| 基础消息 | 支持 | 支持 | 平手 |
alt / opt / loop | 支持 | 支持 | 平手 |
par / critical / break | 支持 | 支持 | 平手 |
| activation | activate/deactivate、+/- | activate/deactivate、++/--、autoactivate | PlantUML 更完整 |
| 参与者创建/销毁 | create / destroy | create、destroy、**、!! | PlantUML 写法更多 |
| 参与者类型 | 支持 actor、boundary、control、entity、database、collections、queue 等外形 | 直接使用对应关键字 | 两者都支持，PlantUML 更直接 |
| 返回语义 | 通常显式书写返回消息 | 支持 return label | PlantUML 更精确 |
| 片段引用 | 可用 note 近似表达 | 支持 ref over | PlantUML 更符合 UML 语义 |
| 长图分页 | 官方语法没有对应的单源码分页指令 | 支持 newpage | PlantUML 胜出 |
| 标题与页脚 | 支持标题等基础展示 | 支持 title、header、footer | PlantUML 更适合正式输出 |
这意味着“图现在能不能画出来”不是最有价值的判断标准。真正需要考虑的是：调用链加深以后，源码是否还能准确表达返回关系和阶段边界。按这个标准，PlantUML 的余量更大。
Mermaid 能否表达复杂控制流程？
可以。根据 Mermaid 官方时序图语法，它原生支持 alt、opt、loop、par、critical 和 break 六类控制片段。仅仅因为流程包含嵌套分支或并行处理，并不足以判定 Mermaid 无法胜任。
下面是一个支付流程：有库存则扣款，支付成功写订单并发消息，支付失败释放库存；没有库存则直接返回。
Mermaid 代码和图
sequenceDiagram
autonumber
actor User
participant Web
participant API
participant Inventory
participant Payment
participant DB
participant Queue
participant Email
User->>Web: Submit order
Web->>API: POST /orders
activate API
API->>Inventory: Reserve items
alt items available
Inventory-->>API: Reserved
API->>Payment: Charge card
alt payment success
Payment-->>API: Payment confirmed
API->>DB: Save paid order
API->>Queue: Publish OrderPaid
Queue-->>Email: Send confirmation
API-->>Web: Show success
else payment failed
Payment-->>API: Payment declined
API->>Inventory: Release items
API-->>Web: Show payment error
end
else out of stock
Inventory-->>API: Not available
API-->>Web: Show out of stock
end
deactivate API
PlantUML 代码和图
@startuml
autonumber
actor User
participant "Web App" as Web
participant "Order API" as API
participant "Inventory Service" as Inventory
participant "Payment Service" as Payment
database "Database" as DB
queue "Message Queue" as Queue
participant "Email Service" as Email
User -> Web: Submit order
Web -> API: POST /orders
activate API
API -> Inventory: Reserve items
alt items available
Inventory --> API: Reserved
API -> Payment: Charge card
alt payment success
Payment --> API: Payment confirmed
API -> DB: Save paid order
API -> Queue: Publish OrderPaid
Queue -> Email: Send confirmation
API --> Web: Show success
else payment failed
Payment --> API: Payment declined
API -> Inventory: Release items
API --> Web: Show payment error
end
else out of stock
Inventory --> API: Not available
API --> Web: Show out of stock
end
deactivate API
@enduml
这个案例中，两张图都能完整表达嵌套条件和多参与者协作，效果没有本质差距。如果你还需要描述状态变化而不是消息先后，可以继续对比 Mermaid vs PlantUML 状态图；如果重点是跨角色业务步骤，则更适合查看 Mermaid vs PlantUML 活动图。
参与者类型还是 PlantUML 的独有优势吗？
不是。Mermaid 当前已支持 actor、boundary、control、entity、database、collections 和 queue 等参与者外形；PlantUML 也支持这些类型，并可直接通过 database、queue 等关键字声明。差异已经从“能不能表达”变成“语法是否直接”，详情可对照两者的参与者定义与 PlantUML 参与者类型。
下面用最常见的 checkout 流程说明这个差别。示例中的 Mermaid 代码使用普通 participant，PlantUML 则直接把数据库声明为 database。
Mermaid 代码和图
sequenceDiagram
actor User
participant Web
participant API
participant DB
User->>Web: Click checkout
Web->>API: POST /orders
API->>DB: Insert order
DB-->>API: Order saved
API-->>Web: 201 Created
Web-->>User: Show confirmation
PlantUML 代码和图
@startuml
actor User
participant "Web App" as Web
participant "Order API" as API
database "Database" as DB
User -> Web: Click checkout
Web -> API: POST /orders
API -> DB: Insert order
DB --> API: Order saved
API --> Web: 201 Created
Web --> User: Show confirmation
@enduml
PlantUML 在这里仍然更顺手，因为角色类型就是语法关键字，读源码时也能立即识别。这个优势真实存在，但不足以单独决定选型，更关键的差距出现在长图和深调用栈中。
PlantUML 为什么更适合长图和深调用栈？
因为 PlantUML 能把返回、激活、引用和分页写成独立语义，而不必用普通消息或注释近似替代。PlantUML 官方时序图文档明确提供 return、autoactivate、ref over、newpage、title 和 footer；截至 2026-07-22，Mermaid 当前官方文档未提供这些能力的等价专用语法。newpage 会把同一份源码拆成多张图像，并不自动生成多页 PDF。
下面的例子同时展示片段引用、返回语义、分页、标题和页脚。
PlantUML 代码和图
@startuml
title Checkout Sequence
footer OnUML Architecture Review - Sequence Diagram
autonumber
autoactivate on
actor User
participant "Web App" as Web
participant "Order API" as API
participant "Payment Service" as Payment
database "Database" as DB
User -> Web: Submit order
Web -> API: POST /orders
ref over API, Payment
Shared payment authorization flow
end ref
API -> Payment: Authorize payment
return Authorization result
alt authorized
API -> DB: Save paid order
return Order id
API --> Web: Show success
else declined
API --> Web: Show payment error
end
newpage Fulfillment handoff
API -> DB: Load order
return Order details
API --> Web: Show fulfillment status
@enduml
Mermaid 近似表达
sequenceDiagram
autonumber
actor User
participant Web
participant API
participant Payment
participant DB
User->>Web: Submit order
Web->>API: POST /orders
Note over API,Payment: Shared payment authorization flow
API->>Payment: Authorize payment
Payment-->>API: Authorization result
alt authorized
API->>DB: Save paid order
DB-->>API: Order id
API-->>Web: Show success
else declined
API-->>Web: Show payment error
end
Note over API,Web: Fulfillment handoff starts here
API->>DB: Load order
DB-->>API: Order details
API-->>Web: Show fulfillment status
两份源码都能让读者看懂业务，但它们并不等价：
- Mermaid 用
Note over标出共享流程；PlantUML 用ref over表达正式引用片段。 - Mermaid 显式书写一条返回消息；PlantUML 的
return会返回到最近一次激活的调用点。 - Mermaid 用 note 标记阶段切换；PlantUML 的
newpage会把同一份源码拆成多张图像。 - PlantUML 还可用
autoactivate自动管理激活条，减少深调用栈中的成对语句。
当时序图承担架构评审或设计归档职责时，源码语义是否准确会直接影响后续修改。需要继续比较更高层的系统结构时，可参考 Mermaid vs PlantUML 软件架构图；若需要 C4 Dynamic 与时序图的边界，可看 Mermaid C4 vs C4-PlantUML。
时序图选择建议
默认选择 PlantUML。对照两套官方时序图语法的能力范围，它能覆盖 Mermaid 的主要时序表达，同时为返回、激活、引用和分页这 4 类进阶需求保留更大的演进空间。只有在需求已经明确局限于中短请求链路、普通业务分支或简单并行时，Mermaid 才是足够且合适的选择。
优先选 PlantUML，如果时序图需要：
- 表达多层调用栈，并准确对应返回关系。
- 用
ref over标记被引用的交互片段。 - 用
newpage将一份源码拆成多张连续图像。 - 自动管理 activation，或表达复杂对象生命周期。
- 稳定输出标题、页眉、页脚和编号。
可以选 Mermaid，如果你能确定图只需要：
- 展示一次 API 请求链路。
- 说明成功、失败等普通业务分支。
- 展示简单并行处理。
- 保持在中短长度，且不需要分页或正式片段引用。
不要只按当前图的长度选择。时序图往往会随着异常分支、补偿流程和异步回调不断增长；如果这些变化已经可以预见，直接从 PlantUML 开始，通常比后续迁移更稳妥。
关于 Mermaid 与 PlantUML 时序图的常见问题
以下答案均以 Mermaid 与 PlantUML 当前官方时序图文档为准。
Mermaid 时序图支持 alt 吗？
支持。Mermaid 官方文档列出的控制片段包括 alt、opt、loop、par、critical 和 break。有条件分支不等于必须使用 PlantUML。
参与者类型是 PlantUML 独有能力吗？
不是。Mermaid 当前文档也列出了 boundary、control、entity、database、collections 和 queue 等参与者外形。PlantUML 的优势是可以直接使用同名关键字，源码更直观，而不是独占这些类型。
PlantUML 一定更适合复杂流程吗？
是，但这里的“复杂”需要定义清楚。控制流复杂，例如分支多、参与者多、循环或并行时，两者都能处理；调用栈语义复杂，例如明确返回、自动激活、引用片段或分页时，PlantUML 的专用语法更强。
只看图形表达能力，最终该选谁？
选 PlantUML。Mermaid 足以完成基础和中等复杂度的时序图，但 PlantUML 的表达上限更高，面对正式设计、长流程和持续演进的调用链时更可靠。
结论不取决于图是否“够短”，而取决于它是否需要保留调用栈语义。能预见增长的设计图，应从 PlantUML 开始。