响应头超时

Go 里看到“响应头超时”，先不要急着把所有超时都改成同一个数。Transport.ResponseHeaderTimeout 只负责请求完整写出后，等待服务端返回响应头的这段时间；http.Client.Timeout 则是连接、重定向、读取响应体在内的整个请求预算。前者适合限制服务端迟迟不开始响应，后者适合给一次调用设置总上限。

迁移旧代码时，最稳妥的组合是：复用一个配置好的 Transport，用 ResponseHeaderTimeout 卡住“等头部”，再用 Client.Timeout 兜住整个请求。这样日志里出现超时，才能知道是哪一层预算先耗尽。

本文结论：只想限制“等响应头”就看 ResponseHeaderTimeout；还要限制响应体读取和重定向，就必须配置 Client.Timeout，两者不是互相替代的开关。

响应头超时到底限制哪一段

ResponseHeaderTimeout 属于 http.Transport。它的起点不是创建请求，也不是一定从拨号开始，而是请求（包括请求体）已经写完之后；计时对象是服务端响应头是否在指定时间内到达。值为零表示不设置这一段的超时。

它不包含响应体读取。例如服务端很快返回了状态码和响应头，但随后用很慢的速度发送大 JSON，ResponseHeaderTimeout 不会因为这段慢速读取而单独触发。要限制这种情况，应该依赖 Client.Timeout 或请求上下文的整体截止时间。

ResponseHeaderTimeout 与 Client.Timeout 怎么分工

可以把两个字段看成不同层级的预算。ResponseHeaderTimeout 是传输层的阶段性限制，关注“服务端有没有及时开始回复”；Client.Timeout 是客户端总预算，覆盖连接建立、重定向和 Response.Body 的读取，而且在 Do 返回后仍可能中断后续读取。

因此，旧代码里只有 http.Get 或只有一个很大的 Client.Timeout 时，迁移重点不是简单替换字段，而是先决定要观察哪个边界。

把默认客户端迁移为分层配置

旧写法常把默认客户端当成永久配置，既看不到响应头阶段的单独上限，也容易让调用方忘记关闭响应体：

client := http.DefaultClient
resp, err := client.Get(url)
if err != nil {
    return err
}
defer resp.Body.Close() // 读取结束后关闭响应体，便于连接复用

可以把配置集中到构造函数中，并复用同一个 Transport。这里的时间值只是示例，实际项目应依据上游接口的正常响应分布设定：

func newHTTPClient() *http.Client {
    transport := &http.Transport{
        ResponseHeaderTimeout: 3 * time.Second, // 只限制请求写完后的响应头等待
    }

    return &http.Client{
        Transport: transport,
        Timeout:   8 * time.Second, // 覆盖连接、重定向和响应体读取的总预算
    }
}

func fetch(ctx context.Context, client *http.Client, endpoint string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
    if err != nil {
        return err // URL 或请求构造失败时不进入网络阶段
    }

    resp, err := client.Do(req)
    if err != nil {
        return err // 保留原始包装，交给上层统一判断超时来源
    }
    defer resp.Body.Close() // 无论后续读取是否成功，都释放响应体
    _, err = io.Copy(io.Discard, resp.Body)
    return err
}

不要每次调用都新建一个 Transport；标准库会在其中维护连接复用状态。若需要不同上游的不同预算，按上游复用少量命名客户端即可。

迁移后怎么判断超时来源

不要只匹配错误字符串。网络错误通常会被 url.Error 包装，可以用 errors.As 找到实现了 net.Error 的错误，再读取 Timeout()；如果业务还需要区分阶段，应同时记录请求阶段、客户端名称和配置预算。

func isTimeout(err error) bool {
    var netErr net.Error
    // errors.As 能穿过 url.Error 等包装，避免依赖易变化的错误文本。
    return errors.As(err, &netErr) && netErr.Timeout()
}

当请求在响应头还没到达时失败，通常优先检查 ResponseHeaderTimeout；当响应体读到一半才被中断，重点看 Client.Timeout 或请求上下文的截止时间。若总预算小于响应头预算，总预算会先结束，阶段性设置就不会按预期体现。

回归检查建议只保留三项：响应头慢时是否在阶段预算内结束；响应体慢时是否受总预算约束；正常响应是否关闭 Body 并复用连接。日志中记录“配置名 + 预算 + 请求阶段”，比记录一句“超时”更有用。

常见问题

只配置 ResponseHeaderTimeout 能限制下载时间吗？不能，它不覆盖响应体读取；需要总预算或上下文截止时间。

Client.Timeout 设置为零是什么意思？表示不设置 Client 层的整体请求时限，但不代表底层每个阶段都天然安全，仍应按调用场景配置必要的 Transport 或上下文边界。

两个值应该谁更大？通常总预算要覆盖连接、响应头和响应体等全部阶段，因此应结合接口的实际时延设计，而不是机械地只比较两个数字。

迁移清单

• 明确要限制的是响应头等待，还是整次请求。
• 在可复用的 Transport 上设置 ResponseHeaderTimeout。
• 在 http.Client 上设置整体 Timeout，并保留请求上下文取消能力。
• 统一用错误类型和请求阶段记录超时，不依赖字符串匹配。
• 每次成功拿到响应后关闭 Body，避免迁移后连接复用退化。