Go 流式响应为什么被缓冲到最后才发送

写了一个 Go HTTP 接口后，服务端明明每隔一段时间就写入一小段内容，客户端却在处理结束时一次性收到全部结果。这个现象不能只归因于“网络慢”：最常见的三层原因分别是 Handler 没有刷新响应、包装后的 ResponseWriter 丢失了 http.Flusher，以及下游代理在继续缓存。

要让流式响应尽早离开 Go 服务端，必须在每个完整业务片段写入后调用 Flush；但 Flush 只负责把服务端已缓冲的数据推向客户端，不能保证代理和最终客户端一定立刻显示。

先判断：缓冲发生在 Go 服务端还是链路上

ResponseWriter.Write 负责把字节交给 HTTP 服务端的响应写出路径，但“交给写出路径”和“客户端此刻能读到”不是同一件事。http.Flusher 的职责是把当前已经缓冲的数据刷新到客户端方向；Go 官方文档也提醒，代理可能在响应完成前继续缓存，即使服务端支持并调用了 Flush。

因此排查时先做一个最小区分：Handler 是否在每次写完一个完整片段后刷新；如果服务端刷新了，再比较直连和经过代理的接收时间。不要一上来把问题归到某个特定网关参数。

没有 Flush 时，写入循环会把“分段”变成“末尾一坨”

下面的处理器把每个事件写成一行，并在行写入后刷新。这里用接口断言是为了兼容仍以 http.Flusher 为主的代码；如果当前包装器不提供这个能力，应该显式返回错误，而不是假装已经实现流式传输。

func streamHandler(w http.ResponseWriter, r *http.Request) {
    // 流式正文不预设总长度，让响应可以持续写出。
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")

    flusher, ok := w.(http.Flusher)
    if !ok {
        // 包装器可能没有转发 Flusher，不能静默退化成假流式。
        http.Error(w, "streaming is not supported", http.StatusInternalServerError)
        return
    }

    for i := 1; i 

这个例子解决的是 Go 服务端自己的缓冲边界。它没有承诺客户端界面会同步刷新，也没有解决中间件把 Flusher 隐藏的问题。另一个容易忽略的点是刷新时机：应当放在一个完整事件写完之后，不要把结构化数据拆在两次刷新之间。

中间件包装后，Flusher 能力可能已经不在了

很多日志、压缩、统计中间件会重新包一层 ResponseWriter。如果新类型只实现了 Header、Write 和 WriteHeader，它就不一定还能通过 http.Flusher 断言。Go 的默认 HTTP/1.x 和 HTTP/2 ResponseWriter 支持 Flusher，但官方明确要求 Handler 在运行时检查，因为包装器可能不支持。

如果项目使用 Go 1.20 或更高版本，可以让 ResponseController 负责向原始 Writer 或可解包的 Writer 请求刷新，并检查返回错误：

type wrappedWriter struct {
    http.ResponseWriter
}

// Unwrap 让 ResponseController 有机会找到原始 ResponseWriter 的能力。
func (w *wrappedWriter) Unwrap() http.ResponseWriter {
    return w.ResponseWriter
}

func flushOne(w http.ResponseWriter, payload []byte) error {
    // 先写完整片段，再请求刷新，保持业务事件的边界。
    if _, err := w.Write(payload); err != nil {
        return err
    }

    // Flush 失败时把错误交给上层，避免继续伪造“已发送”的状态。
    return http.NewResponseController(w).Flush()
}

如果 Flush 返回 ErrNotSupported，优先检查最外层包装器是否实现了 Unwrap，以及它是否真的转发了写出能力。不要仅凭类型名判断；同一个业务 Handler 在直接使用原始 Writer 和经过中间件后，能力集合可能不同。

用现象把三层原因分开

这张表的关键是先定位层级，再改配置。服务端调用 Flush 后仍然延迟，并不能反推出 Go 代码没有生效；相反，经过代理的路径才延迟，也不能用“多调用几次 Flush”解决。

常见问题

为什么只设置 Content-Type 还是不能流式返回？

Content-Type 只是媒体类型，不负责把已经写入的数据刷新出去。仍需在业务片段写入后调用可用的 Flush，并留意后续代理是否缓冲。

使用 httptest 测试时，能判断 Flush 是否被调用吗？

可以在测试中使用 httptest.ResponseRecorder 的 Flushed 状态判断 Handler 是否调用过 Flush，但这只说明测试替身收到了刷新调用，不等于真实网络链路会即时显示。

流式响应应该每写一个字节就 Flush 吗？

不应该。更合理的边界是一个完整事件、行或协议帧；过于频繁的刷新会增加开销，也会让客户端更难按业务单位处理数据。

把问题拆成“服务端是否刷新、包装器是否保留能力、下游是否继续缓存”之后，Go 流式响应的延迟就有了可操作的排查顺序。先确认 Handler 的刷新点，再用直连与代理路径的差异判断最后一层。