ResponseController Flush 后客户端仍无数据的原因

我第一次遇到这个问题时，服务端日志已经打印了“写入一小段数据并 Flush”，但浏览器和 SDK 都像没有收到任何内容。后来把链路拆开才发现，Flush 解决的只是 Go 服务端当前这一层的缓冲；包装器、反向代理和客户端读取方式仍然可能继续等待。

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

先检查 Flush 的返回错误和 ResponseWriter 是否透传，再分别观察服务端、代理、客户端三段的首字节时间。只要其中一段仍在缓冲，客户端就可能看不到中间数据。

先确认 Flush 真正作用到了哪一层

http.NewResponseController(w).Flush() 会尝试调用 FlushError 或 Flusher，也会沿着包装器提供的 Unwrap 找到原始的 ResponseWriter。如果中间件只实现了 Header、Write 和 WriteHeader，却没有透传这些能力，调用可能返回不支持错误，或者刷新只发生在外层缓冲。

func stream(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)
    w.Header().Set("Content-Type", "text/plain; charset=utf-8") // 先声明分段文本格式

    for _, part := range []string{"part-1\n", "part-2\n"} {
        if _, err := io.WriteString(w, part); err != nil { // 写入失败时立即结束，避免继续刷新无效连接
            return
        }
        if err := controller.Flush(); err != nil { // 记录不支持或连接断开的真实原因
            http.Error(w, "flush failed", http.StatusInternalServerError)
            return
        }
    }
}

示例中的返回错误很重要：Flush 成功只表示当前 ResponseWriter 接受了刷新请求，并不等于数据已经经过代理并被客户端应用层读取。

把响应格式和客户端等待拆开

服务端即使逐段写入，客户端也可能因为自己的读取策略而暂时不返回结果。例如客户端按完整 JSON 解码，就会一直等待闭合的 JSON；浏览器对某些响应类型也可能先积累数据。排查时先用纯文本和明确的换行验证“是否收到字节”，不要一上来把格式解析和网络传输混在一起。

还要注意首个分段太小的情况：Go 侧已经调用刷新，但中间设备可能按自身阈值积累；这不是把 Flush 多调用几次就能解决的。可以在每个分段前后记录序号和时间，把服务端写出时间与客户端读取时间对照。

把缓冲位置拆成三段来查

我现在会按三段排查，而不是只盯着 Go 日志：

• Go 服务端：记录 Write 和 Flush 的错误、响应头、分段序号，确认包装器是否实现 Unwrap。
• 反向代理：确认是否启用了响应缓冲、压缩或缓存。代理可能等到响应完成才向下游转发。
• 客户端：改用能按块读取的方式观察首字节和每个分段，不要只看最终解析结果。

官方对 Flusher 的说明也特别提醒：即便 ResponseWriter 支持 Flush，经过 HTTP 代理时，缓冲数据仍可能直到响应完成才到达客户端。所以问题出现在代理链路时，继续改 Go 代码通常不会改变现象。

修复顺序：先透传，再处理代理缓冲

如果是自定义 ResponseWriter，优先补齐 Unwrap() http.ResponseWriter，让 ResponseController 能回到原始对象；不要只在外层伪造一个 Flush 方法。随后在测试环境逐段关闭代理响应缓冲或压缩，观察首字节时间是否变化。生产环境是否关闭缓冲，要结合响应大小、缓存策略和连接数决定，不能把所有接口都改成实时流。

最后确认请求是否真的需要流式响应。如果客户端只在完整结果到齐后才处理，流式写出没有用户价值；如果是进度、事件或长任务状态，则应同时设计分段协议、断开重连和超时策略。

常见问题

Flush 返回 nil，为什么客户端仍然没有数据？

因为 nil 只说明当前服务端写出层没有报告错误，代理或客户端仍可能缓冲。继续查三段链路的首字节时间。

把 ResponseWriter 转成 Flusher 还需要 ResponseController 吗？

直接断言只能覆盖当前对象实现 Flusher 的情况。ResponseController 能处理 FlushError，并沿 Unwrap 查找原始 writer，更适合经过中间件的代码。

是否可以通过不断 Flush 强制浏览器立即显示？

不能保证。Flush 不是端到端实时协议；应先确认响应格式、代理配置和客户端读取方式，再决定是否调整分段大小。

这类故障最有效的判断标准不是“代码里有没有 Flush”，而是能否回答三个时间点：Go 何时写出、代理何时转发、客户端何时读到。把这三个点分别记录下来，通常就能快速判断到底是能力没透传，还是数据卡在下游缓冲。