Go net/http/httputil 怎样记录请求转发细节

反向代理最难排查的现场，往往不是“请求有没有转发”，而是日志只留下了一个入口地址：我们不知道代理把请求改成了什么、后端返回了什么，也不知道 502 是后端拒绝还是网络失败。Go 的 net/http/httputil 不负责替你设计完整链路日志，但它提供了足够清晰的观察点。

官方地址：https://pkg.go.dev/net/http/httputil

本文把记录拆成三层：入口请求、Rewrite 后的出站请求、后端响应或代理错误。这样日志字段能和代理生命周期对应起来，又不会把完整请求体和敏感头部无差别写入日志。

先把请求转发拆成三个观察边界

ReverseProxy 是一个 HTTP Handler：它接收入站请求，再通过 Transport 发给后端，并把响应复制回客户端。记录时不要只在外层 Handler 打一条“开始代理”，而应该为三个边界保留同一个 request_id：

• 入站边界：记录方法、原始路径、Host 和客户端生成的请求标识。
• 出站边界：在 Rewrite 中确认目标 URL、Host 以及必要的 X-Forwarded-* 信息。
• 响应边界：在 ModifyResponse 记录状态码、响应长度和耗时；后端不可达时由 ErrorHandler 记录错误。

这个分层很重要：Rewrite 收到的是 ProxyRequest，其中 In 是代理收到的请求，Out 是准备发往后端的请求。文档明确要求 Rewrite 不要修改 In，也不要在返回后继续访问这组对象。

用 Rewrite 记录真正发往后端的请求

新代码优先使用 Rewrite，而不是已经弃用的 Director。Rewrite 执行前，代理会移除一批 hop-by-hop 头；SetURL 可以设置目标的 scheme、host 和基础路径，SetXForwarded 可以补充转发链信息。

package main

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

func newProxy(target *url.URL) *httputil.ReverseProxy {
	proxy := &httputil.ReverseProxy{
		Rewrite: func(pr *httputil.ProxyRequest) {
			// 只改写 Out，保留 In 作为入站审计上下文。
			pr.SetURL(target)
			pr.SetXForwarded()
			// 业务需要保留原 Host 时显式恢复，避免日志含义不清。
			pr.Out.Host = pr.In.Host
		},
		ErrorLog: log.Default(),
	}
	return proxy
}

func main() {
	target, err := url.Parse("http://backend.internal")
	if err != nil {
		log.Fatal(err) // 目标地址不可解析时不要启动错误代理。
	}
	http.Handle("/", newProxy(target))
	log.Fatal(http.ListenAndServe(":8080", nil)) // 示例服务监听代理入口。
}

如果只想记录请求行和头部，可以在 Rewrite 内调用 httputil.DumpRequestOut(pr.Out, false)。它面向出站客户端请求，包含标准 Transport 可能补充的 User-Agent 等头部；参数为 false 时不会读取正文，适合默认日志路径。

不要把 DumpRequestOut 当作脱敏器。Authorization、Cookie、签名参数和个人信息仍然需要在写日志前过滤；日志字段最好只保存方法、路径、目标服务、状态和 trace_id。

用响应钩子补上成功与失败链路

请求能发出去不代表链路完整。ModifyResponse 在后端返回响应后执行，后端不可达时它不会执行；这时应由 ErrorHandler 统一写入错误事件。下面的示例只演示日志边界，不把响应体复制到日志。

proxy := &httputil.ReverseProxy{
	Rewrite: func(pr *httputil.ProxyRequest) {
		// 先确定目标，再补充可追踪的转发头。
		pr.SetURL(target)
		pr.SetXForwarded()
	},
	ModifyResponse: func(resp *http.Response) error {
		// 这里只记录稳定元数据，避免读取或泄露响应正文。
		log.Printf("proxy response status=%d content_length=%d", resp.StatusCode, resp.ContentLength)
		return nil
	},
	ErrorHandler: func(w http.ResponseWriter, req *http.Request, err error) {
		// 记录请求路径和错误原因，并给客户端一个明确的网关状态。
		log.Printf("proxy error method=%s path=%s err=%v", req.Method, req.URL.Path, err)
		http.Error(w, "upstream unavailable", http.StatusBadGateway)
	},
}

注意 ModifyResponse 可能看到任意 HTTP 状态码，不应把“执行了该回调”直接等同于业务成功；业务是否成功要结合状态码和自己的响应协议判断。对于流式响应，FlushInterval 的行为也有特殊边界，记录代码不要为了采集正文破坏响应转发。

三条日志收敛规则

1. 默认不记正文。 DumpRequestOut(req, true) 会读取请求体；即使库会替换成新的 Reader，生产日志也不应默认复制大正文、上传文件或密码字段。
2. 不要信任客户端的转发头。 用 Rewrite 与 SetXForwarded 重新建立边界；如果还要沿用已有 X-Forwarded-For，先明确哪些代理是可信的。
3. 让一次请求只有一个关联标识。 将 request_id 放入入站日志、Rewrite 日志、响应日志和 ErrorHandler 日志，排障时按标识聚合，不依赖时间戳猜测上下游关系。

还要避免继续使用旧的 Director 作为新实现的默认选择。官方文档指出它存在 hop-by-hop 头被后续移除、客户端伪造 X-Forwarded-* 等风险；迁移到 Rewrite 后，代码应显式决定目标 URL、Host 和转发头。

常见问题

DumpRequest 和 DumpRequestOut 有什么区别？ DumpRequest 面向服务端收到的请求，DumpRequestOut 面向即将发出的客户端请求，后者能体现 Transport 添加的部分头部。

为什么日志里看不到后端错误？ 后端不可达时不会调用 ModifyResponse，应在 ErrorHandler 中记录错误；ModifyResponse 只适合处理“已经收到响应”的情况。

ReverseProxy 会自动转发所有头吗？ 不会。hop-by-hop 头会被清理，Rewrite 前的转发头也有明确处理规则；需要的头应在可信边界内显式重建。

归纳起来，ReverseProxy 的可观测性不是给每个回调都打一份完整 dump，而是用 Rewrite 记录“要发什么”，用 ModifyResponse 记录“收到了什么”，用 ErrorHandler 记录“为什么没收到”，再用脱敏、采样和请求体上限控制日志成本。