Go http.Transport 怎样设置 ResponseHeaderTimeout 防止请求久等

Go HTTP 客户端遇到“请求已经发出，但一直等不到响应头”时，最直接的参数是 http.Transport.ResponseHeaderTimeout。它只限制请求体完全写出后等待响应头的时间，不包含后续读取响应体的时间；如果还要限制整个请求，就要同时设置 http.Client.Timeout。

官方地址：https://pkg.go.dev/net/http

这篇文章只讨论客户端分阶段超时和 Transport 复用，不把连接建立超时、TLS 握手超时、响应体读取超时混成一个概念。

先定位：到底是哪一段在等待

在高并发服务里，我更愿意先画出一次请求的边界，再决定参数。一个请求大致经过：建立连接、TLS 握手、写入请求、等待响应头、读取响应体。ResponseHeaderTimeout 位于“写完请求到拿到响应头”这一段；服务端已经返回响应头后，即使响应体读取很慢，它也不会单独中断这段读取。

因此，“响应头慢”和“连接不上”不是同一种故障。前者适合用 ResponseHeaderTimeout，后者通常要看 net.Dialer.Timeout 或 TLSHandshakeTimeout。如果只设置一个很小的 Client.Timeout，虽然能兜底，但定位信息会变差。

在复用的 Transport 上设置响应头超时

官方文档建议复用 Client 和 Transport，因为 Transport 内部会缓存连接。实际项目中不要每次请求都创建一个新 Transport，否则连接复用、空闲连接管理和参数统一都会变得不可控。

package main

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

func newHTTPClient() *http.Client {
    // 把连接建立阶段和响应头等待阶段拆开，便于分别定位慢点。
    dialer := &net.Dialer{Timeout: 3 * time.Second}
    transport := &http.Transport{
        DialContext:           dialer.DialContext,
        TLSHandshakeTimeout:   5 * time.Second,
        ResponseHeaderTimeout: 8 * time.Second,
        IdleConnTimeout:       60 * time.Second,
        MaxIdleConnsPerHost:   16,
    }

    return &http.Client{
        // 这是整个请求的最后一道上限，包含连接、重定向和读取响应体。
        Transport: transport,
        Timeout:   20 * time.Second,
    }
}

func fetch(ctx context.Context, client *http.Client, url string) error {
    // 请求级 Context 可以提前取消，但不能替代 Transport 的阶段配置。
    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 {
        // 阶段超时通常会包装在 *url.Error 中，保留原错误便于上层判断。
        return fmt.Errorf("请求失败: %w", err)
    }
    defer resp.Body.Close() // 无论后续解析是否出错，都要释放响应体。
    return nil
}

这段配置有两个重点：一是 ResponseHeaderTimeout 从请求内容写完后开始计算，二是 Client.Timeout 仍然存在，避免响应头及时返回但响应体无限拖延。IdleConnTimeout 只管空闲连接的存活时间，不是响应超时。

不要把四种超时混成一个参数

可以把它们按职责记成一张小表：

如果业务请求本身上传大文件，响应头超时不会覆盖上传请求体的写入时间；如果服务端很快给出响应头、却慢慢输出大响应，应该检查整体超时和读取策略，而不是继续缩短 ResponseHeaderTimeout。

上线时怎样判断数值是否合适

我通常先按上游接口的正常响应头分位数设定初始值，再给少量余量，而不是直接套一个很大的秒数。发生超时后记录目标主机、请求类型、阶段错误和业务调用名；不要只记录“请求失败”，否则无法区分 DNS、TCP、TLS、响应头和响应体阶段。

还要保持 Transport 的生命周期稳定：共享一个配置好的 Client，按请求使用 Context 做取消；拿到 Response 后及时关闭 Body，避免连接复用受到影响。若需要主动清理空闲连接，可以调用 Transport 的 CloseIdleConnections，但它不是响应头超时的替代品。

常见问题

ResponseHeaderTimeout 为零是不是没有任何超时？

它表示该阶段不设置独立上限，但不代表 Client.Timeout、Context 或其它网络层超时不存在。最终是否会一直等待，要看整套配置。

设置了 Client.Timeout，还需要 ResponseHeaderTimeout 吗？

如果只关心总耗时，一个整体上限可以工作；如果要区分“连接不上”和“上游迟迟不回响应头”，分阶段配置更容易解释错误和调整容量。

总结

ResponseHeaderTimeout 解决的是“请求写完后，响应头迟迟不来”的边界问题。把它放在复用的 http.Transport 上，并与连接、TLS 和 Client.Timeout 配合，既能限制慢上游，又能保留故障定位的层次。最重要的是先确认等待发生在哪个阶段，再设置对应参数。