当前位置：首页 > 文章列表 > Golang > Go教程 > 用自定义 RoundTripper 注入请求头与耗时记录

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

来源：17golang原创 2026-10-07 02:52:08 0浏览收藏

自定义 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 是否合适	注意点
注入调用方、版本或追踪请求头	合适	先克隆请求，避免污染原对象
记录发出请求到收到响应头的耗时	合适	直接包围底层 RoundTrip
记录读取完整响应体的耗时	合适	还要包装 Response.Body
把 500 状态码转成传输错误	不合适	获得响应就应返回 nil error，由业务判断状态码
自动跟随重定向	通常不放这里	交给 Client.CheckRedirect

官方契约还要求 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 中无条件注入。

Client、自定义 RoundTripper、克隆请求、独立请求头与底层 Transport 的静态调用关系 — 图1：请求侧静态结构图。自定义 RoundTripper 只修改克隆请求中的独立 Header，再把请求委托给底层 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() 关闭响应体。如果不去重，同一请求会产生两条“完整耗时”。反过来，如果调用方既不读完也不关闭，完整阶段不会上报，这恰好能暴露响应体生命周期没有结束的问题。

响应头观察、响应体包装器、EOF或Close完成信号与指标记录器的静态关系 — 图2：响应侧静态观察结构图。响应头耗时由 Transport 返回点记录，完整生命周期由 Body 包装器在 EOF、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、重试策略和业务错误模型才能各自保持清晰边界。