时序图的「else / alt / opt / loop」控制流

时序图不只是 A -> B，控制流关键字才是它真正有用的地方。

alt / else —— 分支

最常用。alt 表示 if，else 表示 else：

@startuml
title 登录返回
participant FE
participant API

FE -> API: POST /login
alt 成功
  API --> FE: 200 + JWT
else 凭据错
  API --> FE: 401
else 用户锁定
  API --> FE: 423
end
@enduml

三个分支平铺，else 跟着 alt 后面，多个 else 都合法。

opt —— 可选分支

opt 携带 refresh_token
  FE -> API: POST /refresh
  API --> FE: 200 + 新 JWT
end

opt 没有 else，等价于 if (cond) { ... }。

loop —— 循环

loop 每 10 秒
  FE -> API: GET /health
  API --> FE: 200
end

loop 最多 3 次
  FE -> API: 重试
end

loop 后面带任意 label，渲染时会显示在横条上。

par —— 并行分支

par
  FE -> API: GET /user
else
  FE -> API: GET /orders
end

两个分支同时发生，常用于前端并发请求。

critical / end critical —— 关键区

critical 数据库写入
  API -> DB: BEGIN
  API -> DB: INSERT
  DB --> API: ok
option 失败回滚
  API -> DB: ROLLBACK
  API --> FE: 500
end

option 等价于 else，专门用于错误处理风格。

break —— 提前跳出

1
2
3

break 用户取消
  API --> FE: 499
end

break 触发时跳出整个时序图，常用于取消流程。

note —— 注释

放在某个参与者的生命线上或横跨几个：

note over FE, API
  这里请求带 Idempotency-Key
end note
note right of API
  缓存命中率约 60%
end note

note over A, B 横跨多参与者，note left of A / note right of A 单边。

实战组合示例

把上面几个塞进一个「支付」的完整流程：

@startuml
title 支付完整流程
participant 用户
participant FE
participant API
participant Bank

用户 -> FE: 点击支付
FE -> API: POST /pay
opt 余额不足
  FE -> 用户: 弹窗充值
  用户 -> FE: 充值
end
API -> Bank: 扣款
Bank --> API: ok
alt 成功
  API --> FE: 200
  FE --> 用户: 显示成功
else 失败
  critical 退款
    API -> Bank: REFUND
    Bank --> API: ok
  option 退款失败
    API --> 用户: 人工客服
  end
else 超时
  loop 最多 3 次
    FE -> API: 查询订单
  end
end
@enduml

调试 tips

alt / par 必须以 end 收尾，少一个 end 整张图都不渲染。
note over 中如果写 , 或 :，建议包到 """ 块里：note over A """多行带, 字符"""，否则偶发解析报错。
loop 的次数描述里避免中英文混合，部分渲染器对全角字符不友好，先用 ASCII 数字 + 英文。