Go net/http/httputil 怎样构造反向代理目标

Go 里构造反向代理目标，关键不是把字符串直接塞进 httputil，而是先用 url.Parse 得到目标 URL，再把这个 *url.URL 交给 httputil.NewSingleHostReverseProxy。这样代理才能按目标的协议、主机和基础路径改写入站请求；如果还要明确控制 Host 或转发头，则应使用 ReverseProxy 的 Rewrite。

本文只围绕“怎样构造反向代理目标”展开，示例中的后端地址是配置示意，不代表已经在本机运行。Go 官方文档说明，NewSingleHostReverseProxy 会把目标的 scheme、host、base path 与入站路径组合起来，同时保留入站 Host；需要更细粒度控制时，可以改用 Rewrite 和 ProxyRequest.SetURL。

先把后端地址解析成 url.URL

代理目标至少要有协议和主机。最稳妥的入口是配置文件中的完整地址，例如 https://api.internal.example/base。解析失败时直接返回配置错误，不要让一个半成品目标进入 HTTP Handler。

package main

import (
    "fmt"
    "log"
    "net/url"
    "net/http/httputil"
)

func buildProxy(rawTarget string) (*httputil.ReverseProxy, error) {
    // 先解析配置，避免把非法地址交给请求处理链。
    target, err := url.Parse(rawTarget)
    if err != nil {
        return nil, fmt.Errorf("解析代理目标失败: %w", err)
    }
    // 只接受能实际路由请求的绝对 URL，避免相对路径造成歧义。
    if target.Scheme == "" || target.Host == "" {
        return nil, fmt.Errorf("代理目标必须包含 scheme 和 host")
    }
    return httputil.NewSingleHostReverseProxy(target), nil
}

func main() {
    // 真实项目中可从环境变量或配置中心读取，而不是写死地址。
    proxy, err := buildProxy("https://api.internal.example/base")
    if err != nil {
        log.Fatal(err)
    }
    _ = proxy
}

这里的检查不是对 URL 做业务授权，而是保证目标对象具备路由所需的基本字段。生产环境还应在配置加载阶段限制允许的协议、域名或地址集合。

用 NewSingleHostReverseProxy 绑定单一目标

当所有请求都应该送到同一个后端，NewSingleHostReverseProxy(target) 是最短路径。它返回一个实现了 http.Handler 的 ReverseProxy，可以直接交给路由器。

package main

import (
    "log"
    "net/http"
    "net/http/httputil"
    "net/url"
)

func main() {
    // 目标 URL 决定协议、主机和基础路径，解析错误必须停止启动。
    target, err := url.Parse("https://api.internal.example/base")
    if err != nil {
        log.Fatal(err)
    }

    proxy := httputil.NewSingleHostReverseProxy(target)
    mux := http.NewServeMux()
    // 所有 /api/ 请求都交给同一个后端目标处理。
    mux.Handle("/api/", proxy)

    // 监听失败直接退出，避免误以为代理已启动。
    if err := http.ListenAndServe(":8080", mux); err != nil {
        log.Fatal(err)
    }
}

这段代码的核心是“目标对象”和“入站路由”分开：target 描述后端，mux 决定哪些请求交给代理。不要在每次请求到来时重新解析固定目标。

路径和查询参数到底怎样拼接

假设目标是 https://api.internal.example/base，入站请求路径是 /orders，代理会把基础路径和入站路径组合为类似 /base/orders。目标 URL 自己带查询参数时，入站查询参数会继续拼接到后面。

这意味着目标的 path 不是“替换所有入站路径”的开关，而是一个基础前缀。若业务需要完全自定义外发路径，应在 Rewrite 中直接调整 r.Out.URL，不要误以为改变字符串格式就能绕过路径组合规则。

package main

import (
    "fmt"
    "net/url"
)

func main() {
    target, _ := url.Parse("https://api.internal.example/base?tenant=core")
    incoming, _ := url.Parse("http://gateway.local/orders?page=2")

    // 这里只展示目标与入站 URL 的关键字段，实际拼接交给 ReverseProxy。
    fmt.Println("scheme:", target.Scheme)
    fmt.Println("host:", target.Host)
    fmt.Println("base path:", target.Path)
    fmt.Println("incoming path:", incoming.Path)
    fmt.Println("target query:", target.RawQuery)
    fmt.Println("incoming query:", incoming.RawQuery)
}

需要留意斜杠：目标是 /base、请求是 /orders 时会补一个分隔符；两边都有斜杠时不会产生重复斜杠。对于带转义路径的 URL，路径的转义形式也会参与组合，不能只用字符串截取模拟。

什么时候改用 Rewrite 和 SetURL

NewSingleHostReverseProxy 适合简单单目标代理，但它出于兼容性使用了已弃用的 Director。当你需要明确控制转发头、Host 或请求改写逻辑时，可以直接构造 ReverseProxy，在 Rewrite 里调用 SetURL。

package main

import (
    "log"
    "net/http"
    "net/http/httputil"
    "net/url"
)

func newRewriteProxy(rawTarget string) (*httputil.ReverseProxy, error) {
    target, err := url.Parse(rawTarget)
    if err != nil {
        return nil, err
    }
    return &httputil.ReverseProxy{
        Rewrite: func(r *httputil.ProxyRequest) {
            // SetURL 默认把外发 Host 改为目标 Host，并组合目标基础路径。
            r.SetURL(target)
            // 只有后端明确依赖入口域名时才保留入站 Host。
            r.Out.Host = r.In.Host
            // 按受信任的代理边界重新生成转发头，避免直接信任客户端值。
            r.SetXForwarded()
        },
    }, nil
}

func main() {
    proxy, err := newRewriteProxy("https://api.internal.example/base")
    if err != nil {
        log.Fatal(err)
    }
    // 生产服务还应配合超时、日志和后端健康策略。
    log.Fatal(http.ListenAndServe(":8080", proxy))
}

官方文档特别区分了两种行为：NewSingleHostReverseProxy 不改写 Host；SetURL 默认会改写外发 Host。如果要保持入站 Host，就像示例一样显式赋值。Rewrite 执行前，代理会移除部分转发头，随后再由应用根据部署信任边界决定是否调用 SetXForwarded。

给代理目标输入设边界

反向代理目标通常来自部署配置，而不是用户请求参数。若把用户可控的完整 URL 直接传给 url.Parse 再代理，服务可能被变成任意地址转发器。至少要把“解析 URL”和“允许访问哪些目标”分成两层判断。

• 协议只允许部署需要的值，例如只开放 http 或 https。
• 主机使用明确的允许列表、服务发现结果或内部注册表，不用字符串后缀猜测可信域名。
• 目标配置变更要有审计记录；请求日志记录路由结果，但不要把授权信息写入日志。
• 后端不可达时用 ErrorHandler 或统一中间件返回可识别的 502，避免把内部错误细节直接暴露给客户端。

另外，NewSingleHostReverseProxy 会保留客户端送来的 X-Forwarded-* 头，这在直接暴露于不可信客户端时可能造成来源 IP 欺骗。需要自定义安全边界时，优先考虑 Rewrite，清理旧头后再按自己的代理链规则生成新头。

小结：按目标复杂度选择构造方式

常见追问

目标 URL 可以只写主机不写协议吗？

不建议。代理路由需要明确的 scheme；对外部输入还应同时检查 Host 和允许的协议。

为什么后端收到的 Host 和目标域名不一样？

这是 NewSingleHostReverseProxy 的默认兼容行为，它不会改写 Host。若要按目标 Host 发送，改用 Rewrite 和 SetURL，或在改写逻辑里显式设置。

目标带查询参数会覆盖入站参数吗？

不会简单地覆盖；目标查询和入站查询会按代理实现拼接。若业务要求完全控制参数，应在 Rewrite 中明确重建 RawQuery。