Go http.Client 超时到底控制哪一段：请求级 Timeout 与 Transport 超时的分工

线上调用一个响应很慢的接口时，最容易误判的是“连接超时”。实际上，Go 的 http.Client.Timeout 从建立连接、跟随重定向到读取 Response.Body 都可能计时；Transport.ResponseHeaderTimeout 则只管请求写完后等待响应头的这段时间。两者解决的是不同层次的问题。

需要限制一次调用的总生命周期，就设置 Client.Timeout；只想防止服务端迟迟不返回响应头，再配置 Transport.ResponseHeaderTimeout。如果响应头已经到了但正文很慢，前者仍可能触发，后者不会替你限制正文读取。

先把一次 HTTP 调用拆成四段

一次普通的 Client.Do 可以按排查顺序拆成：连接建立、请求发送、等待响应头、读取 Response.Body。连接可能复用，也可能重新拨号；请求体较大时，发送本身也可能拖长。响应头到达并不表示业务数据已经全部读完。

这四段不是四个互相独立的计时器。Client.Timeout 更像包住整个调用的外层预算，而 ResponseHeaderTimeout 是 Transport 内部针对“等头部”的局部限制。

Client.Timeout 为什么会影响 Response.Body

看一个最小客户端。代码刻意把超时放在 Client 上，方便观察总预算如何跨过 Client.Do 延伸到后续的 Response.Body 读取。

client := &http.Client{
    Timeout: 3 * time.Second,
}

resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

_, err = io.Copy(io.Discard, resp.Body)
return err

Client.Do 成功返回后，计时并不自动结束；官方文档明确说明，计时器仍会在读取响应体时运行。因此服务器可以很快发回响应头，却在正文阶段持续停顿，最终错误仍可能表现为客户端总超时。

这张图中的 Client.Do、Response.Body 和 Client.Timeout 都对应上面的代码节点。排查时如果日志只记录了收到响应头，就不能据此断定整个请求已经完成。

ResponseHeaderTimeout 只截断等待响应头

如果问题是上游已经收到请求，却长时间不吐出响应头，可以把预算放到 Transport：

transport := &http.Transport{
    ResponseHeaderTimeout: 2 * time.Second,
}
client := &http.Client{
    Transport: transport,
}

这个字段的语义是：request body（请求体）完整写出后，等待服务器 response headers（响应头）的最长时间。响应头一旦到达，Transport 的这一项就不再负责限制正文读取。正文还需要多长时间，应由 Client.Timeout 或请求上下文的截止时间来决定。

第二张图只展示 Transport.ResponseHeaderTimeout、请求发送和响应头三个正文节点。它不能被理解成“整个 HTTP 请求的超时”，这正是配置名称相同却行为不同的地方。

生产配置怎么组合才不互相打架

更稳妥的组合是：用 Client.Timeout 作为一次调用的总预算，再用 ResponseHeaderTimeout 给“服务端迟迟不开始响应”设置更短的局部预算。例如总预算 10 秒、响应头预算 2 秒，意味着头部阶段不能独占全部时间，但头部及时到达后仍可在剩余预算内读取正文。

不要把两个值设置成完全相同后就认为语义重复。它们的计时起点和覆盖范围不同；真正的约束关系还会受到连接复用、TLS 握手、重定向和响应体大小影响。

如果调用方本身已经有请求级截止时间，优先让 context.WithTimeout 表达这次业务操作的预算，再把 Transport 的响应头保护作为连接层的补充。出现错误时记录 url.Error、errors.Is(err, context.DeadlineExceeded) 和请求阶段，别只打印一句“timeout”。

三个容易踩坑的判断

收到响应头就代表请求成功了吗

不代表。状态码和响应头只说明服务器开始返回响应；正文读取仍可能失败。尤其是流式响应，Response.Body 的生命周期可能远长于响应头等待。

设置了 ResponseHeaderTimeout 就不用关闭 Body 吗

仍然要关闭。Go 文档建议调用方在完成读取后关闭 Response.Body；读到 EOF 再关闭通常更有利于底层连接复用。

Client.Timeout 越大越安全吗

不一定。过大的总预算会让卡住的请求占据连接、goroutine 或上游并发额度。预算应从业务允许的端到端时延倒推，再用日志确认到底卡在头部还是正文。

最后用一张检查清单收口

• 需要限制整次调用：检查 Client.Timeout 或请求上下文。
• 需要限制等待响应头：检查 Transport.ResponseHeaderTimeout。
• 响应已返回仍报超时：检查 Response.Body 的读取速度和总预算剩余时间。
• 每次拿到非空响应：确认调用方最终执行了 Response.Body.Close。

把超时看成“请求生命周期上的边界”，比把所有错误都归为连接问题更可靠。先确认卡在哪一段，再决定是收紧总预算、缩短响应头等待，还是处理正文消费速度。

相关问题

Transport 的 DialContext 超时和 Client.Timeout 冲突吗

它们可以叠加：拨号超时是连接建立阶段的局部上限，Client.Timeout 是更外层的请求总预算，先到哪一个就会先结束。

为什么只读取一部分 Body 也要关闭

关闭可以释放响应体相关资源；如果希望复用连接，通常还应按业务需要把正文读到 EOF，再关闭。