Go 长连接空闲后复用失败怎么办

Go 的长连接空闲后再次请求失败，先不要急着把所有超时都调大。最常见的原因是客户端 Transport 认为连接仍可复用，但服务端的 keep-alive 空闲时间更短；另一类原因是响应体没有读完并关闭，或者每次请求都新建了 http.Client。稳定做法是复用一个 Transport，并让客户端的 IdleConnTimeout 略短于服务端的空闲回收时间。

一、先分清复用失败发生在哪个连接边界

“空闲后复用失败”描述的是现象，不一定表示 IdleConnTimeout 太小。Go 的 Transport 会缓存连接供后续请求使用，而服务端也可能在自己的 keep-alive 时长到期后主动关闭连接。两边的计时器互相独立：客户端计时更短，通常会主动换一条新连接；服务端计时更短，客户端就可能在取用旧连接时发现对端已经关闭。

因此排查时先记录三个事实：失败是否只发生在长时间无请求之后，失败前后是否更换了服务端实例，以及请求是否始终使用同一个 Transport。如果只在固定空闲时长后出现，优先比较两端的连接回收时间；如果每次请求都像第一次建立连接，则先检查 Transport 是否被重复创建。

二、按服务端空闲时长选择 IdleConnTimeout

IdleConnTimeout 表示 keep-alive 连接在客户端空闲多久后关闭，零值表示不限制。它只管理空闲连接，不负责限制 DNS、建立连接、读取响应头或读取响应体的总耗时。当前 Go 官方文档中的 DefaultTransport 使用 90 秒的空闲连接时长；自定义配置时仍应以实际服务端、代理和负载均衡器的最短空闲时间为基准。

假设服务端或中间代理会在 60 秒空闲后关闭连接，可以把客户端空闲回收设置在 45 秒左右，给客户端留下主动淘汰旧连接的余量：

var sharedTransport = &http.Transport{
	// 统一控制跨主机和单主机的空闲连接数量。
	MaxIdleConns:        100,
	MaxIdleConnsPerHost: 20,
	// 示例：服务端约 60 秒回收时，客户端提前 15 秒回收。
	IdleConnTimeout: 45 * time.Second,
	// 这里只限制 TLS 握手，不替代请求总超时。
	TLSHandshakeTimeout: 10 * time.Second,
}

var sharedClient = &http.Client{
	// Client 与 Transport 都应在进程内复用，而不是每次请求重新创建。
	Transport: sharedTransport,
	Timeout:   20 * time.Second,
}

不要为了“保住长连接”把 IdleConnTimeout 设成无限大。连接经过代理、网关或服务端时，真正生效的是链路中更短的那一个空闲策略；无限等待只会让客户端保留更多已经没有复用价值的连接。MaxIdleConnsPerHost 过小则会限制每个主机能留存的空闲连接数，它和空闲时长是两个不同的选择维度。

三、先处理 Response.Body，再谈连接复用

即使两端的空闲时长匹配，响应体处理不完整也会让 HTTP/1.x 连接无法稳定复用。Client.Do 返回成功响应后，调用方必须关闭 Response.Body；需要复用连接时，应按实际业务读取到结束，再关闭它。只读取响应头就直接丢弃响应，会让连接池缺少重新利用的条件。

func fetch(ctx context.Context, client *http.Client, url string) ([]byte, error) {
	// 请求使用调用方的 ctx，便于上游取消，而不是重新创建 background context。
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}

	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close() // 无论后续读取是否报错，都释放响应体资源。

	body, err := io.ReadAll(resp.Body) // 读取完整响应，为 HTTP/1.x 复用留下条件。
	if err != nil {
		return nil, err
	}
	if resp.StatusCode >= http.StatusBadRequest {
		return nil, fmt.Errorf("远端返回 %s", resp.Status)
	}
	return body, nil
}

如果程序需要在配置切换、进程优雅退出或主动清理时释放空闲连接，可以调用 Client.CloseIdleConnections()。它不会中断正在使用中的连接，所以不应把它放在每次正常请求之后，否则会主动放弃本来可以复用的连接。

四、用症状选择修复动作

配置方案要和现象对应，不要把所有问题都归因于 keep-alive：

最后记住，DisableKeepAlives 会让每条连接只服务一个 HTTP 请求，它和 TCP 层同名的 keep-alive 不是一回事。只有明确需要关闭 HTTP 连接复用时才选择它；普通的空闲复用故障，优先修正两端空闲时长、响应体生命周期和 Transport 复用方式。

相关问题

IdleConnTimeout 能限制单次请求耗时吗？

不能。它只处理空闲 keep-alive 连接；单次请求可以用 Client.Timeout、上下文或更细的阶段超时分别控制。

MaxIdleConnsPerHost 越大越好吗？

不一定。它应匹配并发量和服务端承载能力，过大可能保留没有实际复用价值的连接，过小则可能增加重新建连。