用自定义 RoundTripper 注入请求头与耗时记录

自定义 http.RoundTripper 很适合把“每次请求都要做”的客户端逻辑集中起来：在请求发送前注入统一请求头，在底层传输返回后记录耗时，再把响应原样交还给 http.Client。关键不是把代码塞进 RoundTrip 就结束，而是要遵守三个边界：不要直接修改传入的 Request、不要把 4xx/5xx 当成传输错误、包装层和指标回调必须能被多个 goroutine 并发调用。

下面给出一个可直接复用的实现。它既记录“收到响应头”的耗时，也通过包装 Response.Body 记录调用方读到 EOF 或关闭响应体时的完整生命周期。

官方地址：https://pkg.go.dev/net/http

先确定包装层只做哪些事

RoundTripper 表示一次 HTTP 事务。自定义实现通常不是替代网络传输，而是包住真正的底层 Transport：做少量前置处理，把请求委托给下一层，再做少量后置记录。重定向、Cookie 和认证策略仍然属于更高层的 http.Client。

官方契约还要求 RoundTripper 可被多个 goroutine 并发使用。因此，下面的结构体在创建后不再修改；如果指标函数内部维护 map 或计数器，它自己也必须使用锁、原子操作或并发安全的指标库。

克隆请求后再注入请求头

最容易写出的错误是直接执行 req.Header.Set。传入请求可能还被调用方持有，也可能在重试、跳转或并发逻辑中复用。官方要求 RoundTrip 除消费和关闭请求体外，不应修改请求。使用 req.Clone(req.Context()) 可以深复制 Header、URL 等字段，同时保留原上下文；Body 只是浅复制，所以包装层不要自行重复读取请求体。

package clientx

import (
    "io"
    "net/http"
    "sync"
    "time"
)

// ObserveFunc 接收阶段、请求维度、状态码、耗时和传输错误。
// 回调可能被多个 goroutine 同时调用，具体实现必须并发安全。
type ObserveFunc func(
    phase string,
    method string,
    host string,
    status int,
    elapsed time.Duration,
    err error,
)

type InstrumentedTransport struct {
    Base    http.RoundTripper
    Caller  string
    Observe ObserveFunc
}

func (t *InstrumentedTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    base := t.Base
    if base == nil {
        base = http.DefaultTransport // 未指定底层时沿用标准传输实现
    }

    // Clone 会复制 Header 等字段，避免修改调用方持有的原始请求。
    cloned := req.Clone(req.Context())
    cloned.Header.Set("X-Caller", t.Caller)

    started := time.Now()
    resp, err := base.RoundTrip(cloned)

    status := 0
    if resp != nil {
        status = resp.StatusCode
    }
    t.emit("headers", cloned, status, time.Since(started), err)

    if err != nil {
        // 传输失败时没有可继续读取的响应体，直接记录完整阶段。
        t.emit("complete", cloned, status, time.Since(started), err)
        return resp, err
    }

    if resp.Body != nil {
        // 包装响应体，等调用方读到 EOF 或关闭时再记录完整耗时。
        resp.Body = &observedBody{
            ReadCloser: resp.Body,
            started:    started,
            finish: func(phase string, bodyErr error) {
                t.emit(phase, cloned, status, time.Since(started), bodyErr)
            },
        }
    }
    return resp, nil
}

func (t *InstrumentedTransport) emit(
    phase string,
    req *http.Request,
    status int,
    elapsed time.Duration,
    err error,
) {
    if t.Observe != nil {
        t.Observe(phase, req.Method, req.URL.Host, status, elapsed, err)
    }
}

type observedBody struct {
    io.ReadCloser
    started time.Time
    once    sync.Once
    finish  func(phase string, err error)
}

func (b *observedBody) Read(p []byte) (int, error) {
    n, err := b.ReadCloser.Read(p)
    if err == io.EOF {
        b.done("body_eof", nil) // 正常读完只上报一次
    } else if err != nil {
        b.done("body_error", err) // 读取失败也结束本次观察
    }
    return n, err
}

func (b *observedBody) Close() error {
    err := b.ReadCloser.Close()
    b.done("body_close", err) // 调用方提前关闭时保留独立阶段
    return err
}

func (b *observedBody) done(phase string, err error) {
    b.once.Do(func() {
        b.finish(phase, err) // EOF 与 Close 只允许第一个事件完成记录
    })
}

这里使用 Set，意味着包装层拥有 X-Caller 的最终值，调用方不能伪造它。如果需求是“只在业务没有设置时补默认值”，应先用 Get 判断。像 Authorization 这类敏感头，不应在一个面向所有域名的全局 Transport 中无条件注入。

为什么要区分响应头耗时和完整响应耗时

如果只在 base.RoundTrip 前后调用 time.Now 与 time.Since，测到的主要是建立连接、发送请求和等待响应头的时间。此时响应体通常还没有被业务读取，大文件下载、流式接口或慢速响应体的耗时不会进入这个数字。

上面的实现提供四个可区分阶段：

• headers：底层 RoundTrip 返回，已经拿到响应头或发生传输错误；
• body_eof：调用方把响应体正常读到 EOF；
• body_close：调用方在 EOF 前或 EOF 后主动关闭响应体；
• body_error：读取响应体期间发生错误。

sync.Once 很重要，因为正常代码往往先读到 EOF，随后又通过 defer resp.Body.Close() 关闭响应体。如果不去重，同一请求会产生两条“完整耗时”。反过来，如果调用方既不读完也不关闭，完整阶段不会上报，这恰好能暴露响应体生命周期没有结束的问题。

把包装层装配到长期复用的 Client

Transport 内部维护连接池，不应为每个请求重新创建。初始化一次 Client，把自定义包装层挂在 Transport 字段，然后在整个服务中复用它。

package main

import (
    "log"
    "net/http"
    "time"

    "example.com/project/clientx"
)

func newUpstreamClient() *http.Client {
    transport := &clientx.InstrumentedTransport{
        Base:   http.DefaultTransport,
        Caller: "order-service",
        Observe: func(
            phase, method, host string,
            status int,
            elapsed time.Duration,
            err error,
        ) {
            // 示例使用标准日志；生产环境可替换成并发安全的指标或追踪上报。
            log.Printf(
                "phase=%s method=%s host=%s status=%d elapsed=%s err=%v",
                phase, method, host, status, elapsed, err,
            )
        },
    }

    return &http.Client{
        Transport: transport,
        Timeout:   5 * time.Second, // 给整个请求生命周期设置最终保护上限
    }
}

http.DefaultTransport 本身支持并发复用。如果还需要调整连接池、代理或 TLS 设置，先把它断言为 *http.Transport 并调用 Clone，再把克隆值作为 Base；不要在服务运行中修改共享的全局 Transport。

调用代码不再关心横切逻辑

func fetchProfile(ctx context.Context, client *http.Client, url string) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }

    resp, err := client.Do(req)
    if err != nil {
        return err // 这里只处理传输、超时或客户端策略错误
    }
    defer resp.Body.Close() // 保证完整耗时观察最终能够结束

    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("上游状态异常: %s", resp.Status)
    }

    // 业务只负责消费响应；调用方请求头与耗时由 Transport 统一处理。
    _, err = io.Copy(io.Discard, resp.Body)
    return err
}

注意状态码判断仍然留在业务层。RoundTripper 只要成功获得 HTTP 响应，就应返回 err == nil，即使状态码是 404 或 500。这样 Client、重试策略和业务错误模型才能各自保持清晰边界。

运行检查时看这五个结果

1. 服务端收到的 X-Caller 是固定调用方标识，原始 Request 的 Header 没有被修改。
2. 正常请求先出现 headers，响应体读完后只出现一次 body_eof 或 body_close。
3. 连接失败、DNS 失败或上下文取消时，status 为 0，并记录传输错误。
4. HTTP 500 仍返回 Response，由业务层判断状态码，而不是被包装层伪装成网络错误。
5. 并发请求下没有修改共享 map、切片或 Request 的数据竞争。

若要写单元测试，可以使用 httptest.Server 检查请求头和状态码，再用一个延迟写入响应体的 Handler 验证 headers 与完整阶段的差异。测试结束要关闭响应体和测试服务器，避免资源泄漏。

常见误区与扩展方式

• 直接改 req.Header：破坏 RoundTripper 契约，也可能影响调用方复用请求；应使用 Clone。
• 每次请求创建包装层：包装对象本身很轻，但它背后的 Transport 应长期复用，否则连接池被拆散。
• 把 RoundTrip 耗时叫“下载耗时”：它默认只覆盖到响应头，完整读取必须包装 Body。
• 回调里同步写慢存储：会直接增加请求延迟；可使用低开销指标库或有界异步队列。
• 所有域名注入同一敏感头：存在信息外泄风险；应按目标主机拆 Client 或在包装层检查允许列表。
• 忽略包装顺序：多个 RoundTripper 组合时，外层测到的耗时包含内层开销；顺序应固定并写进初始化代码。

这个模式最适合稳定、无状态的横切能力：调用方标识、追踪头、低成本指标、审计标签和有限的主机策略。需要读取或重放请求体、复杂重试、签名认证时，要额外处理 Body 的可重建性与幂等性，不能只靠简单包装完成。

相关问题

为什么不用 http.Client 的方法直接注入请求头？

http.Client 没有“全局默认请求头”字段。可以在每次构造 Request 时设置，也可以用 RoundTripper 统一处理；后者更适合多个调用点共享同一策略。

Request.Clone 会复制请求体吗？

不会深复制 Body。它对 Body 只做浅复制，因此包装层不应自行读取或重放请求体。需要重试带 Body 的请求时，应使用可重新创建内容的 GetBody 或业务自己的重建逻辑。

自定义 RoundTripper 可以返回 500 对应的 error 吗？

不应该。只要获得了 HTTP 响应，传输层应返回响应和 nil error。状态码语义交给调用方或更高层策略判断。

怎样避免指标标签爆炸？

不要把完整 URL、请求 ID 或用户 ID 当成指标标签。常见做法是保留方法、规范化路由、目标服务和阶段，把高基数字段放进日志或追踪系统。