Go http.NewResponseController 怎么统一刷新与全双工控制

http.NewResponseController 是 Go 服务端处理器里统一调用扩展响应能力的入口：要分段刷新就用 Flush，要在 HTTP/1 请求中一边读取请求体、一边写响应就先用 EnableFullDuplex。它还统一提供读写截止时间和连接接管能力，避免业务代码到处对 ResponseWriter 做零散类型断言。

官方文档：https://pkg.go.dev/net/http#NewResponseController

先按响应负载选择控制能力

是否需要 EnableFullDuplex，取决于请求与响应是否要交错，而不是响应是否很大。下载文件、SSE 或分段生成内容通常只需要刷新；上传流每读一段就回一段确认，才属于全双工控制。把两者分开，能避免不必要地改变 HTTP/1 对未读请求体的默认处理。

理解 ResponseController 的统一入口

NewResponseController 从传入的 ResponseWriter 开始查找能力。如果当前对象没有对应方法，但实现了 Unwrap() http.ResponseWriter，控制器会继续向内解包；最终仍找不到时，返回一个可匹配 http.ErrNotSupported 的错误。控制器应接收 ServeHTTP 获得的原始 Writer，或一个能正确 Unwrap 的包装器。

type metricsWriter struct {
    http.ResponseWriter
    status int
}

// Unwrap 把原始 Writer 暴露给 ResponseController，避免中间件吞掉扩展能力。
func (w *metricsWriter) Unwrap() http.ResponseWriter {
    return w.ResponseWriter
}

不要在 ServeHTTP 返回后继续保存并使用控制器。官方文档明确限制 ResponseController 的生命周期只能位于当前处理器调用内。

用 Flush 输出分段响应

下面的处理器每次写入一个事件后立即刷新。它适合展示长任务进度或服务端事件，但示例只说明应用缓冲已经提交给底层响应实现，并不承诺中间代理立刻把字节交给浏览器。

func streamHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    rc := http.NewResponseController(w)

    for i := 1; i 

重要的核对点有两个：响应头必须在第一次写入前设置；Flush 的错误必须被处理。若链路上有 Nginx、网关或 CDN，还要单独确认它们是否缓冲流式响应。

为 HTTP/1 开启全双工

Go 的 HTTP/1 服务端通常会先消费请求体未读部分，再开始写响应。这样能简化连接复用，却会阻止处理器交错读写。EnableFullDuplex 会关闭这一默认行为；HTTP/2 本来就允许并发读取请求与响应，因此不依赖这个开关。

func duplexHandler(w http.ResponseWriter, r *http.Request) {
    rc := http.NewResponseController(w)

    // Go 1.21+：允许 HTTP/1 处理器交错读取请求体和写回确认。
    if err := rc.EnableFullDuplex(); err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "当前响应实现不支持全双工", http.StatusHTTPVersionNotSupported)
            return
        }
        http.Error(w, "启用全双工失败", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    scanner := bufio.NewScanner(r.Body)
    for scanner.Scan() {
        // 每读取一行上传内容，就在同一处理器中写回一行确认。
        if _, err := fmt.Fprintf(w, "ack: %s\n", scanner.Text()); err != nil {
            log.Printf("写确认失败: %v", err)
            return
        }
        if err := rc.Flush(); err != nil {
            log.Printf("刷新确认失败: %v", err)
            return
        }
    }
    // 响应可能已经部分发送，扫描错误应记录而不是再次改写状态码。
    if err := scanner.Err(); err != nil {
        log.Printf("读取请求体失败: %v", err)
    }
}

这个示例在一个 goroutine 内交错读写，已经能满足“每读一段就回复一段”的协议。EnableFullDuplex 不会自动让自定义 Writer、业务状态或多个 goroutine 变得并发安全；若要并行读写，仍要自行处理同步与取消。

处理协议、中间件与代理边界

上线前应把限制放进架构决策，而不是只看本地 Handler：

• 版本：ResponseController 从 Go 1.20 提供，EnableFullDuplex 从 Go 1.21 提供。
• 协议：HTTP/1 的交错读写需要显式开启；HTTP/2 服务端始终允许并发读取请求并写响应。
• 包装器：中间件若不实现 Unwrap，控制器可能看不到底层支持的能力。
• 代理：服务端 Flush 成功不代表代理立即转发，链路上的响应缓冲策略需要单独配置。
• 截止时间：SetReadDeadline 覆盖整个请求读取，包括 Body；零值表示不设置截止时间。已经超过的读写截止时间不能靠再次设置延长。

上线落地清单

1. 先按负载区分“只刷新”与“交错读写”，不要默认开启全双工。
2. 确认最低 Go 版本；使用 EnableFullDuplex 时至少是 Go 1.21。
3. 检查所有 ResponseWriter 包装器是否实现 Unwrap。
4. 所有控制方法都检查错误，并用 errors.Is 识别 http.ErrNotSupported。
5. 给请求体读取、响应写入和客户端断连设置一致的取消策略。
6. 在实际反向代理链路下观察首字节和分段到达，而不是只在直连本机时判断。

相关问题

Flush 成功后客户端一定马上收到吗？

不一定。它会把底层支持的缓冲数据向客户端刷新，但反向代理或客户端自身仍可能缓冲。

HTTP/2 也必须调用 EnableFullDuplex 吗？

不需要依赖它才能交错读写。Go 官方说明 HTTP/2 请求始终允许并发读取请求并写响应。

为什么中间件包装后返回 ErrNotSupported？

常见原因是包装器没有实现 Unwrap() http.ResponseWriter，导致控制器无法继续找到底层能力。