Go httptrace.WroteHeaderField 记录请求头写入时机的实现方式

排查 Go HTTP 客户端时，经常需要知道“请求头什么时候被 Transport 写出”。httptrace.WroteHeaderField适合做这个观测：它在 Transport 写出每个请求头字段后回调，但回调发生时，字段值仍可能留在缓冲区里，不能当成已经抵达网卡或服务端的抓包证据。

httptrace.WroteHeaderField 到底观察哪个时刻

这个钩子属于客户端 Transport 的写入观察点。它接收字段名和字段值切片，说明某个请求头已经由 Transport 处理到写出阶段；但文档特意保留了一个边界：值可能还在缓冲。因此它适合诊断“客户端准备了哪些头、写入顺序如何、某个头是否进入 Transport”，不适合证明“服务端已经收到”。

用 ClientTrace 把钩子挂到一次请求

追踪不是全局开关，而是放进请求的 Context。下面的代码只给这一轮请求挂上回调，并用 WroteHeaders 和 WroteRequest 补足阶段信息。

package main

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

func main() {
    trace := &httptrace.ClientTrace{
        WroteHeaderField: func(key string, values []string) {
            // 这里只演示字段事件；生产日志不要直接打印 Cookie 或 Authorization。
            fmt.Printf("header written: %s (%d values)\\n", key, len(values))
        },
        WroteHeaders: func() {
            // 这表示请求头阶段完成，不代表响应已经返回。
            fmt.Println("all request headers written")
        },
        WroteRequest: func(info httptrace.WroteRequestInfo) {
            // Err 只反映客户端写请求的结果，业务状态仍要读取 HTTP 响应。
            fmt.Printf("request write error: %v\\n", info.Err)
        },
    }

    req, err := http.NewRequestWithContext(
        httptrace.WithClientTrace(context.Background(), trace),
        http.MethodGet,
        "https://example.com/health",
        nil,
    )
    if err != nil {
        panic(err)
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close() // 读取响应体后及时释放连接资源。
    fmt.Println("status:", resp.StatusCode)
}

这里的 example.com 只是文档示例地址，不表示本文执行过网络请求。真正接入时，应把追踪 Context 绑定到要诊断的请求，而不是修改全局 Transport。

回调里怎样记录而不泄露敏感头

回调拿到的 values 不应直接写入长期日志。更稳妥的做法是对敏感字段只保留字段名，对普通字段保留值数量；如果必须分析值，也应先复制并脱敏。由于 ClientTrace 的钩子可能从不同 goroutine 调用，事件切片需要互斥保护。

type HeaderEvent struct {
    Key        string
    ValueCount int
    Redacted   bool
}

func newTrace(events *[]HeaderEvent, mu *sync.Mutex) *httptrace.ClientTrace {
    return &httptrace.ClientTrace{
        WroteHeaderField: func(key string, values []string) {
            // 敏感字段不落原值，只记录数量，降低日志泄露风险。
            lower := strings.ToLower(key)
            sensitive := lower == "authorization" || lower == "cookie" || lower == "set-cookie"
            event := HeaderEvent{Key: key, ValueCount: len(values), Redacted: sensitive}

            mu.Lock()
            *events = append(*events, event) // 保护共享切片，避免并发追加产生竞态。
            mu.Unlock()
        },
    }
}

示例中的辅助函数需要额外导入 strings、sync 和 net/http/httptrace。如果只做一次简单诊断，也可以把事件写入带缓冲的 channel，再由单独的消费者统一落盘。

把三个时刻放进同一张诊断记录

调试日志最好明确标注阶段：字段事件用于回答“哪个头被 Transport 处理了”，WroteHeaders 用于回答“请求头阶段是否结束”，WroteRequestInfo.Err 用于回答“客户端写请求是否报错”。发生重定向或请求重试时，某些回调可能再次出现，所以记录中应带 request ID，并允许同一请求存在多组事件。

常见误区是把 WroteHeaderField 和服务端访问日志做一一对应。两者处于不同观测面：前者来自客户端 Transport，后者来自服务端接收与解析。要确认链路到达，仍需结合服务端日志、代理日志或抓包工具，不能只看 httptrace。

相关问题

WroteHeaderField 会不会包含 Host？

它观察 Transport 写出的请求头字段，具体字段集合受请求、Transport 和协议实现影响。不要用它推断某个字段一定出现，应该在回调中按实际 key 记录。

为什么回调里的值和服务端看到的不同？

回调点可能早于真正的网络发送，而且代理、协议层和服务端解析还可能改变呈现方式；它只说明客户端写入阶段看到的值。

如何确认请求体也写成功了？

使用 WroteRequest 的 Err 判断客户端写请求结果，再读取响应并结合服务端日志确认业务处理，不要只依据请求头回调。