用 ResponseController 在代理中逐块刷新数据

我在做一个反向代理时遇到过一个很容易误判的现象：上游明明每隔一小段时间就产生数据，代理也持续调用 Write，但浏览器仍然等到响应结束才显示。处理这类场景，关键不是把整个响应读完再转发，而是“读一块、写一块、刷新一块”，并且把刷新失败当成客户端可能已经断开的信号。

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

代理为什么“写了数据”却没有及时显示

代理如果使用 io.ReadAll，自然会等上游结束；即使改成循环 Write，ResponseWriter 或中间件仍可能暂存数据。旧代码常见的写法是先断言 http.Flusher，这在原始 ResponseWriter 上可以工作，但自定义包装器没有实现 Flusher 时就会退化。

ResponseController 从 Go 1.20 引入，创建时接收当前的 ResponseWriter。它会优先寻找 FlushError() error 或 Flush()，也会沿着包装器提供的 Unwrap() 向下寻找。因此代理只需要保留当前 Handler 收到的 w，不必把它强行转换成某个服务器内部类型。

用 ResponseController 把上游响应逐块交给客户端

下面的示例把上游固定大小的读取缓冲直接转发到下游。示例只展示代理核心，不把它当作可直接暴露到公网的完整网关；生产代码还应补上超时、目标地址白名单和请求头过滤。

func proxyStream(w http.ResponseWriter, r *http.Request) {
    upstream, err := http.Get("https://example.internal/events")
    if err != nil {
        http.Error(w, "upstream unavailable", http.StatusBadGateway)
        return
    }
    defer upstream.Body.Close() // 无论读取还是下游写入失败，都及时释放连接

    w.Header().Set("Content-Type", upstream.Header.Get("Content-Type"))
    w.WriteHeader(upstream.StatusCode)
    controller := http.NewResponseController(w)
    buf := make([]byte, 32*1024) // 固定缓冲避免把整段响应读入内存

    for {
        n, readErr := upstream.Body.Read(buf)
        if n > 0 {
            if _, writeErr := w.Write(buf[:n]); writeErr != nil {
                log.Printf("proxy write stopped: %v", writeErr) // 客户端断开时停止转发
                return
            }
            if flushErr := controller.Flush(); flushErr != nil {
                log.Printf("proxy flush stopped: %v", flushErr) // 刷新失败不应继续读上游
                return
            }
        }
        if readErr == io.EOF {
            return // 上游正常结束，最后一块已经写出
        }
        if readErr != nil {
            log.Printf("upstream read stopped: %v", readErr) // 记录上游异常但不伪造完整响应
            return
        }
    }
}

这里不把 Flush 放在循环开头，是为了保证每次刷新前确实有新数据写入。Flush 返回错误时继续读取上游只会浪费连接和带宽；对长连接事件流来说，及时退出比尝试补发更可靠。

包装器、HTTP/2 和反向代理缓冲要分开判断

ResponseController 能否刷新，取决于当前 ResponseWriter 是否实现 Flush、FlushError，或能通过 Unwrap 返回支持这些方法的原始对象。若能力不存在，它会返回与 ErrNotSupported 匹配的错误；这时应该记录并结束流式路径，而不是假设刷新成功。

HTTP/2 不支持 Hijack，但普通响应刷新并不等于连接接管；代理只需使用 Flush。另外，官方文档明确提醒：即使 ResponseWriter 支持 Flush，客户端经过 HTTP 代理时，缓冲数据也可能要等响应结束才到达客户端，所以网关层还要检查是否启用了响应缓冲和压缩。

哪些场景不适合强行逐块刷新

小响应、需要完整校验后才能返回的 JSON，通常不值得为每一块增加刷新动作；刷得过密也会增加系统调用和网络包数量。对于 SSE、日志跟随、长任务进度等持续产生内容的接口，逐块刷新才更有意义。

采用前先做四项检查：上游是否真的持续产生数据；下游是否允许流式响应；中间件是否实现了正确的 Unwrap；写入、刷新和请求取消是否都能停止上游读取。若使用请求体与响应交错的 HTTP/1 场景，再单独评估 EnableFullDuplex，不要把它和代理输出刷新混为一谈。

常见问题

ResponseController.Flush 和直接调用 Flusher 有什么区别？

直接调用 Flusher 只覆盖当前对象实现该接口的情况；ResponseController 还能识别 FlushError，并沿 Unwrap 查找被包装的原始 ResponseWriter。

调用 Flush 后客户端一定马上看到内容吗？

不一定。它表示服务端尝试把缓冲交给客户端连接，前置网关、压缩层、浏览器和网络仍可能继续缓冲。

刷新失败后应该重试吗？

通常不应重试。写入或刷新失败往往代表客户端已断开；停止读取上游并关闭 Body，避免无意义地消耗资源。