Go HTTP 超时回收空闲连接避免资源占满的排查指南

我排查过一类很容易误判的 Go HTTP 问题：下游请求已经超时，进程里的连接数却没有立刻回到低位。真正要先分开的，是“请求还在执行”和“请求已经结束、连接留在 keep-alive 池里”这两种状态。http.Client.Timeout负责一次请求的整体时限；连接池里的空闲连接则由 http.Transport.IdleConnTimeout、MaxIdleConns 和 MaxIdleConnsPerHost共同约束。

先把 Go HTTP 的三种超时分开

最常见的旧写法只给 Client 设置一个很短的 Timeout，然后看到 ESTABLISHED 连接仍在增长，就认为超时没有生效。这个判断少了一层：Client 的整体超时决定请求何时返回，但不会把所有连接池参数一起改掉。

ResponseHeaderTimeout只等待响应头，IdleConnTimeout则从连接变为空闲开始计时。连接仍承载请求时，不能被空闲回收器清理；CloseIdleConnections同样只关闭之前建立、当前处于 keep-alive 空闲状态的连接。

从连接池参数判断资源到底卡在哪里

我通常先看 Transport 是否被每个请求重新创建。这样做会失去复用，也让连接统计变得难以解释。官方文档建议复用 Transport；它可以被多个 goroutine 并发使用。连接很多不一定是泄漏，关键要把“活跃数、空闲数、每主机上限”放在同一时间窗口观察。

共享 Transport，给空闲连接设置可解释的边界

下面的配置把请求时限和连接池时限分开。数值只是示例，应按下游负载、代理和服务端 keep-alive 策略调整；不要为了让连接数马上下降而关闭所有 keep-alive。

package main

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

func newHTTPClient() *http.Client {
    transport := &http.Transport{
        MaxIdleConns:        100,              // 限制所有主机的空闲连接总量
        MaxIdleConnsPerHost: 8,                // 防止单个下游占满空闲池
        MaxConnsPerHost:     32,               // 同时限制拨号、活跃和空闲连接
        IdleConnTimeout:     60 * time.Second, // 空闲超过时长后由 Transport 回收
        TLSHandshakeTimeout: 10 * time.Second, // 避免 TLS 建连阶段无限等待
    }
    return &http.Client{
        Transport: transport, // 一个进程内共享 Transport，保留连接复用
        Timeout:   12 * 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 err // URL 或请求构造失败时不进入连接池
    }
    resp, err := client.Do(req)
    if err != nil {
        return err // 超时或网络错误由调用方记录并决定是否重试
    }
    defer resp.Body.Close() // 读完响应体并关闭，连接才有机会回到空闲池
    fmt.Println(resp.Status)
    return nil
}

这里的关键不是把所有超时都设成同一个数字，而是让每个参数承担单一职责。响应体没有关闭时，连接可能无法回到可复用的空闲状态；这时调小 IdleConnTimeout也解决不了根因。

切换下游或故障恢复时主动清理空闲连接

如果 DNS、代理、证书或下游实例刚发生切换，可以在确认不需要保留旧连接后主动清理。它不会中断正在使用的连接，所以适合放在配置热更新或下游恢复动作里；不要把它当成每次请求结束都要调用的“垃圾回收”。

func closeIdle(client *http.Client) {
    // 只关闭 keep-alive 空闲连接，不打断正在处理的请求
    client.CloseIdleConnections()
}

复查时建议固定一个观察窗口：记录请求超时数、正在使用的连接、空闲连接和新建连接次数。若超时后活跃连接长期不降，继续查 context 是否传递、响应体是否关闭、下游是否迟迟不读完；若只是空闲连接在 IdleConnTimeout 后下降，说明回收路径正常。

常见问题：为什么设置了 Timeout 还会有连接

把 Client.Timeout 设为 5 秒，空闲连接会立即消失吗？

不会。它控制请求总时长，不是空闲池的保留时长；要调整后者看 Transport 的 IdleConnTimeout 和空闲连接上限。

把 IdleConnTimeout 设为 0 可以吗？

可以，官方语义是空闲时间不设限制，但多下游或低频访问场景下可能让空闲资源长期保留。除非有明确的连接复用需求，否则应给出可解释的上限。

什么时候调用 CloseIdleConnections？

服务切换、代理变更或下游连接需要快速退出时调用；正常请求路径只需正确关闭响应体并让 Transport 自己管理。

排查顺序可以压缩成一句话：先确认连接是否仍在使用，再检查响应体和 Transport 是否复用，最后才调 IdleConnTimeout、MaxIdleConnsPerHost 或主动关闭空闲连接。这样既能避免资源占满，也不会把健康的 keep-alive 复用误杀。