Go net/http Transport.NewClientConn 怎样创建独立客户端连接

如果你需要“每次都创建一条不进入 Transport 连接池的客户端连接”，Go 1.26 开始可以直接调用 Transport.NewClientConn。它返回的是 *http.ClientConn：连接会按 scheme、address 和 Transport 的协议配置创建，但不会加入 Transport 的连接缓存，也不会被普通 Transport.RoundTrip 复用。使用结束后必须由调用方显式关闭。

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

需要连接池复用时继续使用 http.Client.Do；只有在确实需要一条独立连接、单独观察它的容量或单独控制关闭时，才选择 NewClientConn。

NewClientConn 解决的是什么问题

Transport 的普通请求路径会维护连接复用和空闲连接管理。NewClientConn 则把“创建一条独立的客户端连接”作为明确入口：即使 Transport 已经缓存了同一主机的连接，它仍会新建连接；这条连接不会加入缓存，也不计入 MaxIdleConns 和 MaxConnsPerHost。

这意味着它适合连接级协议实验、需要独立容量观察的长连接协作，或需要把这条连接的关闭责任交给当前组件的场景。它不是把普通 http.Client 换一个写法，也不是让所有请求自动绕过连接池。

按 scheme 和 address 创建 ClientConn

调用时需要传入创建上下文、协议方案和目标地址。http 表示未加密连接，https 表示使用 TLS；实际协议还会受到 Transport.Protocols 和服务端支持情况影响。连接创建成功后，要通过返回的 ClientConn.RoundTrip 发送请求。

package main

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

func requestOnDedicatedConn() error {
    transport := &http.Transport{}
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel() // 创建阶段超时后，及时释放上下文资源

    // scheme 决定是否使用 TLS，address 是目标主机和端口。
    conn, err := transport.NewClientConn(ctx, "https", "api.example.com:443")
    if err != nil {
        return fmt.Errorf("创建独立连接失败: %w", err)
    }
    defer conn.Close() // ClientConn 不归 Transport 缓存管理，由调用方关闭

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/health", nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }
    resp, err := conn.RoundTrip(req)
    if err != nil {
        return fmt.Errorf("独立连接请求失败: %w", err)
    }
    defer resp.Body.Close() // 响应体仍按普通 HTTP 响应规则关闭
    return nil
}

示例中的 api.example.com 只是占位地址，实际项目要替换成服务端地址。RoundTrip 发送请求时使用已创建的 ClientConn，不会再转回 Transport 的连接缓存路径。

不要把 ClientConn 当成普通连接池

ClientConn 提供的是一条可以承载请求的连接抽象，而不是 http.Client 的完整替代品。它的 RoundTrip 会把请求发到这条连接上；文档明确说明，此时请求 URL 或代理设置不会改变已经选定的连接。

需要留意三个边界：

• 连接每次都会新建，即使同一 Transport 已有目标主机的缓存连接。
• 连接不加入 Transport 缓存，不被 Transport.RoundTrip 使用，也不计入两个连接数限制。
• 它不会替你提供 Cookie、重定向等 http.Client 的高层语义；这些需求应继续走 Client.Do。

因此，普通业务请求、需要稳定复用和统一代理策略的请求，继续复用一个长期存在的 http.Client 更合适。为了“每个请求都独立”而频繁调用 NewClientConn，反而会失去连接复用并增加连接建立成本。

用状态方法管理创建、请求和关闭

在连接生命周期较长时，可以用 Available 查看当前还能无阻塞发送多少请求，用 InFlight 查看正在处理的请求数，用 Err 判断连接是否已经不可用。关闭动作仍然要由调用方负责；Close 会关闭连接并中断尚未完成的 RoundTrip。

func useConnState(conn *http.ClientConn) error {
    if conn.Err() != nil {
        return fmt.Errorf("连接不可用: %w", conn.Err())
    }

    // Available 是容量观察值，不能替代业务层的并发协调。
    if conn.Available() == 0 {
        return fmt.Errorf("当前连接没有可用发送容量")
    }
    fmt.Printf("可用容量=%d，进行中=%d\n", conn.Available(), conn.InFlight())
    return nil
}

这些方法适合做组件内部的状态展示和关闭前判断，但不要把某一次 Available 读取当成永久承诺：并发请求完成后容量会变化，连接错误也可能随时出现。

版本迁移时怎么选

NewClientConn 是 Go 1.26 新增的 API。迁移前先确认构建环境和部署环境都满足版本要求；如果项目仍要支持更早的 Go 版本，就不能直接在公共代码路径中引用它，应把这段能力隔离在对应版本的文件或构建约束中。

选择可以按下面的速查表判断：

常见问题

NewClientConn 创建的连接会被 Transport.RoundTrip 复用吗？

不会。它不加入 Transport 的连接缓存，也不会被 Transport.RoundTrip 使用。

连接会受到 MaxConnsPerHost 限制吗？

不会计入 Transport 的 MaxIdleConns 和 MaxConnsPerHost 限制，但这不代表可以忽略服务端容量或本地资源控制。

为什么创建成功后还要 defer Close？

因为这条连接不归 Transport 的缓存生命周期管理，官方文档把关闭责任交给调用方。把 Close 放在成功创建后的清理路径上，可以避免错误返回或请求结束时遗漏释放。