Go http.ResponseController Flush 失败时怎样判断响应是否支持

先说结论：http.ResponseController.Flush() 失败时，先判断 errors.Is(err, http.ErrNotSupported)。如果匹配，说明当前 ResponseWriter 及其可展开的包装层没有提供 Flush 或 FlushError；如果不匹配，就要保留底层返回的真实错误，不能一律当成“不支持刷新”。

另外，服务端调用 Flush 成功，只表示 Go 已尝试把当前缓冲交给连接。客户端前面如果还有反向代理或 HTTP 缓冲层，仍可能等到更多数据甚至整个响应结束后才看到内容。排查时要把“接口是否支持”“刷新调用是否报错”和“客户端何时看到”分成三个问题。

一、先用原始 ResponseWriter 创建 ResponseController

ResponseController 从传入的 ResponseWriter 开始查找能力。如果中间件包装了它，包装对象最好提供返回原始对象的 Unwrap() http.ResponseWriter；否则控制器可能只能看到包装层，而看不到底层的 Flush。

func streamChunk(w http.ResponseWriter, text string) error {
    controller := http.NewResponseController(w) // 用 Handler 收到的原始响应对象创建控制器

    if _, err := io.WriteString(w, text); err != nil {
        return fmt.Errorf("写入响应失败: %w", err) // 写入失败与刷新能力是两个独立问题
    }
    if err := controller.Flush(); err != nil {
        return fmt.Errorf("刷新响应失败: %w", err) // 保留原始错误链供上层判断
    }
    return nil
}

不要在 ServeHTTP 返回后继续调用控制器。它的生命周期属于当前处理函数，异步任务如果还要向客户端写数据，应重新设计响应所有权，而不是把 ResponseWriter 保存到后台 goroutine。

二、用 ErrNotSupported 区分能力缺失和底层错误

ResponseController.Flush 会优先使用 FlushError() error，其次使用无返回值的 Flush()，还会沿着 Unwrap 继续查找。如果这些入口都没有找到，就返回匹配 http.ErrNotSupported 的错误。

func flushWithReason(w http.ResponseWriter) error {
    err := http.NewResponseController(w).Flush()
    if err == nil {
        return nil // 刷新调用已被当前响应对象接受
    }
    if errors.Is(err, http.ErrNotSupported) {
        return fmt.Errorf("当前响应对象不支持 Flush: %w", err) // 能力缺失，适合降级或记录配置问题
    }
    return fmt.Errorf("底层刷新失败: %w", err) // 不能丢掉 FlushError 返回的具体原因
}

这里不要只比较错误字符串。http.ErrNotSupported 还可以与 errors.ErrUnsupported 匹配，使用 errors.Is 才能保留包装错误的语义。

三、包装 ResponseWriter 时保留可探测能力

最容易踩坑的中间件写法，是只实现 Header、Write 和 WriteHeader，却没有实现 Unwrap。这会让控制器无法穿过包装层找到底层能力。

type responseLog struct {
    http.ResponseWriter
}

// Unwrap 让 ResponseController 能继续探测底层 ResponseWriter 的扩展接口。
func (w responseLog) Unwrap() http.ResponseWriter {
    return w.ResponseWriter // 不改变日志包装，只恢复能力探测路径
}

func handler(w http.ResponseWriter, r *http.Request) {
    wrapped := responseLog{ResponseWriter: w}
    if _, err := io.WriteString(wrapped, "第一块数据\n"); err != nil {
        http.Error(w, "write failed", http.StatusInternalServerError) // 写入失败时及时结束请求
        return
    }
    if err := http.NewResponseController(wrapped).Flush(); err != nil {
        if errors.Is(err, http.ErrNotSupported) {
            http.Error(w, "streaming is not supported", http.StatusNotImplemented) // 能力不支持时给出明确降级结果
            return
        }
        return // 连接层错误通常不能再安全写入新的 HTTP 错误响应
    }
}

如果包装器自己实现了带错误返回的 FlushError，就应该把真实错误向上传递。不要为了让调用方“看起来成功”而吞掉错误；否则上层只能看到一次 nil，却无法判断数据是否已经交给连接。

四、检查写入顺序，再判断客户端延迟

流式响应通常要先写入一块内容，再调用 Flush。如果尚未写入任何正文，刷新没有可见数据是正常的；如果已经写入并且调用返回 nil，也不能据此断言浏览器马上会显示。

1. 确认处理函数仍在执行，并且没有把 ResponseWriter 交给已失去生命周期控制的后台任务。
2. 先写入带有明确边界的数据块，再调用 Flush。
3. 记录 errors.Is(err, http.ErrNotSupported) 的结果和原始错误文本。
4. 若服务端调用成功但客户端仍延迟，检查反向代理、网关或客户端自身的读取缓冲。

官方文档也提醒，默认的 HTTP/1.x 与 HTTP/2 ResponseWriter 支持 Flusher，但包装器未必支持；即使支持刷新，代理仍可能继续缓冲。因此“Flush 返回 nil”适合做服务端调用结果记录，不适合当成端到端到达确认。

常见问题

为什么直接类型断言 Flusher 不如 ResponseController？

直接断言只能看到当前对象是否实现接口；ResponseController 还能识别带错误返回的 FlushError，并沿 Unwrap 查找底层对象，错误分类也更统一。

Flush 返回 ErrNotSupported 还能继续 Write 吗？

可以把它当成“不具备流式刷新能力”的信号，再决定继续生成完整响应还是返回降级结果。不要假设后续每次 Write 都能产生分块可见效果。

Flush 返回 nil 但浏览器没有马上显示怎么办？

先确认确实写入了正文，再排查代理和客户端缓冲。服务端的刷新调用成功与客户端的即时渲染不是同一个确认点。

小结

排查 ResponseController.Flush 时按“控制器是否拿到原始对象 → 是否匹配 ErrNotSupported → 是否保留底层错误 → 是否存在代理缓冲”的顺序处理。包装器提供 Unwrap，调用方用 errors.Is，并把服务端刷新结果与客户端可见时间分开记录，才能准确判断到底是能力不支持、底层连接失败，还是链路仍在缓存。