Go ResponseController Flush 为什么可能返回 ErrNotSupported

在 Go 的 HTTP Handler 里调用 http.NewResponseController(w).Flush()，如果返回 ErrNotSupported，通常不是 Flush 把网络“刷坏了”，而是当前的 ResponseWriter 没有暴露可刷新的能力。最常见的原因是中间件包了一层只实现 Header、Write、WriteHeader 的包装器，却没有实现 http.Flusher 或 Unwrap() http.ResponseWriter。

先分清能力缺失和网络延迟

官方 net/http 文档把 ResponseController 定义为 Handler 控制响应的入口。它并不凭空制造 Flush 能力，而是从传入的响应对象上查找实现。原生 HTTP/1.x 和 HTTP/2 响应通常支持 Flusher，但包装器可能把这个接口隐藏掉；这也是“直接传入 w 正常，经过中间件后返回 ErrNotSupported”的典型差异。

Flush 成功，只能说明服务器侧找到了并调用了刷新能力。客户端经过反向代理时，代理仍可能缓冲数据，直到响应结束才转发。因此排查时要把问题拆成两层：第一层是 Go 对象是否支持刷新，第二层是链路是否允许及时看到刷新结果。

Flush 为什么会返回 ErrNotSupported

可以把它理解成一条有限的探测链：先看当前对象是否实现带错误返回值的 FlushError() error；没有时再看是否实现 Flush()；仍没有时，如果有 Unwrap() http.ResponseWriter 就继续向内层走；都不满足才返回匹配 http.ErrNotSupported 的错误。

因此，下面这种包装器会截断能力：它完成了 http.ResponseWriter 的基本方法，却没有把 Flush 转发出去。不要只看它能不能 Write，就假定它能流式输出。

type plainWriter struct {
	// 只保存基础 ResponseWriter，未暴露 Flusher 或 Unwrap。
	http.ResponseWriter
}

func handler(w http.ResponseWriter, r *http.Request) {
	wrapped := plainWriter{ResponseWriter: w}
	ctl := http.NewResponseController(wrapped)
	if err := ctl.Flush(); err != nil {
		// ErrNotSupported 是能力分支，不能把它当成服务器崩溃。
		if errors.Is(err, http.ErrNotSupported) {
			_, _ = io.WriteString(wrapped, "buffered response")
			return
		}
		http.Error(wrapped, "flush failed", http.StatusInternalServerError)
		return
	}
	_, _ = io.WriteString(wrapped, "stream chunk")
}

示例中的降级路径只是说明处理策略：真实 Handler 还应在开头设置响应头、检查写入错误，并避免在已经开始响应后再次调用 http.Error。关键点是对能力缺失保持可接受的输出，而不是无条件强制转换成某个私有类型。

用 Unwrap 让中间件保留 Flush 能力

如果包装器确实需要统计字节数、记录状态码或统一加 Header，可以提供一个返回内层对象的 Unwrap 方法。ResponseController 会沿着包装链继续查找；这比在每个中间件里复制一套协议判断更容易维护。

type countingWriter struct {
	http.ResponseWriter
	bytes int
}

func (w *countingWriter) Write(p []byte) (int, error) {
	// 统计成功写入的字节，底层错误仍原样返回给 Handler。
	n, err := w.ResponseWriter.Write(p)
	w.bytes += n
	return n, err
}

func (w *countingWriter) Unwrap() http.ResponseWriter {
	// 让 ResponseController 能继续探测内层的 Flusher 或 FlushError。
	return w.ResponseWriter
}

func flushIfPossible(w http.ResponseWriter) error {
	// errors.Is 兼容 ResponseController 返回的包装错误。
	err := http.NewResponseController(w).Flush()
	if errors.Is(err, http.ErrNotSupported) {
		return nil // 不支持刷新时由调用方继续按普通响应处理。
	}
	return err
}

如果中间件自己实现了 FlushError() error，则应真实转发底层错误，而不是固定返回 nil。固定吞掉错误会让调用方误以为数据已经被刷新。

测试和线上排查要看哪些边界

单元测试里，httptest.NewRecorder() 实现了 http.Flusher，所以它可能比某个线上中间件更“强”。如果要覆盖包装器回归，应额外写一个只实现基础响应方法的测试 double，再写一个实现 Unwrap 的版本，分别断言 errors.Is(err, http.ErrNotSupported) 的结果。

最后还要确认调用时机：ResponseController 只能在 Handler 返回前使用。若业务并不依赖逐块可见，普通写响应往往更简单；只有明确需要 SSE、长轮询或渐进式输出时，才把 Flush 当作一个可探测的优化能力。

相关问题

ErrNotSupported 和 FlushError 返回的错误有什么区别？

前者表示没有找到可调用的刷新能力，后者表示能力存在但执行刷新时发生了具体错误。两者都应保留错误语义，调用方可用 errors.Is 区分能力分支。

实现了 Unwrap 就一定能让客户端立刻看到内容吗？

不一定。Unwrap 只解决 Go 响应对象的能力探测；反向代理、压缩中间件或客户端仍可能继续缓冲。

能不能直接断言 w.(http.Flusher)？

可以用于简单判断，但它无法穿过只提供 Unwrap 的包装器，也无法统一处理 FlushError。需要兼容中间件链时，优先使用 ResponseController。