Go Transport 连接池复用失效的排查方案

我曾经遇到过一类很容易误判的 HTTP 性能问题：代码明明设置了 http.Transport，但抓包或服务端连接统计仍然像“每次请求都新建连接”。第一反应通常是把 MaxIdleConnsPerHost 调大，结果连接数变多了，复用率却没有改善。

真正的排查顺序应该是：先确认所有请求是否共享同一个 Transport，再确认响应体是否读到 EOF 并关闭，之后用 httptrace.GotConn 看连接是否复用，最后才调整连接池参数。下面这套方法专门处理“连接池复用失效”的定位，不把连接数变大当成万能修复。

先确认请求真的共享同一个 Transport

Transport 会缓存连接供后续请求使用，而且官方文档建议复用 Transport；它本身可以被多个 goroutine 并发使用。相反，如果每次调用都创建一个新的 http.Client 和 http.Transport，每个实例都有自己的连接缓存，连接自然无法跨实例复用。

package main

import (
	"net/http"
	"time"
)

// 共享 Transport，让同一个目标主机的请求使用同一份连接缓存。
var sharedTransport = &http.Transport{
	MaxIdleConns:        100,
	MaxIdleConnsPerHost: 16,
	IdleConnTimeout:     90 * time.Second,
}

// Client 也可以作为长期复用的进程级对象，而不是每次请求临时创建。
var sharedClient = &http.Client{
	Transport: sharedTransport,
	Timeout:   15 * time.Second,
}

如果业务需要按租户、代理或 TLS 配置区分客户端，应该明确分组并长期持有这些 Transport，而不是在请求函数内部无条件初始化。连接池的“复用范围”首先由对象生命周期决定。

Response.Body 没有消费完，连接就很难回池

这是最常见也最隐蔽的原因。成功返回后，调用方需要关闭 Response.Body；如果希望 HTTP/1.1 的持久连接被后续请求复用，通常还要把响应体读到 EOF。只写 defer resp.Body.Close() 而不读取内容，在某些响应和传输条件下仍然会让连接不能按预期回到空闲池。

package client

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

// fetchStatus 读取完整响应体后再关闭，给 Transport 回收连接的机会。
func fetchStatus(client *http.Client, url string) error {
	resp, err := client.Get(url)
	if err != nil {
		return fmt.Errorf("发送请求失败: %w", err)
	}
	defer resp.Body.Close() // 无论读取是否成功，都要释放响应体。

	if _, err := io.Copy(io.Discard, resp.Body); err != nil {
		return fmt.Errorf("读取响应体失败: %w", err)
	}
	if resp.StatusCode = 300 {
		return fmt.Errorf("服务端返回状态码 %d", resp.StatusCode)
	}
	return nil
}

对于确实需要解析 JSON 的请求，应先用 json.Decoder 读取数据，再关闭 body；对于只关心状态码的探活请求，使用 io.Copy(io.Discard, resp.Body) 是一种清晰的消费方式。不要用“看到 2xx 就立即 return”替代资源处理。

用 GotConn 判断到底有没有复用

仅看服务端的连接数，无法区分连接没有复用、连接刚好空闲超时，还是服务端主动关闭。httptrace.ClientTrace.GotConn 可以记录本次请求拿到连接时的 Reused、WasIdle 和空闲时长，把猜测变成单次请求证据。

package diagnose

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

// doWithTrace 记录连接取得时的复用状态，便于和响应体处理日志对照。
func doWithTrace(client *http.Client, url string) error {
	trace := &httptrace.ClientTrace{
		GotConn: func(info httptrace.GotConnInfo) {
			fmt.Printf("got conn: reused=%v wasIdle=%v idleTime=%s\\n",
				info.Reused, info.WasIdle, info.IdleTime.Round(time.Millisecond))
		},
	}

	req, err := http.NewRequestWithContext(httptrace.WithClientTrace(context.Background(), trace), 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 _, err := io.Copy(io.Discard, resp.Body); err != nil {
		return fmt.Errorf("消费响应体失败: %w", err)
	}
	return nil
}

上面的代码还需要补充 io 导入。日志中 reused=true 表示本次拿到的是已经使用过的连接；wasIdle=true 说明它曾在空闲池中等待。连续多次为 false 时，再沿着对象生命周期、响应体处理、池容量和服务端关闭四条线排查。

不要混淆四个连接池参数

连接复用失效时，参数名称很像，但作用并不相同。可以先按下面的关系建立判断：

MaxIdleConnsPerHost 为零时使用标准库默认值；不要把“空闲连接上限”理解成“整个请求并发上限”。如果请求间隔很长，连接因 IdleConnTimeout 过期后重新拨号是正常现象；如果同一时刻并发很多请求，应该结合 MaxConnsPerHost 判断，而不是只调空闲连接数。

四种常见边界会让复用看起来失效

1. 请求实际上发往不同的连接目标

URL 的主机名、端口、代理路径和 TLS 配置变化，都可能让 Transport 使用不同的连接池键。业务日志应同时记录最终请求地址和代理/协议配置，不能只按“业务接口名称”统计连接。

2. 服务端或中间代理主动关闭连接

客户端空闲时间设置得很长，并不代表服务端会一直保留连接。如果服务端的 keep-alive 更短，客户端拿到旧连接时可能发现连接已关闭，再重新建立连接。这属于两端策略不一致，应通过服务端日志、响应头和 GotConn 记录共同判断。

3. 关闭了 keep-alive

DisableKeepAlives=true 会关闭 HTTP keep-alive，每条连接只服务一个请求；它和 TCP 层的 keep-alive 不是一回事。排查时先确认没有被公共 Transport 配置、环境分支或测试开关意外打开。

4. HTTP/2 被误当成 HTTP/1.1 连接池

HTTPS 请求可能协商到 HTTP/2。此时多个请求可以复用同一条连接，但“空闲连接数”和 HTTP/1.1 的直觉不完全一致。不要用“看到连接数没有增加”直接推导请求没有并发；需要结合协议协商信息和请求级 trace 判断。

一份更稳妥的共享配置

package main

import (
	"net/http"
	"time"
)

// newHTTPClient 集中定义连接复用和超时策略，避免调用方各自创建 Transport。
func newHTTPClient() *http.Client {
	tr := &http.Transport{
		MaxIdleConns:        100,              // 控制所有主机的空闲连接总量。
		MaxIdleConnsPerHost: 16,               // 为高频目标保留足够的空闲连接。
		MaxConnsPerHost:     64,               // 防止单个目标无限制占用连接。
		IdleConnTimeout:     90 * time.Second, // 与服务端 keep-alive 策略一起调整。
		ResponseHeaderTimeout: 8 * time.Second, // 只限制等待响应头的时间。
	}
	return &http.Client{
		Transport: tr,
		Timeout:   15 * time.Second, // 给整个请求设置兜底超时。
	}
}

这不是适合所有流量的固定数字，而是一份把决策集中起来的起点。高并发服务还要依据目标主机数量、请求耗时、服务端连接上限和失败重试策略调整。若要在配置变更或进程退出时释放空闲连接，可以调用 Transport.CloseIdleConnections；它不会中断正在使用的连接。

排查完成前的复查清单

1. 确认所有请求是否持有并共享同一个 http.Transport。
2. 确认每个成功响应都读取到需要的末尾，并且一定执行 Body.Close。
3. 使用 httptrace.GotConn 记录 reused、wasIdle 和目标地址。
4. 分别核对四个连接池参数，不把 MaxIdleConnsPerHost 当作并发上限。
5. 检查 DisableKeepAlives、代理、HTTP/2 协商和服务端 keep-alive 策略。
6. 区分“连接复用率低”和“连接池容量不足”：前者先查生命周期与响应体，后者再调容量。

我的经验是，Transport 复用问题最怕“只看连接数调参数”。先让每一次请求带上连接取得证据，再把响应体处理和对象生命周期固定下来，最后才讨论池大小，通常能很快分清是代码问题、参数问题还是对端策略问题。

相关问题

为什么复用同一个 Client 仍然没有复用连接？

先确认这个 Client 没有被中途替换，且它的 Transport 不是每次复制出来的；然后检查 Response.Body 是否读完并关闭。

MaxIdleConnsPerHost 调大后连接数为什么仍然增长？

它只控制空闲连接保留数，不限制请求拨号总数。还要检查并发峰值、MaxConnsPerHost、请求目标是否一致以及服务端是否主动关闭。

什么时候应该调用 CloseIdleConnections？

在切换代理、TLS 配置、下线某类目标或进程准备释放资源时可以调用；它只关闭空闲连接，不会打断正在使用的连接。