Go 流式响应延迟发送的 Flush 处理

Go 的流式响应已经写入了一段文字，但客户端要等很久才看到，最常见的处理不是无条件多调用几次 Flush()，而是先确认响应对象真的支持刷新，再把“服务端写出”“代理转发”“客户端读取”拆开判断。http.Flusher 只负责把当前响应对象能够刷出的缓冲数据交给连接，不能绕过代理或客户端自己的缓冲。

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

处理 Go 流式响应延迟时，先用运行时类型断言确认 http.Flusher，每个完整片段写完后再刷新；如果包装器不暴露该能力，优先修正包装器或改用 http.NewResponseController。服务端已经刷新而客户端仍延迟，则继续检查反向代理和客户端消费方式。

先确认延迟发生在哪一层

我处理这类问题时会先画出四个节点：Handler 写入响应、ResponseWriter 刷新、代理转发、客户端读取。只看服务端日志里的“已经调用 Flush”还不够，因为 Go 官方文档明确提醒：即使 ResponseWriter 支持刷新，客户端经过 HTTP 代理时，数据也可能等到整个响应结束才到达客户端。

因此可以先用下面的顺序判断：

把每个完整片段作为一次发送边界

流式接口不应该把每个字符都当成一个事件。更实用的边界是“一个完整状态、一条 SSE 事件或一段可解析 JSON 行”：先写完整片段，再调用刷新。响应头、内容类型和缓存策略也要在第一次写入前设置。

package main

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

func streamHandler(w http.ResponseWriter, r *http.Request) {
    // 明确告诉客户端这是按事件逐段消费的响应，并在第一次写入前设置头部。
    w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")

    // 包装器可能没有实现 Flusher，先拒绝不具备流式能力的响应对象。
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming is not supported", http.StatusInternalServerError)
        return
    }

    for i := 1; i 

这里的关键不是调用次数，而是调用位置：片段已经完整写入后刷新，下一段开始前再等待。Flush() 没有返回错误，因此写入操作本身仍要检查错误；客户端断开时，写入通常比继续刷新更早暴露问题。

包装器不支持 Flush 时不要硬转型

标准 HTTP/1.x 和 HTTP/2 的默认 ResponseWriter 支持 http.Flusher，但中间件常常会用自定义类型包住它。如果包装器只转发了 Header、Write 和 WriteHeader，却没有转发 Flush，类型断言就会失败，或者流式语义在包装层被截断。

type streamingWriter struct {
    http.ResponseWriter
}

// Flush 将底层的刷新能力显式暴露给后续 Handler。
func (w streamingWriter) Flush() {
    if f, ok := w.ResponseWriter.(http.Flusher); ok {
        // 只有底层确实支持刷新时才调用，避免包装器伪造能力。
        f.Flush()
    }
}

func handler(w http.ResponseWriter, r *http.Request) {
    // ResponseController 可以沿着 Unwrap 找到原始 ResponseWriter。
    controller := http.NewResponseController(w)
    if err := controller.Flush(); err != nil {
        http.Error(w, "flush is not supported", http.StatusInternalServerError)
        return
    }
    // 这里继续写入业务片段；真实项目中应先设置完整响应头。
    _, _ = w.Write([]byte("data: ready\\n\\n"))
}

上面的包装器示例只是说明接口转发关系。实际项目中更推荐让包装器实现一个返回原始对象的 Unwrap() http.ResponseWriter，这样 http.NewResponseController 才有机会把刷新请求传给底层对象。若底层根本不支持刷新，应该返回清楚的错误或降级为普通响应，而不是宣称已经实时发送。

ResponseController 适合需要错误判断的场景

直接使用 http.Flusher 的优点是简单，缺点是 Flush() 没有错误返回。Go 1.20 引入的 http.ResponseController 提供了返回错误的刷新方式，并能处理带有 Unwrap 的响应包装器：

func writeEvent(w http.ResponseWriter, event string) error {
    // 先写完整事件，再让 ResponseController 把缓冲交给连接。
    if _, err := fmt.Fprintf(w, "data: %s\\n\\n", event); err != nil {
        return fmt.Errorf("write event: %w", err)
    }

    // Flush 返回错误，便于把不支持刷新或连接异常纳入排障日志。
    if err := http.NewResponseController(w).Flush(); err != nil {
        return fmt.Errorf("flush event: %w", err)
    }
    return nil
}

如果 Handler 同时读取请求体并写响应，还要注意 HTTP/1 的默认行为。EnableFullDuplex 用于声明读写交错意图，但它不是解决所有客户端兼容问题的开关；如果业务允许，先完整读取请求体再开始输出通常更容易判断，也更容易兼容中间件。

按证据排查 Flush 不生效

1. 先查能力：记录 w.(http.Flusher) 是否成功；失败时检查最近加入的压缩、中间件或自定义 ResponseWriter。
2. 再查发送边界：确认首次写入前已设置头部，事件或数据行已经完整结束，而不是只写入一半 JSON。
3. 再查链路：分别记录 Handler 写入时间、Flush 调用时间和客户端收到时间。第三个时间明显靠后时，优先查代理缓冲与客户端读取代码。
4. 最后查读写关系：如果 HTTP/1 请求体还没有读完就开始写响应，先改成先读后写；只有业务确实需要交错读写时再评估 EnableFullDuplex。

# 用 curl 按到达顺序显示响应，辅助区分客户端等待行为。
curl --no-buffer http://127.0.0.1:8080/events

# 用时间戳记录每次事件的到达顺序，不把最终响应时间误当成首段延迟。
curl --no-buffer http://127.0.0.1:8080/events | while IFS= read -r line; do
  date '+%H:%M:%S' >&2
  printf '%s\\n' "$line"
done

curl --no-buffer 只能减少 curl 自己的显示缓冲，不能证明链路中的代理已经关闭缓冲。若服务端日志显示每 500 毫秒刷新一次，而客户端仍一次性获得全部内容，排查重点就应从 Go Handler 转向代理配置、响应压缩和客户端读取策略。

什么时候应该回退为普通响应

如果客户端不需要逐段消费，或者入口代理无法稳定转发分块数据，普通响应往往更可靠。流式输出还需要处理连接断开、超时、取消信号、并发写入和中间件兼容；为了“看起来实时”而让所有接口都使用 Flush，反而会增加运维成本。

可以把最终决策压缩成三句话：

• 响应对象支持 Flusher，就按完整片段写入并刷新；不支持时明确失败或降级。
• 刷新成功只说明 Go 已推动当前响应对象，不能替代理解代理和客户端的缓冲。
• 需要错误返回或响应包装器兼容时使用 ResponseController，请求体读写交错则单独评估 EnableFullDuplex。

相关问题

为什么调用 Flush 后浏览器还是最后一次性显示？

浏览器、反向代理或压缩层都可能继续聚合响应。先用不主动缓冲的客户端观察，再分别对比服务端和代理的时间点。

ResponseWriter 包一层后为什么 Flusher 断言失败？

因为 Go 的接口能力由当前动态类型决定，包装器没有实现并转发 Flush 就不会自动继承底层接口。修正包装器，或提供 Unwrap 让 ResponseController 找到底层对象。

Flush 能不能替代定时发送心跳？

不能。Flush 负责推动已经写入的数据，心跳内容仍需要业务代码按协议写出；两者应分别处理。