Go ResponseController 怎样让 HTTP handler 边读边写

在流式上传或边接收边反馈的 HTTP handler 中，如果你直接读取 Request.Body，又希望尽早写出响应，HTTP/1 的默认行为可能让两件事互相等待。Go 的做法不是改 Transport，而是在 handler 入口通过 http.NewResponseController(w) 创建控制器，并调用 EnableFullDuplex。

官方资料入口：https://pkg.go.dev/net/http#ResponseController.EnableFullDuplex

核心结论：HTTP/1 服务端默认会在开始写响应前消费未读请求体；EnableFullDuplex 会关闭这项等待，让 handler 可以交替读取请求体和写出响应。HTTP/2 默认允许并发读写，所以这个开关主要解决 HTTP/1 的读写顺序限制。

生产目标：让流式 handler 不再卡在未读请求体

我更愿意把这个 API 当成“读写边界声明”，而不是性能开关。典型场景是上传内容较大、服务端需要按块解析，或者每读到一段就要反馈处理进度。默认 HTTP/1 语义下，服务端可能先处理完未读请求体，才真正开始发送响应；如果客户端又在等待早期反馈，就会形成看似无故的停顿。

环境准备：在原始 ResponseWriter 上开启能力

ResponseController 应该从传给 ServeHTTP 的原始 ResponseWriter 创建；官方文档也允许包装器提供返回原始 writer 的 Unwrap 方法。调用要放在真正交替读写之前，并把不支持该能力当作明确错误处理。

func prepareDuplex(w http.ResponseWriter) (*http.ResponseController, error) {
    // 从当前请求的原始 ResponseWriter 创建控制器，避免脱离 handler 生命周期。
    controller := http.NewResponseController(w)

    // HTTP/1 需要显式声明允许交替读请求体和写响应。
    if err := controller.EnableFullDuplex(); err != nil {
        // 不支持时交给上层决定降级或返回错误，不假设所有 writer 都有该能力。
        return nil, fmt.Errorf("enable full duplex: %w", err)
    }
    return controller, nil
}

这里没有把错误吞掉，是因为中间件、测试 writer 或特殊协议适配器未必实现 EnableFullDuplex。如果调用失败，最好在还没有写出响应头时返回清晰的服务错误；如果业务允许，也可以降级为“读完再写”的普通模式。

安全配置：分块读取后交替写出响应

开启能力后，handler 可以在一次循环中读取一块请求体、写出一条反馈，再继续读取。Flush 负责把已缓冲的响应尽快交给底层 writer，但它不保证客户端一定立刻看到数据，代理或客户端仍可能缓冲。

func streamHandler(w http.ResponseWriter, r *http.Request) {
    // 先开启读写交替能力，失败时还可以安全返回错误状态。
    controller := http.NewResponseController(w)
    if err := controller.EnableFullDuplex(); err != nil {
        http.Error(w, "full duplex is unavailable", http.StatusNotImplemented)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    defer r.Body.Close() // 提前释放请求体，避免异常分支留下读取资源。

    buf := make([]byte, 32*1024)
    chunk := 0
    for {
        n, readErr := r.Body.Read(buf)
        if n > 0 {
            chunk++
            // 每读到一块就写反馈，示例只返回计数，不回显上传内容。
            if _, writeErr := fmt.Fprintf(w, "chunk=%d bytes=%d\n", chunk, n); writeErr != nil {
                return // 客户端断开或 writer 失败时停止继续读取。
            }
            // Flush 只表达尽快发送的意图，代理是否立即转发由链路决定。
            if flushErr := controller.Flush(); flushErr != nil {
                return
            }
        }

        if errors.Is(readErr, io.EOF) {
            return // 正常读完请求体，handler 结束。
        }
        if readErr != nil {
            // 已经写过部分响应时不要再强行改状态码，记录错误后结束更稳妥。
            return
        }
    }
}

示例特意没有把上传内容原样写回响应，避免把输入数据变成无意的回显通道。生产代码还应结合请求大小限制、超时、鉴权和客户端断开日志；全双工只改变读写协调方式，不替代这些边界控制。

权限边界：区分 HTTP/1、HTTP/2 与 handler 生命周期

这个 API 的边界有三层。第一，文档针对 HTTP/1 的默认消费行为提供了开关；HTTP/2 服务端本来就允许请求读取与响应写入并行。第二，ResponseController 只能在 ServeHTTP 返回前使用，不能把它保存到后台 goroutine 中继续操作。第三，Flush 的存在不代表网络链路没有缓冲，反向代理和客户端策略仍会影响可见延迟。

发布检查：把读写策略写进上线清单

上线前我会按下面顺序检查：是否真的需要请求体未读完就开始响应；是否在第一次写入前处理了 EnableFullDuplex 错误；是否限制了请求体大小并记录读写失败；是否确认代理不会吞掉分块反馈；是否在 handler 返回前结束所有对 writer 的使用。若只是普通上传后返回结果，保持默认模式通常更简单。

• 只需要最终结果：读完请求体后一次性响应，不要为了“流式”调用 API。
• 需要交替读写：在 handler 入口开启能力，分支处理不支持和客户端断开。
• 需要可见进度：结合 Flush、代理缓冲策略和客户端读取方式一起判断。

相关问题：EnableFullDuplex 能替代 WebSocket 吗？不能，它只调整 HTTP handler 的读写协调，不提供 WebSocket 升级语义。调用 Flush 就一定实时吗？不一定，中间代理和客户端仍可能缓存。HTTP/2 还要调用它吗？通常不依赖这个开关，但代码若要兼容多种 writer，仍应按返回错误设计降级策略。