Go httptrace.PutIdleConn 怎样判断连接未能放回连接池

如果你想知道 Go HTTP 客户端的连接有没有成功回收到 Transport 的空闲池，重点看 httptrace.ClientTrace.PutIdleConn 的参数：err == nil 表示这次连接被成功放入空闲池，err != nil 则表示没有放回，并且错误描述了原因。它不是“连接池当前有多少条连接”的查询接口，也不能替代关闭 Response.Body。

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

下面把回调信号、响应体责任和协议边界拆开。这样排查“连接复用没有命中”时，不会把一个回调的结果误当成整个 Transport 的健康结论。

PutIdleConn 的 err 到底表示什么

PutIdleConn 的语义是“连接尝试返回空闲连接池时通知你”。因此判断很直接：

• err == nil：这次回收到空闲池的动作成功。
• err != nil：没有成功回收，错误值说明了未回收原因。
• 回调没有出现：不能直接推导出“连接池坏了”，还要看是否禁用了 keep-alive，以及请求是否走了 HTTP/2。

回调发生在客户端处理一次响应的过程中，并且官方文档特别说明，它位于调用方的 Response.Body.Close 返回之前。也就是说，图中的两个节点是有关联的，但职责不同：PutIdleConn 报告 Transport 的回收结果，调用方仍然要负责关闭响应体。

用 ClientTrace 记录成功和失败

把 trace 放入请求上下文，再交给 http.Client.Do，可以把回收结果记录到自己的诊断日志。示例只观察回调，不修改 Transport 的连接策略：

package main

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

func doWithTrace(ctx context.Context, client *http.Client, req *http.Request) error {
    trace := &httptrace.ClientTrace{
        PutIdleConn: func(err error) {
            if err == nil {
                // nil 表示本次连接成功回收到 Transport 的空闲池。
                fmt.Println("put idle connection: ok")
                return
            }
            // 非 nil 只说明本次回收失败，保留原始错误便于定位原因。
            fmt.Printf("put idle connection: %v\n", err)
        },
    }

    tracedCtx := httptrace.WithClientTrace(ctx, trace)
    response, err := client.Do(req.WithContext(tracedCtx))
    if err != nil {
        // Do 失败时没有可关闭的响应体，直接返回请求错误。
        return err
    }
    defer response.Body.Close() // 响应体关闭责任仍由调用方承担。
    return nil
}

这个例子有三个容易被忽略的点。第一，回调只保存诊断信号，不应该在回调里把连接池参数动态改掉。第二，Do 成功后仍然要关闭响应体；只监听 PutIdleConn 并不能替代这个清理动作。第三，若你还要判断响应内容是否完整，应在读取和关闭流程中单独记录，不要把“回收到空闲池”当成“业务响应处理完成”。

三种场景要分开判断

选排查手段时，先确认请求所处的连接模式。下面的对比比单看一个 err 更有用：

因此，“没有看到 PutIdleConn”至少有三种解释：连接复用被显式关闭、当前请求使用了 HTTP/2，或者请求在更早的阶段失败。只有在确认是 HTTP/1.1 keep-alive，且确实进入了可回收的路径后，才适合把回调作为主要证据。

按现象选择排查方向

可以按下面的顺序做判断，但它是排查思路，不是把回调包装成完整监控指标：

1. 先确认 client.Transport 是否启用了 DisableKeepAlives，以及请求是否使用 HTTP/2。
2. 再确认 Do 成功后是否始终关闭了 Response.Body，必要时记录关闭前后的响应处理状态。
3. 对于 HTTP/1.1，再读取 PutIdleConn 的错误：nil 是本次回收成功，非 nil 是本次回收失败原因。
4. 最后才结合 MaxIdleConns、MaxIdleConnsPerHost 和 IdleConnTimeout 判断容量或淘汰策略。

常见问题

PutIdleConn 返回 nil 能证明连接池永远不会耗尽吗？

不能。它只表示某一次连接成功回收到空闲池，不能代表所有主机、所有时刻或整个 Transport 的容量状态。

只要回调没有触发，就一定是响应体没有关闭吗？

不一定。先排除 DisableKeepAlives 和 HTTP/2，再检查响应体关闭、请求失败阶段以及 Transport 的实际配置。

应该用 PutIdleConn 还是 GotConn 判断连接复用？

两者观察点不同：PutIdleConn 看本次连接能否回到空闲池，GotConn 更适合观察请求拿到连接时是否复用。需要完整判断时可以同时记录，但不要用一个回调替代另一个。

记住一句话：PutIdleConn 只回答“这次连接回收成功了吗”，Response.Body.Close 回答“调用方有没有完成资源交接”，而协议和 Transport 配置决定这个回调是否适用。