http.RoundTripper 是拦截 HTTP 请求的唯一可控入口，所有拦截逻辑（如加 header、日志、Mock）必须实现在其 RoundTrip 方法中；直接修改 *http.Request 无效，且需注意并发安全、Body 可读性及阻塞操作风险。
Go 的 http.RoundTripper 是拦截请求的唯一可控入口
标准库 http.Client 发起请求时，真正执行网络通信的是其 Transport 字段，而该字段类型为 http.RoundTripper 接口。所有请求拦截（如加 header、重写 URL、记录日志、Mock 响应）都必须通过自定义实现该接口完成。直接修改 http.Request 对象本身无效——它在进入 Transport 后就不再受你控制。
常见错误是试图在 http.Client.Do() 调用前修改 *http.Request，但此时请求尚未被 Transport 处理，且无法覆盖重定向、TLS 握手等底层行为。
- 必须把自定义逻辑放在
RoundTrip(*http.Request) (*http.Response, error)方法中 - 若需复用默认行为，应包装
http.DefaultTransport或新建&http.Transport{} - 注意并发安全：多个 goroutine 可能同时调用你的
RoundTrip方法
用 http.RoundTripper 实现请求日志与 header 注入
最典型的需求是统一添加认证 token、User-Agent，或记录请求耗时。下面是一个线程安全、可复用的拦截器示例：
type loggingRoundTripper struct {
base http.RoundTripper
}
func (l *loggingRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
// 注入 header（不影响原始 req，因 req 是指针）
req.Header.Set("X-Request-ID", uuid.New().String())
req.Header.Set("User-Agent", "my-app/1.0")
start := time.Now()
resp, err := l.base.RoundTrip(req)
elapsed := time.Since(start)
log.Printf("HTTP %s %s → %d (%v)", req.Method, req.URL,
resp.StatusCode, elapsed)
return resp, err
}
// 使用方式
client := &http.Client{
Transport: &loggingRoundTripper{
base: http.DefaultTransport,
},
}
注意：req.Header.Set() 会覆盖同名 header；若需追加（如多个 X-Forwarded-For），应改用 req.Header.Add()。
立即学习“go语言免费学习笔记（深入）”；
拦截特定域名或路径做 Mock 响应
测试或本地开发时，常需对某些 API 返回预设 JSON，避免真实调用。关键点在于：不能提前 return nil resp，必须构造合法的 *http.Response，否则上层 client.Do() 会 panic。
- 用
httptest.NewRecorder()构造响应体最安全 - 手动设置
resp.StatusCode、resp.Header和resp.Body（需是io.ReadCloser） - 匹配条件建议用
strings.HasPrefix(req.URL.Host, "api.test")，而非完全相等，以兼容端口和子域
func (m *mockRoundTripper) RoundTrip(req *http.Request) (*http.Response, error) {
if strings.HasPrefix(req.URL.Host, "mock.api.local") {
body := `{"data": "fake", "ok": true}`
rec := httptest.NewRecorder()
rec.WriteHeader(http.StatusOK)
rec.Write([]byte(body))
return &http.Response{
Status: "200 OK",
StatusCode: http.StatusOK,
Proto: "HTTP/1.1",
ProtoMajor: 1,
ProtoMinor: 1,
Header: rec.Header(),
Body: io.NopCloser(bytes.NewReader(rec.Body.Bytes())),
ContentLength: int64(len(body)),
}, nil
}
return m.base.RoundTrip(req)
}
不要在 RoundTrip 中做阻塞 I/O 或长耗时操作
Go 的 HTTP client 默认启用连接复用和 keep-alive，一个 RoundTripper 实例会被多个 goroutine 复用。若你在 RoundTrip 里同步调用数据库查询、外部 RPC 或 sleep，会直接拖慢所有后续请求。
真正需要异步处理的场景（如上报审计日志），应启动 goroutine 并立即返回响应：
go func() {
// 非阻塞上报，不等待结果
audit.Log(req.URL.String(), req.Header.Get("X-Request-ID"))
}()
更隐蔽的问题是：某些拦截器会在 RoundTrip 中读取 req.Body（比如解析 JSON），但 Body 是单次读取的 io.ReadCloser。一旦读完未重置，下游 handler 就收不到数据。解决方法是用 io.TeeReader + bytes.Buffer 缓存并重放，或明确文档要求“此拦截器不支持 body 重用”。
