Go tls.ConnectionState.NegotiatedProtocol 为空怎样判断 ALPN 是否协商成功

Go 里看到 tls.ConnectionState.NegotiatedProtocol 为空，先不要把它当成 TLS 握手失败。这个字段表示握手完成后通过 ALPN 协商出的应用层协议；如果没有配置 NextProtos，或者对端没有使用 ALPN，连接仍可能成功但结果为空。只有在握手完成后读取，空值才有诊断意义。

官方文档入口：https://pkg.go.dev/crypto/tls#ConnectionState

判断顺序是：先确认 HandshakeComplete，再对照连接两端的 NextProtos，最后区分“没有启用 ALPN”和“启用了但没有共同协议”。不要用空字符串去推断 TLS 版本或证书是否有效。

先确认空值是不是读取得太早

值班时最容易遇到的误判，是在创建 tls.Conn 后立即调用 ConnectionState()。Go 官方文档说明，返回的状态只有在握手完成后才有意义；首次读写会自动触发握手，也可以显式调用 Handshake 或 HandshakeContext。

func readALPN(conn *tls.Conn) (string, error) {
    // 显式完成握手，避免把尚未填充的 ConnectionState 当成协商结果。
    if err := conn.Handshake(); err != nil {
        return "", fmt.Errorf("TLS 握手失败: %w", err)
    }

    state := conn.ConnectionState()
    // HandshakeComplete 是读取协商字段前的最低判断条件。
    if !state.HandshakeComplete {
        return "", errors.New("TLS 握手尚未完成")
    }
    return state.NegotiatedProtocol, nil
}

如果这里直接返回握手错误，问题还没有进入“ALPN 为空”的分支。先记录错误本身；只有握手成功并且 HandshakeComplete 为真，才继续分析空字符串。

检查客户端和服务端的 NextProtos

Config.NextProtos 是一组应用层协议名，双方需要对 ALPN 的使用有一致预期。比如服务端期望接收 HTTP/2，通常要把 h2 放进服务端配置；客户端也要声明自己支持的协议。协议名是精确字符串，h2、http/1.1 不能写成随意的别名。

func tlsConfigForHTTP2(cert tls.Certificate) *tls.Config {
    // NextProtos 表示应用层协议偏好，不是 TLS 版本配置。
    return &tls.Config{
        Certificates: []tls.Certificate{cert},
        NextProtos:   []string{"h2", "http/1.1"},
        MinVersion:   tls.VersionTLS12,
    }
}

func hasProtocol(protocols []string, wanted string) bool {
    // 逐项比较协议名，避免把“配置了其他协议”误当成目标协议已启用。
    for _, protocol := range protocols {
        if protocol == wanted {
            return true
        }
    }
    return false
}

这里的 MinVersion 只是在示例中表达 TLS 安全下限，它和 ALPN 是两层配置。检查 HTTP/2 是否可能协商时，重点看两端是否都出现 h2，不要只看 TLS 版本。

把 NegotiatedProtocol 为空拆成三个原因

空字符串本身不是完整结论。结合连接结果和配置，可以按下面的分支处理：

尤其要注意最后两行：对端完全不支持 ALPN 时，空值可能和“本端没配置”表现相同；而双方都参与 ALPN 协商但没有共同协议时，连接可能直接失败。不能仅凭空字符串区分这两种情况，需要结合两端配置和握手错误。

用一条诊断记录确认真实协商结果

排障记录建议同时放入 HandshakeComplete、NegotiatedProtocol、TLS 版本和握手错误。这样后续看日志时，可以判断是读取时机、协议列表还是连接本身出了问题。

type TLSALPNReport struct {
    HandshakeComplete bool
    Protocol          string
    TLSVersion        uint16
}

func reportALPN(conn *tls.Conn) (TLSALPNReport, error) {
    // 统一在一次握手后读取状态，避免日志中的字段来自不同时间点。
    if err := conn.Handshake(); err != nil {
        return TLSALPNReport{}, fmt.Errorf("TLS 握手失败: %w", err)
    }
    state := conn.ConnectionState()
    report := TLSALPNReport{
        HandshakeComplete: state.HandshakeComplete,
        Protocol:          state.NegotiatedProtocol,
        TLSVersion:        state.Version,
    }
    // 空协议只表示 ALPN 没有产出结果，不能伪造一个默认协议名。
    if report.Protocol == "" {
        return report, nil
    }
    return report, nil
}

如果业务必须使用 HTTP/2 或其他协议，可以在得到空值时让上层明确报错，例如“未协商 h2”，而不是把它悄悄降级成未知成功。对普通 TLS 通道，空值可能完全正常；业务要求决定了它是信息还是故障。

配置变更失败时怎样回滚和复盘

如果刚上线的 ALPN 配置让握手失败，先回退“应用协议期望”这一层：恢复上一版双方都能接受的 NextProtos，保留现有证书校验和 TLS 最低版本。不要为了让连接恢复，就关闭证书验证或降低 MinVersion。

复盘时至少保留四项：客户端实际发送的协议列表、服务端发布的协议列表、ConnectionState 中的最终协议和握手错误。若中间有代理或网关，还要确认它是否终止并重新建立了 TLS；前后两段连接的 ALPN 结果不一定相同。

常见问题

NegotiatedProtocol 为空是不是 TLS 1.2？不是。它只描述 ALPN 应用层协议，TLS 版本应读取 ConnectionState.Version。

只在服务端配置 h2，客户端没写可以吗？不能把它当成已协商。ALPN 需要双方对协议有共同声明，最终应以握手后的 NegotiatedProtocol 为准。

NegotiatedProtocolIsMutual 能不能拿来判断成功？不建议。当前 Go 文档标记该字段已弃用且始终为 true，应使用 NegotiatedProtocol 和握手结果。

小结

处理 NegotiatedProtocol 为空时，先确认握手完成，再核对两端 NextProtos，最后结合对端能力和握手错误区分原因。空值可能是正常的“未使用 ALPN”，也可能暴露协议配置不一致；真正可靠的判断来自握手后的连接状态，而不是一个提前读取的空字符串。