流式响应

Go 的流式响应不能只看“有没有调用 Write”。真正决定分段内容能否尽快到达客户端的是 http.Flusher 以及链路上的缓冲层。遇到中间件包装后的 ResponseWriter 不支持 Flusher 时，正确做法是运行时判断：支持就刷新，不支持就继续完成一次性响应，或明确返回一个不依赖实时刷新的降级结果。

优先用 http.NewResponseController(w).Flush() 判断能力；如果返回可匹配 http.ErrNotSupported，不要强转或反复重试，把剩余内容写完并接受“响应结束后才可见”的语义。

先把写入和及时到达分开

ResponseWriter.Write 成功，只表示数据交给了当前响应写入链路，并不等于浏览器已经收到这一段。Flusher 的职责是把服务端已经缓冲的数据向客户端推进；默认的 HTTP/1.x 和 HTTP/2 响应实现支持它，但中间件、测试替身或其他包装器可能没有透传这个能力。

因此，流式接口应把“内容能否写出”和“内容能否分段可见”拆成两个判断。没有刷新能力时，普通文本、进度摘要可以继续写完；而依赖逐段消费的 SSE、长轮询进度或交互式输出，则应选择明确的降级策略，不要假装仍然是实时流。

用 ResponseController 做运行时能力判断

Go 1.20 及以上可以从原始的 ResponseWriter 创建控制器。它会尝试调用 FlushError 或 Flusher.Flush，也会沿包装器提供的 Unwrap 继续查找；找不到时返回匹配 http.ErrNotSupported 的错误。

func flushIfPossible(w http.ResponseWriter) (bool, error) {
    controller := http.NewResponseController(w)
    if err := controller.Flush(); err != nil {
        // 不支持刷新是能力差异，不应被当成服务端故障。
        if errors.Is(err, http.ErrNotSupported) {
            return false, nil
        }
        // 连接断开等真实写出错误仍要交给上层处理。
        return false, err
    }
    return true, nil
}

如果项目还要兼容更早的 Go 版本，可以使用 f, ok := w.(http.Flusher) 做兼容分支；但要注意，直接断言看不到包装器背后的实现，能控制版本时优先使用 ResponseController。

不支持 Flush 时怎样安全降级

降级的核心不是伪造实时性，而是保证响应仍然完整。写入每个片段后尝试刷新；第一次遇到 ErrNotSupported 就停止继续调用 Flush，但把剩余片段写完。这样既不会因为包装器缺少一个可选接口而返回 500，也不会在循环里不断重试一个确定不支持的能力。

func writeChunks(w http.ResponseWriter, chunks []string) error {
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    controller := http.NewResponseController(w)
    canFlush := true

    for i, chunk := range chunks {
        if _, err := io.WriteString(w, chunk); err != nil {
            // 客户端断开等写入错误应立即结束处理。
            return err
        }
        if !canFlush {
            continue
        }
        if err := controller.Flush(); err != nil {
            // 后续内容继续写，但不再承诺逐段即时可见。
            if errors.Is(err, http.ErrNotSupported) {
                canFlush = false
                continue
            }
            // 非能力差异错误不能静默吞掉。
            return fmt.Errorf("flush chunk %d: %w", i, err)
        }
    }
    return nil
}

这个方案适合“能流式就流式、不能流式也要返回完整结果”的接口。若调用方必须逐条收到事件，则应在入口处把不支持能力转换成明确的非流式接口、短错误响应或重新选择支持刷新的传输路径，而不是让客户端无限等待下一段。

代理和测试环境要单独核对

即使服务端实现了 Flush，Go 官方文档也提醒：客户端经过 HTTP 代理时，缓冲数据仍可能直到响应完成才到达。因此，本地浏览器看到分段输出不能证明生产链路具备同样语义。应分别检查响应包装器是否提供 Unwrap、反向代理是否配置了缓冲策略，以及客户端是否按流式协议消费。

httptest.ResponseRecorder 实现了 http.Flusher，适合测试处理器是否调用刷新，但它不是线上代理链路的替身。测试至少覆盖两类 writer：一个记录 Flush 调用的实现，以及一个只实现 http.ResponseWriter 的包装器；后者要验证正文完整、没有因不支持刷新而报错。

常见疑问

不支持 Flusher 还能返回流式响应吗？ 只能返回分段写入的正文，不能保证分段及时可见。若实时性是协议要求，应改用明确的降级响应或换到支持刷新的链路。

为什么本地测试能刷新，线上却一起到达？ 线上可能增加了不透传 Flusher 的中间件，也可能是反向代理继续缓冲；需要分层定位，不能只看处理器里的类型断言。

速查：支持刷新时调用一次并继续写；遇到 http.ErrNotSupported 只降级一次；遇到连接或写出错误立即返回；任何情况下都不要在 ServeHTTP 返回后继续使用 ResponseWriter。