Go ReverseProxy 怎样重写上游请求的 Host 和路径

在网关里把 /api/users 转给另一个服务时，最容易混淆的是“目标主机”“目标路径”和“Host 请求头”其实是三件事。Go 的 httputil.ReverseProxy 可以在 Rewrite 回调里分别处理它们：用 SetURL 设定上游地址和基础路径，需要保留客户端 Host 时再显式写回 Out.Host。

官方文档：https://pkg.go.dev/net/http/httputil#ProxyRequest.SetURL

实战上先记住一句话：SetURL 会把目标的基础路径与入站路径拼接，并默认把出站 Host 改成目标 Host；想保留入站 Host，就在同一个 Rewrite 中写 r.Out.Host = r.In.Host。

Rewrite 回调里要分清 In 和 Out

ProxyRequest 有两个关键字段。In 是代理收到的请求，Rewrite 不应修改它；Out 是最终交给 Transport 的请求，Rewrite 可以修改或替换它。代理调用 Rewrite 前会先处理一部分代理边界，例如移除 hop-by-hop 头，因此不要把客户端请求头的原样副本当成 Out 的默认状态。

这一区分决定了排查顺序：先看入站 URL 是否是预期，再看 Rewrite 之后的 Out.URL、Out.Host 和需要主动设置的转发头。不要在回调返回后继续保存并修改 ProxyRequest，官方文档明确要求 Rewrite 返回后不要再访问它及其内容。

用 SetURL 完成上游主机和基础路径改写

如果目标是把外部的 /api/users 转到上游的 /internal/api/users，可以把上游 URL 设置为 https://users.internal.example/internal，再让 SetURL 自动拼接入站的 /api/users。这个方法适合“网关统一加前缀”的场景。

package main

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

func main() {
    target, err := url.Parse("https://users.internal.example/internal")
    if err != nil {
        log.Fatal(err) // 目标地址解析失败时不要启动一个半配置的代理。
    }

    proxy := &httputil.ReverseProxy{
        Rewrite: func(r *httputil.ProxyRequest) {
            // SetURL 会设置 scheme、host，并把 /internal 与入站路径拼接。
            r.SetURL(target)
            // 需要把客户端 Host 传给上游时，再显式覆盖 SetURL 的默认 Host。
            r.Out.Host = r.In.Host
            // 让上游知道客户端地址、原始 Host 和连接协议。
            r.SetXForwarded()
        },
    }

    log.Println("proxy listening on :8080") // 生产环境可替换成结构化启动日志。
    if err := http.ListenAndServe(":8080", proxy); err != nil {
        log.Fatal(err) // 监听失败时直接暴露错误，便于编排系统重启。
    }
}

这里入站路径是 /api/users 时，目标请求路径会按文档规则形成 /internal/api/users。同时，SetURL 会默认将出站 Host 设为 users.internal.example；示例中的下一行把它改回客户端看到的 Host。两种 Host 语义没有谁绝对正确，取决于上游按哪个域名做路由、租户识别或签名。

路径拼接和 Host 保留要分开决定

不要把“路径要不要加前缀”和“Host 要不要保留”绑成一个开关。前者由 SetURL 或 Out.URL 决定，后者由 Out.Host 决定。

如果你的路由规则已经计算出完整 URL，直接赋值更直观，但要确保赋值对象不会复用并被后续请求共享。常见做法是在回调外准备不可变的目标信息，在回调内创建或复制需要交给 Out.URL 的 URL 值。

不想拼接路径时直接设置 Out.URL

例如外部请求 /health 必须固定转成上游的 /ready，而不是变成“目标基础路径 + /health”。这时不要调用 SetURL 后再依赖它的拼接结果，可以在回调中直接设置出站 URL 的 scheme、host、path 和查询串。

Rewrite: func(r *httputil.ProxyRequest) {
    // 直接构造固定出口，避免 SetURL 自动追加入站路径。
    r.Out.URL.Scheme = "https"
    r.Out.URL.Host = "health.internal.example"
    r.Out.URL.Path = "/ready"
    r.Out.URL.RawQuery = "check=proxy"

    // 是否保留客户端 Host 必须按上游协议约定选择。
    r.Out.Host = "health.internal.example"
    // 需要转发客户端来源信息时再显式生成 X-Forwarded-*。
    r.SetXForwarded()
}

直接赋值时要把 URL 字段当成一个整体检查，尤其是 Path、RawPath 和 RawQuery 的组合。只改字符串拼接而忽略转义，可能让上游看到的路径与网关日志不一致。本文不展开自定义编码规则，但排查时应把最终出站 URL 记录成结构化字段。

X-Forwarded-* 和 Hop-by-hop 头怎么处理

SetXForwarded 会设置 X-Forwarded-For、X-Forwarded-Host 和 X-Forwarded-Proto。如果上游需要这些信息，直接在 Rewrite 中调用即可。需要注意，ReverseProxy 的 Rewrite 语义与旧的 Director 不同：文档说明部分转发头会在 Rewrite 前被移除，客户端带来的同名头不应未经判断就信任。

Rewrite: func(r *httputil.ProxyRequest) {
    // 先完成目标地址改写，避免只改 Host 却仍指向错误的上游。
    r.SetURL(target)
    // 用标准库根据入站连接生成来源信息，不直接复制不可信头。
    r.SetXForwarded()
    // 该业务要求上游按公共域名路由，因此保留入站 Host。
    r.Out.Host = r.In.Host
}

Hop-by-hop 头是连接级语义，不能把它们当作普通业务头跨代理层透传。若确实有特殊协议需要补充这类头，应明确写在 Rewrite 中，并同步评估上游和客户端的连接语义。普通 HTTP API 场景则保持默认清理行为更容易维护。

线上出现 404 或 Host 不匹配时怎么回滚

运维上可以按“路径、Host、转发头”三层回退。先把 SetURL 的目标基础路径恢复到旧配置；如果 404 消失，说明问题在路径拼接。若路径正确但上游按域名拒绝，再决定是保留入站 Host 还是使用目标 Host。最后再检查 X-Forwarded-Proto 等头是否满足上游的重定向和审计逻辑。

1. 记录一条入站方法、Host、Path 和 RawQuery，确认请求确实命中预期代理。
2. 记录出站 URL、出站 Host 和上游收到的路径，优先比较差异而不是猜测。
3. 只回退一个变量：先回退路径，再回退 Host，避免两个改动同时发生导致无法定位。
4. 保留 SetXForwarded 的处理决定，并确认可信代理边界已经定义。

最终速查：需要基础路径拼接用 SetURL；需要完全控制路径就改 Out.URL；需要保留入站域名就显式设置 Out.Host。这三项分别对应三个问题，分开写、分开排查，ReverseProxy 的 Rewrite 就不会因为一个默认行为带出另一处意外。

常见问题

SetURL 会不会自动保留客户端 Host？

不会。官方文档说明它会把出站 Host 改为目标 Host；需要保留入站 Host 时写 r.Out.Host = r.In.Host。

Rewrite 可以修改 In 吗？

不应修改。把 In 当作入站事实，把 Out 当作即将发送的请求，排查和审计都会更清楚。

什么时候不用 SetURL？

当目标路径不是“基础路径 + 入站路径”，而是经过路由表计算出的完整路径时，可以直接设置 Out.URL，并同时处理 Host 和查询串。