Go http.Transport 复用连接时 IdleConnTimeout 怎么设置

如果 Go 客户端需要复用 keep-alive 连接，又不希望连接长期躺在池里，可以在复用的一份 http.Transport 上设置 IdleConnTimeout。例如 90 * time.Second 表示连接连续空闲 90 秒后允许被回收；设为 0 则不限制空闲时长。它只看“连接现在是否空闲”，不会限制正在执行的请求，也不是响应头超时。

常用做法是复用一份 Transport，按上游 keep-alive 和进程连接预算设置 IdleConnTimeout，再用 MaxIdleConnsPerHost 控制数量；请求结束后务必关闭 Response.Body。

IdleConnTimeout 只管空闲的 keep-alive 连接

一次请求完成后，如果响应体已经读完并关闭，HTTP/1.1 连接可能进入 Transport 的空闲池，等待下一次请求复用。IdleConnTimeout 计算的就是这段“没人使用”的时间。连接正在写请求、等响应头或读取响应体时，不会因为这个字段到期就被当成空闲连接清理。

几个容易混淆的参数可以这样区分：

一个可复用的 Transport 应该怎么配

Transport 应该在进程中长期复用，而不是每次调用都新建。下面的配置给空闲连接一个明确上限，同时给单个上游保留少量复用空间：

package main

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

var client = &http.Client{
    Transport: &http.Transport{
        // 空闲 keep-alive 连接超过 90 秒后允许回收。
        IdleConnTimeout: 90 * time.Second,
        // 限制单个上游保留的空闲连接数量，避免主机很多时池子膨胀。
        MaxIdleConnsPerHost: 8,
        // 给等待响应头的阶段单独设置上限；它不是 IdleConnTimeout。
        ResponseHeaderTimeout: 5 * time.Second,
    },
    Timeout: 15 * time.Second,
}

func fetch(url string) error {
    resp, err := client.Get(url)
    if err != nil {
        return err
    }
    defer resp.Body.Close() // 释放响应体，读完后连接才有机会回到空闲池。
    _, err = io.Copy(io.Discard, resp.Body) // 读取完响应体，尽量保留连接复用机会。
    return err
}

这里的 Timeout 是整个请求生命周期的上限，和连接进入空闲池之后的保留时间分开计算。生产环境不要只把 IdleConnTimeout 调得很大来掩盖连接池配置问题；先确认上游允许的 keep-alive 时长，再结合本地 fd 和并发预算调整。

连接复用不只靠一个超时参数

如果空闲连接数量经常升高，优先看三件事：所有请求是否共用同一个 Transport，响应体是否总能关闭，以及 MaxIdleConnsPerHost 是否与并发量匹配。只设置空闲时间，不会主动减少正在使用的连接，也不会替代上游服务端或代理的连接策略。

HTTPS 请求可能协商到 HTTP/2。官方实现中，HTTP/1 连接放入空闲池时会设置空闲计时器；HTTP/2 的空闲管理由对应实现处理。因此排查时不要只盯着 TCP 连接数，还要确认实际协议和客户端是否因为自定义拨号器、TLS 配置而改变了 HTTP/2 的启用方式。

进程优雅退出或切换上游时，可以主动清理已经空闲的连接：

func closeIdleTransport() {
    tr, ok := client.Transport.(*http.Transport)
    if !ok {
        return // 使用自定义 RoundTripper 时，不假定它支持 Transport 方法。
    }
    tr.CloseIdleConnections() // 只关闭空闲连接，不打断正在使用的连接。
}

怎么判断设置已经生效

不要把“第二次请求成功”直接等同于复用成功，可以用 httptrace.GotConn 观察连接事件。Reused 表示连接曾被使用，WasIdle 表示本次取到它时处于空闲状态，IdleTime 则能帮助判断空闲时间是否符合预期：

trace := &httptrace.ClientTrace{
    GotConn: func(info httptrace.GotConnInfo) {
        // 记录复用和空闲时长，便于和 Transport 配置对照。
        log.Printf("reused=%v wasIdle=%v idle=%s", info.Reused, info.WasIdle, info.IdleTime)
    },
}
req, err := http.NewRequest("GET", url, nil)
if err != nil {
    return err // URL 不合法时，不进入请求阶段。
}
req = req.WithContext(httptrace.WithClientTrace(req.Context(), trace))
resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close() // 观测完成后仍要按正常规则关闭响应体。

若两次请求间隔小于设定值但 Reused=false，还要检查服务端是否主动关闭、响应体是否提前中断、请求是否使用了不同的主机或代理，以及是否关闭了 keep-alive。IdleConnTimeout 是客户端空闲池策略，不保证远端一定保留这条连接。

几个容易混淆的设置

IdleConnTimeout 设成 0 会马上关闭连接吗？

不会。0 表示不限制空闲时长，并不等于禁用 keep-alive；如果要禁止复用，应明确使用 DisableKeepAlives，但通常会增加建连成本。

它能限制慢请求的总耗时吗？

不能。慢请求应使用 http.Client.Timeout 或针对阶段的超时配置；IdleConnTimeout 只在请求完成、连接进入空闲状态后才有意义。

调小它就一定能降低连接数吗？

只能减少长时间闲置的连接。并发中的连接数量仍由请求负载和其他 Transport 限制决定，单主机空闲数量还应配合 MaxIdleConnsPerHost 观察。