Go http.Client超时只覆盖请求阶段的时间边界

我排查 Go HTTP 慢请求时，最容易误判的一点是把 http.Client.Timeout 当成“只等响应头的时间”。实际上，它约束的是一次完整的 HTTP 交换：拨号、TLS 握手、重定向、响应头以及读取 Response.Body 都在范围内；Do 调用前后的业务计算不在这个计时器里。想定位到底卡在哪一段，应该让 Transport 的阶段参数负责给出证据，再用 Client.Timeout 做总预算兜底。

官方文档：https://pkg.go.dev/net/http

先分清Client.Timeout到底覆盖哪一段

可以把一次 client.Do(req) 想成一条连续链路：建立连接、TLS握手、发送请求、等待响应头、读取响应体。Client.Timeout从发起这次交换开始计时，遇到重定向时也不会自动重置；即使 Do 已经返回，读取响应体仍可能被同一个总计时器打断。

所以，响应头很快并不代表请求一定不会超时：服务端如果持续输出大响应体，读取阶段照样会消耗总预算。反过来，Client.Timeout也不会自动包住序列化、业务计算或调用方在 Do 之前排队的时间；这些要交给业务层的 context 或队列超时。

用Transport超时定位卡住的具体阶段

Transport的参数是阶段性证据，不能简单当作几个独立的“总超时”。常见边界如下：

排查时先看现象：拨号失败优先检查网络和 Dialer.Timeout；连接已建立但首字节迟迟不来，检查 ResponseHeaderTimeout；响应头到了、下载仍拖长，则要看总预算、响应体大小和读取策略。不要因为看见 context deadline exceeded 就直接把所有数字加大。

把Client与Transport组合成可解释的配置

下面的配置把“总预算”和“阶段定位”放在一起。阶段值应小于总预算，但还要给DNS、连接复用、重定向和响应体读取留余量：

transport := &http.Transport{
	// 连接建立单独设上限，避免拨号长期占用请求预算。
	DialContext: (&net.Dialer{Timeout: 2 * time.Second}).DialContext,
	// TLS慢只归因于握手阶段，不把它误判成服务端响应慢。
	TLSHandshakeTimeout: 2 * time.Second,
	// 请求写完后，限定等待响应头的时间；不限制响应体读取。
	ResponseHeaderTimeout: 3 * time.Second,
	// 只有使用Expect: 100-continue时，这个等待才会发挥作用。
	ExpectContinueTimeout: 1 * time.Second,
}

client := &http.Client{
	// 总预算覆盖拨号、握手、重定向、响应头和Response.Body读取。
	Timeout:   8 * time.Second,
	Transport: transport,
}

resp, err := client.Do(req)
if err != nil {
	// 记录阶段信息时保留原始错误，便于区分总预算与阶段预算。
	return fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close() // 无论读取是否成功，都释放响应体和连接复用机会。

body, err := io.ReadAll(resp.Body)
if err != nil {
	// 总预算可能在读取响应体期间到期，这里仍要保留错误上下文。
	return fmt.Errorf("read response body: %w", err)
}
_ = body

这套写法的重点不是数字本身，而是每个数字都能回答一个问题：连接慢看哪里、首字节慢看哪里、下载慢由谁兜底。真实项目还应通过请求级 context.WithTimeout 给业务调用设上限，并根据重试策略重新计算总预算，避免一次重试把上游SLA吃光。

用边界清单反向检查生产请求

上线前可以按这张清单复核：

• 是否明确区分“建立连接慢”“响应头慢”和“响应体慢”？
• 是否在成功拿到响应后始终关闭 Response.Body？
• 是否知道重定向也消耗 Client.Timeout，没有把它当成每跳独立预算？
• 是否把调用前排队、JSON解码和业务处理纳入了业务context，而不是期待Client替你计时？
• 是否记录了阶段参数和原始错误，方便下一次从现象反推原因？

一个实用判断是：Client.Timeout解决“这次HTTP交换最多允许多久”，Transport解决“哪一段网络阶段不该等这么久”，业务 context解决“整个业务动作最多允许多久”。三者边界清楚，超时日志才有可操作性。

相关问题

ResponseHeaderTimeout会限制下载大文件吗？

不会。它只限制等待响应头；响应头已经到达后，读取响应体仍由总预算、业务context和读取策略共同决定。

Client.Timeout设成0代表永不超时吗？

代表Client层不设置总超时，但并不等于网络永远安全。仍应为拨号、TLS、响应头和业务调用设置可解释的边界。

为什么Do返回成功后读Body还会报超时？

因为Client总计时器会持续到响应体读取结束；响应头到达只说明交换完成了一部分。