Go TLS 连接怎样读取握手后的协商协议

在 Go 中读取 TLS 握手后的协商协议，核心代码只有两步：先调用 Handshake（或确保第一次读写已经触发握手），再读取 ConnectionState().NegotiatedProtocol。这个字段就是 ALPN 的结果，例如 h2；如果双方没有协商出应用层协议，它会保持为空。

官方资料：https://pkg.go.dev/crypto/tls

不要在握手完成前把 ConnectionState 当作最终结果。日志里最好同时记录 HandshakeComplete、NegotiatedProtocol、TLS 版本和密码套件，这样才能区分“还没握手”“握手成功但没有 ALPN”和“握手失败”。

先让 TLS 握手完成，再读取连接状态

tls.Conn 的握手通常会被第一次 Read 或 Write 自动触发，也可以显式调用 Handshake。如果代码的目的就是记录协商结果，显式调用更直观：错误先返回，成功后再读取状态。

package main

import (
	"crypto/tls"
	"fmt"
)

func readTLSState(conn *tls.Conn) error {
	// 显式完成握手，避免在握手未结束时读取到未准备好的状态。
	if err := conn.Handshake(); err != nil {
		return fmt.Errorf("TLS 握手失败: %w", err)
	}

	state := conn.ConnectionState()
	// HandshakeComplete 是后续字段可用于诊断的前提。
	if !state.HandshakeComplete {
		return fmt.Errorf("TLS 握手尚未完成")
	}

	fmt.Printf("protocol=%q version=%d cipher=%s resumed=%t\n",
		state.NegotiatedProtocol,
		state.Version,
		tls.CipherSuiteName(state.CipherSuite),
		state.DidResume,
	)
	return nil
}

这里的 NegotiatedProtocol 是字符串，适合直接写入结构化日志；Version 和 CipherSuite 是数值标识，使用 tls.CipherSuiteName 可以让密码套件日志更容易阅读。DidResume 则用于区分本次连接是否复用了之前的会话。

NegotiatedProtocol 为空时，先判断 ALPN 配置

空字符串不等于握手失败。客户端和服务端通过 tls.Config.NextProtos 声明支持的应用层协议，只有双方存在共同协议时，NegotiatedProtocol 才会得到具体值。没有配置 NextProtos、对端没有共同协议，或者连接本身还没有完成握手，都可能让日志里的协议字段为空，但判断方式不同。

func logNegotiatedProtocol(conn *tls.Conn) error {
	// 先确保状态来自已经完成的握手。
	if err := conn.Handshake(); err != nil {
		return err
	}

	state := conn.ConnectionState()
	switch {
	case !state.HandshakeComplete:
		// 这条分支表示状态读取时机不正确，而不是 ALPN 没配。
		return fmt.Errorf("握手状态未完成")
	case state.NegotiatedProtocol == "":
		// 空值只说明没有可记录的 ALPN 协议，TLS 连接仍可能是成功的。
		fmt.Println("TLS 已握手，但没有协商出 ALPN 协议")
	default:
		fmt.Printf("ALPN 协议: %s\n", state.NegotiatedProtocol)
	}
	return nil
}

如果业务只支持 HTTP/2，可以在应用层对空值做明确策略；如果业务同时允许 HTTP/1.1，则不要仅凭空字符串判定连接不可用。还要注意，NegotiatedProtocolIsMutual 已不适合作为新的判断入口，当前文档将它标记为弃用并说明该值始终为 true。

把协商结果放进客户端或服务端日志

诊断时建议把“协议结果”和“握手是否成功”放在同一条日志里。客户端可以在拨号并完成握手后记录；服务端则可以在接受连接、完成服务端握手后记录。两边都应保留 ServerName、TLS 版本和密码套件等必要上下文，但不要把证书原文或敏感业务数据直接写入普通日志。

func tlsLogFields(conn *tls.Conn) map[string]any {
	state := conn.ConnectionState()
	// 只整理诊断所需字段，不把证书内容写入业务日志。
	return map[string]any{
		"handshake_complete": state.HandshakeComplete,
		"alpn":               state.NegotiatedProtocol,
		"tls_version":        state.Version,
		"cipher_suite":       tls.CipherSuiteName(state.CipherSuite),
		"resumed":            state.DidResume,
		"server_name":        state.ServerName,
	}
}

当线上看到 alpn="" 时，可以按这个顺序排查：是否真的调用了握手、双方是否都设置了 NextProtos、协议名是否完全一致，以及当前连接是否经过了不支持 ALPN 的中间层。不要先修改证书或密码套件，因为它们与“有没有共同应用层协议”是不同层次的问题。

常见问题

为什么 ConnectionState 里的 NegotiatedProtocol 读出来是空字符串？

先确认握手已经完成，再检查双方的 NextProtos 是否存在共同协议。没有共同协议时 TLS 仍可能握手成功，因此空字符串不能单独当作网络错误。

读取 TLS 协议时一定要手动调用 Handshake 吗？

不一定。第一次 Read 或 Write 会自动触发握手；但如果要在连接建立阶段就记录协商结果，显式调用 Handshake 更容易把错误和状态读取放在同一条控制路径中。

总结：先完成握手，再读取 ConnectionState；用 NegotiatedProtocol 记录 ALPN，用 HandshakeComplete 判断读取时机，用 TLS 版本、密码套件和恢复标志补足诊断上下文。