Go http.ResponseController 怎样检测 Flush 能力并平滑降级

如果一个 Go 处理器需要分段写响应，最稳妥的判断方式不是直接把 http.ResponseWriter 断言成某个接口，而是用 http.NewResponseController 调用 Flush。当底层 writer 或包装器链不提供 Flush 能力时，方法会返回匹配 http.ErrNotSupported；这时可以保留已经写入的内容，让响应在正常结束时发送。真正的写入错误则不能被吞掉。

官方地址：https://pkg.go.dev/net/http

我在处理流式接口时最容易误判的一点，是把“服务端支持 Flush”和“客户端马上看到了这一段”当成同一件事。Go 文档明确提醒，代理可能继续缓冲数据，所以降级逻辑应该只围绕服务端能力和错误类型展开。

先把 Flush 能力和客户端到达分开

ResponseController.Flush 的职责是尝试把服务端已经缓冲的响应数据推向客户端。它不是网络链路的送达确认，也不会绕过客户端、反向代理或网关自己的缓冲策略。即使调用成功，读者仍然可能要等到更多数据到来或响应结束才看到内容。

另一条边界是能力检测。标准 HTTP/1.x 和 HTTP/2 的默认 writer 支持 Flusher，但自定义包装器不一定保留这个能力。包装器如果提供 Unwrap() http.ResponseWriter，控制器可以继续沿链查找底层 writer；没有解包方法的包装器就可能成为能力边界。

用 ResponseController 统一探测包装后的 writer

下面的辅助函数先写入一段数据，再尝试 Flush。示例把“能力暂不支持”视作可降级情况，把其他错误交给调用方。代码只展示设计方式，未在本机编译或运行。

package stream

import (
    "errors"
    "fmt"
    "net/http"
)

// writeChunk 写入一段响应，并在底层支持时尝试尽快刷新。
func writeChunk(w http.ResponseWriter, payload []byte) error {
    if _, err := w.Write(payload); err != nil {
        // 写入本身失败时，不能把失败伪装成 Flush 不支持。
        return fmt.Errorf("write response chunk: %w", err)
    }

    controller := http.NewResponseController(w)
    if err := controller.Flush(); err != nil {
        // 没有 Flush 能力时保留已写入内容，等待响应结束时正常发送。
        if errors.Is(err, http.ErrNotSupported) {
            return nil
        }
        // 连接断开或底层传输失败仍需让上层决定是否停止响应。
        return fmt.Errorf("flush response chunk: %w", err)
    }
    return nil
}

这里的顺序很重要：先检查 Write，再检查 Flush。如果 Write 已经失败，不能把后续的 ErrNotSupported 当作主要原因。errors.Is 用于匹配官方约定的错误，而不是比较错误字符串。

NewResponseController 接收的是当前处理器拿到的原始 writer，或仍然保留 Unwrap 能力的包装器。不要在处理器返回后继续使用控制器；官方文档明确限制了它的生命周期。

只对 ErrNotSupported 做平滑降级

平滑降级不等于“忽略所有 Flush 错误”。可接受的降级是：数据已经成功交给 Write，但当前 writer 没有 Flush 能力，于是继续完成普通响应。这样中间件即使不能实时推送，也不会因为一次能力探测失败而丢掉正文。

如果返回的是其他错误，常见含义可能是连接或底层传输已经不可用。示例把它包装后返回，是为了让调用方停止继续生成数据、记录上下文或结束处理。对于已经开始写响应的 Handler，不要再尝试写一个新的错误页面来覆盖此前的响应。

按中间件和代理边界排查现象

我会把这段逻辑放在流式响应的一个小辅助函数里，而不是散落在每个循环分支中。这样“支持就刷新、不支持就完成、真实错误就停止”的边界只有一处，后续替换日志或中间件时也更容易复查。

能不能直接断言 http.Flusher？

可以在非常明确的原始 writer 场景中使用，但包装器链会让直接断言失效。ResponseController 能统一处理 Flush、带错误的 FlushError 和 Unwrap 链，通常更适合作为公共辅助逻辑。

ErrNotSupported 是否说明客户端收不到响应？

不是。它只说明当前服务端 writer 没有可用的 Flush 能力；已经成功写入的内容仍可随响应正常结束发送。

Flush 成功是否保证浏览器立刻显示？

不保证。代理或客户端仍可能缓冲，Flush 只完成服务端侧的刷新请求。

参考文档：https://pkg.go.dev/net/http；https://go.dev/src/net/http/responsecontroller.go。