Go 怎样让流式响应及时刷新到客户端

做一个“边生成边返回”的 Go 接口时，单纯多次调用 Write，客户端常常还是等到处理器结束才看到完整内容。关键不是把响应拆成更多字符串，而是在每个完整片段写入后主动刷新缓冲区：先判断 http.ResponseWriter 是否实现 http.Flusher，再调用 Flush()。不过它只负责 Go 服务端这一段，代理和客户端仍可能继续缓冲。

官方资料：https://pkg.go.dev/net/http

先判断 ResponseWriter 是否支持刷新

标准库默认的 HTTP/1.x 和 HTTP/2 响应写入器支持 Flusher，但日志中间件、压缩中间件或自定义包装器可能只转发了 Header、Write 和 WriteHeader。因此不要直接强制断言，否则换一层中间件就可能 panic。

func streamHandler(w http.ResponseWriter, r *http.Request) {
	// Flusher 是可选接口，先判断能力，避免被包装器隐藏时直接崩溃。
	flusher, ok := w.(http.Flusher)
	if !ok {
		http.Error(w, "streaming is not supported", http.StatusNotImplemented)
		return
	}

	// 第一次 Write 会提交响应头，所以类型必须在写入正文前设置。
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	for i := 1; i 

示例中的 fmt 和 time 需要导入。这里的 Flush 没有错误返回值，真正的网络写入失败通常会在下一次 Write 时体现，所以循环内仍要检查写入结果。

写入顺序决定首个片段能否尽快出去

实际使用时可以把判断、响应头和循环拆成三个稳定阶段。先设置内容类型等头部；再写一个客户端能识别的完整片段；最后刷新。不要把刷新放在循环外，也不要在写入前设置一个会让客户端误判长度的固定 Content-Length。

如果接口输出的是 JSON，不能把多个独立 JSON 对象直接拼在一起期待客户端一次解析。可以采用换行分隔的 JSON、明确的文本协议，或者让调用方按自己的流协议消费；本文只讨论刷新动作，不替代具体协议设计。

用客户端和 httptest 分开观察两件事

本地观察时，客户端也可能主动把标准输入攒起来。使用 curl --no-buffer 可以减少 curl 自己的显示缓冲：

# --no-buffer 只关闭 curl 的显示缓冲，不代表代理一定不会缓冲。
curl --no-buffer http://127.0.0.1:8080/stream

测试中则不必等待真实网络。httptest.ResponseRecorder 实现了 http.Flusher，可以检查处理器是否调用过刷新：

rec := httptest.NewRecorder()
req := httptest.NewRequest(http.MethodGet, "/stream", nil)

// 调用处理器后检查 Flushed，验证的是服务端调用行为。
streamHandler(rec, req)
if !rec.Flushed {
	t.Fatalf("expected handler to flush response")
}

这个断言只能证明处理器调用了 Flush，不能证明浏览器已经在某个时间点显示了第一个片段。服务端行为和端到端到达是两层不同的问题。

为什么 Flush 后客户端仍可能看不到数据

优先按下面的顺序排查：

• 包装器：确认中间件是否实现并转发 http.Flusher；如果不支持，先修正包装器或在该路径明确降级。
• 服务端：确认每次片段写入后都刷新，且没有在处理器返回后才统一拼接正文。
• 代理：即使 Go 已经刷新，HTTP 反向代理也可能按自己的缓冲策略攒到响应结束。
• 客户端：命令行工具、浏览器脚本或 SDK 可能等待读取更多内容后才回调业务层。

所以，Flusher 的准确含义是“把 Go 服务端当前的已缓冲数据交给连接层”。它不是“强制所有网络中间设备立即展示”的开关。生产环境应把代理配置、客户端读取方式和断开后的写入错误一起纳入验证。

相关问题

ResponseWriter 一定支持 Flusher 吗？

不一定。默认 HTTP/1.x 和 HTTP/2 实现通常支持，但包装器可能不支持，代码应在运行时判断。

Flush 是否会自动解决代理缓存？

不会。官方文档明确提醒代理可能继续缓存，必须单独检查反向代理和客户端。

测试里检查 Flushed 就等于验证实时到达吗？

不等于。它只验证处理器调用了刷新，网络链路的即时显示需要另外做分层测试。