Go net/http ResponseController 如何提前刷新响应：Flush、流式输出与代理边界

做 SSE、日志跟随或大文件分段输出时，服务端明明已经写入第一段内容，客户端却要等到整个处理结束才看到结果，问题通常不在 Write 本身，而在响应仍停留在缓冲区。Go 的 net/http 可以用 http.NewResponseController(w).Flush() 请求刷新当前响应；但它只解决服务端这一层，ResponseWriter 包装和反向代理的缓冲仍要单独核对。

先分清“写入成功”和“客户端已收到”

ResponseWriter.Write 返回成功，只能说明当前处理器把字节交给了 HTTP 服务端的响应链。对于流式接口，还要确认三个边界：首段是否已经写出、服务端是否调用了 Flush、链路中是否还有代理缓冲。

从 Go 1.20 开始，ResponseController 把刷新、连接接管以及读写截止时间等能力收在一个控制器里。它会沿着支持 Unwrap() 的 ResponseWriter 包装向内查找；不支持目标能力时返回与 http.ErrNotSupported 匹配的错误。

最小实验：写一段就刷新一段

下面的处理器先写入 part-1，随后刷新，再等待一个短暂信号，最后写入 part-2。真实项目里不要用固定等待模拟业务，这里只是为了让客户端检查首段是否已经可读。

package main

import (
    "fmt"
    "net/http"
    "time"
)

func stream(w http.ResponseWriter, r *http.Request) {
    ctl := http.NewResponseController(w)

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    fmt.Fprintln(w, "part-1: headers and first result")
    if err := ctl.Flush(); err != nil {
        http.Error(w, "flush failed", http.StatusInternalServerError)
        return
    }

    time.Sleep(300 * time.Millisecond)
    fmt.Fprintln(w, "part-2: final result")
}

func main() {
    http.HandleFunc("/stream", stream)
    http.ListenAndServe(":8080", nil)
}

这个例子有一个容易忽略的点：刷新前先写入内容，刷新只会处理已经进入响应的字节。若业务还没有产生任何数据，单独调用 Flush 不会凭空制造客户端可见内容。

用 httptest 检查首段数据是否先到

仅看最终响应正文，无法证明流式边界生效。测试应在读取首段后再放行处理器继续写入，这样测试会在 Flush 失效时卡在首段读取处。

func TestStreamFlush(t *testing.T) {
    release := make(chan struct{})
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctl := http.NewResponseController(w)
        fmt.Fprint(w, "part-1")
        if err := ctl.Flush(); err != nil {
            t.Errorf("Flush() error = %v", err)
            return
        }
        

实际测试文件还需要导入 fmt、io、net/http、net/http/httptest 和 testing。检查重点不是响应最终包含两段，而是第二段尚未放行时，第一段已经可以被 io.ReadFull 读到。

ResponseWriter 被包装后，为什么会出现 ErrNotSupported

中间件常常把 http.ResponseWriter 包成自己的类型，只转发 Header、Write 和 WriteHeader。如果这个包装器没有实现 Flush，也没有实现返回原始 writer 的 Unwrap，控制器就找不到真正的刷新能力。

type responseWrapper struct {
    http.ResponseWriter
}

// 让 ResponseController 能够继续查找底层 writer。
func (w responseWrapper) Unwrap() http.ResponseWriter {
    return w.ResponseWriter
}

func handler(w http.ResponseWriter, r *http.Request) {
    wrapped := responseWrapper{ResponseWriter: w}
    ctl := http.NewResponseController(wrapped)
    fmt.Fprintln(wrapped, "ready")
    if err := ctl.Flush(); err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(wrapped, "streaming is not supported", http.StatusNotImplemented)
            return
        }
        http.Error(wrapped, "flush failed", http.StatusInternalServerError)
        return
    }
}

这里的 Unwrap 不是装饰性方法，它是 ResponseController 穿过包装层的约定。若中间件还需要自己实现 Flush，也应该明确处理底层刷新错误；不要只声明一个空方法让上层误以为数据已经发出。

代理边界：Flush 不是“立刻渲染”开关

Go 文档明确提醒，即使 ResponseWriter 支持 Flush，客户端经过 HTTP 代理时，已刷新的内容也可能等到响应完成后才到达。因而排查时要把链路拆成“处理器写入 → Go 服务端刷新 → 网关转发 → 客户端读取”四段，不能只在应用日志里看到 Flush() 返回 nil 就下结论。

SSE 通常还需要设置 Content-Type: text/event-stream，并按事件格式写入空行；普通文本流则应让客户端采用逐块或逐行读取。是否需要关闭代理缓存，要按实际网关的配置和安全策略验证，不能把某个产品的配置名当成 Go 标准库行为。

常见问题：Flush 到底该怎么判断

调用 Flush 后还需要再次调用 Write 吗？

需要。Flush 只处理调用前已经写入的内容，后续业务数据仍要通过 Write 写入；每次希望形成一个可观察的分段时，再根据场景调用 Flush。

为什么本地 httptest 能分段，线上浏览器却看不到？

最常见是反向代理或客户端读取策略继续缓冲。先用命令行按流式方式读取，再逐层绕过网关对比，确认到底是哪一段重新聚合了响应。

ResponseController.Flush 返回错误时能不能忽略？

不建议。至少应记录错误并停止继续发送依赖分段边界的内容；如果业务允许降级，可以把完整响应作为备用路径，但要由调用方明确知道结果已经改变。

清理与验收清单

• 首段内容已经 Write，再调用 ResponseController.Flush，并检查返回错误。
• 所有 ResponseWriter 包装层都明确支持 Flush 或 Unwrap。
• 测试在第二段写入前读取并断言首段，而不是只比较最终正文。
• 分开核对 Go 服务端、代理网关和客户端读取方式的缓冲行为。
• 客户端断开时及时结束生成工作，避免继续生产无用的流式内容。