Go Transport.CloseIdleConnections 清理空闲连接的使用边界

如果 Go HTTP 客户端只是想清理已经完成请求后留在 keep-alive 池里的连接，应调用 Transport.CloseIdleConnections()。它不会取消正在执行的请求，也不会替代 Response.Body.Close()；活动连接、响应体和空闲连接是三个不同的生命周期。

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

结论：把同一个 http.Transport 交给多个请求复用，在测试收尾、切换客户端配置或进程准备退出时清理空闲连接；正在使用的连接继续完成，新的请求仍可能重新建立连接。

本文要点：先分清三类资源，再看调用层级、连接池参数和常见排查误区。

先分清响应体、活动连接和空闲连接

Transport.CloseIdleConnections 的对象是已经完成上一轮通信、当前处于 keep-alive 空闲状态的连接。它不会打断仍在读取响应的连接，也不会自动关闭当前请求的 Response.Body。调用方仍要在读取结束后关闭响应体，否则连接可能无法正常回到复用池。

最小的客户端写法是复用 Transport，并在确定不再需要空闲连接时清理它：

package main

import (
	"io"
	"net/http"
)

func fetchAndClose(client *http.Client, url string) error {
	// Client 负责发送请求；Response.Body 仍由调用方负责关闭。
	resp, err := client.Get(url)
	if err != nil {
		return err
	}
	defer resp.Body.Close() // 先释放本次响应的读取资源。

	_, err = io.Copy(io.Discard, resp.Body)
	return err
}

func closeIdleTransport(tr *http.Transport) {
	// 这里只清理 keep-alive 空闲连接，不取消正在执行的请求。
	tr.CloseIdleConnections()
}

在 Transport 生命周期边界调用清理

调用时机应跟 Transport 的所有权绑定。测试结束前可以清理空闲连接，避免连接池中的 goroutine 或 socket 影响泄漏检查；程序准备切换一组代理或 TLS 配置时，也可以先停止使用旧 Transport，再清理它的空闲连接。不要在每个请求后都调用，否则刚建立的连接失去复用价值。

func newClient() (*http.Client, func()) {
	// Transport 应长期复用，避免每次请求都创建新的连接池。
	tr := http.DefaultTransport.(*http.Transport).Clone()
	client := &http.Client{Transport: tr}

	cleanup := func() {
		// 清理尚未被使用的 keep-alive 连接；活动请求不在这里被取消。
		tr.CloseIdleConnections()
	}
	return client, cleanup
}

如果调用清理后仍观察到连接没有结束，先确认请求是否还在使用连接、响应体是否已经关闭，以及是否有其他代码持有同一个 Transport。这个方法不是“强制断网”开关。

Client 与 Transport 的调用层级怎么选

http.Client 也提供 CloseIdleConnections，它会把请求转交给底层 Transport 的同名能力；当代码只持有 Client 时，使用 Client 层更容易表达所有权。当代码明确管理自定义 Transport，尤其要清理某一个连接池时，直接调用 Transport 方法更清楚。

IdleConnTimeout 等参数解决的是长期策略

CloseIdleConnections 是一次性的生命周期动作，IdleConnTimeout 是空闲连接自动过期的策略；MaxIdleConns 和 MaxIdleConnsPerHost 控制池容量，DisableKeepAlives 则直接改变复用模型。生产环境先确定请求模式和连接复用目标，再调参数。

import "time"

tr := &http.Transport{
	// 限制每个目标主机保留的空闲连接数量。
	MaxIdleConnsPerHost: 8,
	// 让长期不用的 keep-alive 连接自动过期。
	IdleConnTimeout: 90 * time.Second,
}

// 连接池参数改变后，仍需用同一 Transport 发送请求。

它只说明策略字段的职责，不代表所有服务都应该使用固定数值。突发流量、目标主机数量和连接建立成本不同，参数应通过指标和压测决定。

连接问题的三项排查清单

1. 响应体：每个成功的 Do 或 Get 都检查错误，并在读取结束后关闭 Response.Body。
2. 空闲池：确认调用的是实际承载请求的 Client 或 Transport，而不是另一个新建实例。
3. 请求取消：需要中止活动请求时给请求绑定可取消的 Context，不要把清理空闲连接当成取消手段。

相关问题

CloseIdleConnections 会中断正在下载的响应吗？

不会。它针对已经空闲的 keep-alive 连接；正在使用的连接仍由当前请求控制。

每次请求结束都应该调用它吗？

通常不应该。频繁清理会削弱 Transport 的连接复用，只有在明确的生命周期边界或测试收尾时才调用。

为什么关闭 Response.Body 后还要清理空闲连接？

关闭响应体负责结束本次响应的资源使用；清理空闲连接负责释放池中暂时没有请求使用的 keep-alive 连接，两者处理的是不同阶段。