httpProtocols配置HTTP协议集合

Go 1.24 起，可以用 http.Protocols 显式配置 HTTP/1、TLS 上的 HTTP/2，以及明文 TCP 上的 HTTP/2。最小写法是创建一个协议集合，再按需要调用 SetHTTP1、SetHTTP2 或 SetUnencryptedHTTP2。要注意：这个集合的零值是空集合，写成 new(http.Protocols) 后如果一个开关都不打开，就不是“使用默认协议”。

先把协议集合写成显式配置

http.Protocols 是一组开关，而不是一个只容纳单值的枚举。HTTP/1 同时覆盖 HTTP/1.0 和 HTTP/1.1；HTTP2 针对 TLS 连接；UnencryptedHTTP2 针对没有 TLS 的 HTTP/2。通常先从“允许 HTTP/1 和 HTTPS 上的 HTTP/2”开始：

package main

import "net/http"

func defaultProtocols() *http.Protocols {
	protocols := new(http.Protocols)
	protocols.SetHTTP1(true) // 保留 HTTP/1.0 和 HTTP/1.1
	protocols.SetHTTP2(true) // 允许 TLS 连接上的 HTTP/2
	return protocols
}

需要检查配置时，直接使用同名查询方法即可。它们返回的是当前集合是否包含该协议，不代表某个请求已经完成协商：

func describe(p *http.Protocols) string {
	if p == nil {
		return "使用所属组件的默认协议集合" // nil 与空集合不是同一语义
	}
	return p.String() // 便于日志中记录当前组合
}

服务端用 Server.Protocols 明确接收范围

服务端把集合放到 http.Server.Protocols。只接收 HTTP/1 时只打开 HTTP/1；同时接收 HTTP/1 和 HTTP/2 时打开前两个开关。明文 HTTP/2 是独立选项，适合已经明确采用 h2c 连接模型的内网场景，不要因为打开了 HTTPS 上的 HTTP/2 就认为它也会自动接受明文 HTTP/2。

package main

import (
	"log"
	"net/http"
)

func main() {
	srv := &http.Server{
		Addr: ":8443",
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			w.WriteHeader(http.StatusNoContent) // 用最小响应确认请求已进入处理器
		}),
		Protocols: new(http.Protocols),
	}
	srv.Protocols.SetHTTP1(true) // 接收 HTTP/1
	srv.Protocols.SetHTTP2(true) // 通过 TLS 接收 HTTP/2

	log.Fatal(srv.ListenAndServeTLS("cert.pem", "key.pem")) // 证书由部署环境提供
}

如果只想让一个端口接受明文 HTTP/2，可以把 SetUnencryptedHTTP2(true) 打开；如果同时需要兼容普通 HTTP/1，则把 SetHTTP1(true) 也打开。协议集合只决定接收范围，证书、监听地址和客户端实际协商仍由部署条件决定。

客户端用 Transport.Protocols 控制协商

客户端的协议集合放在可复用的 http.Transport 上，而不是每次请求临时创建。下面的配置允许 HTTP/1，并在 HTTPS 连接上尝试 HTTP/2：

package main

import (
	"log"
	"net/http"
)

func newClient() *http.Client {
	tr := http.DefaultTransport.(*http.Transport).Clone() // 复用默认连接参数
	tr.Protocols = new(http.Protocols)
	tr.Protocols.SetHTTP1(true) // 兼容普通 HTTP 请求
	tr.Protocols.SetHTTP2(true) // 允许 HTTPS 上的 HTTP/2
	return &http.Client{Transport: tr}
}

func fetch() error {
	res, err := newClient().Get("https://example.com/")
	if err != nil {
		return err // 连接或协商失败交给调用方处理
	}
	defer res.Body.Close() // 及时归还连接池资源
	return nil
}

var _ = log.Print // 示例只展示配置，实际项目可记录 res.Proto

如果给 Transport 设置了自定义 Dial、DialTLS 或 TLS 配置，默认行为会更保守，可能不再自动尝试 HTTP/2；这时显式设置 Protocols，或者按官方说明评估 ForceAttemptHTTP2，比猜测连接版本可靠。

参数与边界速查

排查时按三项记录：请求 URL 是 http:// 还是 https://，目标是服务端还是客户端，以及集合中三个查询方法各自返回什么。再查看响应的 res.Proto 或服务端日志，才能判断实际协商结果；只看配置对象本身，只能证明“允许范围”，不能证明“本次连接用了哪个版本”。

常见问题

new(http.Protocols) 是否等于默认配置？

不等于。它得到空集合；默认策略只在 Server.Protocols 或 Transport.Protocols 保持 nil 时由所属组件决定。

打开 SetHTTP2(true) 后能访问明文 HTTP/2 吗？

不能直接这样推断。HTTP2 表示 TLS 上的 HTTP/2，明文 HTTP/2 需要另开 SetUnencryptedHTTP2(true)，并且两端连接模型要匹配。

为什么客户端配置了 HTTP/2 仍然使用 HTTP/1？

协议开关只是允许范围，最终还取决于 URL、TLS、服务端支持和协商结果。先确认目标是 HTTPS，再记录 res.Proto，不要只凭配置字段判断。