什么是时序图？
时序图展示的是对象或服务之间随时间推移的交互过程。它和流程图的区别在于：流程图关注的是"走哪条路"，时序图关注的是"谁发消息、谁接收、接下来发生了什么"。
典型的使用场景：
- 记录 API 请求/响应流程
- 说明登录和鉴权机制
- 梳理微服务间的调用链路
- 给新成员讲解陌生模块的工作原理
- 排查问题时，把"理论上应该发生的事"画出来对比实际行为
三个核心元素
时序图由三个基本元素构成：
| 元素 | 含义 | |---|---| | 参与者（Participant） | 一个角色、服务或组件，画在最顶部 | | 生命线（Lifeline） | 从参与者向下延伸的竖虚线，表示它的时间轴 | | 消息（Message） | 生命线之间的横向箭头，标注操作名 |
消息从左到右、从上到下流动——时间向下走。掌握这三个元素，就能读懂任何时序图。
同步消息 vs 异步消息
- 实心箭头 → 同步调用。发送方等待对方响应后才继续。
- 空心箭头 ⇒ 异步消息。发送方发完就走，不等回应。
- 虚线箭头 ← 返回消息。通常是同步调用的应答。
激活框
生命线上的细长矩形叫激活框，表示该参与者正在处理某件事的时间段。它帮助你直观感知处理时长和并发行为。
一个实际例子：用户登录
以下是一个简单的登录流程，涉及三个参与者：浏览器、API 服务、认证服务。
浏览器 → API 服务 : POST /login {email, password}
API 服务 → 认证服务 : verifyCredentials(email, password)
认证服务 → API 服务 : {valid: true, userId: 42}
API 服务 → API 服务 : 生成 JWT
API 服务 → 浏览器 : 200 OK {token: "..."}
画成时序图后，一眼就能看出：
- 浏览器发起登录请求
- API 服务把验证逻辑交给认证服务
- 认证服务确认用户身份
- API 服务生成 Token 并返回
如果不画图，这个流程要么散落在四个文件注释里，要么埋在一段没人耐心读完的长段落中。
什么时候用时序图（什么时候不用）
适合画时序图的场景：
- 需要记录两个或多个系统/服务之间的通信
- 向没有参与开发的工程师解释某个功能
- 排查问题时，想把完整调用链路画出来
- 设计新 API 时，在写代码之前先验证交互模型
不适合的场景：
- 只有一个系统的内部逻辑——用流程图更简单
- 需要展示系统整体结构——用架构图
- 只有一个参与者——编号列表就够了
在 CodePic 中画时序图
CodePic 的手绘风格让时序图看起来像白板草图，而不是正式文档，更容易激发讨论和修改意见。
操作步骤：
- 打开空白画布或从时序图模板开始
- 添加参与者 — 在顶部创建方框，标注服务名（浏览器、API、数据库……）
- 画生命线 — 从每个参与者向下延伸竖虚线
- 添加消息 — 在生命线之间画横向箭头，标注操作名
- 添加激活框 — 可选，在生命线上标注处理时间段
- 用 frame 分组 — 用带
alt或loop标签的矩形框标注条件分支或循环逻辑
画出清晰时序图的小技巧
- 参与者名字要短。"认证服务"比"用户认证与权限管理微服务"好用得多
- 每条箭头都要标注。空白箭头让人困惑，哪怕写"请求"或"响应"也比什么都没有强
- 返回箭头按需画。只在返回值有意义时（Token、状态码、ID）才画虚线返回箭头
- 参与者按流向排列。发起方放最左边，让箭头尽量从左到右流动
让图表活在文档里
时序图最有价值的地方，是和代码放在一起。有些团队会把图片嵌进 README 或 PR 描述，每次新增接口时一并更新。有些团队维护一个 /docs/diagrams/ 文件夹，在 Code Review 阶段同步更新。
无论哪种方式，时序图都会成为回答"X 调用 Y 的时候到底发生了什么"这个问题的最快捷径。
从 CodePic 导出 PNG 或 SVG，放到团队实际查看的地方——Wiki、PR、设计文档都行。手绘风格辨识度高，也更容易迭代修改。
时序图看起来是可选项，直到你花了三个小时排查一个 bug，才意识到这个问题两分钟就能画清楚。从简单开始：三个参与者，五条消息。通常这已经足够找到问题所在。