Go httptrace.GotFirstResponseByte 定位首字节延迟

Go HTTP 请求出现“连接很快、响应却迟迟不回来”时，单看总耗时很难知道慢在哪里。httptrace.ClientTrace.GotFirstResponseByte 给出的不是完整响应耗时，而是“响应头的第一个字节已经可用”的时间点。把它与请求开始时间配对，就能得到首字节延迟；再与 RoundTrip 总耗时比较，便可判断慢点是在服务端等待，还是在后续读取响应体。

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

先把首字节延迟和总耗时分开

首字节延迟更接近“客户端发出请求后，等到服务器开始回应需要多久”。它包含连接建立、TLS、服务端排队和生成响应头等阶段，但不包含完整响应体的读取时间。总耗时则要等 resp.Body.Close 前的读取逻辑结束，两者相减可以帮助定位“大响应体慢”或“服务端迟迟不写头”的场景。

用 ClientTrace 记录 GotFirstResponseByte

回调通过 httptrace.WithClientTrace 放进请求上下文。下面的代码只记录一个请求的两个时间点：发起请求的时间，以及响应头首字节可用的时间。回调可能在不同 goroutine 中触发，因此共享变量要用互斥锁或原子变量保护；示例使用互斥锁，便于同时保存多个阶段数据。

package main

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

func requestTTFB(ctx context.Context, client *http.Client, url string) (time.Duration, time.Duration, error) {
    var mu sync.Mutex
    var firstByte time.Time
    started := time.Now()

    trace := &httptrace.ClientTrace{
        GotFirstResponseByte: func() {
            // 回调只保存时间，避免在 Transport 回调线程里做日志或网络操作。
            mu.Lock()
            firstByte = time.Now()
            mu.Unlock()
        },
    }
    req, err := http.NewRequestWithContext(httptrace.WithClientTrace(ctx, trace), http.MethodGet, url, nil)
    if err != nil {
        return 0, 0, fmt.Errorf("创建请求失败: %w", err)
    }
    resp, err := client.Do(req)
    if err != nil {
        return 0, 0, fmt.Errorf("发送请求失败: %w", err)
    }
    // 关闭响应体，避免连接池因未释放资源而失去复用机会。
    defer resp.Body.Close()

    mu.Lock()
    observed := firstByte
    mu.Unlock()
    if observed.IsZero() {
        return 0, 0, fmt.Errorf("本次请求没有收到首字节回调")
    }
    return observed.Sub(started), time.Since(started), nil
}

这里的 client.Do 返回时通常已经收到了响应头，因此首字节时间会先于或接近返回时间。若要把响应体读取也纳入总耗时，应在读取完成后再记录结束时间；不要用 Do 返回时间替代完整下载耗时。

怎样解释两个耗时的差值

拿到首字节延迟与总耗时后，先看数量级，不要急着改超时：

不要在回调里直接打印完整请求、响应体或敏感头部。生产指标只保留路由模板、协议、状态码、首字节耗时和错误类型，避免把 Authorization 等内容带进日志。

重定向、取消和 HTTP/2 的边界

ClientTrace 只跟踪一次 HTTP 请求与响应的单次 round trip，重定向链不能用一个首字节值代表全部跳转阶段。需要分析重定向时，应在 CheckRedirect 中为每次请求建立独立记录。

请求被取消或传输失败时，回调可能没有机会触发；这不是“首字节为 0”，而是一次未完成的观测。更重要的是，官方文档写明 GotFirstResponseByte 当前不用于 HTTP/2，所以指标结构必须带上 resp.Proto 或传输协议标签，不能因为缺少回调就把 HTTP/2 请求判为服务端超时。

常见问题

GotFirstResponseByte 能代表服务器处理完成吗？

不能。它只说明响应头首字节已可用，响应体可能还没有开始完整传输。

为什么回调时间和 Do 返回时间几乎一样？

因为客户端通常在拿到响应头后才让 Do 返回；这两个时间点都不能替代响应体读完时间。

HTTP/2 请求怎样测首字节？

不要依赖这个 hook。可以记录请求开始、Do 返回、响应体首次读取和读取结束等应用层时间点，并明确它们不是同一个 Transport 回调口径。