Go 怎么实现带路径前缀的 HTTP 反向代理

如果外部请求是 /api/users?id=7，而后端真正提供的是 /internal/users，Go 里可以用 net/http/httputil 的 ReverseProxy 完成转发。关键不在于直接套用目标 URL，而是在 Rewrite 中先移除公开前缀，再用 ProxyRequest.SetURL 拼接后端基路径。这样查询字符串仍然保留，路由职责也比较清楚。

最容易出错的写法，是把目标地址写成 http://127.0.0.1:9000/internal 后不处理入站路径，结果后端收到的是 /internal/api/users。本例明确约定：公网 /api 只是入口前缀，不属于后端业务路径。

先确定公开路径与后端路径的映射

先把路径规则写成表格，代码中的每一次修改都围绕这张表进行。Path 是路径字段，RawQuery 是问号后面的原始查询字符串，两者不要混为一谈。

用 Rewrite 去掉公开前缀并拼接目标基路径

NewSingleHostReverseProxy 可以快速代理单个主机，但这里需要明确控制前缀，所以直接构造 ReverseProxy 并使用 Rewrite。官方文档说明，SetURL 会把目标的 scheme、host、base path 与当前出站路径合并；因此去前缀必须发生在调用它之前。

package main

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

const publicPrefix = "/api"

func main() {
	target, err := url.Parse("http://127.0.0.1:9000/internal")
	if err != nil {
		log.Fatal(err) // 目标地址写错时直接停止启动，避免带着错误配置运行
	}

	proxy := &httputil.ReverseProxy{
		Rewrite: func(pr *httputil.ProxyRequest) {
			// 只修改出站请求，In 代表客户端原始请求，不能直接改写。
			path := pr.Out.URL.Path
			switch {
			case path == publicPrefix:
				pr.Out.URL.Path = "/" // /api 映射到 /internal/
			case strings.HasPrefix(path, publicPrefix+"/"):
				pr.Out.URL.Path = strings.TrimPrefix(path, publicPrefix)
			}
			// 清掉旧 RawPath，让 net/url 按新的 Path 重新编码。
			pr.Out.URL.RawPath = ""
			pr.SetURL(target)       // 拼成 /internal + 去前缀后的路径
			pr.SetXForwarded()      // 补充客户端 IP、Host 和协议来源
		},
		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
			http.Error(w, "backend unavailable", http.StatusBadGateway) // 统一返回 502
		},
		FlushInterval: -1, // 对流式响应尽快刷新；普通响应也可设为 0
	}

	mux := http.NewServeMux()
	mux.Handle("/api", proxy)  // 覆盖恰好为 /api 的请求
	mux.Handle("/api/", proxy) // 覆盖 /api/ 下的所有子路径
	log.Fatal(http.ListenAndServe(":8080", mux)) // 监听代理入口
}

这里没有手动拼接完整 URL，也没有重建请求对象。SetURL 负责目标协议、主机和基路径，SetXForwarded 负责转发来源头。默认情况下，SetURL 会把出站 Host 改成目标主机；如果后端必须看到原始 Host，可在它之后补上 pr.Out.Host = pr.In.Host。

补上转发头、路由入口和失败处理

ReverseProxy 会把后端响应复制给客户端。SetXForwarded 会设置 X-Forwarded-For、X-Forwarded-Host 和 X-Forwarded-Proto，后端可以据此记录来源或生成绝对地址。不要把客户端直接传来的转发头当成可信身份；如果代理前面还有不受信任的节点，应先设计好清理和信任边界。

ErrorHandler 只处理到达后端失败，或者 ModifyResponse 返回错误的情况。后端自己返回 404、500 等 HTTP 响应时，代理通常会把该响应转回客户端，不应在 ErrorHandler 里重复改写。FlushInterval: -1 适合需要及时刷新的流式响应，普通接口可以按响应特性选择默认值。

按请求样例检查常见路径坑

写完后先用请求样例做静态检查，再接入真实后端。重点是确认没有重复前缀、查询参数没有丢失、精确根路径能匹配。

• /api/users?id=7：应转成 /internal/users?id=7。
• /api：应转成 /internal/，而不是 /internal/api。
• /api/users?next=a%2Fb：不要用字符串拼接重写查询串，保留 RawQuery 的编码形式。
• /apix：不能误匹配为公开前缀；路由和 HasPrefix 判断都要带斜杠边界。

如果使用 http.StripPrefix("/api", proxy)，就不要再在 Rewrite 中移除一次 /api，否则会把有效路径截短。两种方案选一种即可：本例选择 Rewrite，便于把路径合成规则集中写在代理配置中。

相关问题

SetURL 会不会自动删除公开前缀？

不会。它会把目标基路径与当前路径合并，所以需要在调用前自行把不属于后端的 /api 去掉。

为什么后端收到的是 /internal/api/users？

通常是只设置了目标 /internal，没有修改 pr.Out.URL.Path。先移除公开前缀，再调用 SetURL 即可。

Director 还能不能用？

旧代码仍可能使用，但当前官方文档建议使用 Rewrite。它能在改写前清理 hop-by-hop 和转发头，减少客户端伪造或覆盖代理设置的风险。

参考：Go httputil.ReverseProxy 官方文档、Go net/url.URL 官方文档。