Go httputil.ReverseProxy ErrorHandler 怎样接管上游失败响应

如果 httputil.ReverseProxy 访问后端失败，客户端经常只看到一个笼统的 502。要接管这类错误，直接给 ReverseProxy.ErrorHandler 赋值即可：它负责处理“无法到达后端”的错误，也负责处理 ModifyResponse 返回的错误；没有自定义处理器时，标准库默认记录错误并返回 502。

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

关键边界是：ErrorHandler 不是所有代理异常的统一兜底。响应已经开始复制之后，如果读取响应体失败，标准库会按复制错误路径中止请求，不能再把它当成一个尚未写响应的普通上游错误来改状态码。

ErrorHandler 的触发范围先划清

ReverseProxy 内部先用 Transport 向后端发起请求。连接失败、DNS 失败、TLS 握手失败或 RoundTrip 返回错误时，代理还没有拿到可转发的后端响应，这时会调用 ErrorHandler。如果后端响应已经拿到，但 ModifyResponse 主动返回错误，也会走同一个处理器。

因此可以把处理器的职责压缩成三件事：记录经过脱敏的上下文、把内部错误映射为稳定的对外状态、写出一段不暴露后端地址和连接细节的响应。原始 error 适合写日志，不适合直接返回给用户。

自定义 ErrorHandler 怎么写

下面的示例把客户端主动取消与后端不可达分开处理，并给请求分配一个可追踪但不包含敏感信息的标识。状态码只是示例，实际项目应和网关、监控告警约定一致。

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "net/http/httputil"
    "net/url"
    "time"
)

func proxyError(w http.ResponseWriter, r *http.Request, err error) {
    // 先记录稳定的请求信息，不把后端地址和原始错误直接返回给客户端。
    requestID := r.Header.Get("X-Request-ID")
    log.Printf("proxy error request_id=%q method=%s path=%s err=%v", requestID, r.Method, r.URL.Path, err)

    status := http.StatusBadGateway // 默认把后端不可达归为 502。
    message := "upstream unavailable"
    if errors.Is(r.Context().Err(), context.Canceled) {
        status = 499 // 这是应用层约定，表示客户端已取消请求。
        message = "request canceled"
    } else if errors.Is(r.Context().Err(), context.DeadlineExceeded) {
        status = http.StatusGatewayTimeout
        message = "upstream timeout"
    }

    // 先设置类型和状态，再写固定文案，避免泄露内部错误细节。
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.WriteHeader(status)
    _, _ = w.Write([]byte(message + "\n")) // 响应写失败只记录在上层指标中。
}

func newProxy() http.Handler {
    target, _ := url.Parse("http://backend.internal") // 示例目标，生产环境应来自受控配置。
    proxy := &httputil.ReverseProxy{
        Rewrite: func(pr *httputil.ProxyRequest) {
            pr.SetURL(target) // 只展示目标替换，认证和路由策略不在本文范围内。
        },
        ErrorHandler: proxyError,
        ModifyResponse: func(resp *http.Response) error {
            if resp.StatusCode >= 500 {
                return errors.New("backend returned server error") // 让统一处理器接管策略。
            }
            return nil
        },
    }
    return proxy
}

func main() {
    srv := &http.Server{
        Addr: ":8080",
        Handler: newProxy(),
        ReadHeaderTimeout: 5 * time.Second, // 示例只展示服务入口的基本边界。
    }
    log.Fatal(srv.ListenAndServe())
}

示例里的 ModifyResponse 把 5xx 转成错误只是为了演示触发路径；如果业务需要把后端的 503 原样透传，就不要这样写。另一个细节是 499 并非 Go 标准库内置常量，而是常见的网关侧约定，团队没有统一约定时可以改成 408 或直接记录后返回。

三个容易误判的边界

一是响应写出后不能随意改状态。如果处理器已经调用 WriteHeader 或写入正文，后续再修改状态码通常不会生效。因此 ErrorHandler 应尽量一次性决定状态和固定文案，并避免把错误处理器再交给可能重复写响应的中间件。

二是 ErrorHandler 不等于 body 复制失败处理器。后端响应头和状态已经写给客户端后，代理开始复制响应体；复制过程中发生读取错误时，连接可能只能被中止。要观察这类问题，应在后端、Transport 和代理连接指标中记录，而不是期待 ErrorHandler 重新返回 JSON。

三是客户端取消要看请求上下文。后端错误本身不一定能说明请求为什么结束。用 r.Context().Err() 区分取消和 deadline，再结合内部日志中的 request ID，能避免把用户主动离开页面误报成后端故障。

常见问题

默认 ErrorHandler 返回什么？标准库默认记录错误，并向客户端返回 502 Bad Gateway；自定义处理器可以改变状态码和正文，但应保留内部错误只进日志。

ModifyResponse 返回错误后还能保留后端响应吗？不能把它当成正常响应继续透传。返回错误后会交给 ErrorHandler，是否返回 502、503 或其他状态由你的处理器决定。

能不能在 ErrorHandler 里直接返回 err.Error()？不建议。错误可能包含内部主机名、路径、证书或连接信息；对外返回稳定文案，对内记录脱敏后的上下文更安全。

结论是：把 ErrorHandler 当成“尚未写出后端响应时的错误策略入口”，覆盖后端请求失败和 ModifyResponse 错误；把响应体复制失败、客户端取消和已写响应后的限制单独看，代理错误处理才不会被一个 502 误导。