Go http.Flusher 断言失败的兼容处理

在 Go HTTP 中，直接把 http.ResponseWriter 断言成 http.Flusher 并不总能成功。默认的 HTTP/1.x 和 HTTP/2 响应写入器通常支持 Flush，但中间件为了记录状态码、追加响应头或做压缩而包了一层之后，外层类型可能不再暴露这个可选接口。

兼容处理的关键不是强行让每个包装器都实现 Flush，而是先判断能力，再选择透传或降级路径。Go 1.20 及更高版本还可以用 http.NewResponseController 统一调用，并通过 Unwrap 找回原始写入器。

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

先看断言失败发生在哪一层

假设一个流式响应经过日志中间件。处理函数拿到的是中间件返回的对象，而不是服务器内部最初创建的响应写入器。如果中间件只实现了 Header、Write 和 WriteHeader，那么这个包装器满足 http.ResponseWriter，却不一定满足 http.Flusher。

因此不要写成无条件断言。用 ok 形式可以把“当前写入器是否支持 Flush”变成一个明确分支：

func writeChunk(w http.ResponseWriter, data []byte) {
	// 先写入本次响应内容，避免只 Flush 空缓冲区。
	if _, err := w.Write(data); err != nil {
		return
	}

	// Flusher 是可选接口；包装器或测试替身可能不提供它。
	if flusher, ok := w.(http.Flusher); ok {
		flusher.Flush()
		return
	}

	// 不支持时保留普通 ResponseWriter 语义，交给调用方决定是否降级。
}

这个分支只能说明“写入器暴露了 Flush 能力”，不能保证客户端马上看到数据。官方文档特别提醒，代理仍可能继续缓冲；接口断言、服务器实现和网络链路是三个不同问题。

包装器要透传能力，但不要制造假能力

中间件如果需要包装响应写入器，至少应保持核心方法行为一致。对于 Go 1.20+，推荐增加 Unwrap，让上层控制器有机会找到原始写入器：

type loggingWriter struct {
	http.ResponseWriter
	status int
}

func (w *loggingWriter) WriteHeader(code int) {
	// 只记录第一次状态码，随后仍把调用转交给底层写入器。
	if w.status == 0 {
		w.status = code
	}
	w.ResponseWriter.WriteHeader(code)
}

func (w *loggingWriter) Unwrap() http.ResponseWriter {
	// 返回原始对象，供 ResponseController 继续寻找可选能力。
	return w.ResponseWriter
}

这里没有直接给 loggingWriter 增加一个无条件的 Flush 方法。因为一旦包装器声明了 Flush，外层的类型断言就会成功；如果底层其实不支持，空实现会把“不支持”伪装成“已经刷新”。

如果项目必须兼容旧版本，也可以显式实现一个有条件转交的包装方法，但要接受一个边界：只要方法存在，外层就会被看作支持 http.Flusher。此时应在方法内部记录底层能力缺失，不能静默当成实时发送成功。

Go 1.20+ 用 ResponseController 统一调用

当项目不想在每个业务处理器里逐层判断接口，可以把 Flush 的调用集中到一个辅助函数。ResponseController 会尝试调用 Flush 或带错误返回的 FlushError；若当前链路没有这个能力，会返回匹配 http.ErrNotSupported 的错误。

func tryFlush(w http.ResponseWriter) error {
	// Controller 会沿 Unwrap 关系寻找原始 ResponseWriter。
	controller := http.NewResponseController(w)
	if err := controller.Flush(); err != nil {
		// ErrNotSupported 表示能力不存在，不等同于业务写入失败。
		if errors.Is(err, http.ErrNotSupported) {
			return nil
		}
		return err
	}
	return nil
}

调用方可以把“没有 Flush”当成可接受的降级，也可以把其他错误记录为连接中断或响应写入失败。不要把所有错误都吞掉，否则流式接口出了真实的写入问题时很难定位。

把实时可见性拆成三层检查

处理这类问题时，建议按下面的顺序收敛判断：

1. 类型层：当前对象是否通过 http.Flusher 断言，或者 ResponseController.Flush 是否返回 ErrNotSupported。
2. 包装层：中间件是否保留 Unwrap，是否在记录状态码、写响应头时改变了底层调用语义。
3. 链路层：代理、客户端和协议是否继续缓冲。即便服务器成功调用 Flush，也不应把它承诺成客户端已经显示。

HTTP/2 的默认响应写入器也支持 Flusher，但这不意味着所有自定义包装器都自动继承能力。测试时同样要注意：测试替身是否实现了 Flush，会影响你对中间件行为的判断。

常见误区与结论

• 不要使用 w.(http.Flusher).Flush() 代替安全断言；它会在包装器不支持时直接触发 panic。
• 不要仅凭断言成功就承诺“客户端实时收到”；代理缓冲和客户端读取策略仍在接口之外。
• 不要给所有包装器添加空的 Flush；它会制造表面能力，掩盖底层不支持的事实。

如果只需要兼容普通响应，安全断言加降级已经足够；如果中间件链较长且项目使用 Go 1.20+，优先保留 Unwrap，再用 ResponseController 统一处理。这样既能避免断言失败，也能把“能力不存在”和“真正写入出错”区分开。

相关问题

为什么默认 ResponseWriter 支持 Flush，包装后却不支持？

因为可选接口能力由动态类型暴露。包装器只实现了 ResponseWriter 的核心方法时，外层对象不会自动继承底层的其他接口。

ResponseController 能解决代理缓冲吗？

不能。它只负责调用服务器侧可用的响应控制能力，代理或客户端是否继续缓存属于网络链路问题。

旧版本 Go 没有 ResponseController 怎么办？

使用 ok 形式的 http.Flusher 断言，并在自定义包装器中谨慎透传；如果底层不支持，明确走普通响应或记录降级。