Go ResponseController Flush 返回不支持时的兼容处理

http.NewResponseController(w).Flush() 返回“不支持”时，先用 errors.Is(err, http.ErrNotSupported) 判断，不能写成 err == http.ErrNotSupported。然后按业务约束二选一：允许普通完整响应就降级并结束增量发送；SSE、分块下载等强依赖及时刷新的场景，则把它视为能力缺失并停止流式逻辑。

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

最常见的根因并不是 Go 自带 HTTP 服务端不会 Flush，而是日志、压缩或指标中间件包装了 ResponseWriter，却没有实现 Unwrap() http.ResponseWriter。修好包装器通常比在每个 Handler 里重复类型断言更稳妥。

先判断不支持来自哪里

我排查这类问题时，先不急着改 Handler，而是看 ResponseWriter 是否经过中间件。Go 标准库的默认 HTTP/1.x 和 HTTP/2 Writer 支持 http.Flusher，但包装器可能把这个可选接口“藏”起来。

ResponseController.Flush 的能力发现顺序很明确：优先调用 FlushError() error，其次调用 http.Flusher.Flush()，再检查当前 Writer 是否提供 Unwrap() http.ResponseWriter 并继续查找。整个链条都找不到时，才返回匹配 http.ErrNotSupported 的错误。

标准库为了保留错误链，返回的是包装过的“不支持”错误，因此直接相等比较会漏判。正确写法始终是 errors.Is。

err := http.NewResponseController(w).Flush()
switch {
case err == nil:
	// 服务端 Writer 已接受刷新请求
case errors.Is(err, http.ErrNotSupported):
	// 当前 Writer 链没有暴露刷新能力，可按业务策略降级
default:
	// 这是实际刷新失败，不能当成“不支持”吞掉
	return err
}

比较三种兼容方案

可选方案不是“哪个 API 更新就用哪个”这么简单，关键是 Go 版本、中间件控制权和业务是否必须流式传输。

我的默认选择是：Go 1.20+ Handler 使用 ResponseController；发现自有中间件导致不支持就补 Unwrap；只有维护旧版兼容代码时才保留直接的 http.Flusher 断言。

用 errors.Is 做可控降级

“兼容处理”不等于忽略所有错误。可以把 Flush 包成一个小函数，把“不支持”转换为布尔能力，把真正的 I/O 错误继续返回。

package stream

import (
	"errors"
	"net/http"
)

func flushIfSupported(w http.ResponseWriter) (bool, error) {
	err := http.NewResponseController(w).Flush()
	if err == nil {
		return true, nil
	}
	if errors.Is(err, http.ErrNotSupported) {
		// 不支持属于能力差异，交给调用方选择降级或失败
		return false, nil
	}
	// 网络或底层 Writer 错误必须继续上抛
	return false, err
}

下面是一个尽力流式输出的 NDJSON Handler。第一次刷新不受支持时，它停止逐条 Flush，写完剩余数据后正常返回；客户端仍能得到完整响应，只是失去低延迟增量到达。

func eventsHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/x-ndjson")

	for i := 0; i 

如果业务是 SSE 心跳、长轮询分段结果或必须及时送达的进度流，不应静默降级。此时把 false 转成领域错误并结束请求，同时在部署检查中确认反向代理关闭或调整了相关缓冲策略。

让包装器暴露 Unwrap

中间件包装 ResponseWriter 常用于记录状态码。如果包装器只实现 Header、Write 和 WriteHeader，外层类型就不再满足 http.Flusher。Go 1.20+ 最简单的修复是增加 Unwrap。

type statusWriter struct {
	http.ResponseWriter
	status int
}

func (w *statusWriter) WriteHeader(code int) {
	w.status = code
	w.ResponseWriter.WriteHeader(code)
}

func (w *statusWriter) Unwrap() http.ResponseWriter {
	// 返回真实底层 Writer，让 ResponseController 继续发现可选能力
	return w.ResponseWriter
}

不要让 Unwrap 返回自身，否则控制器会一直循环；也不要返回无关 Writer。若包装器本身需要拦截刷新行为，可实现 FlushError() error，在完成自己的缓冲处理后再向底层转发。

测试支持与不支持两条路径

httptest.ResponseRecorder 实现了 http.Flusher，其 Flushed 字段可验证是否调用过 Flush。要测试不支持路径，则需要一个只实现基础 ResponseWriter 的测试替身。

type plainWriter struct {
	header http.Header
	body   bytes.Buffer
	code   int
}

func (w *plainWriter) Header() http.Header {
	if w.header == nil {
		w.header = make(http.Header)
	}
	return w.header
}

func (w *plainWriter) Write(p []byte) (int, error) {
	if w.code == 0 {
		w.code = http.StatusOK
	}
	return w.body.Write(p)
}

func (w *plainWriter) WriteHeader(code int) {
	w.code = code
}

func TestFlushUnsupported(t *testing.T) {
	w := &plainWriter{}
	err := http.NewResponseController(w).Flush()
	if !errors.Is(err, http.ErrNotSupported) {
		// 必须用 errors.Is，因为标准库返回的是包装错误
		t.Fatalf("got %v, want ErrNotSupported", err)
	}
}

type unwrapWriter struct {
	http.ResponseWriter
}

func (w *unwrapWriter) Unwrap() http.ResponseWriter {
	// 允许控制器穿过测试包装器访问 Recorder 的 Flusher 能力
	return w.ResponseWriter
}

func TestFlushThroughWrapper(t *testing.T) {
	recorder := httptest.NewRecorder()
	w := &unwrapWriter{ResponseWriter: recorder}

	if err := http.NewResponseController(w).Flush(); err != nil {
		t.Fatalf("Flush() error = %v", err)
	}
	if !recorder.Flushed {
		t.Fatal("underlying writer was not flushed")
	}
}

这两条测试覆盖了最关键的兼容边界：真正无能力时错误可被识别；包装器正确暴露底层 Writer 时，控制器能够完成刷新。

不适用情况与代理缓冲

• Handler 已返回：ResponseController 不能在 ServeHTTP 返回后继续使用。
• 代理仍在缓冲：服务端 Flush 成功不代表数据已经穿过反向代理到达客户端，代理可能等响应结束再转发。
• 压缩中间件：压缩器可能有自己的缓冲语义，仅提供 Unwrap 不一定满足业务的立即发送要求，应查清该中间件是否实现 FlushError 或 Flusher。
• Header 已提交：写正文或 Flush 后通常不能再可靠修改状态码，错误处理应记录并结束，而不是尝试返回新的 JSON 错误页。
• 旧版 Go：Go 1.20 以前没有 ResponseController，需要直接断言 http.Flusher，或升级工具链。

兼容选择决策表

相关问题

为什么 err == http.ErrNotSupported 判断失败？

ResponseController 返回的是包装错误，标准库明确保证它能匹配 ErrNotSupported，但不保证直接相等。使用 errors.Is(err, http.ErrNotSupported)。

Flush 返回 nil 就能保证浏览器立即收到吗？

不能。它表示当前服务端 Writer 已执行刷新，但反向代理、网关、压缩层和客户端仍可能缓冲。

ResponseController 比 http.Flusher 好在哪里？

它能返回错误，识别 FlushError，并沿实现了 Unwrap 的包装器继续查找底层能力；直接类型断言只能看到当前最外层对象。