Go http.Transport 自定义 RoundTripper 如何保留默认代理

给 Go HTTP 客户端加日志、Trace 或统一请求头时，最容易踩的坑是重新写一个 &http.Transport{}。这样虽然能编译，却可能把默认代理选择和其他连接配置一起丢掉。更稳妥的做法是：先把 http.DefaultTransport 断言为 *http.Transport，调用 Clone() 得到副本，再把副本放进自定义 RoundTripper。

官方文档：https://pkg.go.dev/net/http

自定义 RoundTripper 不等于重写传输层。要保留默认代理，关键是复用默认 Transport 的配置或直接把它作为包装器的下游；如果确实要调整连接参数，优先对底层 *http.Transport 做 Clone()。

为什么直接 new http.Transport 会丢掉默认代理能力

http.DefaultTransport 虽然名字像一个结构体变量，但它声明为 RoundTripper。它的默认实现包含 Proxy: ProxyFromEnvironment，会根据请求协议读取环境变量，并用 NO_PROXY 判断是否绕过代理。另一个重要行为是连接会被缓存，后续请求可以复用。

下面两种写法的语义不同：&http.Transport{} 是一套新的零值配置；http.DefaultTransport 才是标准库已经组装好的默认实现。前者不会因为“字段没写”就继承后者的字段值。

正确的包装方式是 Clone 后再套 RoundTripper

自定义层只做自己负责的事情，例如记录请求耗时；真正的网络发送仍由克隆后的 Transport 完成。这样代理选择、连接池和协议支持都留在标准库传输层。

package main

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

// loggingTransport 只增加观测，不接管代理和连接建立。
type loggingTransport struct {
    base http.RoundTripper
}

func (t loggingTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    started := time.Now()
    // 请求、代理选择和连接复用全部交给下游 Transport。
    resp, err := t.base.RoundTrip(req)
    log.Printf("%s %s cost=%s err=%v", req.Method, req.URL, time.Since(started), err)
    // 返回原始响应，响应体仍由 http.Client 的调用方负责关闭。
    return resp, err
}

func newClient() (*http.Client, error) {
    // DefaultTransport 是接口，先取出标准库的 Transport 实现。
    base, ok := http.DefaultTransport.(*http.Transport)
    if !ok {
        return nil, errors.New("http.DefaultTransport 不是 *http.Transport")
    }

    // Clone 保留 Proxy 等导出配置，后续修改不会污染共享默认值。
    transport := base.Clone()
    transport.MaxIdleConnsPerHost = 20

    return &http.Client{
        Transport: loggingTransport{base: transport},
        Timeout:   15 * time.Second,
    }, nil
}

这里的关键不是“必须使用 Clone”，而是先确认你要保留的下游是谁。若只加日志，可以直接让包装器持有 http.DefaultTransport；若要改 MaxIdleConnsPerHost、IdleConnTimeout 等字段，就需要得到 *http.Transport 的副本。

RoundTripper 包装器要守住哪些边界

RoundTripper 表示一次 HTTP 事务，并且要能被多个 goroutine 并发使用。包装器不应在请求已经交给下游后再次读取或关闭 req.Body，也不要为了记录日志而修改调用方仍会使用的请求头。响应返回后，调用方依然要关闭 resp.Body，否则连接复用会受到影响。

如果要给请求加 Header，先明确该 Header 是否会改变签名、缓存或重试语义；如果要重试，也不能只看网络错误，还要考虑请求是否幂等以及 GetBody 是否可用。单纯的观测层最好保持透明，让 Transport 负责代理、TLS、HTTP/1.1、HTTP/2 和连接管理。

上线前用环境变量和类型边界排查代理问题

代理问题通常不是 RoundTripper 本身报错，而是下游配置已经换成了另一套 Transport。排查时先确认 http.DefaultTransport 是否仍是 *http.Transport，再检查运行进程实际看到的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY。不要只在开发机 shell 里配置变量，然后假设服务管理器也继承了同样的环境。

另外，Transport 应该创建一次并复用。不要每个请求都 Clone 或 new 一个 Transport；这样会失去连接池收益。Transport 开始处理请求后也不应继续修改其配置，若不同调用方需要不同代理或 TLS 参数，应在启动阶段各自创建并固定。

常见问题

只包一层 RoundTripper，还需要 Clone 吗？

不需要。若不修改底层字段，直接把 http.DefaultTransport 作为下游即可；只有要独立改配置时才 Clone。

为什么设置了 HTTP_PROXY 仍然直连？

先看请求协议是否匹配对应变量，再检查 NO_PROXY 是否命中了目标主机；同时确认客户端实际使用的 Transport 仍保留 ProxyFromEnvironment。

DefaultTransport 被替换后怎么办？

类型断言失败时不要强行转换。可以把当前 http.DefaultTransport 作为下游继续包装，或在启动时显式构造自己的 Transport 并设置代理函数。