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

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

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

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

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

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

调用点应放在处理器拿到原始 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 语义。这时先检查中间件包装链，不要直接删掉错误判断。

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

一次性把 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 版本。

什么时候不该启用 Full Duplex

如果接口必须先完整校验请求体，之后才返回唯一结果，保持普通的先读后写更简单。启用 Full Duplex 还会让客户端取消、响应提前关闭、半关闭连接和超时的组合变多。它适合明确的流式协议，不适合作为“响应更快”的通用开关。

相关问题

调用 EnableFullDuplex 后还要 Flush 吗？

要不要让客户端尽快看到每个片段，仍取决于响应缓冲和协议设计。Full Duplex 解决的是读写并行许可，不能替代按需调用 Flush 的响应刷新策略。

EnableFullDuplex 返回不支持怎么办？

把它当作能力协商失败处理：记录实际响应写入器和中间件链，确认是否真的需要流式交互；如果不需要，回退到先读完再写；如果需要，则修复包装器或调整部署协议。

最值得先测哪一个场景？

先测 HTTP/1、分段请求体、响应首片提前返回、客户端中途取消这四个条件的组合，再补 HTTP/2 对照组。这样能区分协议差异、处理器逻辑和超时配置，而不是只得到一个“请求成功”的结果。

小结

ResponseController.EnableFullDuplex 的价值在于声明一个具体的 HTTP/1 流式交互需求：请求体还在到达，响应已经需要开始发送。正确用法是提前调用、检查错误、配合截止时间，并用分段发送的真实时序验收；普通的先读后写接口则没有必要增加这层复杂度。