Go net/http Transport.TLSNextProto 怎样注册协议处理器

如果你在 http.Transport 里看到 TLSNextProto，不要把它理解成“打开 HTTP/2 的开关”。它真正做的是：TLS 完成 ALPN 协商后，Transport 根据协商出的协议名查找一个函数；函数接收请求的 authority 和已经建立的 *tls.Conn，再返回负责后续请求的 http.RoundTripper。

因此，注册协议处理器的核心写法是给 map[string]func(string, *tls.Conn) http.RoundTripper 添加映射。这个扩展点很低层，处理器需要自己承担协议实现和连接生命周期；如果只是想让普通客户端使用 HTTP/2，优先考虑 Transport.Protocols，不要为了“切换协议”直接改写 TLSNextProto。

先看 TLSNextProto 到底接管了哪一段

Transport 先建立 TLS 连接，TLS 的 ALPN 协商会产生一个协议名，例如 h2。当 TLSNextProto 非空且包含这个键时，对应函数会被调用。回调返回的 RoundTripper 随后负责处理请求；它不是一次性的观察回调，而是连接协议切换后的请求入口。

官方文档给出的关键约束有三个：

• map 的键是协商出的协议名，而不是 URL scheme；常见例子是 h2。
• 回调拿到的 authority 类似 example.com 或 example.com:1234，它描述请求目标的权威主机。
• 回调必须返回一个 RoundTripper，后续请求由它处理；不能只返回 nil 来表示“稍后再处理”。

按签名注册一个协议处理器

下面的代码只演示注册契约和连接交接，不伪装成完整的 HTTP/2 协议实现。真正的处理器需要按照协商出的协议读取和写入 TLS 连接；示例中的 inspectRoundTripper 用错误返回明确标出“协议栈尚未接入”，便于先核对映射是否写对。

package main

import (
	"crypto/tls"
	"fmt"
	"net/http"
)

// inspectRoundTripper 只是说明图对应的占位处理器，不负责实现 h2 帧。
type inspectRoundTripper struct {
	authority string
	conn      *tls.Conn
}

// RoundTrip 必须承担协商后协议的真正请求处理；这里故意返回边界错误。
func (r *inspectRoundTripper) RoundTrip(*http.Request) (*http.Response, error) {
	return nil, fmt.Errorf("协议处理器尚未实现: %s", r.authority)
}

// newProtocolHandler 按 TLSNextProto 的要求接收 authority 和 TLS 连接。
func newProtocolHandler(authority string, conn *tls.Conn) http.RoundTripper {
	// 连接已由 Transport 建立；处理器应明确记录并接管它的生命周期。
	return &inspectRoundTripper{authority: authority, conn: conn}
}

func newTransport() *http.Transport {
	return &http.Transport{
		TLSNextProto: map[string]func(string, *tls.Conn) http.RoundTripper{
			// h2 是 ALPN 协商出的协议名，不是 http:// URL 的 scheme。
			"h2": newProtocolHandler,
		},
	}
}

这段映射里最容易写错的是函数类型：第一个参数是 string，第二个参数是 *tls.Conn，返回值是 http.RoundTripper。如果把它写成接收 *http.Request 的函数，那是普通请求处理逻辑，不能直接放进 TLSNextProto。

authority 和 TLS 连接不能被当成普通参数

authority 应用于协议层需要知道目标主机的场景，例如建立连接状态、生成协议握手上下文或区分同一处理器服务的不同目标。它不是完整 URL，也不应被重新拼成另一个请求地址。

第二个参数是已建立的 TLS 连接。回调接管后，后续处理器必须负责它的使用和关闭策略。示例把连接保存到结构体，只是为了突出所有权边界；在真实实现中，应由协议处理器在连接关闭、握手失败和 Transport 退出时保持一致的清理路径。

type protocolRoundTripper struct {
	authority string
	conn      *tls.Conn
}

// closeOnce 保证错误路径和正常结束路径不会重复关闭底层连接。
type closeOnce struct {
	closed bool
}

func (p *protocolRoundTripper) closeConnection() error {
	if p.conn == nil {
		return nil // 没有连接时不执行无意义的清理。
	}
	// 真实协议实现应把关闭动作放进统一的连接状态机。
	return p.conn.Close()
}

这里不建议把同一个 *tls.Conn 再交给另一个 Transport 的默认 HTTP/1 逻辑。TLSNextProto 的意义是把连接交给对应的替代协议处理器；重复套用普通 RoundTripper，往往会让协议字节和连接关闭责任互相冲突。

为什么 TLSNextProto 非 nil 会影响 HTTP/2

当前 Go 文档明确说明：只要 TLSNextProto 非 nil，HTTP/2 就不会自动启用。即使 map 里没有 h2，也不能把它当作“我只注册了另一个协议，所以 HTTP/2 仍会照常自动接入”。如果你的目标只是控制 HTTP/1、HTTP/2 或明文 HTTP/2，使用 Transport.Protocols 更直接。

func transportForOrdinaryHTTP2() *http.Transport {
	return &http.Transport{
		// 普通客户端只表达支持哪些协议，不接管 TLS 连接。
		Protocols: new(http.Protocols),
	}
}

func transportWithCustomDialer() *http.Transport {
	return &http.Transport{
		// 自定义 DialContext 或 TLSClientConfig 时，按需允许尝试 HTTP/2。
		ForceAttemptHTTP2: true,
	}
}

上面的片段只表达配置职责，具体的 Protocols 位设置应根据项目支持的 Go 版本和目标协议补全。重要的是不要把 ForceAttemptHTTP2 当成 TLSNextProto 的替代回调：前者控制尝试 HTTP/2，后者改变 TLS 协议协商后的连接接管方式。

注册前后的判断清单

结论：把 TLSNextProto 当成协议接管点

TLSNextProto 的正确用法可以概括为“协议名映射到连接级 RoundTripper”：TLS ALPN 选出协议名，Transport 调用对应函数，处理器接管 TLS 连接并处理后续请求。它适合需要自己控制协议接管边界的底层场景；普通 HTTP/2 客户端配置则应优先使用更明确的 Protocols。

相关问题：

• TLSNextProto 的 map 键为什么不是 https？
• 给 TLSNextProto 设置空 map 会不会自动启用 HTTP/2？
• 自定义 DialContext 后应该检查 ForceAttemptHTTP2 哪些边界？