Go net/http ResponseController Flush 在代理后不生效怎么办

我排查 Go 流式响应时，最容易误判的一点是：http.ResponseController.Flush() 返回 nil，并不等于浏览器已经马上看到了这一块内容。它只说明 Go 的响应写入链路接受了刷新请求；如果中间的反向代理继续缓存，客户端仍可能等到响应结束才一次性收到数据。

结论：先确认 Go 端的 ResponseWriter 能否刷新，再检查代理是否开启响应缓冲。Go 端调用 Flush 与代理端把数据立即转发给客户端，是两个独立的决策点。

官方资料：https://pkg.go.dev/net/http@go1.27.3#ResponseController.Flush

先区分 Flush 成功与客户端及时收到

Go 官方对 Flusher 的定义是“把已缓冲数据发送给客户端”，但同时明确提醒：客户端经过 HTTP 代理时，即使响应写入器支持 Flush，数据也可能在响应完成前到不了客户端。这里的“客户端”应理解为 Go 服务端连接的下一跳，不代表已经穿过所有代理、网关和 CDN。

因此排查时不要只看应用日志里的“Flush 成功”。更有价值的是把链路拆成三段：处理器是否写出了分块，代理是否立即转发，客户端是否按流式方式读取。只要第二段有缓存，第一段正常也不会改变最终体验。

确认 ResponseWriter 是否仍暴露 Flush 能力

ResponseController 的好处是可以适配包装后的响应写入器。它会优先寻找 FlushError() error，其次寻找 Flush()，再沿着包装器的 Unwrap() 继续查找；找不到时返回可用 errors.Is 判断的 http.ErrNotSupported。这解决的是 Go 进程内的包装边界，不会修改外部代理的缓存策略。

func stream(w http.ResponseWriter, r *http.Request) {
	// 这些响应头分别用于减少缓存，并告诉 Nginx 不要缓存这条响应。
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.Header().Set("Cache-Control", "no-cache")
	w.Header().Set("X-Accel-Buffering", "no")

	controller := http.NewResponseController(w)
	for i := 1; i <= 3; i++ {
		// 每一轮先写一块，再请求 Go 端把当前缓冲交给下一跳。
		if _, err := fmt.Fprintf(w, "chunk %d\n", i); err != nil {
			return
		}
		if err := controller.Flush(); err != nil {
			// 包装器没有暴露刷新能力时，应该记录并平滑结束。
			if errors.Is(err, http.ErrNotSupported) {
				return
			}
			return
		}
		time.Sleep(time.Second)
	}
}

示例里的 X-Accel-Buffering 是 Nginx 识别的响应头，不是 Go 标准库的控制开关。如果链路中没有 Nginx，它不会自动让其他代理关闭缓存；此时仍要在对应代理或网关上找流式响应配置。

把代理缓冲放在链路配置里处理

以 Nginx 为例，proxy_buffering 默认是 on。开启时 Nginx 会尽快从上游读取响应，并保存到缓冲区或临时文件；关闭后，响应会在接收时同步传给客户端。也就是说，Go 端的 Flush 负责把数据交给 Nginx，而 Nginx 是否立即转发要由代理配置决定。

location /stream {
    # 只对需要逐块返回的接口关闭代理响应缓冲。
    proxy_buffering off;
    proxy_pass http://go_backend;
}

如果不能为某个路径单独改配置，可以保留代理默认策略，让上游按响应头声明不缓存：

// 上游服务按接口声明：经过 Nginx 时不要缓存这条响应。
w.Header().Set("X-Accel-Buffering", "no")

这类设置应只用于确实需要实时分块的接口。普通 JSON、下载或大响应继续缓冲，通常更利于吞吐和磁盘/内存控制；把全站缓冲关闭会扩大连接占用和慢客户端带来的压力。

用最小处理器判断问题落在哪一层

我通常先保留三块、每块间隔一秒的最小处理器，再通过同一路径分别直连 Go 服务和经过代理访问。直连也不分块时，优先检查写入顺序、响应包装和客户端读取方式；直连分块而代理不分块时，优先看 proxy_buffering、缓存规则和 CDN 的响应策略。

排查清单可以压缩成四项：

1. 确认在第一次写入前已经设置好响应头，避免响应开始后再修改缓存相关字段。
2. 确认中间件没有把原始 ResponseWriter 包装成既不实现 Flush、也不提供 Unwrap 的类型。
3. 记录 Flush 返回的错误；nil 只代表 Go 端接受了刷新，不代表整条链路即时可见。
4. 只对流式接口关闭代理缓冲，并同时关注慢客户端、超时和连接数成本。

这样定位后，“代理后 Flush 不生效”通常会被还原成一个更准确的结论：Go 端刷新成功，但代理仍在按自己的缓存策略聚合响应。

相关问题

ResponseController.Flush 返回 nil，为什么客户端还是最后才收到？

因为返回值只反映 Go 端响应写入器的刷新结果；反向代理、网关、CDN 或客户端本身仍可能缓存或等待更多数据。

一定要使用 ResponseController 才能流式输出吗？

不一定。直接判断并使用 http.Flusher 也可以，但 ResponseController 能处理支持 Unwrap 的包装层，并把不支持情况统一返回为错误。

关闭代理缓冲后就能保证浏览器逐块显示吗？

不能保证。还要看客户端读取方式、协议和其他中间层；关闭 Nginx 缓冲只是消除其中一个常见聚合点。