当前位置：首页 > 文章列表 > Golang > Go问答 > Go 问答：net/http ResponseController.EnableFullDuplex 什么时候值得开启

Go 问答：net/http ResponseController.EnableFullDuplex 什么时候值得开启

来源：17golang原创 2026-08-28 01:49:16 0浏览收藏

做一个边读上传请求体、边返回处理进度的 HTTP 接口时，最容易踩到的坑不是 goroutine，而是 Go HTTP/1 服务端默认会先消费未读请求体，再开始写响应。需要让两条方向交错进行时，可以在真正写响应前调用 http.NewResponseController(w).EnableFullDuplex()；HTTP/2 则默认允许并行读取请求和写响应。

EnableFullDuplex 只解决 HTTP/1 请求体与响应写入的交错问题，不负责刷新缓冲、不建立 WebSocket，也不会替中间件修复失去原始 ResponseWriter 的问题。

要点速览

方法从 Go 1.21 起提供，作用对象是 HTTP/1 的未读 Request.Body。
调用位置应靠近 Handler 的入口，并且早于第一次写响应。
HTTP/2 服务端本来就允许并行读写，通常不需要额外开启。
包装 ResponseWriter 的中间件应保留原始能力，必要时提供 Unwrap。

EnableFullDuplex 解决的到底是哪一个阻塞

假设请求体很大，Handler 先读一小段数据，再想把“已收到多少”写回客户端。HTTP/1 的默认行为可能让服务端在第一次响应写入前继续消费剩余请求体，于是客户端看不到预期的中间进度。EnableFullDuplex 的语义就是告诉服务器：这个 Handler 会交错读取 Request.Body 和写入 ResponseWriter。

Go net/http HTTP/1 Handler 通过 EnableFullDuplex 让 Request.Body 与 ResponseWriter 交错流动的控制流示意图

HTTP/1、HTTP/2 与 ErrNotSupported 的边界

这个 API 从 Go 1.21 加入。官方文档明确区分了协议行为：HTTP/1 默认会在开始写响应前处理未读请求体，调用该方法后才允许 Handler 继续读请求并同时写响应；HTTP/2 服务端始终允许并发读取请求和发送响应。

调用通过 ResponseController 转发到原始 ResponseWriter。如果当前对象及其可展开的包装层都没有 EnableFullDuplex() error，返回的错误应按 http.ErrNotSupported 判断，而不是把它当成网络断开。

Go ResponseController EnableFullDuplex 在 HTTP/2 和不支持 ResponseWriter 时的判断分支

最小可验证写法：先开启，再交错读写

下面的 Handler 只展示关键顺序。它先取得控制器并开启全双工，再逐块读取请求体，把每个块的长度写入响应。真实业务还应限制请求体大小、处理客户端断开，并避免把原始数据直接回显。

func uploadProgress(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)
    if err := controller.EnableFullDuplex(); err != nil && !errors.Is(err, http.ErrNotSupported) {
        http.Error(w, "full duplex unavailable", http.StatusHTTPVersionNotSupported)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    buffer := make([]byte, 32*1024)
    for {
        n, err := r.Body.Read(buffer)
        if n > 0 {
            fmt.Fprintf(w, "received=%d\n", n)
            if f, ok := w.(http.Flusher); ok {
                f.Flush()
            }
        }
        if err == io.EOF {
            return
        }
        if err != nil {
            return
        }
    }
}

这里的关键不是把 Read 放进 goroutine，而是让服务器知道读写可以交错。Flush 只负责尽快推出已经写入的响应数据；它与 EnableFullDuplex 是两件事，前者不能替代后者。

怎么判断这段代码真的按预期工作

请求使用 HTTP/1 时，客户端上传仍在进行，响应中可以看到已读取块的进度行。
请求使用 HTTP/2 时，即使不调用该方法，协议本身也允许请求读取与响应发送并行。
如果包装器不支持该能力，代码只忽略 http.ErrNotSupported，其他错误仍然结束请求。

中间件包装 ResponseWriter 时要保留什么

常见日志中间件会把 http.ResponseWriter 包成自定义类型。如果包装器没有实现目标方法，也没有提供返回原始对象的 Unwrap，ResponseController 可能只能返回 ErrNotSupported。因此，包装器不要随意截断底层能力；需要兼容控制器时，应设计清楚转发方法或 Unwrap。

同时不要把该方法当作长连接协议的通用开关。需要双向消息、独立帧边界或连接升级时，应选择合适的协议和 API；这里只处理 HTTP 请求体与响应流在 Handler 内的并行推进。