Go HTTP 客户端怎样设置分阶段超时

Go HTTP 客户端的“分阶段超时”不是给一个请求随手填几个数字，而是把请求生命周期拆开管理：连接建立由 DialContext 控制，TLS 握手由 TLSHandshakeTimeout 控制，等待响应头由 ResponseHeaderTimeout 控制，整个请求再由 http.Client.Timeout 或请求级 context 兜底。这样遇到超时日志时，能知道是连不上、握手慢、服务端迟迟不回头，还是业务截止时间已经到了。

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

先确定四类超时分别管什么

一个请求通常会经历 DNS/连接、TLS、发送请求、等待响应头、读取响应体几个阶段。Transport 能精确限制前四段，但它没有一个“读取完整响应体”的通用超时字段；读取阶段要用请求级 context、连接级 deadline，或业务自己的读取策略收口。

用 Transport 组合连接与响应头超时

下面的小客户端把连接建立、TLS 握手和响应头等待分开设置。http.Client.Timeout 设为 8 秒，是防止响应体读取或某个未覆盖的环节无限拖延；它不是把前面的阶段参数替换掉。

package main

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

func newHTTPClient() *http.Client {
    dialer := &net.Dialer{
        Timeout:   2 * time.Second, // TCP 连接建立最多等待 2 秒
        KeepAlive: 30 * time.Second, // 复用连接的保活间隔，不等同于请求超时
    }
    transport := &http.Transport{
        DialContext:           dialer.DialContext, // 限制 DNS/连接阶段的拨号等待
        TLSClientConfig:        &tls.Config{MinVersion: tls.VersionTLS12}, // 只设安全下限
        TLSHandshakeTimeout:   3 * time.Second, // HTTPS 握手超过此时返回错误
        ResponseHeaderTimeout: 4 * time.Second, // 请求发出后等响应头最多 4 秒
        IdleConnTimeout:        30 * time.Second, // 空闲连接回收，避免池中连接长期占用
        MaxIdleConnsPerHost:    20, // 控制单个主机的空闲连接数量
    }
    return &http.Client{
        Transport: transport,
        Timeout:   8 * time.Second, // 覆盖整个请求，包含读取响应体
    }
}

func fetch(ctx context.Context, client *http.Client, url string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err) // URL 或方法不合法时直接返回
    }
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("请求失败: %w", err) // 保留原始错误，便于 errors.Is 判断
    }
    defer resp.Body.Close() // 无论读取是否成功都释放连接复用资格
    return nil
}

示例中的 KeepAlive 和 IdleConnTimeout 管的是连接池生命周期，不是一次请求的截止时间。连接池参数过小会增加建连，过大则可能留下大量空闲连接，不能用它们替代阶段超时。

用请求级 context 覆盖单次业务截止时间

同一个客户端可能服务多个业务：列表查询可以等 5 秒，健康探针可能只给 800 毫秒。此时不要复制多个 Transport，只给具体请求套一个更短的 context。请求级截止时间先到时，client.Do 会结束并把取消原因带回调用方。

func callWithDeadline(client *http.Client, url string) error {
    ctx, cancel := context.WithTimeout(context.Background(), 1200*time.Millisecond)
    defer cancel() // 无论成功或失败都释放计时器资源

    if err := fetch(ctx, client, url); err != nil {
        // 业务截止时间短于 Client.Timeout，先由 context 收口本次调用
        return fmt.Errorf("业务截止时间已到: %w", err)
    }
    return nil
}

实践中建议给预算留出层级：业务 context 最短，阶段超时居中，Client.Timeout 最长。例如业务是 1.2 秒，拨号 2 秒并不意味着它真的会等满 2 秒，因为 context 会先结束；总超时 8 秒则负责兜底。

按错误位置排查，而不是盲目调大数字

超时错误常常包着多层文字。可以先记录请求阶段、目标主机和耗时，再用 errors.Is 判断 context 是否结束。若只看到 “Client.Timeout exceeded”，说明总预算已耗尽；它不能单独证明是连接慢还是响应体慢，所以仍要结合阶段日志。

不要在重试循环里每次新建一个 Transport，也不要忘记关闭响应体。前者会破坏连接复用，后者会让池里的连接无法正常回收，最后表现为越来越多的连接超时。

常见问题

只设置 Client.Timeout 够不够？

能防止请求整体无限等待，但不能告诉你具体卡在连接、TLS、响应头还是响应体。需要定位问题时，补上 Transport 的阶段参数。

ResponseHeaderTimeout 会限制下载文件的全部时间吗？

不会。它只等待响应头；响应体读取仍由 Client.Timeout、context 或更细的读取控制负责。

为什么要复用 Transport？

Transport 内部维护连接池和复用状态。按请求创建会失去复用，还可能制造大量空闲连接；通常创建一个配置好的 Client 并在应用生命周期内复用。

验收时可以按“拨号 2 秒、TLS 3 秒、响应头 4 秒、总请求 8 秒、单次业务 1.2 秒”的层级制造慢服务测试。只要每个超时都能在预期层级先返回，并且响应体始终关闭，这套分阶段配置就具备可维护的边界。