Go http.Transport.TLSHandshakeTimeout 怎样限制 TLS 握手等待时间

我在给 Go 客户端补超时配置时，最容易混淆的是“连接已经建立”和“TLS 握手已经完成”并不是同一个阶段。http.Transport.TLSHandshakeTimeout 只负责等待 TLS 握手完成的时间；它不会替代 DNS、TCP 建连、等待响应头或读取响应体的超时。

所以，HTTPS 请求偶尔卡住时，先把等待链路拆开，再设置对应的边界，比把一个很大的总超时直接塞给 http.Client 更容易判断问题。

先分清 TLS 握手处在请求的哪一段

一次典型的 HTTPS 客户端请求可以看成四个相邻但职责不同的区域：

• 解析地址并建立 TCP 连接；
• 完成 TLS 握手，协商加密参数并校验证书链；
• 发送请求后等待响应头；
• 持续读取响应体。

TLSHandshakeTimeout 只覆盖第二段。连接复用时，如果 Transport 找到了可用的既有 TLS 连接，通常不会重新进入握手阶段；因此把这个值调得很小，并不能限制每一次请求的总耗时。

在 Transport 中设置握手等待上限

需要控制客户端握手等待时，可以显式创建一个 http.Transport，再把它交给 http.Client。下面的配置只表达职责关系，时间值应按目标服务和网络环境调整。

package main

import (
    "context"
    "fmt"
    "net"
    "net/http"
    "time"
)

func requestWithTLSDeadline(ctx context.Context, url string) error {
    transport := &http.Transport{
        // 只限制 TLS 握手等待，不覆盖 TCP 建连和响应体读取。
        TLSHandshakeTimeout: 5 * time.Second,
        // 连接建立阶段单独使用 DialContext 的超时。
        DialContext: (&net.Dialer{Timeout: 3 * time.Second}).DialContext,
    }
    client := &http.Client{
        Transport: transport,
        // 总时限是最后一道边界，避免各阶段配置遗漏时无限等待。
        Timeout: 15 * time.Second,
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("请求失败: %w", err)
    }
    // 响应体必须关闭，避免连接无法回收到连接池。
    defer resp.Body.Close()
    return nil
}

实际项目可以把 Transport 作为长期复用的客户端配置，而不是每个请求都新建。不要在每次调用中重复创建 Transport，否则连接池复用会被削弱。

四种超时配置应该怎样分工

我更倾向于把配置写成一张职责表，排查时先问“卡在哪一段”，再找对应参数：

这些配置不是互相替代的。比如握手完成后服务端迟迟不返回响应头，即使 TLSHandshakeTimeout 设置得很小，也不会提前结束那一段等待；这时应看 ResponseHeaderTimeout 或总时限。

看到什么错误时该先查哪里

如果错误明确指向 TLS handshake timeout，先检查目标地址是否真的走 HTTPS、代理或中间设备是否拖慢握手，以及握手时间是否被错误地估计得过小。若更早出现连接超时，应回到 DialContext；若握手成功后长时间没有响应头，则检查 ResponseHeaderTimeout。

context deadline exceeded 只能说明某个上下文截止时间已经到达，不能单独证明是 TLS 阶段。证书过期、主机名不匹配等错误也属于握手过程中的失败，但它们是校验错误，不是单纯把 TLSHandshakeTimeout 调大就能解决。

最后记住三点：握手超时是阶段性边界；复用连接可能绕过新握手；总超时只是兜底，不等于阶段定位。按这个顺序拆分配置，升级或迁移 HTTP 客户端时会更容易保留原来的行为。

相关问题

TLSHandshakeTimeout 设置为 0 会立即失败吗？

不会。对 http.Transport 来说，零值表示不设置该阶段的超时；是否能结束仍取决于上下文、客户端总时限和其他阶段配置。

为什么设置了握手超时，请求还是很慢？

因为慢点可能发生在 TCP 建连、等待响应头或读取响应体阶段，也可能命中了连接复用。应按阶段分别配置和判断。