Go / 系统课时
实现流式响应与 SSE
实现流式响应与 SSE
SSE 让一个普通 HTTP 响应保持打开,并持续向客户端发送文本事件。要让事件真正逐条到达客户端,处理器不仅要写入数据,还要主动 Flush、监听请求上下文取消,并考虑反向代理缓冲和写超时,否则“服务器已经写了”不等于“客户端已经收到”。
学习目标
- 按 SSE 格式设置响应头并逐条发送事件
- 使用
ResponseController.Flush推送缓冲数据,并通过请求上下文检测断开 - 判断代理缓冲和写超时为什么会让流式接口延迟或中断
SSE 的数据链路
SSE 响应的 Content-Type 是 text/event-stream。每个事件由若干文本行组成,并用一个空行结束;常见字段包括 id、event 和 data。客户端收到完整事件后再交给事件监听器处理。
Go 处理器调用 Flush 只能要求当前 ResponseWriter 尽快推出缓冲数据。如果链路中还有反向代理、网关或 CDN,它们仍可能继续缓冲,因此排查延迟时要把“应用缓冲”和“中间代理缓冲”分开看。

实现可取消的 SSE 端点
下面示例需要 Go 1.20 或更高版本,因为使用了 http.ResponseController。接口每秒发送一个 tick 事件,共发送 5 次;如果客户端提前关闭连接,r.Context().Done() 会使处理器立即退出。
package main
import (
"fmt"
"log"
"net/http"
"time"
)
func events(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
rc := http.NewResponseController(w)
ctx := r.Context()
for id := 1; id <= 5; id++ {
select {
case <-ctx.Done():
log.Printf("client disconnected: %v", ctx.Err())
return
case <-time.After(time.Second):
}
now := time.Now().UTC().Format(time.RFC3339)
if _, err := fmt.Fprintf(
w,
"id: %d\nevent: tick\ndata: %s\n\n",
id,
now,
); err != nil {
log.Printf("write failed: %v", err)
return
}
// Flush 把当前 ResponseWriter 的缓冲数据尽快推向网络。
if err := rc.Flush(); err != nil {
log.Printf("flush failed: %v", err)
return
}
}
}
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/events", events)
server := &http.Server{
Addr: ":8080",
Handler: mux,
ReadTimeout: 5 * time.Second,
WriteTimeout: 15 * time.Second,
}
log.Println("listening on :8080")
log.Fatal(server.ListenAndServe())
}预期输出
<TIME> listening on :8080日志时间属于动态值,因此用 <TIME> 表示。示例流持续约 5 秒,短于服务器的 15 秒 WriteTimeout。
观察事件逐条到达
curl 默认可能缓冲标准输出,使用 -N 可以关闭这层缓冲,更容易观察每秒到达一个事件。
curl -N http://localhost:8080/events预期结果
id: 1
event: tick
data: <TIME>
id: 2
event: tick
data: <TIME>
id: 3
event: tick
data: <TIME>
id: 4
event: tick
data: <TIME>
id: 5
event: tick
data: <TIME>每个 <TIME> 都是服务器实时生成的 UTC 时间,实际值会不同。若在第 5 个事件前终止 curl,服务器会在请求上下文取消或后续写入失败时结束处理,不应继续无意义地产生事件。
处理 Flush、代理与超时
ResponseController.Flush() 比直接断言 http.Flusher 更适合新代码:它可以穿透实现了 Unwrap 的 ResponseWriter 包装器,并在底层不支持 Flush 时返回错误。若直接使用 http.Flusher,必须先做类型断言,因为自定义中间件包装后的 ResponseWriter 不一定保留该能力。
Flush 也不是端到端送达确认。反向代理如果开启响应缓冲,多个事件可能被攒成一批后才转发。部署 SSE 时应检查代理的 buffering、压缩和空闲连接策略;不要只因为本机直连能逐秒输出,就认定线上链路也会如此。
http.Server.WriteTimeout 是另一个常见边界。示例只运行约 5 秒,所以 15 秒足够;永久 SSE 流若直接复用较短的全局写超时,连接可能在达到期限后被终止。可以为专门的流式服务配置合适策略,或使用 ResponseController.SetWriteDeadline 做每请求控制,但不能简单地把所有超时永久关闭,否则慢客户端可能长期占用连接和 goroutine。
稳定的 SSE 接口要同时满足三个条件:应用层能及时 Flush,中间链路不把事件长期缓冲,连接生命周期能在客户端取消或超时策略触发时尽快释放资源。