Go HTTP 客户端超时为什么没有覆盖 DNS 和连接阶段

很多 Go 程序把 ResponseHeaderTimeout 配成 3 秒，却发现 DNS 卡住或新连接建立很慢时，请求仍然没有按预期结束。原因不是 Go 忽略了网络阶段，而是这个字段的边界本来就从“请求已经写完，等待响应头”开始。

如果要给一次 HTTP 调用设总时限，优先使用 http.Client.Timeout 或请求级 context；如果还要分别限制 DNS/TCP、TLS 握手和响应头，再给 Transport 配阶段超时。只配 ResponseHeaderTimeout 不会覆盖 DNS 和建连。

先看清三种超时的边界

一条 HTTPS 请求可以经历 DNS 解析、TCP 建连、TLS 握手、发送请求、等待响应头、持续读取响应体。它们不是同一个计时器。http.Client.Timeout 是一次请求的总预算，官方文档明确说明它包含连接、重定向和响应体读取；计时器在返回响应后仍可能因为读取 Response.Body 而触发。

相反，Transport.ResponseHeaderTimeout 只计算请求（包括请求体）完整写出之后，等待服务端响应头的时间，而且不包含读取响应体。TLSHandshakeTimeout 只负责 TLS 握手。net.Dialer.Timeout 负责拨号，Go 的 net 文档说明必要时包含名称解析。因此，下面两种配置的含义完全不同：

为什么只配 ResponseHeaderTimeout 会漏掉前置阶段

Transport 先尝试从空闲连接池取连接。没有可复用连接时，才进入拨号；HTTPS 还要进行 TLS 握手。只有请求写完，ResponseHeaderTimeout 的计时才有意义。也就是说，它更像“服务端迟迟不回响应头”的保护线，而不是整条网络链路的总闸。

要覆盖完整生命周期，最小配置可以很简单：

package main

import (
	"fmt"
	"io"
	"net/http"
	"time"
)

func fetch(url string) error {
	client := &http.Client{Timeout: 8 * time.Second} // 总预算覆盖建连、响应头和响应体
	resp, err := client.Get(url)
	if err != nil {
		return fmt.Errorf("请求失败: %w", err) // 保留 url.Error 便于上层判断超时
	}
	defer resp.Body.Close() // 读取结束后关闭，避免影响连接复用
	_, err = io.Copy(io.Discard, resp.Body) // 总预算也约束响应体读取
	return err
}

这个写法不需要手动把 DNS、TCP 和 TLS 分别拼起来。若请求在总时限内复用了已有连接，也不会重新执行 DNS 或握手；这不是超时失效，而是这些阶段没有发生。

需要分阶段控制时怎么组合

当日志需要区分“解析慢”“连接不上”和“服务端迟迟不回头”时，再把拨号器交给 Transport，并保留一个更大的总预算：

package main

import (
	"context"
	"fmt"
	"io"
	"net"
	"net/http"
	"time"
)

func fetchWithPhases(ctx context.Context, url string) error {
	dialer := &net.Dialer{
		Timeout:   3 * time.Second,  // 限制 DNS（需要时）和 TCP 拨号
		KeepAlive: 30 * time.Second, // 只控制连接保活，不是请求总时限
	}
	transport := &http.Transport{
		DialContext:           dialer.DialContext, // 把拨号阶段交给 net.Dialer
		TLSHandshakeTimeout:   3 * time.Second,   // 只限制 TLS 握手
		ResponseHeaderTimeout: 5 * time.Second,   // 请求写完后等待响应头
	}
	client := &http.Client{
		Transport: transport,
		Timeout:   10 * time.Second, // 防止各阶段预算叠加后整次请求失控
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return fmt.Errorf("创建请求失败: %w", err)
	}
	resp, err := client.Do(req)
	if err != nil {
		return fmt.Errorf("阶段请求失败: %w", err)
	}
	defer resp.Body.Close() // 无论后续读取是否成功都释放响应体
	_, err = io.Copy(io.Discard, resp.Body)
	return err
}

这里的 ctx 适合承接上游取消信号；请求 context 控制获取连接、发送请求和读取响应的完整生命周期。Client.Timeout 与它同时存在时，较早到期者生效，实际项目应让两者的关系有明确的预算意图，不要随意堆叠。

从错误信息判断到底是哪一段超时

调用返回的错误通常被 *url.Error 包裹。可以先用 errors.As 取出 net.Error，再看 Timeout()；错误文本中出现 “dial tcp” 往往指向拨号阶段，TLS 错误则说明已经走到握手附近，响应头超时通常会出现在请求已经建立之后。文本只能辅助定位，不能替代阶段日志。

var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
	// 超时属性来自底层错误；仍需结合请求是否复用连接来判断阶段
	log.Printf("网络请求超时: %v", err)
}

排查时可按这张清单复核：第一，是否只配置了响应头超时；第二，Transport 是否真的使用了自定义 DialContext；第三，本次请求是否复用了空闲连接；第四，是否读取并关闭了响应体；第五，上游 context 是否比客户端总预算更早取消。

小结与常见问题

“没有覆盖 DNS 和连接阶段”通常是配置字段选错，而不是 http.Client 做不到。简单调用用 Client.Timeout 兜住总生命周期；需要可观测的阶段边界时，再用 net.Dialer.Timeout、TLSHandshakeTimeout 和 ResponseHeaderTimeout 分工，并保留总预算。

http.Client.Timeout 会自动设置 net.Dialer.Timeout 吗？

不会修改你能看到的 Dialer.Timeout 字段，但客户端会用总预算取消底层请求，所以新连接阶段仍受总时限约束。若要单独表达拨号预算，应显式配置 DialContext。

ResponseHeaderTimeout 能限制下载响应体吗？

不能。它只等响应头；下载过程需要总客户端超时、请求 context，或针对业务流式读取设计更细的取消策略。

参考资料：Go net/http Client 文档、Go net/http Transport 文档、Go net.Dialer 文档、Go Request context 文档。