Go http.Transport 怎样控制单个主机的空闲连接

如果 Go 客户端需要反复访问同一个 API 主机，最直接的控制点是 http.Transport.MaxIdleConnsPerHost。它限制的是“每个主机最多保留多少条空闲 keep-alive 连接”，不是并发请求总数，也不是所有主机共享的总连接数。把它配置到一个长期复用的 Transport 上，通常就能避免默认值偏小导致的连接反复建立。

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

本文只讨论单主机空闲连接上限，以及它和几个相邻参数的边界。

先分清三个连接数参数

MaxIdleConnsPerHost 的单位是“每个主机的空闲连接数”。这里的主机是 Transport 按目标地址区分的连接池分组。设置为非零值时，Transport 会按该上限保留某个主机的空闲 keep-alive 连接；设置为零时使用默认的单主机上限。

最容易混淆的是下面三个字段：

因此，想让同一 API 主机在一轮突发请求后留下更多连接，应先看 MaxIdleConnsPerHost；想限制该主机同时占用的全部连接，才看 MaxConnsPerHost。IdleConnTimeout 另管连接空闲多久后关闭，不是数量上限。

把单主机上限配置到可复用的 Transport

配置位置在 http.Transport，使用时再把它交给 http.Client。关键是不要在每次请求里重新创建 Transport，否则刚建立的连接池没有机会被后续请求复用。

package main

import (
    "net/http"
    "time"
)

func newHTTPClient() *http.Client {
    transport := &http.Transport{
        // 单个主机最多保留 8 条空闲 keep-alive 连接。
        MaxIdleConnsPerHost: 8,
        // 所有主机合计最多保留 64 条空闲连接。
        MaxIdleConns: 64,
        // 空闲连接超过 90 秒没有新请求就回收。
        IdleConnTimeout: 90 * time.Second,
    }

    // Client 和 Transport 应在多个请求之间复用。
    return &http.Client{Transport: transport}
}

如果只访问一个主机，可以把关注点放在 MaxIdleConnsPerHost；如果同一个客户端还访问很多主机，就同时给 MaxIdleConns 设一个总量上限，避免每个主机都保留连接后整体规模失控。

参数是 Transport 级别的，不是某一次 Do 调用的选项。需要按租户、区域或上游分别设置时，应为这些连接池边界创建不同的长期 Transport，而不是在请求结束后临时修改共享对象。

为什么设置后仍看不到复用

单主机上限只是“最多保留多少条空闲连接”，并不保证下一次请求一定复用。下面几种情况都会让观察结果与预期不同：

• Transport 被反复创建：每次请求都使用新 Client 或新 Transport，连接池自然是新的。
• 响应体没有正确关闭：请求完成后应关闭 Response.Body；如果响应体没有读完或没有关闭，连接可能不能回到空闲池。
• 空闲时间超过上限：IdleConnTimeout 到期后连接会被清理，下一次请求需要重新建立。
• 请求没有使用 keep-alive：例如主动设置了 DisableKeepAlives，单主机空闲上限就没有可复用对象。

排查时先确认同一个 Client 确实跨请求存在，再确认响应体的资源路径完整，最后再看数量和时间参数。不要把“连接数变少”直接判断成 MaxIdleConnsPerHost 没生效，它可能只是空闲超时或响应未归还造成的。

按场景选择参数

可以按下面的决策顺序配置：

1. 同一主机的请求突发后，希望留下更多连接：调大 MaxIdleConnsPerHost。
2. 客户端访问很多主机，希望限制连接池总规模：再设置 MaxIdleConns。
3. 必须限制同一主机的总并发连接数：使用 MaxConnsPerHost，记住它会包含活动连接。
4. 连接可以空闲多久：用 IdleConnTimeout，它表达的是时间边界。

不要为了“提高复用”盲目把所有数字调大。连接保留数量应结合上游主机数量、请求突发程度和客户端资源预算决定；Transport 本身应保持复用，真正需要清理时再调用对应的关闭空闲连接方法。

常见问题

MaxIdleConnsPerHost 设置为 0 是没有限制吗？

不是。对 Transport 来说，零值表示使用 DefaultMaxIdleConnsPerHost，不是无限保留。要明确控制单主机空闲连接数，应填写正数。

MaxIdleConnsPerHost 能限制正在处理的请求吗？

不能。它只限制空闲 keep-alive 连接；需要限制拨号中、活动和空闲连接的总数时，应看 MaxConnsPerHost。

为什么连接复用仍然很少？

优先排查 Transport 是否被复用、Response.Body 是否关闭、是否启用了 keep-alive，以及空闲连接是否已经超过 IdleConnTimeout。

总结一下：单主机空闲连接看 MaxIdleConnsPerHost，所有主机空闲总量看 MaxIdleConns，单主机全部连接看 MaxConnsPerHost，连接保留时间看 IdleConnTimeout。把参数放在一个长期复用的 Transport 上，边界才会真正作用于后续请求。