Go TLS 怎样声明 ALPN 协议列表

在 Go 里启用 HTTPS 时，证书和 TLS 版本并不是应用层协议协商的全部。浏览器、反向代理或自定义客户端还可能通过 ALPN 告诉服务端自己支持 h2、http/1.1 等协议。Go 把这份候选列表放在 tls.Config.NextProtos 中，握手完成后再从 ConnectionState.NegotiatedProtocol 读取结果。

官方文档：https://go.dev/src/crypto/tls/common.go

最实用的记法是：两端各自声明“我支持什么”，只有存在共同协议时才会得到非空的协商结果。本文只讨论 NextProtos 与协商结果，不把它和 TLS 版本、密码套件混为一谈。

先分清 NextProtos 和 TLS 版本

NextProtos 描述的是 TLS 握手之后，连接准备承载哪一种应用层协议；它不是 MinVersion 或 MaxVersion，也不是证书配置。比如 tls.VersionTLS13 只决定 TLS 版本范围，而 []string{"h2", "http/1.1"} 表示 HTTP/2 和 HTTP/1.1 的应用层候选。

客户端和服务端的配置可以分别写成：

clientConfig := &tls.Config{
    // 按客户端偏好声明应用层协议，优先尝试 HTTP/2。
    NextProtos: []string{"h2", "http/1.1"},
}

serverConfig := &tls.Config{
    // 服务端只声明自己确实能处理的协议，避免协商后无法接管连接。
    NextProtos: []string{"h2", "http/1.1"},
}

这里的列表不是把协议“强行打开”。客户端有候选、服务端没有共同项时，结果仍然取决于双方的配置和 TLS 实现规则。

客户端怎样声明 ALPN 候选

客户端通常在发起连接前创建一份 tls.Config，把候选协议放入 NextProtos。连接成功后，调用 ConnectionState() 查看实际选中的协议，而不要仅凭配置数组推断结果。

package main

import (
    "context"
    "crypto/tls"
    "fmt"
    "net"
    "time"
)

func dialWithALPN(ctx context.Context, address string) error {
    config := &tls.Config{
        // 先声明偏好的协议；这里没有关闭证书校验。
        NextProtos: []string{"h2", "http/1.1"},
        ServerName: "example.com",
    }

    dialer := &net.Dialer{Timeout: 5 * time.Second}
    // 使用 DialContext 保留调用方的取消和超时语义。
    rawConn, err := dialer.DialContext(ctx, "tcp", address)
    if err != nil {
        return fmt.Errorf("连接 %s 失败: %w", address, err)
    }

    conn := tls.Client(rawConn, config)
    // 握手必须成功后再读取协商状态；失败时及时关闭底层连接。
    if err := conn.HandshakeContext(ctx); err != nil {
        _ = rawConn.Close()
        return fmt.Errorf("TLS 握手失败: %w", err)
    }
    defer conn.Close()

    state := conn.ConnectionState()
    fmt.Printf("协商协议: %q\n", state.NegotiatedProtocol)
    return nil
}

NegotiatedProtocol 是最终结果：如果服务端选择了 h2，这里就是 "h2"；如果没有应用层协议被协商，它可能是空字符串。生产代码应把这个结果交给后续协议处理层，而不是把 NextProtos[0] 当作事实。

服务端怎样声明自己能处理的协议

服务端的 NextProtos 应该和实际的连接处理能力保持一致。使用 http.Server 时，Go 的 HTTP/TLS 集成会根据配置参与 ALPN；如果是自定义协议，就需要由自己的连接处理器负责解释协商结果。

func newTLSServer(certFile, keyFile string) (*tls.Config, error) {
    certificates, err := tls.LoadX509KeyPair(certFile, keyFile)
    if err != nil {
        return nil, fmt.Errorf("加载证书失败: %w", err)
    }

    return &tls.Config{
        // 只发布服务端已经实现的协议，顺序表达服务端偏好。
        Certificates: []tls.Certificate{certificates},
        NextProtos:   []string{"h2", "http/1.1"},
        MinVersion:   tls.VersionTLS12,
    }, nil
}

如果服务端只实现 HTTP/1.1，却把 h2 写进列表，协商层可能给出一个服务端无法正确处理的结果。协议声明应当跟代码能力一起变更：增加处理器时加入候选，移除处理器时同步删除。

对于需要按客户端信息选择配置的场景，可以通过 GetConfigForClient 返回不同的 tls.Config，但每份配置的 NextProtos 仍然应当表示该连接实际可用的协议集合。

匹配、空结果和不匹配怎样区分

最容易混淆的是“没有协商协议”和“握手失败”。它们不是一回事：

• 两端存在共同协议：握手成功，NegotiatedProtocol 通常是共同项之一。
• 一端或两端没有声明 ALPN：连接可能成功，但协商结果为空，后续应按未协商路径处理。
• 配置明确要求必须匹配，而双方没有共同协议：握手可能失败，调用方应记录原始错误并结束连接。

func requireProtocol(conn *tls.Conn, want string) error {
    state := conn.ConnectionState()
    // 空结果表示没有得到 ALPN，不要把它误写成 want。
    if state.NegotiatedProtocol == "" {
        return fmt.Errorf("没有协商出应用层协议，期望 %q", want)
    }
    // 只在业务确实要求固定协议时做强校验。
    if state.NegotiatedProtocol != want {
        return fmt.Errorf("协商协议为 %q，不是期望的 %q", state.NegotiatedProtocol, want)
    }
    return nil
}

这段检查适合“必须使用 HTTP/2”或“必须使用某个自定义协议”的入口。对于同时兼容多个协议的客户端，不要写死一个结果，而是根据实际协商值选择对应的编解码器。

接入 HTTPS 时怎样避免只改一端

最稳妥的做法是把协议清单视作一个小型能力契约：客户端列出可接受的候选，服务端列出已实现的候选，连接建立后由结果驱动处理分支。使用标准 HTTP 服务时，可以让 http.Server 和 TLS 配置共用同一份协议意图。

func serveHTTPS(addr, certFile, keyFile string, handler http.Handler) error {
    config, err := newTLSServer(certFile, keyFile)
    if err != nil {
        return err
    }

    server := &http.Server{
        Addr:      addr,
        Handler:   handler,
        TLSConfig: config,
    }
    // ListenAndServeTLS 会使用 TLSConfig 中的证书和 ALPN 候选。
    return server.ListenAndServeTLS("", "")
}

如果项目依赖 HTTP/2 的特性，启动后仍应通过客户端连接状态或应用层请求路径确认处理分支，而不是仅检查 NextProtos 是否存在。配置文件、反向代理和应用服务也要保持同一份协议约定，否则中间层可能只接受 http/1.1。

常见边界和配置取舍

协议名是通信契约的一部分，建议集中定义常量，避免一处写 http/1.1、另一处误写成不同字符串。列表顺序用于表达偏好，但不能替代双方共同支持的事实。

结论

1. tls.Config.NextProtos 用来声明应用层协议候选，不负责选择 TLS 版本。
2. 客户端和服务端都要写入自己真正支持的协议，握手后用 ConnectionState().NegotiatedProtocol 读取事实结果。
3. 结果为空可能表示没有启用 ALPN；没有共同协议时是否失败取决于握手与业务约束，不能统一当成成功。
4. 接入 HTTPS 时要同步检查应用、代理和服务端的协议能力，避免声明了没有实现的 h2。

相关问题

NextProtos 是不是 TLS 版本列表？不是。它描述应用层协议，TLS 版本由 MinVersion 和 MaxVersion 控制。

为什么 NegotiatedProtocol 为空？常见原因是没有一端声明 ALPN，或者双方没有启用共同的应用层协议。

客户端和服务端的 NextProtos 顺序必须相同吗？不要求完全相同，但两端必须有共同项，且应把更符合各自能力和偏好的协议放在前面。