Go ResponseController.EnableFullDuplex 怎样让服务端边读边写

在 Go 的 HTTP 服务端，如果一个请求体还没有读完，handler 却希望先写出一部分响应，HTTP/1 默认行为可能会让这件事看起来“卡住”：服务器会先消耗未读的请求体，再开始写响应。解决这个边界的入口是 http.NewResponseController(w).EnableFullDuplex()。它让 handler 可以继续读取 Request.Body，同时向 ResponseWriter 写响应；HTTP/2 本身已经允许这种并行读写。

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

这个方法不是 WebSocket，也不会自动把普通 handler 变成后台并发任务。更准确的理解是：它调整 HTTP/1 服务端在“请求体尚未读完、响应已经要开始写出”时的处理方式，具体的分块读取、写入和刷新仍由代码负责。

先分清 EnableFullDuplex 的职责

ResponseController 是通过原始的 ResponseWriter 控制响应能力的适配器。EnableFullDuplex 从 Go 1.21 起提供，它表达的是“这个 handler 会交替读取请求体并写入响应”。对于 HTTP/1 请求，调用它后，服务端不会因为还有未读请求体就强制等待全部读取完成；对于 HTTP/2，请求读取和响应写出本来就被协议实现允许同时进行。

在 handler 中交替读取和写入

最小写法是先用原始 ResponseWriter 创建控制器，再在第一次写响应前调用 EnableFullDuplex。下面的例子每读到一块请求体，就写出一条进度信息；它用同一个 handler 交替完成读和写，没有假设存在一个已经启动的后台消费者。

package main

import (
	"errors"
	"fmt"
	"io"
	"net/http"
)

func stream(w http.ResponseWriter, r *http.Request) {
	// 用原始 ResponseWriter 创建控制器，避免包装层隐藏可选能力。
	controller := http.NewResponseController(w)
	if err := controller.EnableFullDuplex(); err != nil {
		if errors.Is(err, http.ErrNotSupported) {
			// 不支持时不要假装实时写出，交给上层选择顺序处理或返回错误。
			http.Error(w, "当前响应写入器不支持全双工", http.StatusNotImplemented)
			return
		}
		// 其他错误也不能继续按全双工语义处理。
		http.Error(w, "无法启用全双工响应", http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	buf := make([]byte, 32*1024) // 以固定块读取，避免一次性吞掉整个请求体。
	for {
		n, readErr := r.Body.Read(buf)
		if n > 0 {
			if _, writeErr := fmt.Fprintf(w, "已接收 %d 字节\n", n); writeErr != nil {
				// 客户端断开或网络写失败时，响应通常已经开始，直接结束更安全。
				return
			}
			if flushErr := controller.Flush(); flushErr != nil {
				// Flush 失败不应被当成读取成功，保留退出路径给调用方记录。
				return
			}
		}
		if errors.Is(readErr, io.EOF) {
			return
		}
		if readErr != nil {
			// 响应可能已经写出，不能再可靠地修改状态码。
			return
		}
	}
}

func main() {
	http.HandleFunc("/stream", stream)
	_ = http.ListenAndServe(":8080", nil) // 示例省略服务关闭编排。
}

代码里有两个容易混淆的点。第一，EnableFullDuplex 必须在响应开始写出前处理；第二，Flush 只负责把当前服务端缓冲尽量推向连接，不能保证浏览器、反向代理或客户端立刻把字节呈现给用户。如果业务需要逐块确认，还应设计自己的消息边界和错误记录。

处理不支持和写入失败

EnableFullDuplex 返回的是错误，不应被忽略。ResponseController 会尝试调用底层 ResponseWriter 提供的同名能力；如果响应写入器不支持该方法，会返回匹配 http.ErrNotSupported 的错误。日志中可以区分“不支持”与其他控制失败，再决定是否退回到先读完、后写响应的顺序方案。

中间件包装 ResponseWriter 时尤其要注意原始对象。官方文档建议把 handler 收到的原始 writer 传给 NewResponseController，或者让包装器提供能返回原始 writer 的 Unwrap 方法。控制器也不能在 ServeHTTP 返回后继续使用；把它保存到异步任务里会越过响应对象的生命周期。

另外，响应一旦因为 Write 或 Flush 开始发送，后续读取失败通常已经不能可靠地改成新的 HTTP 状态码。实际处理应记录错误、停止继续读取，并让客户端依据已经发送的协议内容判断是否重试，而不是再次调用 http.Error 伪造一个完整错误响应。

按 HTTP 版本和链路决定是否采用

这个 API 适合上传流、代理转发、边接收边反馈的 HTTP/1 场景，但不代表所有链路都会呈现出即时效果。

• HTTP/1：只有确实需要在请求体读完前写响应时才启用，普通表单请求没有必要增加这层语义。
• HTTP/2：服务器默认允许读请求体和写响应并行，调用该方法更多是表达意图和兼容统一 handler。
• 代理与客户端：缓冲策略可能延迟小块响应，Flush 不能消除链路上的所有缓冲。
• 接口设计：把每块数据的确认格式、结束标记、客户端断开和重试规则写进协议，而不是依赖某次 TCP 写入恰好被看见。

因此，判断是否采用时，先问“是否必须在上传未结束时反馈”，再问“响应写入器是否保留了底层能力”，最后才决定是否加上全双工控制。它解决的是 Go HTTP/1 服务端的读写时机问题，不是完整的实时通信协议。

常见问题

调用 EnableFullDuplex 后，还需要 Flush 吗？

通常仍需要。前者改变 HTTP/1 服务端对未读请求体的处理，后者尝试把已经写出的响应数据尽快推出当前服务端缓冲；两者职责不同。

HTTP/2 下调用失败就说明不能边读边写吗？

不能这样推断。HTTP/2 的服务端实现本身允许并行读写；调用返回错误时应按控制器能力处理，但不要把这个错误解释成 HTTP/2 一定禁止并发读写。