如何画时序图:完整教程 | text2diagram

一、什么是时序图

二、为什么要画时序图

• 每一步都得指名道姓。 每条箭头必须写清源和目标。模糊的交接 —— 比如「系统发出一个事件」—— 一旦写成 OrderService -->> Kafka: OrderPlaced,就再也含糊不了。
• 顺序上的假设会暴露。 竞态、漏掉的 ack、悄悄的重试,画到图上就藏不住。同一条生命线上两条箭头之间没有 return?那你可能把一个同步调用当异步画了。
• 设计评审和 code review 能对上。 一张时序图三分钟就能在会上讲完;等价的 200 行 Python 走一遍要半小时。图成了 review 的锚点 —— 代码对不对,以图为准。

三、5 个核心元素

四、5 种消息(箭头)类型

五、Mermaid 时序图语法速通

sequenceDiagram
    autonumber
    actor User
    participant Web as Web App
    participant API as API Server
    participant DB as PostgreSQL

    User->>Web: click Login
    Web->>+API: POST /auth (email, password)
    API->>+DB: SELECT user WHERE email=?
    DB-->>-API: user row + password_hash
    API->>API: bcrypt.compare(pw, hash)
    alt password matches
        API-->>-Web: 200 OK + JWT
        Web-->>User: redirect to /dashboard
    else password wrong
        API-->>Web: 401 Unauthorized
        Web-->>User: show error banner
    end
    Note right of API: rate-limit: 5 attempts / min

六、10 条让时序图易读的规范

• 一张图讲一件事。 每张时序图只回答一个问题:登录怎么走,支付失败怎么处理。发现自己在一张图里画两个场景,拆开。
• 参与者最多 5-9 个。 再多图就成蜘蛛网了。相关的组件合并(用「数据层」代替 Redis + Postgres + Elasticsearch),或者拆成几张图。
• 参与者按调用频次从左往右排。 发起调用最多的放最左边,这样横跨整张图的长箭头最少,画面更干净。
• 每个 ->> 都配一个 -->>。 缺 return 箭头是读者困惑的头号原因 —— 调用方是在等,还是继续往下走了?画出来就没有歧义。真的是发完不管才省掉,那种情况用 -)。
• 箭头标签写动作和数据,别只写方法名。 ->> API: POST /login (email, pw) 好过 ->> API: login()。读者想知道发过去的是什么,不是函数叫什么。
• 打开 autonumber。 白送的编号,让每条消息都能在文档、工单、代码注释里被引用(「登录时序第 3 步」)。没有副作用。
• 真干活才画激活条,纯转发不画。 参与者从收到消息到响应之间有实际工作(查库、打外部接口),画激活条。只是转发的路由或网关,不画。
• 时间只往下走。 不要画向上的箭头。A 响应 B,就把响应画在 B 那条请求的 下面。向上的箭头看着像时间倒流,谁都读不懂。
• 每个 alt 都要有 else。 写了 alt success,就该给读者一个 else failure。只有一个分支的 alt 是个信号:真的是可选路径就用 opt。
• 箭头讲 做了什么,注释讲 为什么。 一句到位的注释(Note right of API: 5xx 时重试 3 次)能省掉把上下文塞进箭头标签的努力。箭头短,上下文放注释里。

七、进阶:片段(alt / opt / loop / par / critical / break)

八、3 个实战示例

示例 1 —— OAuth 2.0 授权码流程

sequenceDiagram
    autonumber
    actor U as User
    participant C as Client App
    participant AS as Auth Server
    participant RS as Resource API

    U->>C: click "Log in with X"
    C->>U: 302 redirect to AS/authorize
    U->>AS: GET /authorize (client_id, scope)
    AS-->>U: login form
    U->>AS: submit credentials + consent
    AS->>U: 302 redirect back with code
    U->>C: GET /callback?code=abc
    C->>+AS: POST /token (code, client_secret)
    AS-->>-C: access_token + refresh_token
    C->>+RS: GET /user (Bearer access_token)
    RS-->>-C: user profile JSON
    C-->>U: render dashboard

示例 2 —— 分布式 saga 与补偿

sequenceDiagram
    autonumber
    participant O as OrderService
    participant P as PaymentService
    participant I as InventoryService
    participant B as EventBus

    O->>+B: publish OrderCreated
    B-)P: OrderCreated
    P->>P: charge card
    alt charge succeeds
        P-)B: publish PaymentCharged
        B-)I: PaymentCharged
        I->>I: reserve stock
        alt stock available
            I-)B: publish StockReserved
            B-)O: StockReserved
            O->>-O: mark order Confirmed
        else stock unavailable
            I-)B: publish StockFailed
            B-)P: StockFailed
            P->>P: refund card (compensation)
            P-)B: publish PaymentRefunded
            B-)O: PaymentRefunded
            O->>O: mark order Cancelled
        end
    else charge fails
        P-)B: publish PaymentFailed
        B-)O: PaymentFailed
        O->>O: mark order Cancelled
    end

示例 3 —— WebSocket 聊天 + 已读回执

sequenceDiagram
    autonumber
    participant A as Client A
    participant S as Server
    participant DB as MessageDB
    participant B as Client B

    A-)S: WS send: hello
    S->>+DB: INSERT message (from=A, to=B)
    DB-->>-S: message_id
    S-)B: WS push: new message
    B->>B: render + auto-mark-read
    B-)S: WS ack: read_receipt(message_id)
    S->>+DB: UPDATE message SET status=read
    DB-->>-S: ok
    S-)A: WS push: read_receipt

九、常见错误

• 画成了戴帽子的流程图。 你的「时序图」里出现了菱形判断和绕回自己的分支 —— 那你想画的其实是流程图。时序图画的是参与者之间的交互,不是某一个参与者内部的控制流。
• 漏掉 return 箭头。 ->> API: query 后面没有 -->> Caller: result,读者不知道调用方是在等、超时了,还是继续往下走了。补一行 return 就没有歧义了。
• alt 没有 else。 alt success ... end 不画失败分支,等于在说「失败了什么都不做」,而线上几乎不可能这样。真的可选就用 opt,否则把 else 写出来。
• 参与者太多。 顶上排 10 个参与者,潜在的箭头就有 50 条。超过 9 个就合并(用「数据层」合掉 Redis + Postgres),或者拆两张(一张正常路径,一张错误路径)。
• 向上的箭头。 永远不要把响应画在触发它的请求 上面。时间往下流,向上的箭头看着像时间倒流,会毁掉读者刚建立起来的理解。
• 异步消息画成了实线。 ->> 隐含着调用方在阻塞等待。实际是发完就不管(Kafka publish、WebSocket 推送、后台任务入队),就用 -) —— 以后排查竞态问题的人会感谢你。

十、用 text2diagram 画时序图

• 快速模式 —— 一句话出图。适合描述已经足够精确的场景:参与者 5 个以内、顺序清楚、没有分支。
• 对话模式 —— 出图前先问 1-3 个问题。适合 OAuth 这种复杂度的交互、saga 模式、任何带错误分支的场景。AI 问的问题经常会挖出你自己都没意识到的假设。

十一、可复用的 Prompt 模板

Sequence diagram for [scenario name].

Participants:
- [name] ([role], e.g. user / service / queue / db])
- [name] ([role])
- ...

Happy path:
1. [source] -> [target]: [message + payload]
2. [source] -> [target]: [message]
3. ...

Failure paths:
- If [condition]: [alternative sequence]
- If [condition]: [alternative sequence]

Async / concurrent:
- [message A] and [message B] happen in parallel
- [message C] is fire-and-forget (no return expected)

Notes / constraints:
- [participant]: [rate limit / retry policy / timeout]

十二、小结