OAuth 2.0 登录
跳转授权、用户同意、带 code 的回调,以及服务端换 token。有人问「为什么 code 要给后端而不是浏览器」时,把这张图贴进方案里就行。
5 个参与者 · 14 条消息
时序图模板
8 张画完整的交互流程,连返回都画了。打开就在画布上。然后把它聊成你的系统:「API 和 worker 之间加一个队列、加一次重试、邮件服务删掉」。
挑一个模板
这里每张图都和你导入后拿到的出自同一份结构化定义 —— 没有一张是精修过的截图。点开任意一张能看到原始尺寸。「进对话微调」把图放进画布并打开对话面板,你的第一句话就能开始改它;「用这个模板」只把它放进编辑器,剩下的你自己来。
下单与支付回调
商城 → 订单服务 → 支付渠道,外加那条异步回调 —— 用户看到转圈之后,支付结果才真正确认下来。
6 个参与者 · 16 条消息
带缓存的接口读取
CDN 边缘、Redis、数据库,命中和未命中两条路径都画了。解释「这个过期数据到底是哪一层给的」很好用。
5 个参与者 · 13 条消息
找回密码
发起请求、一次性令牌、邮件送达,以及兑换时的令牌校验。画一次,安全评审就能少聊半小时。
5 个参与者 · 16 条消息
订单履约(多服务)
中间是事件总线,仓储和物流各自响应,最后才通知用户。编排式和协作式的区别,一眼就看出来。
6 个参与者 · 14 条消息
文件直传对象存储
预签名 URL、浏览器直传对象存储、后台 worker 再接手。为什么文件根本不经过你的 API,这张图讲得最清楚。
5 个参与者 · 16 条消息
Webhook 投递与重试
队列、一次投递、非 2xx、退避重试,以及「连续失败就停掉并通知人」的那个点。客服天天在问这条流程。
5 个参与者 · 15 条消息
即时消息投递
Websocket 网关、落库、扩散,收信人不在线时再走推送。一张图上有两个客户端 —— 时序图的价值就在这种场景。
6 个参与者 · 14 条消息
这些模板怎么用
1. 挑参与者最多的那张
有点反直觉但确实好使:选服务比你需要的更多的模板。看着图删掉一列是两秒钟的事,而漏画的那一跳,通常要等它引发故障时才被发现。
2. 打开 —— 整段交互已经画好了
页面加载完图就在画布上,参与者按第一次出现的顺序排好,返回都画成了虚线,异步的那几跳也标出来了。
3. 把它聊成你的系统
打开对话面板,用句子纠正它:「API 和 worker 之间加一个队列、超时后加一次重试、支付渠道改名叫 Stripe、邮件服务删掉」。助手改的就是你眼前这张结构化的图,所以每一轮返回的是重画后的版本,而不是重新猜一张。
4. 手动收尾并导出
分屏视图把 Mermaid 源码和预览摆在一起,做最后几处微调。然后:文档里会被放大的用 SVG,幻灯片和工单用 PNG,或者把源码提交到它描述的那段代码旁边。
时序图是什么
UML 时序图画的是一段随时间展开的交互:谁在什么时候给谁发了什么消息。每个参与者一条竖着的生命线,时间自上而下,每根箭头是一条消息。它回答「谁调用谁、返回了什么」—— 不是「这个系统由什么组成」(那是类图),也不是「接下来做什么」(那是流程图)。
分布式系统的争论,最后往往靠这张图收场。把每一跳按顺序画出来之后,很多问题会自己给出答案:延迟在哪一段、第三次调用挂了会怎样、那个回调有没有可能比它依赖的响应先到。价值大多产生在画的过程里,而不是画完之后。
Mermaid 的 sequenceDiagram 覆盖了工程文档需要的部分:带可读名字的参与者、实线请求、虚线返回、自调用。它不是完整 UML —— 没有带形式化守卫条件的组合片段。不过实践中,加一句注释或者给失败路径单画一张,通常比嵌套框更好读。
时序图语法速查
时序图的信息量几乎全在这六样东西上。最容易画错的是虚线箭头:不画返回,这张图就退化成一张没有时间感的调用关系图。
参与者
participant id as 显示名每一列是一个参与者:用户、服务、队列、数据库。短 id 供箭头引用,显示名是读的人看到的,可以带空格。
时间自上而下
从上到下没有箭头编号 —— 纸面上的先后就是时间上的先后。声明顺序决定左右排布,所以按第一次出现的顺序声明参与者,连线就不会互相穿插。
请求
->>实线加实心箭头:一方调用另一方并等待结果。接口类的时序图里,大部分箭头都是这种。
返回
-->>虚线,回到调用方。返回值、回调、事件都用它 —— 只要不是一次新的请求。把返回画出来,调用关系才变成时间线。
自调用
api->>api参与者给自己发消息,画成绕回自己生命线的一个环。校验、重试、内部处理适合用它,否则这些工作在图上是隐形的。
消息文字
: 文字冒号后面的内容会贴在箭头上。写具体一点 ——「POST /login(email, password)」是接口文档,「登录」什么也没说。
常见问题
导入之后怎么改?
两条路,各管一类改动。对话管「结构性」的:「API 和 worker 之间加个队列」「邮件服务删掉」「把换 token 那步挪到后端」—— 说一轮重画一张。分屏编辑器管「精细」的:消息文字打错了、参与者改个名、两条调用换个顺序。多数人的用法是:导入 → 在对话里把形状聊定 → 回编辑器抛光。
助手真的「看得懂」导入进来的图吗?
看得懂,因为模板是结构化数据,不是一张图片或者一坨文本。导入的参与者和消息直接成为这轮对话的工作状态,所以「把邮件服务删了」删的就是那一列以及挂在它身上的所有消息 —— 助手不是在根据一段描述重新猜你的图。
实线箭头和虚线箭头有什么区别?
实线(->>)是请求:一方调用另一方。虚线(-->>)是回来的东西 —— 返回值、回调、事件。这个约定很重要:只有实线的图,说的只是谁调用了谁;把虚线返回补上,它才变成一条能推理的时间线。
异步怎么画?
把返回画成一条比对应请求晚到的虚线,中间发生的事照常画在那儿。Webhook 和订单履约两个模板都是这么做的:给用户的响应先发出去,支付确认后到 —— 而这恰恰是值得写进文档的那个性质。
时序图和流程图有什么区别?
时序图按参与者组织:列是服务或人,列与列之间的箭头是消息。流程图按步骤组织:方块是动作,不关心是谁做的。你的问题是「哪个服务调了哪个、按什么顺序」,画时序图。
一张图里放几个参与者合适?
限制来自可读性,不是工具。超过六七列,箭头就开始互相穿插,图也宽到要横向滚动。按阶段拆 —— 认证一张、履约一张 —— 别把整个请求生命周期塞进一张。这里的模板刻意都控制在五到六列。
支持导出成什么格式?
SVG、PNG,以及 Mermaid 源码本身。SVG 放多大都不糊,画宽图时有用;PNG 贴幻灯片和工单最省事;源码则可以跟代码一起提交,让图和别的东西一样走评审。