Mermaid 时序图：API 与服务调用

时序图用来说明交互顺序。当核心问题是“谁在什么时候把什么发给谁”时，它比流程图更合适。常见场景包括浏览器到 API 的调用、认证握手、Webhook 投递、队列处理以及服务之间的重试。

用有意义的名称声明参与者

sequenceDiagram
  actor User
  participant Web as Web application
  participant API as Orders API
  participant DB as Database

  User->>Web: Submit order
  Web->>API: POST /orders
  API->>DB: Insert order
  DB-->>API: Order ID
  API-->>Web: 201 Created
  Web-->>User: Show confirmation

别名可以让消息语句更短，同时保留可读标签。人类角色用 actor，软件组件用 participant。参与者的顺序要让主路径更容易阅读。

区分调用和响应

实线箭头通常表示请求或调用，虚线箭头通常表示返回。这是一种沟通约定，不代表一定是同步执行。如果阻塞和异步的差别很重要，应该写进标签或正文里。

用一个图表达分支

当两个结果共享同一个上下文时，可以使用 alt 块：

sequenceDiagram
  Client->>API: GET /profile
  alt token is valid
    API-->>Client: 200 Profile
  else token expired
    API-->>Client: 401 Unauthorized
  end

opt 适合可选分支，loop 适合重复交互。块标签应该描述条件，而不是实现细节。token is valid 比 if checkToken() returns true 更清楚。

保持时间和职责真实

时序图虽然从上到下阅读，但它并不自动代表性能时间线。不要把纵向间距当成精确耗时。如果需要延迟数据，应该把实际数值写进消息标签，或者单独放一个性能图。

也不要把时序图画成所有内部函数调用的总账。只建模跨越有意义边界的交互。聚焦后的图更容易与 API 合同和失败行为保持同步。

把示例贴到 Mermaid 图表编辑器 里，再把参与者逐个替换成你系统里的组件。文档里建议导出 SVG，这样不同宽度下文字和线条都更清晰。