API · 排查路径

API 超时的分层排查

超时是一个症状,不是原因。需要区分客户端超时、网关超时、上游超时还是下游阻塞。

排查步骤

查看、判断、复查

  1. 01

    记录客户端取消机制(如 AbortController 或 SDK 超时)、负载均衡器、API 网关和下游服务的连接/读取超时。

  2. 02

    抓取失败请求的完整链路追踪(trace ID),确认超时应在哪一层首先发生。

  3. 03

    检查下游依赖(数据库、外部 API)的 p99 延迟和连接池状态,排除连接阻塞或慢查询。

  4. 04

    根据真实延迟分布和重试策略安排超时层级,避免各层在同一时刻中断或重复重试。

跟着示例核对

示例内容用于说明方法,非本站探测记录。复核于 2026-09-06。

模拟环境:同一天 UTC+08:00,同一浏览器和 release-example,GET /api/example
09:00 对照样本:200,150 ms
09:05 失败 A:客户端在 3000 ms 主动 abort;未取得 HTTP 状态;服务端记录未知
09:10 失败 B:收到 HTTP 504;网关日志记录等待上游超时;应用和数据库记录尚未取得

怎样解释结果

对照样本只证明那一次请求成功。失败 A 说明客户端观察到中止,需记录 abort 的触发原因,不能推断服务端已经停止执行。失败 B 的 504 表示网关或代理未及时得到所需上游响应;数据库慢、连接耗尽等仍是待验证假设。两种失败不能合并成同一个根因。

不符合预期时

按时间、版本和经过审查的请求关联号查入口与上游日志;找不到记录时明确写未知。核对用户取消、客户端定时器、网关超时和下游延迟,不要只延长超时掩盖问题。写入请求需先核对执行结果及幂等策略,避免盲目重试产生重复写入。

修改后复查

在受控环境复用同一路径、版本与请求条件,每次只改一个已确认的问题,记录状态、耗时、中止原因与上游记录。一次成功不证明所有请求已恢复;观察代表性窗口,并将仍无法复现的条件写入复现记录。