Go httptrace.TLSHandshakeDone 怎样记录 TLS 握手结果

如果你只想知道一次 HTTP 请求的 TLS 握手是成功还是失败，可以在 httptrace.ClientTrace 中设置 TLSHandshakeDone。它会在 TLS 握手结束时收到 tls.ConnectionState 和一个错误值：错误为 nil 时表示握手阶段成功，错误不为 nil 时表示握手阶段失败。

官方资料：https://pkg.go.dev/net/http/httptrace

这只是传输链路中的一个观测点，不等于整个 HTTP 请求成功。连接复用时并不是每个请求都会重新进行 TLS 握手；即使握手成功，后续写请求、读取响应或业务状态码也可能失败。

TLSHandshakeDone 的观测边界

TLSHandshakeDone 属于 httptrace.ClientTrace 的回调字段。它关注的是 TLS 握手完成这一事件，以及握手对应的连接状态和错误，不负责替代响应状态码、响应体校验或业务层错误处理。

使用它前先划清三个边界：

• 它回答“TLS 握手阶段发生了什么”，不回答“服务是否返回了预期业务结果”。
• 成功回调通常可以读取协议版本、服务器名称、协商出的应用协议等连接状态字段；失败时应优先记录错误。
• 回调可能与请求代码并发执行，不能无保护地写入共享切片、计数器或日志缓冲区。

官方文档还提醒，部分 trace 回调可能在请求失败或请求返回之后才执行。因此，如果调用方需要等待“最后一次观测写入”完成，应在自己的记录器中设计明确的同步边界，而不是依赖回调恰好先于函数返回。

最小可用的 ClientTrace 写法

把 trace 放进请求上下文，再用带有该上下文的请求调用客户端。下面的示例只记录握手结果，不把证书内容或敏感请求信息写入日志：

package main

import (
    "context"
    "crypto/tls"
    "fmt"
    "net/http"
    "net/http/httptrace"
)

func newTracedRequest(ctx context.Context, url string) (*http.Request, error) {
    trace := &httptrace.ClientTrace{
        TLSHandshakeDone: func(state tls.ConnectionState, err error) {
            // nil 错误表示握手阶段成功，非 nil 错误表示握手阶段失败。
            if err != nil {
                fmt.Printf("TLS 握手失败: %v\n", err)
                return
            }
            // 只记录可用于排查协商结果的摘要字段，不输出证书原文。
            fmt.Printf("TLS 握手成功: version=%d protocol=%s server=%s\n",
                state.Version, state.NegotiatedProtocol, state.ServerName)
        },
    }

    // 把 trace 放入本次请求的 context，Transport 才能读取它。
    tracedCtx := httptrace.WithClientTrace(ctx, trace)
    return http.NewRequestWithContext(tracedCtx, http.MethodGet, url, nil)
}

httptrace.WithClientTrace 只影响带有该上下文的请求。不要把一个带有请求专属状态的 trace 当成全局变量复用，否则多个请求可能把结果写到同一份不安全的状态里。

如何记录成功和失败字段

实际项目通常需要把结果交给指标、日志或诊断接口，而不是在回调中直接打印。可以定义一个小的结果结构，并在写入时保护共享状态：

type tlsHandshakeResult struct {
    Version            uint16
    NegotiatedProtocol string
    ServerName         string
    HandshakeComplete  bool
    Err                error
}

func traceForResult(save func(tlsHandshakeResult)) *httptrace.ClientTrace {
    return &httptrace.ClientTrace{
        TLSHandshakeDone: func(state tls.ConnectionState, err error) {
            // 回调可能并发执行，保存函数应自行使用 mutex、channel 或原子操作。
            result := tlsHandshakeResult{
                Version:            state.Version,
                NegotiatedProtocol: state.NegotiatedProtocol,
                ServerName:         state.ServerName,
                HandshakeComplete:  state.HandshakeComplete,
                Err:                err,
            }
            save(result)
        },
    }
}

成功时重点看 HandshakeComplete、Version、NegotiatedProtocol 和 ServerName；失败时 Err 是主要诊断入口，状态结构中的字段不应被当成完整的成功证明。

如果只需要计数，回调中可以更新原子计数器；如果要保留多条诊断记录，使用带容量上限的 channel 或受 mutex 保护的切片。日志字段应避免包含私钥、完整证书链、Authorization 头和可直接关联用户身份的 URL 查询参数。

复用连接、并发回调与请求结果

HTTP Transport 会复用已经建立的连接。复用连接时，本次请求可能没有新的 TLS 握手，因此不能把“没有收到 TLSHandshakeDone”解释成“握手失败”。如果要同时观察连接是否复用，可以配合 GotConn；如果要计算握手耗时，则配合 TLSHandshakeStart，并在保存结果时按请求或连接建立一次的语义去重。

握手成功后仍然要检查 client.Do 的返回错误、响应体关闭错误和 HTTP 状态码。一个更完整的调用边界如下：

func doRequest(client *http.Client, req *http.Request) error {
    // Do 返回 nil 错误只表示请求链路拿到了响应，不代表业务状态正确。
    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("发送请求: %w", err)
    }
    // 读取完响应体后关闭，避免连接无法回收到 Transport 的空闲池。
    defer resp.Body.Close()

    // TLS 握手成功与 HTTP 200 是两个不同阶段，必须分别判断。
    if resp.StatusCode = http.StatusMultipleChoices {
        return fmt.Errorf("HTTP 状态异常: %s", resp.Status)
    }
    return nil
}

重定向或 Transport 内部重试会带来多个 RoundTrip。trace 的回调是单次请求链路上的观测点，不要把一次回调自动当成整个重定向序列的最终结论；需要汇总时，给每次请求生成可关联的 request ID，并在上层合并记录。

落地检查清单

如果排查的是握手失败，先保存错误类型和请求关联 ID，再结合 TLSHandshakeStart、GotConn 等邻近事件还原路径；如果排查的是业务失败，则把 TLS 观测和响应状态分开入库，避免指标含义混杂。

相关问题

TLSHandshakeDone 的 err 为 nil 就代表接口调用成功吗？

不代表。它只说明 TLS 握手阶段没有报告错误，接口仍可能在写请求、读取响应或业务处理阶段失败。

为什么有时没有触发 TLSHandshakeDone？

最常见原因是连接复用，本次请求没有重新进行 TLS 握手。可以配合 GotConn 观察连接是否复用，并把“未发生握手”和“握手失败”区分开。

回调里能直接把 state 保存到全局切片吗？

不建议。回调可能并发执行，应使用 mutex、channel 或其他明确的同步方式；同时给记录数量和日志字段设置边界。

怎样记录 TLS 握手耗时？

在 TLSHandshakeStart 记录开始时间，在 TLSHandshakeDone 计算结束时间，并按连接或请求的实际观测语义去重。

官方资料：https://go.dev/blog/http-tracing、https://pkg.go.dev/net/http