Go net/http.ResponseController.EnableFullDuplex 如何边读边写：请求体消费与响应刷新边界

一个上传接口如果要边接收请求体、边把处理进度写回客户端，最容易误判的是把 Flush 当成全部答案。Go 的 HTTP/1 服务端在开始写响应前，默认会先消费请求体的未读部分；真正改变这个行为的入口是 http.ResponseController.EnableFullDuplex。HTTP/2 则默认允许读取请求体和写响应交错进行。

EnableFullDuplex 解决的不是 Flush 缓冲问题

先把三个对象的职责分开：Request.Body 是输入流，ResponseWriter 是输出流，EnableFullDuplex 是告诉 HTTP/1 服务端“这个处理函数会交错使用两条流”。如果只调用 Flush，服务端仍可能先处理未读的 Request.Body，客户端看到的就不是想要的边读边写。

这也是它和缓冲刷新的边界：EnableFullDuplex 改变读取/写入的调度前提，Flush 只推动已经写进响应的内容。调用控制器时，应该传入处理器收到的原始 ResponseWriter；如果中间包装器提供 Unwrap，ResponseController 才能继续找到底层能力。

用分块读取复现边读边写

下面的处理器每读到一块数据就写一行进度。示例没有把请求体一次性读入内存，便于观察读取完成、响应刷新和错误返回各自的位置。

func streamUpload(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)
    if err := controller.EnableFullDuplex(); err != nil {
        http.Error(w, "full duplex unavailable", http.StatusHTTPVersionNotSupported)
        return
    }
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    defer r.Body.Close()

    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 flushErr := controller.Flush(); flushErr != nil {
                return
            }
        }
        if errors.Is(err, io.EOF) {
            return
        }
        if err != nil {
            http.Error(w, "request body read failed", http.StatusBadRequest)
            return
        }
    }
}

这里的顺序有三个验收点：Request.Body.Read 得到正数时才写进度；ResponseWriter 写入成功后再调用 Flush；遇到 io.EOF 正常结束，其他错误走失败分支。defer r.Body.Close() 只负责资源收尾，不代表客户端已经收到了最后一行。

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

不要把“能调用 Flush”理解成“已经启用全双工”。同样，也不要把 HTTP/2 的默认行为推断到 HTTP/1。上线前用实际协议版本、分块请求和客户端接收时间做一次验收，才能发现代理缓冲或中间件包装带来的额外延迟。

常见问题

EnableFullDuplex 会自动开启 HTTP/2 的特殊模式吗？

不会。HTTP/2 服务端本来就允许请求体读取与响应写入并行；调用它主要是让处理器对 HTTP/1 的意图明确。

只写响应、不读取完整请求体时也要调用吗？

只有确实需要交错读取和写入时才调用。若接口先完整读取请求体，再生成响应，普通写法更容易审查。

Flush 返回错误后还能继续读取吗？

通常不应继续把它当作成功响应处理。刷新错误说明输出路径已经不可靠，应记录错误并结束当前处理流程。

为什么调用控制器后仍看不到实时进度？

检查是否真的分块写入、是否调用了 Flush，以及反向代理和客户端是否继续缓冲响应；EnableFullDuplex 只解决服务端读写交错前提。

收尾检查

这个场景可以用一句话记住：EnableFullDuplex 负责声明 HTTP/1 的交错读写意图，Flush 负责推动已经生成的响应，Close 负责释放请求体资源。把三件事分开记录，才能在上传流式接口里判断到底是读取、写入、刷新还是代理缓冲出了问题。