Go HTTP 超时判断客户端超时发生在哪一层的定位方法

Go HTTP 超时排查最容易误判的地方，是把所有 context deadline exceeded 或 timeout 都归为“服务端慢”。实际一次请求可能卡在 DNS、TCP 建连、TLS 握手、写请求、等待响应头，或者已经拿到响应后的 Body 读取。定位时先看错误链，再用阶段时间戳对照 Transport 参数；只看错误字符串通常只能说明“超时了”，不能说明“在哪一层超时”。

先从错误链确认超时类型

Client.Do 返回的错误通常包在 *url.Error 中，官方文档明确说明它的 Timeout() 会反映请求是否超时。调用方应保留原始错误链，用 errors.As 取出 net.Error，再分别检查上下文是否到期。这样既能识别 DNS 或连接层超时，也不会把所有网络失败都当成超时。

// 这段代码只负责分类错误，不把错误文本当作稳定协议。
var netErr net.Error
switch {
case errors.Is(err, context.DeadlineExceeded):
    // 上下文预算先到期，优先检查调用方传入的 deadline。
    log.Printf("stage=context deadline err=%v", err)
case errors.As(err, &netErr) && netErr.Timeout():
    // DNS、拨号、TLS 或读写阶段可能落入这里，继续结合阶段日志判断。
    log.Printf("stage=network timeout temporary=%v err=%v", netErr.Temporary(), err)
default:
    // 连接被关闭、协议错误等情况，不要贴上 timeout 标签。
    log.Printf("stage=non-timeout err=%v", err)
}

如果只配置了 Client.Timeout，它超时后也可能表现为网络超时样式，但仍无法单独指出具体阶段。因此这一步的结论应写成“错误属于超时”，而不是“确定是响应头超时”。

把 Client 总超时映射到 HTTP 阶段

可以先建立一张排查对照表。参数值不是越多越好；它们应该表达不同阶段的预算，外层总预算还要大于内部阶段预算，否则所有问题都会被外层提前截断。

用 httptrace 记录真正的阶段边界

当日志只显示“请求耗时 5 秒”时，net/http/httptrace 能补上关键边界：DNS 开始与结束、连接建立、复用连接、请求写完、收到首字节。回调只做观测，不改变请求逻辑，适合给一次疑难请求临时加 trace_id。

// 用相对时间记录请求阶段，便于和 Client/Transport 的预算对照。
started := time.Now()
stamp := func(name string) { log.Printf("trace=%s elapsed=%s", name, time.Since(started)) }
trace := &httptrace.ClientTrace{
    DNSStart: func(httptrace.DNSStartInfo) { stamp("dns-start") },
    DNSDone: func(httptrace.DNSDoneInfo) { stamp("dns-done") },
    ConnectStart: func(_, _ string) { stamp("connect-start") },
    ConnectDone: func(_, _, _ string, _ error) { stamp("connect-done") },
    GotConn: func(httptrace.GotConnInfo) { stamp("got-conn") },
    WroteRequest: func(httptrace.WroteRequestInfo) { stamp("wrote-request") },
    GotFirstResponseByte: func() { stamp("first-response-byte") },
}
req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
resp, err := client.Do(req)
if resp != nil {
    // 无论后续读体是否成功，都要释放响应体和连接复用机会。
    defer resp.Body.Close()
}

例如 connect-start 到 connect-done 很长，优先查拨号与 DNS；wrote-request 到 first-response-byte 很长，才把重点放到服务端处理或 ResponseHeaderTimeout。如果首字节已经到达，之后卡在 io.ReadAll，问题属于响应体传输或读取节奏，不是响应头等待。

已有响应后的读体超时要单独记录

Client.Timeout 的计时器会覆盖读取响应体。于是 Do 可能已经返回了响应，真正的错误却出现在后续 Body.Read。排查时至少记录状态码、已读字节数、首字节时间和读完时间；不要因为状态码是 200 就认为业务数据已经完整。

• 外层上下文先到期：检查调用方 deadline 是否过短，或重试是否复用了已取消的 context。
• 响应头阶段超时：检查服务端排队、代理转发和 ResponseHeaderTimeout。
• 读体阶段超时：检查服务端是否持续输出、网络抖动、Body 消费方式，以及是否设置了过小的 Client.Timeout。

生产排查可以把阶段名、耗时、目标主机、是否复用连接和最终错误类型写入同一条日志。定位出层级后再调参数：内部预算解决具体阶段，外层预算保护整体请求，二者不要靠反复加大数字来掩盖根因。

相关问题

为什么 net.Error.Timeout() 不能直接告诉我是哪一层？

它只表达错误是否具有超时语义，DNS、拨号、TLS、响应头和读体都可能实现该接口。必须结合 httptrace 时间点和当前 Transport 配置。

ResponseHeaderTimeout 会限制响应体下载时间吗？

不会。它只限制请求完整写出后等待响应头的时间；响应体仍需由上下文、Client 总预算或底层读写错误来约束。

拿到响应后还要关闭 Body 吗？

要。无论读体成功还是失败，都应关闭 Response.Body，否则连接复用和资源回收会受到影响。