Go http.Transport DialTLSContext 自定义 TLS 连接的配置方法与 HTTP/2 边界

给 http.Transport 配置 DialTLSContext 后，最容易出现的误判是“只是换了一个拨号函数”。实际上它会直接接管非代理 HTTPS 请求的 TLS 连接建立：Dial、DialContext 不再负责这类请求，TLSClientConfig 和 TLSHandshakeTimeout 也不会替你完成握手。自定义函数必须返回已经完成 TLS 握手的连接，否则后面的 HTTP 请求就没有可靠的协议状态。

官方地址：https://pkg.go.dev/net/http#Transport

先确定 DialTLSContext 接管的范围

Transport.DialTLSContext 的范围比名字看起来窄。它用于非代理 HTTPS 请求的 TLS 连接；如果请求经过 HTTP 代理，连接过程会先经过代理的 CONNECT 处理；普通 http:// 请求则仍然走 DialContext。排查时先记录 URL scheme、是否命中代理和最终目标地址，不要看到回调没触发就马上修改 TLS 参数。

用 context 控制自定义 TLS 拨号

自定义回调应把传入的 context.Context 传给底层拨号器，并在连接成功后用 tls.Client 完成握手。下面的示例把目标地址拆成主机名，给 TLS 配置设置 ServerName，同时在任何失败分支关闭已经创建的底层连接。生产环境不要用跳过证书校验的配置。

func dialTLS(ctx context.Context, network, addr string) (net.Conn, error) {
    // 使用传入的 context，让请求取消可以中断 TCP 建连。
    raw, err := (&net.Dialer{Timeout: 5 * time.Second}).DialContext(ctx, network, addr)
    if err != nil {
        return nil, err
    }

    host, _, err := net.SplitHostPort(addr)
    if err != nil {
        // 已经建立的底层连接不能泄漏，解析失败时立即关闭。
        _ = raw.Close()
        return nil, fmt.Errorf("解析 TLS 地址失败: %w", err)
    }

    cfg := &tls.Config{ServerName: host, MinVersion: tls.VersionTLS12}
    conn := tls.Client(raw, cfg)
    if err := conn.HandshakeContext(ctx); err != nil {
        // 握手失败时关闭 TLS 包装和底层连接。
        _ = conn.Close()
        return nil, fmt.Errorf("TLS 握手失败: %w", err)
    }
    return conn, nil
}

这个回调返回后，Transport 会把连接当成已经完成 TLS 握手的连接使用。证书校验、SNI 和握手超时如果没有在回调里实现，就不能指望 Transport.TLSClientConfig 或 TLSHandshakeTimeout 再替你补上。

被绕过的参数要重新放回同一层

自定义 TLS 拨号最常见的故障是“配置写了但没有效果”。原因不是字段失效，而是责任已经转移到回调：

• TLSClientConfig：回调自己创建 tls.Config 后，Transport 不会自动把它合并进来。
• TLSHandshakeTimeout：回调自己调用 HandshakeContext 时，应由 context deadline 或自定义计时策略控制。
• DialContext：对非代理 HTTPS 请求不会再承担 TCP 建连职责；若需要统一观测，要在两个入口分别记录。
• Proxy：代理路径另有 CONNECT 语义，不能用非代理连接的计时和证书结论直接替代。

建议把“拨号开始、TCP 成功、TLS 握手成功、协商协议”作为四个独立观测点。日志只记录网络地址、耗时和协议名，不记录证书私钥、Authorization 或完整用户凭据。

保留 ALPN，才有讨论 HTTP/2 的基础

如果回调返回普通的自定义 net.Conn，Transport 可能无法读取 TLS 的连接状态，ALPN 协商结果也就无法按预期参与后续协议选择。官方文档建议返回 *tls.Conn，或者返回实现了与 *tls.Conn 相同 ConnectionState 能力的连接。

需要 HTTP/2 时，在 tls.Config.NextProtos 中保留 h2 与 http/1.1 的协商意图，并确认 Transport 的 HTTP/2 选项没有因为自定义拨号而被保守关闭。不要把“返回的是 TLS 连接”误认为“HTTP/2 一定成功”：服务端 ALPN、Transport 协议设置和自定义连接的状态暴露缺一不可。

tr := &http.Transport{
    // 自定义 TLS 拨号后，HTTPS 请求不会再使用 DialContext。
    DialTLSContext: dialTLS,
    // 自定义拨号或 TLS 配置时，显式允许 Transport 尝试 HTTP/2。
    ForceAttemptHTTP2: true,
}

client := &http.Client{Transport: tr}
resp, err := client.Get("https://example.com/health")
if err != nil {
    return err
}
// 响应体必须关闭，才能让连接有机会回到连接池复用。
defer resp.Body.Close()
fmt.Println(resp.Proto)

用四个证据点完成排查

遇到 HTTP/2 没启用、证书参数不生效或取消请求仍然等待时，可以按下面顺序检查：一是回调是否真的接收到非代理 HTTPS 请求；二是返回连接前是否完成了握手；三是 ConnectionState().NegotiatedProtocol 是否出现预期协议；四是取消 context 后 TCP 拨号和握手是否都能返回。只改 ForceAttemptHTTP2 而不检查第三项，通常只能得到一个模糊的“还是 HTTP/1.1”。

常见问题

设置 DialTLSContext 后为什么 DialContext 没有日志？

对非代理 HTTPS 请求，这是预期行为。DialTLSContext 会直接接管 TLS 连接创建；普通 HTTP 或代理链路要单独检查相应入口。

为什么配置了 TLSHandshakeTimeout 仍然握手很久？

如果握手是在自定义回调里完成，Transport 的握手超时字段不会自动包住这段代码。请用传入 context 设置 deadline，或在回调中实现明确的超时策略。

返回 tls.Conn 后 HTTP/2 仍然没有协商成功怎么办？

继续检查 TLS 配置里的 ALPN、服务端支持情况和 Transport 的协议开关。返回 TLS 连接只是必要条件，不代表服务端一定选择 h2。