Go http.Flusher 怎样判断流式响应能力

做 SSE、日志推送或长轮询接口时，最容易踩到的坑不是不会调用 Flush，而是把它当成了 http.ResponseWriter 的必备方法。正确做法是：先对当前的 ResponseWriter 做运行时类型断言，确认它实现了 http.Flusher；确认后，每写入一段增量内容就调用一次 Flush。如果断言失败，就返回普通响应或明确的降级结果。

官方地址：https://pkg.go.dev/net/http#Flusher

默认的 HTTP/1.x 和 HTTP/2 响应写入器通常支持 Flusher，但中间件包装器可能隐藏这个可选接口；即使服务端成功刷新，代理也可能继续缓冲，所以代码只能保证“请求刷新”，不能保证客户端立刻看到每一块数据。

先判断 ResponseWriter 是否有刷新能力

http.Flusher 只有一个 Flush() 方法，它代表当前响应写入器具备把已缓冲数据发送出去的能力。ResponseWriter 接口本身没有这个方法，因此不要直接写一个假定所有实现都支持的调用。

在处理器入口处做类型断言即可。这里的 ok 不只是语法细节，它是当前链路是否可以走流式路径的明确分界：

func writeStream(w http.ResponseWriter) (http.Flusher, bool) {
	// 可选接口必须在运行时判断，不能假设所有包装器都保留它。
	flusher, ok := w.(http.Flusher)
	if !ok {
		// 返回 false 让调用方选择普通响应或其它降级策略。
		return nil, false
	}
	return flusher, true
}

如果你只是在标准库默认服务器上使用，没有自定义中间件，断言通常会成功；但日志、鉴权、压缩、统一响应等中间件经常会重新包一层 ResponseWriter。因此，把类型断言留在真正需要流式能力的处理器里，比在全局代码中硬编码一个“必定支持”的假设更稳妥。

把 Flush 放在一次写入之后

流式响应的关键顺序是：设置响应头、写入一小段内容、调用 Flush，然后等待下一段内容。Flush 没有返回值，写入本身的错误仍要通过 fmt.Fprintf 或 Write 的返回值处理。

func streamHandler(w http.ResponseWriter, r *http.Request) {
	// 这些头要在第一次写入前设置，避免响应已经提交后再修改。
	w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
	w.Header().Set("Cache-Control", "no-cache")

	flusher, ok := w.(http.Flusher)
	if !ok {
		// 当前写入器不支持增量刷新时，返回清晰的降级结果。
		http.Error(w, "streaming is not supported", http.StatusNotImplemented)
		return
	}

	for i := 1; i 

这个示例只展示服务端的写入顺序，不代表浏览器、网关或客户端一定会逐块渲染。Flush 的职责是把当前服务端写入器中的缓冲向下游推进；它不是一个端到端的“立即可见”承诺。

包装器不支持时要准备普通响应

中间件如果只实现了 Header、Write 和 WriteHeader，即使它内部包着一个原本支持 Flusher 的写入器，外层值也可能无法通过 w.(http.Flusher)。这不是 Go 的断言错误，而是包装器没有把可选能力继续暴露出来。

type responseWrapper struct {
	http.ResponseWriter
}

func (rw responseWrapper) WriteHeader(code int) {
	// 这里转发基础响应能力，但没有声明 Flush 方法。
	rw.ResponseWriter.WriteHeader(code)
}

面对这类链路，业务处理器应明确两条路径：

• 支持 Flusher：发送增量数据，并在每块数据后刷新。
• 不支持 Flusher：改成一次性 JSON、完整文本或明确的“不支持流式”响应。

如果中间件确实需要保留流式能力，应在它的设计中转发所需的可选接口；但不要为了让某一个接口断言通过，就把所有方法都无条件转发。每一个可选能力都应根据底层对象实际支持情况决定是否暴露。

客户端取消和代理缓冲要分开处理

客户端主动关闭连接时，继续计算和写入没有意义。通过 r.Context().Done() 可以在下一次工作循环前退出；写入错误也应视为停止信号。这样做解决的是请求生命周期问题，不能替代对代理缓冲的认识。

官方文档特别提醒：即使当前 ResponseWriter 支持 Flush，客户端经过 HTTP 代理时，数据也可能直到响应完成才到达。于是排查“服务端已 Flush、客户端仍不动”时，至少要分三层看：

一张表记住 Flusher 的使用边界

因此，http.Flusher 最适合被理解成“当前 HTTP 响应写入器提供的一个可选刷新能力”。判断能力、按顺序写入、合理降级，再把代理当作独立链路因素处理，流式接口才不会被一个看似简单的类型断言带偏。

相关问题

为什么 ResponseWriter 不能直接调用 Flush？

因为 Flush 不属于 http.ResponseWriter 基础接口，而是由 http.Flusher 单独表达的可选能力。需要先做类型断言。

Flush 调用成功就代表浏览器马上收到数据吗？

不代表。它只说明服务端写入器执行了刷新动作，代理或客户端仍可能继续缓冲。

包装器怎样避免破坏流式响应？

包装器应根据底层对象真实能力选择性转发可选接口；业务侧仍要保留断言失败时的降级路径。