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 处理器到客户端的时序

实现可取消的 SSE 端点

下面示例需要 Go 1.20 或更高版本,因为使用了 http.ResponseController。接口每秒发送一个 tick 事件,共发送 5 次;如果客户端提前关闭连接,r.Context().Done() 会使处理器立即退出。

go
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())
}

预期输出

text
<TIME> listening on :8080

日志时间属于动态值,因此用 <TIME> 表示。示例流持续约 5 秒,短于服务器的 15 秒 WriteTimeout。

观察事件逐条到达

curl 默认可能缓冲标准输出,使用 -N 可以关闭这层缓冲,更容易观察每秒到达一个事件。

bash
curl -N http://localhost:8080/events

预期结果

text
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,中间链路不把事件长期缓冲,连接生命周期能在客户端取消或超时策略触发时尽快释放资源。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现流式响应与 SSE

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通