Go HTTP 客户端怎样复用连接

Go HTTP 客户端要复用连接，核心不是给每个请求设置一个特殊开关，而是让多个请求共享同一个 http.Client 和底层 Transport，同时正确处理返回的 Response.Body。非流式响应通常应读到结束并关闭；如果每次请求都新建客户端、主动关闭 keep-alive，或者忘记关闭响应体，连接复用就会失去条件。

官方文档：https://pkg.go.dev/net/http；连接观测接口：https://pkg.go.dev/net/http/httptrace。

最小可靠做法是：共享一个可复用的 http.Client，让它使用同一个 Transport；普通响应先读完 Body 再关闭，流式响应按业务结束时关闭；不要在每次请求后调用 CloseIdleConnections。

先分清 Client、Transport 和连接池

http.Client 负责更高层的请求使用方式，例如超时、重定向和 Cookie；真正实现连接缓存与复用的是它使用的 RoundTripper，通常就是 http.Transport。官方文档明确建议复用 Transport，因为它会缓存连接供后续请求使用，并且可以被多个 goroutine 并发使用。

因此，“每次调用都写 &http.Client{}”通常不是一个好的生命周期设计。即使代码能工作，也很难让连接池跨请求存在。连接复用是同一目标主机、协议和 Transport 生命周期下的资源关系，不等于所有请求都只使用一条 TCP 连接；HTTPS 还可能使用 HTTP/2 多路复用。

普通响应先读完 Body，再关闭

当 Client.Do 成功返回时，Response.Body 非空，调用方负责关闭它。对于 JSON、文本或较小的二进制响应，最直接的写法是先读取完整内容，再关闭 Body。读到 EOF 让 Transport 能够确认响应体已经处理完，关闭则释放调用方持有的响应资源。

package main

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

// 共享 Client，让底层 Transport 的连接池跨请求存在。
var client = &http.Client{
    Timeout: 10 * time.Second, // 给一次请求设置总超时，避免无限等待。
}

func fetch(ctx context.Context, url string) ([]byte, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return nil, fmt.Errorf("创建请求：%w", err)
    }

    resp, err := client.Do(req)
    if err != nil {
        return nil, fmt.Errorf("发送请求：%w", err)
    }
    defer resp.Body.Close() // 无论后续读取是否报错，都释放响应体。

    body, err := io.ReadAll(resp.Body) // 普通响应读到 EOF，有利于连接回到空闲池。
    if err != nil {
        return nil, fmt.Errorf("读取响应：%w", err)
    }
    if resp.StatusCode = 300 {
        return nil, fmt.Errorf("服务返回状态码 %d", resp.StatusCode)
    }
    return body, nil
}

这里的 defer 放在拿到响应后立即执行，避免中间新增分支时漏关 Body。状态码判断也要放在读取成功之后处理，因为非 2xx 本身通常不会让 Client.Do 返回 Go 层面的错误。

流式响应不要为了复用强行读完

如果接口返回的是下载流、长连接或持续事件，业务可能不能一次性 io.ReadAll。这时应该边读边处理，在业务确定结束、取消或发生错误时关闭 Body。强行把无限流读到 EOF 会让业务本身无法结束；而只依赖连接复用也不应成为流式处理的前置条件。

另一个常见误区是只写 resp.Body.Close()，却从不读取响应体。关闭 Body 是必须动作，但对于希望稳定复用的普通 HTTP/1.x 响应，读完并关闭更稳妥。大响应体则要结合内存、超时和业务协议做取舍，不能机械复制小 JSON 的写法。

把同一个 Transport 放进长生命周期

如果要调整连接池参数，可以从默认 Transport 克隆一份，再把它交给一个共享的 Client。不要在每个请求里创建新的 Transport，也不要把关闭空闲连接当成每次请求的清理步骤。

package main

import (
    "net/http"
    "time"
)

// Clone 保留默认 Transport 的基础行为，再集中调整连接池参数。
var transport = func() *http.Transport {
    base := http.DefaultTransport.(*http.Transport).Clone()
    base.MaxIdleConns = 100                  // 限制所有目标主机共享的空闲连接总量。
    base.MaxIdleConnsPerHost = 16            // 控制同一主机保留的空闲连接数量。
    base.IdleConnTimeout = 90 * time.Second  // 空闲连接超过时长后由 Transport 回收。
    return base
}()

var sharedClient = &http.Client{
    Transport: transport,
    Timeout:   10 * time.Second, // 这是请求总超时，不替代连接空闲回收。
}

参数没有一套对所有服务都合适的固定值：并发量高、目标主机少时，通常要关注 MaxIdleConnsPerHost；目标主机很多时，还要关注总的 MaxIdleConns。IdleConnTimeout 则用于限制空闲连接的存活时间，避免长期不使用的连接一直占着资源。

不要在这些地方主动阻止复用

排查复用失败时，先找显式的“关闭连接”设置：

• 请求的 Request.Close 被设为 true，会要求请求结束后不复用 TCP 连接。
• Transport 的 DisableKeepAlives 被设为 true，会关闭持久连接复用。
• 每次调用都创建新的 Client 或 Transport，旧连接池没有机会服务后续请求。
• 代码在每个请求完成后调用 CloseIdleConnections，会主动清掉刚刚可供复用的空闲连接。

CloseIdleConnections 不是错误 API，它适合配置切换、服务关闭或明确的资源回收边界。问题在于把它放进普通请求循环，这会把连接池设计成“请求结束即清空”。

用 httptrace 判断到底有没有复用

不要只凭耗时猜连接是否复用。httptrace.ClientTrace.GotConn 可以得到 GotConnInfo，其中 Reused 表示连接是否已经被之前的请求使用，WasIdle 和 IdleTime 可帮助判断它是否来自空闲池。

package main

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

func requestWithTrace(ctx context.Context, client *http.Client, url string) error {
    trace := &httptrace.ClientTrace{
        GotConn: func(info httptrace.GotConnInfo) {
            // 只记录连接来源状态，不打印请求头和响应敏感内容。
            fmt.Printf("reused=%t wasIdle=%t idle=%s\\n", info.Reused, info.WasIdle, info.IdleTime)
        },
    }
    req, err := http.NewRequestWithContext(httptrace.WithClientTrace(ctx, trace), http.MethodGet, url, nil)
    if err != nil {
        return fmt.Errorf("创建请求：%w", err)
    }
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close() // 观测请求也必须遵守响应体生命周期。
    return nil
}

如果连续请求的 Reused 都是 false，按这个顺序检查：Client 是否真的共享、Transport 是否被替换、响应体是否及时关闭、请求是否设置了 Close、Transport 是否禁用了 keep-alive，以及服务端是否主动返回了关闭连接的信号。对于 HTTP/2，不要把“是否建立了新 TCP 连接”当成唯一指标，因为多个请求可能复用同一条连接上的不同流。

一张表记住连接复用条件

常见问题

只调用 Body.Close，不读取 Body，连接一定不能复用吗？

不能用“一定”概括所有协议和版本，但对希望稳定复用的普通 HTTP/1.x 响应，读到 EOF 后再关闭更可靠。关闭时 Transport 也可能异步尝试读取有限内容，因此代码仍要根据响应大小和业务类型选择策略。

是不是把 MaxIdleConnsPerHost 调得越大越好？

不是。它只控制同一主机的空闲连接保留量；过大可能占用更多客户端和服务端资源，过小则可能让突发并发反复建连。应结合 GotConnInfo、请求并发和服务端限制调整。

为什么 Client 共享了，还是看不到复用？

先确认共享的是同一个 Transport，而不是只共享了 Client 外壳；再确认 Body 被正确处理、没有设置 Request.Close 或 DisableKeepAlives，最后再看服务端响应和 HTTP 版本。用 httptrace 的字段做证据，比只看请求耗时更容易定位。

总结一下：共享 Client/Transport 是连接池存在的前提，普通响应读完并关闭 Body 是连接回到复用路径的重要条件，连接池参数只应按实际并发和空闲行为调整。遇到复用异常时，用 GotConnInfo 先观察，再检查生命周期和显式禁用项。