当前位置：首页 > 文章列表 > Golang > Go问答 > Go ResponseController.EnableFullDuplex 怎么用：流式请求体与响应并行读取的边界

Go ResponseController.EnableFullDuplex 怎么用：流式请求体与响应并行读取的边界

来源：17golang原创 2026-08-26 15:02:30 0浏览收藏

做流式上传或边上传边返回进度时，最容易踩到的不是 goroutine 数量，而是 HTTP/1 服务端对未读请求体的默认处理：处理器一旦开始写响应，服务端可能先把剩余请求体读完，客户端又在等响应，于是看起来像“代码卡住了”。Go 1.21 提供的 http.NewResponseController(w).EnableFullDuplex()，就是用来明确打开这条并行通道的。

要点速览

只要 HTTP/1 处理器需要交错读取 Request.Body 和写 ResponseWriter，就应在第一次写响应前尝试启用 Full Duplex。
HTTP/2 天生允许并行读取请求体和写响应，调用仍可保留，但不要把它当成协议升级开关。
启用后仍要设置读写截止时间，并用客户端真实的分块发送场景验证，不要只测一次性完整上传。

先看清：为什么边读边写会互相等待

HTTP/1 请求常见于上传、导入和长连接表单。客户端还在发送请求体时，服务端处理器如果先写进度或首个响应片段，Go 的 HTTP/1 服务端默认会尝试消费剩余请求体，再开始响应写入。这种安排能避免另一类死锁，但不适合“请求还没发完，响应已经要开始”的协议。

可以把它想成两条单向水管：请求体是上传管，响应是下行管。普通请求通常先把上传管收完再开下行管；Full Duplex 则由处理器声明两条管可以交错使用。这里的重点不是“所有请求都更快”，而是把控制权交回给确实需要流式交互的处理器。

HTTP/1 默认先消费 request body 与启用 FullDuplex 后交错读取和写响应的对比

最小写法：在第一次写响应前声明并行意图

调用点应放在处理器拿到原始 ResponseWriter 后、第一次 Write 或刷新响应前。下面的示例只处理能力声明和错误分支，业务读取仍然按你的协议决定。

func stream(w http.ResponseWriter, r *http.Request) {
    rc := http.NewResponseController(w)
    if err := rc.EnableFullDuplex(); err != nil {
        http.Error(w, "full duplex is not supported", http.StatusHTTPVersionNotSupported)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    if _, err := io.WriteString(w, "ready\n"); err != nil {
        return
    }
    if f, ok := w.(http.Flusher); ok {
        f.Flush()
    }

    buf := make([]byte, 32*1024)
    for {
        n, err := r.Body.Read(buf)
        if n > 0 {
            if _, writeErr := fmt.Fprintf(w, "received=%d\n", n); writeErr != nil {
                return
            }
            if f, ok := w.(http.Flusher); ok {
                f.Flush()
            }
        }
        if err == io.EOF {
            return
        }
        if err != nil {
            return
        }
    }
}

这段代码的可验证结果是：客户端分块发送请求体时，能够先收到 ready，随后在继续上传的过程中收到多条 received=...。如果响应一直等到请求体完全结束才出现，先检查请求是否实际使用 HTTP/1，再检查是否在首个写入之前调用了控制器。

三个容易混淆的边界

它不是把普通 HTTP 请求变成 WebSocket

Full Duplex 只改变处理器对请求体和响应写入的交错方式，不会提供消息边界、双向关闭语义或 WebSocket 的握手协议。上传协议仍需要自己规定分块格式、结束条件和错误响应。

HTTP/2 不需要靠它获得并行读写

Go 文档明确说明，HTTP/2 服务端本来就允许并行读取请求体和写响应。因此测试时要把 HTTP/1 与 HTTP/2 分开记录；不能因为 HTTP/2 成功，就断言 HTTP/1 也没有等待。

包装过的 ResponseWriter 可能影响能力探测

NewResponseController 会尝试调用底层响应写入器提供的能力，也支持通过 Unwrap 找回原始对象。自定义中间件如果只复制了部分方法、没有保留底层能力，可能得到 ErrNotSupported 语义。这时先检查中间件包装链，不要直接删掉错误判断。

HTTP/1 和 HTTP/2 的 FullDuplex 能力、ResponseController 调用点与 deadline 边界

验证时别只发一次性完整请求

一次性把 body 全部写完的客户端，很难暴露等待顺序。更有区分度的测试是：先发送一小段，保持连接，再等待服务端的 ready 或进度片段，最后补齐剩余内容。服务端同时设置读写截止时间，避免测试失败时留下无限等待。

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

req := httptest.NewRequest(http.MethodPost, "/stream", io.Reader(body))
req = req.WithContext(ctx)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)
if rec.Code != http.StatusOK {
    t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())
}

httptest.ResponseRecorder 适合核对最终状态和正文，不等同于真实网络上的分块时序。需要验收“响应先到、请求后完”的行为时，应再用真实 TCP 客户端或端到端测试，并明确记录协商出的 HTTP 版本。