接口调用流程图怎么画

调接口出问题时，光看日志往往看不出卡在哪一步，很多人想画张流程图又不知道从哪切。这篇给一套可落地的做法：先按请求生命周期把链路拆成几段，再确定节点粒度与分支画法，最后补上超时、并发、降级、日志这些工程细节，让图既能当文档也能当排错工具。

调接口出问题时，光看日志经常看不出卡在哪一步，于是很多人想画张流程图。但真动手就卡住了：从哪切？切多细？画完发现比日志还难读。这篇给一套能直接用的做法，先按请求生命周期拆链路，再定节点粒度和分支画法，最后把超时、并发、降级、日志这些工程细节补到图上。

核心思路是：流程图不是画给人看的装饰品，而是一张排错索引。图上每个节点都应该能对上一段日志、一个状态码或一个耗时数字。做不到这一点，说明粒度错了，要么太粗漏掉关键段，要么太细把图变成了代码翻译。

先想清楚这张图给谁看

同样是接口调用流程图，给自己排错用、给同事交接用、给非技术方看，画法完全不同。排错版要细到字段名和状态码，交接版要标清模块边界和负责人，对外版只保留业务节点。开画之前先写一句目标，比如「线上 5xx 时能一眼定位是哪一段」，后面所有节点取舍都按这句话判断。

把一次调用拆成哪几段

按请求生命周期切最稳，从客户端到服务端再回到客户端，每一段都问两个问题：这里会不会失败？失败时有什么信号？答不上来的段要么合并，要么说明你还没搞清楚它的行为。走中转或跨境的链路，代理和网关必须单独成节点，别合并进「网络」一个框，否则排错时根本不知道卡在哪。

• 应用发起：参数校验、组装上下文，信号是入参日志
• 拼装请求体：字段映射、序列化，信号是序列化异常
• 鉴权与签名：token 有效期、签名算法，信号是 401/403
• 网络出口：代理、网关、DNS、证书，信号是连接超时
• 服务端排队：并发位、限流，信号是排队耗时或 429
• 模型推理与回包：首字延迟、流式中断，信号是首 token 时间

重试和降级不要画在主链路上，单独拉一条支线。主链路只画一次正常调用，支线画「失败后走哪条路、退避几次、什么时候放弃」。这样图不会因为分支交叉变成一团乱麻。想了解不同中转站在这些环节上的差异，可以到 /sites 看各家的接入说明。

节点粒度与连线规范

一个节点只做一件事，用动词开头命名，比如「校验 token」而不是「鉴权相关」。节点里出现「等等」「其他」「相关」这类词，基本说明该拆了。判断分支用菱形还是直接标条件，按读者定：排错图用条件标注更省地方，交接图用菱形更直观。关键是给每个节点编号，日志里的报错、文档里的说明、图上的编号三者对得上，别人拿着报错就能跳到节点。

1. 列节点先把所有动作写成一列，动词开头，写完回头合并同类项，验证：能不能一句话说清每个节点在做什么
2. 连主线只连正常路径，箭头方向统一从左到右或从上到下，验证：有没有回头箭头混进主线
3. 挂支线把重试、降级、兜底挂到对应节点下方，验证：一条支线能不能单独讲清楚
4. 标编号给节点编号并写进日志字段，验证：随便拿一条报错能不能顺图找到节点
5. 出两版精简到 5 个节点贴 README，详细版放文档当排错索引，验证：两版节点名是否一致

图上必须补的几个工程标注

只有方框和箭头的流程图，排错时用不上。真正有用的是节点旁边的标注：超时分几档、并发位多少、限流怎么退避、失败后切哪条路、这个节点该打哪些日志字段。这些标注让图同时具备文档和埋点清单两个功能。分档口径和退避策略没有统一标准，可以到 /tools/speed-test 看当前链路实测情况再定。

三档超时

连接、读取、整体分开标，避免只写一个笼统的超时值

并发位

节点旁标能同时跑多少请求，超过时是排队还是直接拒

退避方式

固定间隔还是指数退避，退几次后放弃

降级分支

主链路失败后切备用源还是返回兜底结果，画成分支

日志字段

请求 id、模型名、耗时、状态码、token 数，逐节点列出

画完怎么验证这张图是对的

画完先别急着发出去，拿三条真实报错反推：顺着图能不能走到出问题的节点？走不到说明拆得不对，要么漏了段，要么分支画反了。再用一条正常请求走一遍全图，重点检查有没有隐形步骤被吞掉，比如 DNS 解析、证书校验、序列化格式转换，这些平时不出问题，一出就是难查的那类。

• 反推测试：拿近期三条报错，看能否顺图定位到节点
• 正走测试：正常请求走全图，检查有无漏掉隐形步骤
• 改动同步：接口改了立刻改图，图和代码一起 review
• 版本控制：图放进仓库，别只存在本地白板或截图里
• 定期核对：链路涉及第三方时，到 /price-watch 核对当时的行为与口径

图过期比没有图更麻烦，因为它会误导人。把图当成代码的一部分来维护，改动接口时同步改图，比事后补一张漂亮的大图省事得多。