Go http.ResponseController 如何安全刷新流式响应：FlushError、超时与客户端断开

做文件导出、日志订阅或大模型流式返回时，服务端并不是写出第一段数据就算完成。真正容易出问题的是：客户端已经断开，handler 还在继续写；写入卡住后，超时没有生效；代码只判断 `Flush()`，却把底层错误静默丢掉。Go 1.20 引入的 `http.ResponseController` 可以把刷新、写超时和连接控制收拢到同一个入口，关键是要把它放在正确的生命周期里。

先划清 ResponseController 的职责边界

`http.ResponseController` 是对当前响应写入能力的控制器。它可以调用底层实现提供的刷新、读写截止时间、连接劫持等能力；如果当前响应不支持某个能力，会返回对应错误。本文只用其中两个和流式响应直接相关的能力：`FlushError()` 与 `SetWriteDeadline()`。

它解决的是“如何控制一次 HTTP 响应的写入”，不是消息队列，也不是断线重连协议。客户端收到一半后重新请求、如何续传，仍然要由业务层设计。

一条流式响应要经过哪些阶段

可以把 handler 拆成四个阶段：建立响应头、写出一小段数据、刷新到客户端、收到错误后退出。每个阶段都应该有明确检查点，尤其是刷新之后不能无条件继续循环。

最小示例：每个数据块都经过写入和刷新检查

下面的例子用定时器模拟数据生产。真正项目里，`chunks` 可以来自数据库游标、文件读取或上游订阅。示例故意不把所有工作塞进后台 goroutine，这样退出路径更容易核对。

func stream(w http.ResponseWriter, r *http.Request) {
    controller := http.NewResponseController(w)
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.Header().Set("Cache-Control", "no-cache")

    chunks := []string{"chunk-1\n", "chunk-2\n", "chunk-3\n"}
    for _, chunk := range chunks {
        if err := controller.SetWriteDeadline(time.Now().Add(5 * time.Second)); err != nil {
            http.Error(w, "write deadline unavailable", http.StatusInternalServerError)
            return
        }

        if _, err := io.WriteString(w, chunk); err != nil {
            // 客户端断开、网络错误或写超时都会从这里退出。
            return
        }
        if err := controller.FlushError(); err != nil {
            // 刷新失败后不要再生产下一块数据。
            return
        }
    }
}

这里的检查顺序有两个用意。第一，截止时间覆盖的是紧随其后的写入；第二，`FlushError` 失败后立即返回，避免上游生产继续消耗 CPU、数据库游标或订阅连接。

把超时放在每一次可能阻塞的写入前

只在 handler 开始时调用一次 `SetWriteDeadline`，通常不符合长流的预期：截止时间是一个绝对时间点，不会因为已经成功发出一块数据就自动向后延长。若业务允许客户端持续接收，就应在每轮写入前重新设置一个小窗口。

窗口不宜照搬固定值。内网日志流可以是几秒，跨公网的大文件块可能需要更长。建议从监控里的 P99 写入耗时和客户端可接受的空闲时长倒推，并把超时次数、块序号和响应耗时写入服务端日志。

deadline := time.Now().Add(writeWindow)
if err := controller.SetWriteDeadline(deadline); err != nil {
    return fmt.Errorf("set stream deadline: %w", err)
}
if _, err := io.WriteString(w, payload); err != nil {
    return fmt.Errorf("write stream chunk %d: %w", index, err)
}

用停止信号收住上游生产者

如果数据生产和 HTTP 写入分开，单纯从 handler 返回还不够。写入端需要向生产端传递停止信号，否则客户端断开后，生产 goroutine 仍可能从数据库或消息源拿数据。

ctx, cancel := context.WithCancel(r.Context())
defer cancel()

chunks := make(chan string)
go produce(ctx, chunks)

for chunk := range chunks {
    if _, err := io.WriteString(w, chunk); err != nil {
        cancel()
        return
    }
    if err := controller.FlushError(); err != nil {
        cancel()
        return
    }
}

func produce(ctx context.Context, out chan

生产函数必须在发送到 channel 的地方也监听 `ctx.Done()`。否则下游退出后，生产者可能永远阻塞在发送操作上。

推荐的验收流程：先测失败路径，再看正常流

1. 先用一个会主动取消请求的客户端，确认服务端能从 `Write` 或 `FlushError` 返回。
2. 再把写入窗口调小，模拟慢客户端，确认日志包含块序号和超时原因。
3. 最后跑完整流，检查响应块顺序、最终 EOF 和生产 goroutine 数量是否回落。

测试时不要只看浏览器页面是否显示文字。浏览器可能缓冲响应，无法准确告诉你哪一次刷新失败；应在 Go 测试客户端或命令行客户端中记录每个块的到达时间。

常见误区与修正方法

只断言 ResponseWriter 实现了 Flusher

`Flusher` 只说明可以请求刷新，不提供错误返回。优先通过 `ResponseController.FlushError()` 获取这次刷新是否报告问题；如果底层不支持，也要让错误进入可观察日志。

刷新失败后仍继续读取数据库

这是最容易隐藏的资源浪费。刷新失败就是当前响应已经不适合继续发送的信号，应取消上下文、关闭游标并返回。

把客户端断开当成服务端异常告警

用户关闭页面、切换网络都可能造成写入失败。日志里应区分客户端取消、写超时和服务端内部错误，告警策略也不要把每次主动取消都当成事故。

速查表：什么时候继续，什么时候停止

相关问题

FlushError 返回错误后还需要调用 cancel 吗？

如果存在独立的生产 goroutine或外部资源，需要调用取消函数并等待或关闭对应资源；只有完全同步、没有上游资源时，直接返回即可。

ResponseController 能让客户端自动重连吗？

不能。它只控制当前 HTTP 响应，重连、断点和重复数据处理要由客户端协议与业务层定义。

为什么浏览器看不到每一块数据？

浏览器或代理可能缓冲响应。先用明确关闭缓冲的客户端验证服务端刷新，再检查代理层的缓存和响应缓冲策略。

小结

流式响应的核心不是“循环写字符串”，而是为每一块数据建立完整的写入闭环：设置合理的截止时间、检查 `Write`、调用 `FlushError`，失败后取消上游并释放资源。这样客户端断开和慢写入都会在可控位置结束，服务端也不会继续生产已经没人接收的数据。