Go HTTP 服务端怎么边读取请求体边写回响应

我第一次遇到这个问题，是在做一个边接收大请求体、边把处理结果写回客户端的 HTTP handler：代码明明已经调用了 Write，客户端却要等请求体接收得差不多以后才看到响应。把读取循环换成别的写法没有解决，真正的关键在 HTTP/1 服务端对“尚未读完的请求体”有一条默认处理边界。

在 handler 第一次写响应之前，先用当前的 http.ResponseWriter 创建 http.ResponseController，再调用 EnableFullDuplex()。这样 Go 的 HTTP/1 服务端就允许 handler 继续读取 Request.Body，并把分块结果交错写到 ResponseWriter。HTTP/2 本身已经允许并行读取和响应，但调用这个方法仍然应该检查返回错误，因为自定义或包装过的 writer 可能不支持该能力。

要边读边写，调用时机比读取循环更重要：EnableFullDuplex 应该发生在第一次响应写出之前；它解决的是服务端默认消费未读请求体的问题，不是把任意 ResponseWriter 变成网络代理。

为什么普通 Write 看起来没有及时返回

HTTP/1 请求到达服务端后，handler 可以从 r.Body 读取数据。默认情况下，如果请求体还有一部分没有读完，Go HTTP 服务端会在开始写响应前先消费这部分未读数据。这个行为对普通“先收完请求、再返回响应”的接口很自然，却会让流式处理出现错觉：应用代码已经准备好一段结果，网络上的响应却没有按预期开始。

这也是为什么只在循环里增加 Flush 往往不够。Flush 负责把已经写入的响应数据尽量向客户端推进，而 EnableFullDuplex 负责改变 HTTP/1 请求体与响应写出的协调方式。一个是输出刷新，一个是读写边界，不能互相替代。

EnableFullDuplex 要放在第一次响应写出之前

ResponseController 是 handler 控制响应行为的入口。创建它时应传入 handler 收到的原始 ResponseWriter，然后在设置好响应头、但还没有调用 Write 或 WriteHeader 之前开启全双工能力：

func duplexHandler(w http.ResponseWriter, r *http.Request) {
	// 用 handler 收到的 writer 创建控制器，避免丢失底层能力。
	controller := http.NewResponseController(w)
	if err := controller.EnableFullDuplex(); err != nil {
		// 能力不可用时还没有写响应，可以安全返回明确的状态码。
		http.Error(w, "full duplex is not supported", http.StatusNotImplemented)
		return
	}

	// 设置响应头不会开始写响应，仍然可以放在能力开启之后。
	w.Header().Set("Content-Type", "application/octet-stream")
	// 这里再进入读取和写回循环，HTTP/1 才不会先替 handler 消费剩余请求体。
}

调用成功只表示当前 writer 暴露了这项能力，不代表客户端一定会立刻看到每一个小块。网络缓冲、代理、客户端读取方式以及是否调用 Flush，仍然会影响可见的到达节奏。

按块读取 Request.Body 并写回响应

下面的例子把请求体按 32 KB 读取，收到一块就写回一块，并在写入成功后尝试刷新。这个模式适合演示接口边界：真实业务通常会在写回之前做解析、校验或转换，但不能在未开启全双工时假定 HTTP/1 会同时推进读写。

package main

import (
	"io"
	"net/http"
)

func echoDuplex(w http.ResponseWriter, r *http.Request) {
	// 这个 handler 只接受提交请求，其他方法不进入流式读写逻辑。
	if r.Method != http.MethodPost {
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}

	// 必须在第一次 Write 之前开启 HTTP/1 的交错读写能力。
	controller := http.NewResponseController(w)
	if err := controller.EnableFullDuplex(); err != nil {
		// 此时尚未输出正文，仍可返回可读的错误响应。
		http.Error(w, "full duplex is not supported", http.StatusNotImplemented)
		return
	}
	w.Header().Set("Content-Type", "application/octet-stream")

	// 缓冲区控制每次读写的粒度，避免为整个请求体一次性分配内存。
	buf := make([]byte, 32*1024)
	for {
		n, readErr := r.Body.Read(buf)
		if n > 0 {
			// 先处理有效字节，再单独判断本次读取附带的错误。
			if _, writeErr := w.Write(buf[:n]); writeErr != nil {
				// 响应写失败后继续读取没有意义，直接结束 handler。
				return
			}
			// Flush 只负责推动已经写出的数据，不替代 EnableFullDuplex。
			if flushErr := controller.Flush(); flushErr != nil {
				return
			}
		}

		if readErr == io.EOF {
			// 请求体读完，正常结束流式响应。
			return
		}
		if readErr != nil {
			// 请求读取失败时不能把错误当成正常 EOF 继续写回。
			return
		}
	}
}

func main() {
	// 绑定示例 handler；生产服务还应配置超时、大小限制和日志策略。
	http.HandleFunc("/echo", echoDuplex)
	_ = http.ListenAndServe(":8080", nil)
}

代码把 n > 0 放在错误判断前，是因为一个 Read 调用可能同时返回有效字节和 io.EOF。先写出这批有效数据，再结束循环，比只看错误值更稳妥。响应已经开始后，如果后续读取失败，示例直接结束 handler；这时再调用 http.Error 可能把错误文本混进已经开始的二进制响应，不应机械套用。

HTTP/1、HTTP/2 和包装器的边界

EnableFullDuplex 的名字容易让人误以为所有协议都需要额外配置。实际判断可以压缩成下面三类：

如果中间件包装了 ResponseWriter，要特别注意它是否实现了 Unwrap() http.ResponseWriter。ResponseController 会沿着可解包的 writer 查找底层能力；一个只转发 Header、Write、WriteHeader 却把其他方法完全藏起来的包装器，可能让控制器返回不支持。对这类中间件，优先让包装器保留官方约定的底层访问方式，而不是在业务 handler 里猜测具体实现类型。

三个容易把问题带偏的写法

先写一小段，再开启全双工

第一次 Write 可能已经触发响应提交。把 EnableFullDuplex 放到第一次写出之后，不能可靠地改变服务端此前已经做出的协调决定。调用顺序应固定为：创建控制器、开启能力、设置或确认响应头、进入读写循环。

只调用 Flush，不调用 EnableFullDuplex

Flush 解决的是缓冲数据何时向外推进；它并不会告诉 HTTP/1 服务端“不要先消费剩余请求体”。如果症状是请求还没有读完时响应迟迟不开始，先检查全双工能力是否在第一次写出前开启。

把请求体读写当成任意并发安全共享对象

全双工表示服务端允许 handler 交错读取请求体和写响应，不等于可以在多个 goroutine 中无约束地同时操作同一个 Request.Body 或 ResponseWriter。是否并发、如何退出、客户端断开后如何取消，都要由业务代码明确管理。本文示例刻意采用单 goroutine 的读一块、写一块，先把协议边界讲清楚。

我的取舍：需要实时回传时才打开它

如果接口本来就是“完整接收后统一返回”，不必为了形式调用 EnableFullDuplex；普通 handler 更容易阅读，服务端默认消费请求体也更符合常见生命周期。只有当客户端需要在上传尚未结束时看到阶段性结果、回显片段或处理进度，并且响应确实依赖于持续读取请求体时，全双工才有明确价值。

落地时我会把三个判断写在代码评审清单里：第一，调用是否发生在第一次响应写出之前；第二，读取循环是否同时处理有效字节和错误；第三，响应已经开始后是否避免再用 http.Error 破坏正文协议。这样排查时，问题就从“为什么流式响应不实时”收敛到了可以直接检查的接口边界。

相关问题

EnableFullDuplex 会让 HTTP/2 更快吗？

它主要针对 HTTP/1 的默认读写协调。HTTP/2 服务端本身已经允许并行读取请求和写响应，不应把这个方法当成通用性能开关。

调用 EnableFullDuplex 之后还要 Flush 吗？

如果希望已经写入的小块更早向客户端推进，仍可能需要调用 Flush。两者职责不同：前者改变 HTTP/1 的未读请求体处理，后者推动已写响应数据。

为什么 EnableFullDuplex 返回 ErrNotSupported？

通常说明当前 ResponseWriter 或它能解包到的底层 writer 没有提供这项能力。检查中间件是否保留原始 writer 和 Unwrap 能力，并为不支持的环境准备降级路径。