Go tls.Conn 怎样用上下文限制握手时间

如果一个 tls.Conn 在握手阶段一直等待，对它直接调用 Handshake() 并不能表达“最多等多久”。更合适的做法是创建一个带超时的上下文，再调用 HandshakeContext(ctx)：上下文在握手完成前超时或被取消时，握手会被中断并返回错误。

官方参考地址：https://pkg.go.dev/crypto/tls#Conn.HandshakeContext

最小可靠方案是：context.WithTimeout 只包住握手调用；握手返回错误就关闭这条连接；握手成功后，当前上下文的取消不会替代后续读写超时策略。

先区分三段时间：拨号、TLS 握手和业务 I/O

工程里常把“连接超时”混成一个概念，但客户端至少有三段不同的等待：

• TCP 拨号：还没有建立底层网络连接，适合用 net.Dialer.DialContext。
• TLS 握手：底层连接已经拿到，正在协商协议、证书和密钥，适合用 tls.Conn.HandshakeContext。
• 后续读写：握手完成后传输业务数据，适合用 SetDeadline、SetReadDeadline 或 SetWriteDeadline。

tls.Conn 的第一次 Read 或 Write 也可能自动触发握手。因此，如果握手必须有独立预算，应该在第一次业务读写前显式调用 HandshakeContext。

用 WithTimeout 包住 HandshakeContext

下面的函数假设调用方已经有一个底层连接，并把它包装成客户端 TLS 连接。握手预算由调用方传入，函数只负责握手这一段；这样可以在不同业务场景复用，而不会偷偷改变整个请求的截止时间。

package tlsdemo

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

func handshakeWithin(ctx context.Context, raw net.Conn, cfg *tls.Config, budget time.Duration) (*tls.Conn, error) {
    // 先包装底层连接，再把握手预算限制在这一段。
    conn := tls.Client(raw, cfg)

    handshakeCtx, cancel := context.WithTimeout(ctx, budget)
    defer cancel() // 释放定时器，避免成功返回后继续保留计时资源。

    if err := conn.HandshakeContext(handshakeCtx); err != nil {
        // 握手没有完成时不要把半初始化连接交给上层继续读写。
        _ = conn.Close()
        if handshakeCtx.Err() != nil {
            return nil, fmt.Errorf("TLS 握手被取消或超时: %w", handshakeCtx.Err())
        }
        return nil, fmt.Errorf("TLS 握手失败: %w", err)
    }

    // 握手成功后返回可继续使用的 tls.Conn；后续 I/O 另行设置边界。
    return conn, nil
}

这里有三个关键点。第一，ctx 必须非空，通常传入请求上下文；第二，defer cancel() 负责释放超时上下文的资源；第三，只有握手成功才把 *tls.Conn 返回给调用方。若握手失败后仍复用这条连接，后续读写很容易把“握手中断”和“业务协议失败”混在一起。

取消发生时，为什么还要显式 Close

HandshakeContext 会在握手尚未完成时响应上下文取消，但“函数返回错误”和“连接资源已经由你的业务回收”是两个动作。连接由谁创建，通常就由谁负责关闭；在这个示例里，握手函数已经接管了连接，所以错误分支主动调用 Close。

取消来源可以分成两类：

• 超时：context.DeadlineExceeded 表示这次握手超过了预算。
• 上游取消：context.Canceled 常见于请求撤销、服务关闭或调用方主动放弃。

不要把“握手成功后再取消原来的上下文”当成关闭连接信号。官方文档明确说明，握手完成后，上下文的取消不会影响已经建立的连接；如果业务需要在请求结束时断开它，仍要显式调用 Close，或者为后续 I/O 设置自己的截止时间。

什么时候改用 DialContext 或 SetDeadline

三个 API 都能让等待有边界，但它们覆盖的对象不同。选择时先问自己：此时有没有底层连接？要不要把 TCP 建连也算进预算？握手完成后还要不要继续限制读写？

还没有连接：用 DialContext 覆盖拨号阶段

如果 TCP 连接也可能卡住，先把拨号放进带超时的上下文，再把返回的连接交给 tls.Client。这时可以为“拨号”和“TLS 握手”分别设置预算，也可以让它们共享一个更大的请求级截止时间。

func dialTLS(ctx context.Context, address string, cfg *tls.Config) (*tls.Conn, error) {
    d := net.Dialer{}
    // DialContext 只负责建立底层网络连接，不会替你完成 TLS 握手。
    raw, err := d.DialContext(ctx, "tcp", address)
    if err != nil {
        return nil, fmt.Errorf("TCP 拨号失败: %w", err)
    }

    conn := tls.Client(raw, cfg)
    // 连接已建立，这里把同一个 ctx 继续交给 TLS 握手。
    if err := conn.HandshakeContext(ctx); err != nil {
        _ = conn.Close() // 握手失败时回收底层连接和 TLS 包装。
        return nil, fmt.Errorf("TLS 握手失败: %w", err)
    }
    return conn, nil
}

已经连接或还要管读写：用 SetDeadline

SetDeadline 是连接级的绝对时间点，覆盖读和写；它不是只针对一次 HandshakeContext 调用。可以在必须防止底层 I/O 无限阻塞时使用，但成功握手后如果要延长业务会话，记得按业务重新设置截止时间。TLS 写超时后连接状态可能不再适合继续写入，因此不要把写超时简单当成可无限重试。

一张表选出合适的超时方式

常见问题

HandshakeContext 成功后，ctx 超时会自动断开连接吗？

不会。取消只影响尚未完成的握手；握手成功后要由业务自行关闭连接或管理后续 I/O 截止时间。

只给 tls.Conn 设置 HandshakeContext，能限制 TCP 拨号吗？

不能。拨号发生在拿到 tls.Conn 之前，应使用 net.Dialer.DialContext 或其它拨号阶段的超时设置。

为什么不直接在第一次 Read 前调用 SetDeadline？

可以，但它表达的是连接读写的绝对截止时间，范围比一次握手更大。若目标只是给握手单独预算，HandshakeContext 的语义更清楚。

总结

给 tls.Conn 限制握手时间时，核心组合是 context.WithTimeout 加 HandshakeContext。错误分支立即关闭未完成握手的连接；需要覆盖 TCP 拨号时加入 DialContext；需要管理握手后的读写时，再使用 SetDeadline 系列。把三段时间拆开，超时策略就不会互相覆盖。