HTTP客户端明明设置了超时，为什么仍会长时间占用连接

直接答案：设置超时，只代表 Go HTTP客户端会在某个等待边界到达后取消请求，并不保证你在连接池、服务端或系统监控里立刻看到连接消失。最常见的原因不是“超时失效”，而是超时覆盖范围理解错了、响应体没有在所有分支关闭、请求正在连接池里排队，或者把只管理空闲连接的 IdleConnTimeout 当成了活动请求超时。

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

一个典型现场是：客户端已经设置 Timeout: 10 * time.Second，日志也打印了超时错误，但监控中的连接数仍在高位，新的请求还偶尔卡住。此时先不要继续缩短一个总超时值，而应把“占用连接”拆成具体状态。

先把长时间占用拆成四种状态

一次请求至少会跨过 TCP 建连、TLS 握手、响应头等待和响应体读取。Client.Timeout 是整次请求的总预算，覆盖建连、重定向以及读取响应体；即使 Do 已经返回，计时器仍可能在响应体读取期间触发。阶段超时则只约束自己的边界，二者不能混为一谈。

• TCP 建连慢：应观察 net.Dialer.Timeout，而不是依赖更大的总超时兜底。
• TLS 握手慢：由 TLSHandshakeTimeout 控制。
• 服务端迟迟不返回响应头：由 ResponseHeaderTimeout 控制，它不限制响应体读取时间。
• 响应体持续慢读：受请求上下文或 Client.Timeout 影响；如果业务需要流式下载，就不该用过短的统一总时限。

只设置 Client.Timeout 的旧写法有什么风险

旧写法通常只给客户端一个总时限。它能防止请求无限等待，却无法告诉你究竟卡在建连、握手、响应头还是读取正文，也无法限制连接池里并发连接的总量。

client := &http.Client{
    // 总时限能兜底，但无法区分具体慢在哪个阶段。
    Timeout: 10 * time.Second,
}

另一个误区是继续调整 IdleConnTimeout。它只表示 keep-alive 连接空闲多久后关闭，不会中止一个正在传输的活动请求。把它从 90 秒改成 10 秒，通常解决不了慢接口占用连接的问题，反而可能增加重复建连和 TLS 握手。

把总时限与阶段时限分开配置

更稳妥的迁移方式是复用一个长期存活的 http.Client 和 http.Transport，同时给关键阶段设置独立边界。不要为每次请求新建 Transport，否则连接池无法复用。

dialer := &net.Dialer{
    // 限制 TCP 建连时间，并为长连接设置探活周期。
    Timeout:   2 * time.Second,
    KeepAlive: 30 * time.Second,
}

transport := http.DefaultTransport.(*http.Transport).Clone()
transport.DialContext = dialer.DialContext
transport.TLSHandshakeTimeout = 3 * time.Second
transport.ResponseHeaderTimeout = 4 * time.Second
transport.ExpectContinueTimeout = 1 * time.Second
transport.MaxIdleConns = 100
transport.MaxIdleConnsPerHost = 20
transport.MaxConnsPerHost = 50
transport.IdleConnTimeout = 90 * time.Second

client := &http.Client{
    // 总时限覆盖整次请求，并包含响应体读取阶段。
    Transport: transport,
    Timeout:   10 * time.Second,
}

MaxConnsPerHost 统计拨号中、活动中和空闲中的连接。当某个主机达到上限，后续拨号会等待。因此“请求卡住但没有新连接”也可能是连接池排队，而非网络建连超时。参数值应根据下游容量、请求耗时和实例并发量压测确定，示例数值不是通用答案。

响应体必须沿所有返回路径关闭

只要 client.Do 成功返回了 resp，调用方就应关闭 resp.Body。如果响应体既没有读完也没有关闭，默认 Transport 可能无法复用 HTTP/1.x keep-alive 连接。错误状态、JSON 解析失败和体积超限这些分支尤其容易漏掉。

func doJSON(ctx context.Context, client *http.Client, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, err
    }

    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    // Do 成功后立即登记关闭，覆盖后续所有返回分支。
    defer resp.Body.Close()

    // 限制最大读取量，避免异常响应长期消耗内存与连接。
    body, err := io.ReadAll(io.LimitReader(resp.Body, 1= 300 {
        return nil, fmt.Errorf("unexpected status: %s", resp.Status)
    }
    return body, nil
}

不必机械地在每个请求后都额外执行 io.Copy(io.Discard, resp.Body)。对于确定需要完整读取的小响应，正常读完即可；对于超大响应或提前终止的场景，应优先保护业务资源并关闭响应体，而不是为了复用连接无上限地排空数据。

如何判断是请求超时还是连接池排队

日志至少应记录目标主机、总耗时、是否拿到响应头、读取字节数、错误类型以及上下文是否超时。再配合连接池等待时间和活动连接数，才能把“超时”从一个模糊错误拆成可定位的阶段。

回归检查与上线清单

• 全局复用 http.Client 与 http.Transport，不在高频请求函数里重复创建。
• 为 TCP、TLS、响应头和整次请求分别设定预算，并确认流式接口不被统一总时限误杀。
• 检查所有 Do 成功后的返回分支，确保 resp.Body.Close() 一定执行。
• 用压测验证 MaxConnsPerHost，同时观察排队时间、下游容量和连接复用率。
• 分别模拟慢建连、慢响应头、慢响应体和异常状态码，确认日志能指出具体阶段。
• 上线后对比超时率、活动连接数、空闲连接数和下游错误率，而不是只看一个请求耗时指标。

常见问题

Client.Timeout 触发后，连接为什么没有立即从服务端消失？

客户端取消会终止自己的等待，但服务端、代理和系统连接状态的更新存在传播与回收过程。应结合客户端错误、服务端取消感知和连接池指标判断，而不是只看某一刻的连接数。

ResponseHeaderTimeout 能限制下载大文件的总时间吗？

不能。它只限制请求写完后等待响应头的时间，不覆盖读取响应体。大文件下载应使用请求上下文、业务级截止时间或速率控制。

把 IdleConnTimeout 调小能解决慢请求吗？

通常不能。它管理的是已经空闲的 keep-alive 连接，不会中止活动请求。过小还可能降低连接复用率，增加建连成本。

每次请求都新建一个 http.Client 更安全吗？

通常相反。Client 和 Transport 可并发复用，长期复用才能发挥连接池效果。需要隔离不同代理、证书或容量策略时，再按配置边界建立少量独立客户端。