Transport 连接池不复用时的配置排查指南

Go 的 HTTP 连接池不在 http.Client 里，而是由它使用的 http.Transport 持有。连接总是新建，通常先看三件事：是否每次请求都创建了新的 Transport、响应体是否读完并关闭、是否有配置主动关闭 keep-alive。把 Client 和 Transport 作为长期复用对象，并正确处理 Response.Body，再按目标主机和服务端行为排查，通常比单纯调大连接数更有效。

• 连接池归属：复用的是同一个 Transport 实例。
• 资源释放：响应体要读到结束并关闭，连接才有机会回到空闲池。
• 配置边界：DisableKeepAlives、空闲超时和目标地址都会影响观察结果。

先确认连接池的归属和生命周期

http.Client 负责更高层的请求调用，真正维护空闲连接的是它的 Transport。如果把下面两者写进请求函数，每次调用都会得到一套新的连接池，前一个池里的连接自然无法被后一个请求复用。

var sharedClient = &http.Client{
    // Transport 放在长期对象中，多个请求才能看到同一个连接池。
    Transport: &http.Transport{
        MaxIdleConns:        100,
        MaxIdleConnsPerHost: 20,
        IdleConnTimeout:     90 * time.Second,
    },
    // Client.Timeout 覆盖一次请求的总时间，按业务需要设置。
    Timeout: 10 * time.Second,
}

func call(ctx context.Context, url string) error {
    // 使用传入的上下文，让调用方能够取消这次请求。
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }
    resp, err := sharedClient.Do(req)
    if err != nil {
        return err
    }
    // 读完并关闭响应体，Transport 才能判断连接是否可回收复用。
    defer resp.Body.Close()
    _, err = io.Copy(io.Discard, resp.Body)
    return err
}

这里的关键不是变量名，而是对象生命周期：程序复用同一个 Transport，请求结束后再处理响应体。若确实需要更换代理、证书或拨号策略，也应明确创建新 Transport 的边界，不要在普通请求路径中隐式创建。

建立不主动破坏复用的 Transport 配置

MaxIdleConns 控制所有主机的空闲连接总量，MaxIdleConnsPerHost 控制单个主机的空闲连接数，IdleConnTimeout 控制空闲连接最长保留时间。它们解决的是“允许保留多少、保留多久”，不是强制每次请求都复用。

func newHTTPClient() *http.Client {
    tr := &http.Transport{
        // 给所有主机预留空闲连接总量，避免池过小导致频繁淘汰。
        MaxIdleConns: 100,
        // 单主机并发较高时，按实际并发设置，而不是沿用过小默认值。
        MaxIdleConnsPerHost: 20,
        // 空闲太久的连接主动回收，时间要和服务端策略协调。
        IdleConnTimeout: 90 * time.Second,
        // 保持 keep-alive；这不是 TCP 层的 TCP keepalive 开关。
        DisableKeepAlives: false,
    }
    return &http.Client{
        // Client 和 Transport 一起作为长期对象复用。
        Transport: tr,
        Timeout:   10 * time.Second,
    }
}

不要把 MaxConnsPerHost 误当成“连接复用开关”。它限制单主机的总连接数，包含拨号中、使用中和空闲连接；设置过小可能让请求等待，设置过大也不会修复每次新建 Transport 的问题。排查时还要确认请求的 scheme、主机名和端口确实一致，因为不同目标不会共享同一条连接。

按复用条件排查配置

如果同一个 Client 仍然频繁新建连接，可以按下面顺序缩小范围：

1. 搜索请求函数里是否出现 http.Transport{}、http.DefaultTransport.Clone() 或新的 http.Client；它们不应在每次请求中创建。
2. 确认每条成功响应都执行了 Body.Close，需要复用时还要把响应体读到 EOF。只拿状态码后直接结束，连接可能无法回到空闲池。
3. 确认没有把 DisableKeepAlives 设为 true，也没有在每次调用后执行 CloseIdleConnections。
4. 检查服务端是否主动关闭连接、空闲超时是否比客户端更短，以及请求是否实际落到了不同的主机或端口。

这些条件是并列的排查边界，不是“把某个数字调大就一定生效”。尤其要区分 HTTP/1.1 的空闲连接列表和 HTTP/2 的多路复用连接：后者可以被多个请求同时使用，不能只用“空闲连接数量”来解释所有现象。

用 httptrace 观察是否真的复用

怀疑连接池失效时，可以给一次请求挂上 httptrace.ClientTrace，读取 GotConnInfo.Reused 和 WasIdle。它们告诉你本次请求拿到的连接是否曾被使用、取得时是否处于空闲状态，适合做排查日志，不应被当成服务端监控指标。

func traceRequest(ctx context.Context, client *http.Client, url string) error {
    trace := &httptrace.ClientTrace{
        GotConn: func(info httptrace.GotConnInfo) {
            // Reused 表示连接来自已有连接；WasIdle 表示取得时处于空闲状态。
            log.Printf("reused=%t was_idle=%t idle_time=%s", info.Reused, info.WasIdle, info.IdleTime)
        },
    }
    ctx = httptrace.WithClientTrace(ctx, trace)
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    // 诊断请求同样要释放响应体，避免排查代码制造新的不复用现象。
    defer resp.Body.Close()
    _, err = io.Copy(io.Discard, resp.Body)
    return err
}

相关问题

只调用 resp.Body.Close，不读取内容，可以复用吗？ 最稳妥的做法是先读到 EOF 再关闭；这样 Transport 能完整判断响应是否正常结束。只关闭而不读取时，不要假设连接一定会回到空闲池。

调大 MaxIdleConnsPerHost 仍然不复用怎么办？ 先确认 Transport 实例、目标主机和 keep-alive，再检查服务端是否关闭连接；连接池容量只能解决“保留不够”，不能解决“对象不同”或“连接已被关闭”。