Go net/http.ResponseController 在自定义 ResponseWriter 中转发控制能力

中间件给 http.ResponseWriter 加日志、指标或响应体统计后，普通 Write 往往仍然正常，但流式刷新、读写期限或全双工能力突然变成“不支持”。根因通常不是 ResponseController 失效，而是最外层包装器没有把原始 Writer 暴露出来。

官方资料：https://pkg.go.dev/net/http

最稳妥的做法是让自定义包装器实现 Unwrap() http.ResponseWriter，再由 ResponseController 沿包装链查找能力；调用每个扩展方法时仍要用 errors.Is(err, http.ErrNotSupported) 做运行时降级。

定位症状：包装器让能力探测失败

这类故障常出现在 SSE、文件下载或代理接口：handler 调用 Flush 后客户端迟迟收不到数据，或者设置写期限时返回 ErrNotSupported。只要把中间件临时移除就恢复，基本可以锁定 Writer 包装链。

注意，能调用 Write 只代表它满足基础的 http.ResponseWriter 接口，不代表它还保留 Flush、Hijack、SetWriteDeadline 或 EnableFullDuplex。这些是额外能力，需要在运行时逐项判断。

拆开 ResponseController 的查找规则

NewResponseController 期望拿到 handler 收到的原始 Writer，或者拿到一个带 Unwrap 方法、能够返回原始 Writer 的包装器。源码的关键逻辑是：先检查当前对象是否实现目标方法；没有时，如果实现了 Unwrap 就继续向内查找；两者都没有才返回匹配 http.ErrNotSupported 的错误。

因此，包装器只记录状态而不改写响应控制语义时，优先提供 Unwrap。不要为了“看起来支持”而无条件实现 Flush 或 Hijack；伪造能力会把真正的运行时边界隐藏起来。

实现可转发的 ResponseWriter 包装器

package main

import "net/http"

// auditWriter 只增加观测字段，并把原始 Writer 留在包装链中。
type auditWriter struct {
	http.ResponseWriter
	bytes int
}

// Unwrap 让 ResponseController 能继续查找底层的扩展能力。
func (w *auditWriter) Unwrap() http.ResponseWriter {
	return w.ResponseWriter
}

// Write 记录字节数，同时保留原始响应写入行为。
func (w *auditWriter) Write(p []byte) (int, error) {
	n, err := w.ResponseWriter.Write(p)
	w.bytes += n
	return n, err // 错误原样返回，避免中间件掩盖网络失败
}

func withAudit(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		next.ServeHTTP(&auditWriter{ResponseWriter: w}, r)
	})
}

这里没有手工复制四五个扩展接口，原因是 ResponseController 已经定义了向内查找的规则。若包装器本身还要改变某个能力，例如对 Flush 增加统计，就应实现该方法并明确转发失败；否则只保留 Unwrap，维护成本更低。

在 handler 中按能力安全调用

func stream(w http.ResponseWriter, r *http.Request) {
	rc := http.NewResponseController(w)

	// 写期限只限制响应写出；不支持时按部署环境选择降级。
	if err := rc.SetWriteDeadline(time.Now().Add(3 * time.Second)); err != nil {
		if !errors.Is(err, http.ErrNotSupported) {
			http.Error(w, "set write deadline failed", http.StatusInternalServerError)
			return
		}
	}

	// 全双工主要影响 HTTP/1 请求，HTTP/2 本身允许并发读写。
	if err := rc.EnableFullDuplex(); err != nil && !errors.Is(err, http.ErrNotSupported) {
		http.Error(w, "full duplex unavailable", http.StatusNotImplemented)
		return
	}

	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	for _, part := range []string{"ready\n", "working\n", "done\n"} {
		if _, err := io.WriteString(w, part); err != nil {
			return // 客户端断开时停止继续写入
		}
		// Flush 失败代表当前 Writer 不支持或连接已经出错。
		if err := rc.Flush(); err != nil && !errors.Is(err, http.ErrNotSupported) {
			return
		}
	}
}

示例需要导入 errors、io、net/http 和 time。Flush、deadline、全双工都只能在 ServeHTTP 返回前使用。Hijack 更要单独判断：HTTP/2 故意不支持它，包装器也可能不支持，不能把失败当成普通网络错误后继续使用原始 Request.Body。

中间件落地前的检查清单

第一，包装器是否实现了返回下一层 Writer 的 Unwrap，并且没有把 nil Writer 藏起来。第二，是否把 ErrNotSupported 与真实 I/O 错误分开处理。第三，是否在 handler 生命周期内完成控制调用，尤其不要把 ResponseController 保存到异步 goroutine 里跨请求使用。第四，是否分别用支持和不支持扩展接口的测试 Writer 覆盖降级分支。

一句话总结：基础响应能力由 ResponseWriter 提供，扩展控制能力由底层 Writer 的接口实现决定；自定义包装器要么正确转发，要么通过 Unwrap 把查找权交回底层。

常见问题

为什么包装器实现了 Flush 还是不稳定？ 如果只实现了无返回值的 Flush，可能吞掉底层错误；优先让控制器沿 Unwrap 找到原始对象，或明确实现带错误返回的转发逻辑。

EnableFullDuplex 返回不支持是不是代码写错？ 不一定。它与 Writer、协议和服务器实现有关；HTTP/2 已允许并发读写，应用应把 ErrNotSupported 当作能力边界处理。