Go http.Transport空闲连接失效时的回收参数配置

Go 的 http.Transport 会缓存已经建立过的连接，下一次请求可能直接复用它。遇到“空闲一段时间后第一次请求失败”时，优先把客户端的 IdleConnTimeout 设置为不大于服务端 keep-alive 时长，并同时检查 MaxIdleConnsPerHost。这个参数只回收客户端连接池里处于 idle 状态的 HTTP/1.x 连接，不能阻止服务端主动关闭连接，也不等同于请求超时。

先分清空闲回收和连接失效

连接从一次请求结束到下一次请求开始，处于连接池的 idle 状态。IdleConnTimeout 从连接变为空闲时计时，超过时长后由 Transport 回收。请求正在使用的连接不受它影响，正在拨号的连接也不受它直接控制。

另一种常见情况是服务端、代理或负载均衡器先关闭了空闲连接。客户端连接池里可能还保留着这条连接，下一次复用时才暴露出 EOF、broken pipe 或连接重置。此时把客户端超时调得更长并不能修复问题，应该让客户端的空闲保留时间短于对端的空闲阈值。

把回收参数放进可复用 Transport

下面的配置适合一个请求会反复访问同一组 API 主机的客户端。数值不是通用答案：示例假设服务端约 60 秒清理空闲连接，因此客户端预留一点提前量。

package main

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

func newHTTPClient() *http.Client {
    transport := &http.Transport{
        // 比服务端的空闲清理阈值略短，减少复用已被对端关闭的连接。
        IdleConnTimeout: 45 * time.Second,
        // 限制所有主机的 idle 连接总量，避免访问大量主机时连接池膨胀。
        MaxIdleConns: 100,
        // 控制同一主机保留的 idle 连接数，不是并发请求数上限。
        MaxIdleConnsPerHost: 10,
    }
    return &http.Client{
        // Transport 应复用，避免每次请求都新建连接池和 TLS 状态。
        Transport: transport,
        // 只限制等待响应头，不替代请求上下文的整体截止时间。
        ResponseHeaderTimeout: 8 * time.Second,
    }
}

func main() {
    client := newHTTPClient()
    req, err := http.NewRequest(http.MethodGet, "https://api.example.com/health", nil)
    if err != nil {
        // 构造请求失败时立即返回，避免把无效请求送入 Transport。
        panic(err)
    }
    resp, err := client.Do(req)
    if err != nil {
        // 生产代码应记录 host、错误类型和请求间隔，辅助区分连接失效原因。
        fmt.Println("request failed:", err)
        return
    }
    // 响应体必须关闭，连接才有机会回到 Transport 的空闲池。
    defer resp.Body.Close()
    fmt.Println("status:", resp.StatusCode)
}

关键点是把 Transport 和 Client 放在长生命周期对象中。若把它们写在每次调用的函数里，连接复用几乎失去意义；若只设置 MaxIdleConnsPerHost 而不设置 IdleConnTimeout，对端较短的 keep-alive 策略仍可能造成失效连接复用。

按现象定位是哪一个参数在起作用

需要主动清空连接池时，可以调用 client.CloseIdleConnections()；它只关闭已经空闲的连接，不会打断正在使用的连接。这个动作适合配置热更新或下游网络切换，不适合作为每个请求结束后的固定动作。

上线前的参数检查清单

先向服务端确认 keep-alive、代理和负载均衡器的空闲策略，再按最短阈值减去缓冲设置 IdleConnTimeout。接着确认所有成功响应都会关闭 Body，并记录请求间隔、目标主机和网络错误类型。若服务端使用 HTTP/2，连接复用和空闲管理由 HTTP/2 实现参与，不能简单套用 HTTP/1.x 连接池的观察方式。

不要一看到偶发连接错误就设置 DisableKeepAlives: true。它会让每条连接只服务一个 HTTP 请求，通常增加 TCP/TLS 建连成本。只有下游明确不接受长连接、代理行为无法协调，或短生命周期命令行程序确实不需要复用时，才考虑关闭。

常见问题

IdleConnTimeout 为零是不是永不关闭？

对 Transport 自己的空闲计时来说，零值表示不限制，但服务端、代理或系统仍可能主动关闭连接，所以它不代表连接一定永久可用。

调大 MaxIdleConnsPerHost 能修复 EOF 吗？

不能直接修复。它只改变单主机保留多少空闲连接；EOF 更应先检查对端空闲阈值、响应体关闭和客户端是否复用了过期连接。

参考：Go 官方 net/http.Transport 文档与标准库源码中的空闲计时实现。