Go net/http Transport MaxConnsPerHost 如何设置上限

我在给一个小型 HTTP 拉取器加并发控制时，最容易误判的地方不是字段怎么写，而是“连接数”到底怎么算。MaxConnsPerHost 限制的是同一主机的拨号中、活动中和空闲连接总数；达到上限后，新的拨号会等待。直接把它设在复用的 http.Transport 上即可。

官方地址：https://pkg.go.dev/net/http#Transport

先把 MaxConnsPerHost 的“上限”定义清楚

这个字段是 int，填写正整数就是每个主机的连接总上限，填写 0 则不设上限。这里的 host 实际要结合端口理解：api.example.com:443 和另一个端口是不同目标。限制触发时，Transport 不会凭空报“连接池满了”，而是让后续拨号阻塞，直到已有连接离开拨号、活动或空闲状态。

MaxIdleConnsPerHost 只决定每个主机最多保留多少条空闲 keep-alive 连接，不能替代并发总量控制。下面这张图是参数和连接状态的静态关系示意。

把上限放进一个可复用的 HTTP 客户端

我更倾向于把连接策略集中在一个 Transport 中，再交给 Client 使用。这样业务函数只负责请求，不会每次调用都生成新的连接池。示例把上限设为 8，并用一个小函数统一创建客户端：

package main

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

// newHTTPClient 集中设置连接上限，让多个请求复用同一个 Transport。
func newHTTPClient() *http.Client {
    transport := &http.Transport{
        MaxConnsPerHost:     8,  // 限制每个 host:port 的拨号中、活动中和空闲连接总数。
        MaxIdleConns:        16, // 控制所有主机的空闲连接总量，不等于并发上限。
        MaxIdleConnsPerHost: 4,  // 请求结束后，每个主机最多保留 4 条空闲连接。
        IdleConnTimeout:     30 * time.Second, // 空闲连接超过时间后关闭，减少长期占用。
    }
    return &http.Client{
        Transport: transport,
        Timeout:   5 * time.Second, // 给等待连接、请求和读取响应设置总超时。
    }
}

// fetch 只负责一次请求，并在所有路径关闭响应体。
func fetch(ctx context.Context, client *http.Client, url string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("发送请求失败: %w", err)
    }
    defer resp.Body.Close() // 释放响应资源，避免连接长期占用连接槽位。
    if resp.StatusCode = 300 {
        return fmt.Errorf("响应状态异常: %s", resp.Status)
    }
    return nil
}

这里的关键不是数字 8 本身，而是让上限成为共享配置。实际数值应结合对端承载能力、请求耗时和本机资源压测决定，不能把示例值当成通用最佳值。

为什么设置了上限后请求会排队

当同一 host:port 已经占满 8 条连接，新请求如果需要新建连接，就会在 Transport 内等待；这不是 goroutine 数量上限，也不是服务端 QPS 限流。若已有可复用的空闲连接，请求可能直接复用它，因此观察到的连接建立次数不一定等于请求数。

排查时我会先看三件事：请求 URL 是否真的指向同一个主机和端口；是否有多个 Transport 或多个 Client 把连接池拆散；是否每条响应都关闭了 Body。如果只修改 MaxIdleConnsPerHost，只能改变空闲连接保留策略，不能解决总连接数失控。

用可观察现象验收配置

配置验收不应只检查字段赋值。可以给请求设置小于业务容忍度的 Client.Timeout，并在并发压测或测试环境观察：超过上限的请求是否出现等待、超时是否能返回、服务端看到的同一 host:port 连接数是否被限制。若请求耗时变长，要区分“等待连接槽位”和“服务端响应慢”，后者不能靠调大上限自动解决。

最终可以把“每个目标最多 8 条连接、超限允许等待、请求有总超时、响应体必关闭”写入配置说明和回归用例。这样以后调整数字时，团队知道改的是资源边界，而不是随手改一个性能开关。

常见问题

MaxConnsPerHost 设置为 0 是多少条连接？

0 表示不限制总连接数，不是禁止建立连接，也不是使用默认值。若需要明确的并发边界，应设置正整数。

设置了 MaxConnsPerHost 还需要 MaxIdleConnsPerHost 吗？

两者解决不同问题：前者限制拨号中、活动中和空闲中的连接总数，后者限制请求结束后继续保留的空闲连接数量。是否同时设置，取决于你是否还要控制 keep-alive 资源。