Go ReverseProxy 转发请求头的改写边界

Go ReverseProxy 改请求头时，新代码优先使用 Rewrite，只修改 ProxyRequest.Out，不修改 In。路由目标用 SetURL 配置；需要后端收到特定 Host 时改 Out.Host，而不是 Header.Set("Host", ...)。Director 与 Rewrite 不能同时设置，两者的清理时机和默认转发头行为不同，不能仅改一个函数名就认为迁移完成。

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

固定上游代理可以先用这段写法

下面的原创构造函数面向受控的固定上游，例如内部商品查询服务。它返回可注册到路由的 HTTP Handler，不启动监听，也不接受客户端指定任意目标。示例使用 Go 1.20 起提供的 Rewrite 接口；上线时仍需另行配置访问控制、目标白名单、超时与日志，这些不属于本段头改写代码的保证范围。

package gateway

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

// targetText必须来自受控配置，不能直接接收客户端提供的任意上游地址。
func NewCatalogProxy(targetText string) (*httputil.ReverseProxy, error) {
    target, err := url.Parse(targetText)
    if err != nil {
        return nil, fmt.Errorf("解析上游地址: %w", err)
    }
    if (target.Scheme != "http" && target.Scheme != "https") || target.Host == "" {
        return nil, fmt.Errorf("上游地址需要http或https协议及主机")
    }
    if target.User != nil || target.RawQuery != "" || target.Fragment != "" {
        return nil, fmt.Errorf("上游配置不接受用户信息、查询串或片段")
    }
    proxy := &httputil.ReverseProxy{
        Rewrite: func(pr *httputil.ProxyRequest) {
            // 使用目标协议、主机和基础路径；默认Host也采用目标主机。
            pr.SetURL(target)
            // 只根据本跳入口请求重建转发元数据，不继承外部提供的地址链。
            pr.SetXForwarded()
            // 普通业务头使用Set明确覆盖，不修改只读的In请求。
            pr.Out.Header.Set("X-Proxy-Route", "catalog")
        },
        ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
            // 返回稳定的网关错误，不把内部目标或底层错误暴露给客户端。
            http.Error(w, "上游服务暂不可用", http.StatusBadGateway)
        },
    }
    return proxy, nil
}

核心只有三处：SetURL 决定上游地址，SetXForwarded 生成本跳转发信息，Out.Header.Set 覆盖普通业务头。X-Proxy-Route 是示例自定义标记，不是标准认证字段，也不能作为允许访问后端的唯一凭证。代码没有自行读取或关闭请求正文，正文转发由 ReverseProxy 管理。

Director 与 Rewrite 应该怎样选择

当前官方文档已将 Director 标记为弃用，并建议采用 Rewrite。原因不只是名称更新：在 Director 中设置的字段，后续可能因逐跳头清理而消失。Rewrite 把可修改边界放在清理之后，更容易明确自己最终发出的普通业务头。

不要在 NewSingleHostReverseProxy 返回的对象上直接再赋值 Rewrite，却忘记其原有 Director。该辅助构造器采用 Director 路径；迁移时直接构造 ReverseProxy 并只保留 Rewrite，通常更清楚。维护不能升级的旧项目时，需按其对应工具链文档处理，不能把本文接口直接塞进不支持的版本。

URL.Host 与 Out.Host 各自决定什么

URL.Host 表示路由使用的目标主机；Out.Host 表示发给上游的 HTTP Host 语义。两者经常相同，但不是同一字段。普通 Header 映射不负责替代 Request.Host，所以用 Out.Header.Set("Host", ...) 往往解决不了虚拟主机选择问题。

SetURL 会把目标的协议、主机和基础路径应用到 Out.URL，并让上游 Host 采用目标主机。NewSingleHostReverseProxy 则默认不改原始 Host。这是两种写法切换后，后端突然进入不同站点时应先核对的差异。

例如受控目标为 http://catalog.internal:8080/base，入口 Host 为 shop.example.test，访问路径为 /items：使用 SetURL 后，目标路径会拼接为 /base/items，目标主机来自 catalog.internal:8080，而 Host 默认也按目标处理。这些是字段规则推导，不是本文声称已经抓到的网络结果。

若后端确实依赖入口域名，可在 SetURL 之后把 Out.Host 设为 In.Host。但应先在入口验证允许的域名；不应为了“保持原样”而把任意外部 Host 交给依赖域名做租户选择的上游。另一个常见需求是独立指定已配置的虚拟主机名，此时应赋受控值，而不是误改拨号地址。

转发头要重建，还是继承原地址链

本例把代理当成直接接收客户端连接的一跳入口。Rewrite 中调用 SetXForwarded，按本跳连接地址、入口 Host 和是否存在入站 TLS 生成 X-Forwarded-For、X-Forwarded-Host、X-Forwarded-Proto。入口没有TLS时，不能仅凭任意客户端声称的协议头就判断外部连接是HTTPS。

如果前面还有负载均衡器，本跳看到的连接地址可能是负载均衡器，而不是最初用户。此时是否继承已有地址链，需要依据可信前置代理的来源与部署协议单独设计。不要无条件把 In.Header 中所有 X-Forwarded-* 复制到 Out，尤其不要把客户端可填写的值直接当作真实身份。

Rewrite 不是“删除全部请求头”的开关。普通业务字段是否保留、覆盖或删除，仍由你的代理契约决定；授权头、Cookie、租户标识等也不能不分场景全部透传。本文仅用无敏感信息的 X-Proxy-Route 演示覆盖操作，不提供认证系统的完整设计。

这套改写方式不适合解决哪些问题

• 只改 Host 不能解决所有 HTTPS 证书或握手问题，HTTP主机语义不能代替传输层配置。
• 设置 X-Forwarded-Host 不会改变上游的实际 Host；它只是提供入口主机元数据。
• SetURL 默认连接基础路径与入站路径，不等于无条件替换整个路径。
• Rewrite 返回后不要继续持有并异步修改 ProxyRequest，也不要修改 In。

项目选择可以归纳为：新固定上游代理用 Rewrite 与 SetURL；后端需要入口虚拟主机时，再明确配置 Out.Host；已有 Director 项目先列出旧 Host、路径与转发头契约，再做迁移，不用一张“字段能设置”的表替代行为比较。

常见问题速查

为什么Header里能看到Host，后端收到的却不是它？

Request.Host 是特殊字段。应查看 Out.Host 和 Out.URL.Host 的关系，而不是只看普通 Header 映射。

设置Rewrite后还需要Director吗？

不需要，不能同时配置二者。尤其要注意辅助构造器是否已经填入 Director。

SetXForwarded能直接给出用户真实IP吗？

它反映本跳可见的连接与入口信息；多层代理下，需要可信来源规则才能解释地址链，不能把该方法当作身份真实性证明。

最终要固定的是三个不同契约：上游路由到哪里、Host采用谁、哪些入口元数据允许传递。把这三件事分开写清，再选择回调接口，头改写才不会变成一组互相覆盖的赋值。