Go tls.Conn.HandshakeContext 取消后怎样判断连接是否还能复用

在 Go 里给 TLS 握手加超时，最容易留下一个误判：HandshakeContext 返回了取消或超时错误，但调用方仍把这条连接放回连接池，下一次读写才发现连接已经不可用。正确的判断不是“有没有拿到一个 *tls.Conn”，而是握手是否成功完成。

如果 context 在 TLS 握手完成前被取消，握手会被中断，连接应当关闭并丢弃；只有 HandshakeContext 返回 nil，且 ConnectionState().HandshakeComplete 为 true，才适合进入业务读写。握手完成之后，再取消原 context 不会影响这条连接。

官方文档：https://pkg.go.dev/crypto/tls#Conn.HandshakeContext

先分清 HandshakeContext 取消的是哪一段

HandshakeContext 只负责“尚未完成的 TLS 握手”。它接收的 context 不是整条连接的永久生命周期开关：握手已经完成后，后续取消这个 context 不会让已建立的 TLS 会话自动失效。

真正容易出问题的是握手中途。此时 tls.Conn 还没有可以交给业务层的完整加密状态，标准库需要终止这次握手。当前实现会把输入 context 的取消与底层连接关闭关联起来，所以不能把返回 context.Canceled 或 context.DeadlineExceeded 的连接理解成“稍后还能继续握手”。

图中要重点看三个边界：调用方持有 parent context，HandshakeContext 把它用于当前握手，TLS 状态则由连接内部维护；当取消发生在握手尚未完成时，底层 net.Conn 也不能再被当作一条干净的 TLS 连接复用。

为什么只看返回错误还不够

通常应该先看 err，再看握手状态。context.Canceled 和 context.DeadlineExceeded 能说明取消来源，但网络读写错误、证书校验失败、协议不匹配等问题同样会让握手失败。它们的共同点是：连接没有完成可交付给业务层的 TLS 建立过程。

ConnectionState 的字段在握手完成前没有完整意义，不能因为读到了某个版本或证书字段，就推断连接可以复用。对连接池来说，最小且稳定的规则是：

• 返回错误：关闭连接，不放回池中；
• 返回 nil：再确认 HandshakeComplete；
• 握手完成：才开始业务读写或交给上层连接管理。

这也是“错误分类”和“资源处置”要同时做的原因。错误可以用于日志、重试策略和指标标签，但是否保留连接首先由握手是否成功决定。

用一个小函数固定连接去留

下面的封装把握手超时、错误包装和关闭责任放在同一处。示例没有连接真实服务器，代码只展示生命周期决策；实际项目可以把返回成功的 *tls.Conn 交给后续协议层。

package tlsutil

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

// CompleteHandshake 只返回已经完成 TLS 握手的连接。
func CompleteHandshake(conn *tls.Conn, timeout time.Duration) error {
    ctx, cancel := context.WithTimeout(context.Background(), timeout)
    defer cancel() // 只释放本次握手的计时器，不代替关闭连接

    if err := conn.HandshakeContext(ctx); err != nil {
        // 取消、超时、证书和协议错误都不能把半成品连接交给业务层。
        _ = conn.Close()
        if errors.Is(err, context.Canceled) {
            return fmt.Errorf("TLS 握手被取消: %w", err)
        }
        if errors.Is(err, context.DeadlineExceeded) {
            return fmt.Errorf("TLS 握手超时: %w", err)
        }
        return fmt.Errorf("TLS 握手失败: %w", err)
    }

    state := conn.ConnectionState()
    if !state.HandshakeComplete {
        // 正常返回后仍确认状态，避免把异常状态当成可复用连接。
        _ = conn.Close()
        return errors.New("TLS 握手未完成")
    }
    return nil
}

这个函数有两个关键点。第一，defer cancel() 只回收本次 context 的计时资源，不能替代 conn.Close()。第二，错误路径统一关闭连接，成功路径再检查 HandshakeComplete，因此调用方不会拿到“握手没完成但看起来像连接”的对象。

用返回错误和 HandshakeComplete 决定连接去留

可以把连接处置抽象成一张很小的判断表：

注意不要把“原 context 已经取消”和“握手完成后 context 被取消”混为一谈。前者发生在握手窗口内，会影响这次建立过程；后者发生在握手成功之后，对已经完成的 TLS 连接没有持续控制作用。业务请求自己的超时，应另行设计读写 deadline 或请求级 context。

三个容易重复出现的坑

把 HandshakeContext 当成永久连接 context

它不是连接存活租约，只约束握手阶段。连接建立后，读写超时、服务端关闭和业务取消要由对应的读写 deadline、关闭逻辑或上层协议处理。

超时后只清空错误，不关闭连接

这样会把底层连接和半完成的 TLS 状态泄漏给后续调用。即使下一次读写再次触发握手，也不能把一个已经收到取消信号的连接当成可重试容器。

只看 ConnectionState 的版本字段

握手完成前，状态字段不应被当作成功证据。将 HandshakeComplete 作为唯一成功门槛更直接，也更容易在连接池、代理拨号和自定义协议代码中保持一致。

相关问题

HandshakeContext 返回 context.DeadlineExceeded 后能否重新调用？

不建议在同一条失败连接上继续尝试。关闭并重新建立底层连接，再使用新的 context 执行握手，边界最清楚。

握手成功后取消原 context 会不会关闭连接？

不会。官方文档明确区分了握手完成前后的行为；握手完成后，原 context 的取消不会影响这条连接。

只调用 Conn.Read 是否还需要显式握手？

不一定。标准库会在第一次 Read 或 Write 时自动触发握手；如果需要单独控制握手超时或在连接入池前确认状态，就显式调用 HandshakeContext。