Go http.Flusher 什么时候能把流式响应及时发给客户端

做 SSE、实时日志或长耗时接口时，常见现象是服务端明明调用了 Flush()，浏览器却等到请求结束才一次性看到内容。关键结论是：http.Flusher 只负责把 Go HTTP 服务端当前缓冲的数据向客户端连接推进，不能越过不支持刷新的 ResponseWriter 包装器，也不能强迫反向代理取消缓冲。

http.Flusher 到底保证了什么

Flusher 是一个只有 Flush() 方法的接口。Go 官方文档说明，默认的 HTTP/1.x 和 HTTP/2 响应实现支持它，但自定义 ResponseWriter 包装器不一定支持；处理器应在运行时用类型断言判断。调用成功也只表示服务端尝试刷新已缓冲数据，经过代理后仍可能被继续缓存。

因此要把链路拆成三段看：Handler 是否写出了事件，Go 的响应实现是否执行了刷新，中间代理和客户端是否把字节继续攒住。不要把“Flush 被调用”直接等同于“用户已经看到”。

最小可用的流式响应写法

下面的例子把每条消息写成 SSE 事件。头部必须在第一次写入前准备好；类型断言失败时应直接返回明确错误，避免把普通响应误当成流式响应。

func stream(w http.ResponseWriter, r *http.Request) {
    // 先声明事件流格式，并禁止客户端按缓存响应处理
    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")

    flusher, ok := w.(http.Flusher)
    if !ok {
        // 包装器没有转发 Flush 时，不继续伪装成流式接口
        http.Error(w, "streaming is not supported", http.StatusInternalServerError)
        return
    }

    for i := 1; i 

这个顺序很重要：Write 产生数据，Flush 推进当前缓冲，下一轮再写下一条。生产代码还应处理写入错误、服务端写超时和业务取消。若使用心跳，心跳本身也要写成客户端能识别的格式并定期刷新。

Flush 仍不及时到达时怎么排查

排查时可先绕过代理访问 Go 服务，再加入代理比较首字节和每条事件的到达时间。不要在生产环境盲目设置 Content-Length；持续响应通常要让服务器使用适合流式传输的方式。若启用了 gzip 等压缩，中间层可能等待更多数据才输出，测试时应暂时移除或明确配置。

把包装器和代理纳入设计

最稳妥的接口契约不是承诺“调用 Flush 后用户立刻看到”，而是承诺“服务端按事件写入并尽力刷新；若链路不支持则返回可诊断错误”。自定义包装器至少要明确是否转发 http.Flusher；在较新的 Go 代码中，也可以了解 http.NewResponseController(w).Flush() 的错误返回语义，但它同样不能绕过代理缓冲。

上线前做一次分层检查：直连 Go 服务能否逐条收到；经过网关是否仍逐条到达；启用压缩、鉴权和日志中间件后类型断言是否仍成功；客户端断开后 Handler 是否及时退出。做到这些，http.Flusher 才会从“看似调用了但没效果”变成可解释的流式链路。

常见问题

调用 Flush 之前必须先调用 WriteHeader 吗？

不一定。第一次 Write 会隐式提交成功状态，但建议先设置所有响应头，再写数据并刷新；一旦头部提交，后续修改普通响应头通常不会生效。

ResponseWriter 一定实现 http.Flusher 吗？

默认 HTTP/1.x 和 HTTP/2 实现支持，但包装器可能不支持，所以必须运行时检测，不能只凭服务端类型或协议版本猜测。

Flush 能解决代理缓存吗？

不能保证。官方文档明确提醒，客户端经过 HTTP 代理时，缓冲数据可能直到响应完成才到达客户端；需要把代理配置和压缩策略一起排查。

参考：Go net/http Flusher 文档。