SSE

Server-Sent Events

SSE 是一种基于 HTTP 的服务端单向推送技术。服务端通过一个不关闭的 HTTP 响应持续向客户端发送事件流。

SSE vs WebSocket 的通信形态

┏━━━━━━━━━━━━ WebSocket ━━━━━━━━━━━━┓
┃                                    ┃
┃  Client ◀━━━━ data ━━━━━▶ Server   ┃  全双工，双向通信
┃                                    ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛


┏━━━━━━━━━━━━━━ SSE ━━━━━━━━━━━━━━━━┓
┃                                    ┃
┃  Client ◀━━━━ event ━━━━ Server    ┃  单向，服务端推送
┃  Client ◀━━━━ event ━━━━ Server    ┃  基于 HTTP，自动重连
┃  Client ◀━━━━ event ━━━━ Server    ┃  纯文本流
┃                                    ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

基础概念

工作原理

SSE 本质上就是一个不会结束的 HTTP 响应：

Client                                       Server
  │                                             │
  │─── GET /api/events ────────────────────────▶│  ① 普通 HTTP 请求
  │◀── 200 OK                                   │  ② 响应头：Content-Type: text/event-stream
  │    Content-Type: text/event-stream          │
  │                                             │
  │◀── data: {"msg": "hello"}\n\n ──────────────│  ③ 持续推送事件
  │◀── data: {"msg": "world"}\n\n ──────────────│     （响应不关闭）
  │◀── data: {"msg": "..."}\n\n ────────────────│
  │                                             │
  │    （连接断开）                              │  ④ 网络异常
  │                                             │
  │─── GET /api/events ────────────────────────▶│  ⑤ 浏览器自动重连
  │    Last-Event-ID: 3                         │     携带上次事件 ID
  │◀── 200 OK ...                               │  ⑥ 服务端从断点恢复

协议格式

SSE 使用纯文本格式，每个字段占一行，事件之间用空行分隔。

单个事件的完整结构：

event: notification
data: {"title": "新消息"}
id: 42

连续多个事件的流（空行是事件边界）：

event: message
data: {"text": "Hello"}
id: 1

event: message
data: {"text": "World"}
id: 2

特殊字段（注释、省略 event、retry）：

: 这是注释，会被忽略（常用于心跳保活）

data: 没有 event 字段时，触发默认 message 事件
id: 3

retry: 5000
data: 设置重连间隔为 5 秒（retry 被浏览器记住，同时 data 仍会触发 message 事件）

字段说明

多行 data 示例

data: 第一行
data: 第二行
data: 第三行

客户端收到的 event.data 为 "第一行\n第二行\n第三行"。

浏览器端：EventSource API

const es = new EventSource("/api/events");

// 默认 message 事件（没有 event 字段的事件）
es.onmessage = (event) => {
  console.log("收到:", event.data);
  console.log("ID:", event.lastEventId);
};

// 监听自定义事件
es.addEventListener("notification", (event) => {
  const data = JSON.parse(event.data);
  console.log("通知:", data);
});

es.onopen = () => {
  console.log("连接已建立");
};

es.onerror = () => {
  // 不需要手动重连，浏览器会自动处理
  if (es.readyState === EventSource.CLOSED) {
    console.log("连接已永久关闭");
  } else {
    console.log("连接中断，浏览器正在重连...");
  }
};

// 主动关闭（调用后不会自动重连）
es.close();

服务端：响应头要求

res.writeHead(200, {
  "Content-Type": "text/event-stream", // 告诉浏览器这是 SSE
  "Cache-Control": "no-cache", // 禁止缓存
  Connection: "keep-alive", // 保持连接
});

完整 Node.js 实现见 Node.js 实现。

断线重连机制

浏览器原生支持断线重连，且能从断点恢复：

① 服务端发送事件时附带 id
   → id: 42\ndata: {...}\n\n

② 连接断开（网络异常）

③ 浏览器等待 retry 时间后自动重连（默认约 3 秒）

④ 重连请求自动携带请求头 Last-Event-ID: 42

⑤ 服务端读取 Last-Event-ID，从 43 开始继续推送

POST 与 ReadableStream 替代方案

EventSource 只支持 GET 且不能带自定义请求头。需要 POST 或 Authorization 时，用 fetch + ReadableStream 手动解析：

const res = await fetch("/api/chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer " + token,
  },
  body: JSON.stringify({ prompt: "Hello" }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // 按 SSE 协议切分事件（空行分隔）
  const events = buffer.split("\n\n");
  buffer = events.pop() ?? "";

  for (const evt of events) {
    const data = evt
      .split("\n")
      .filter((l) => l.startsWith("data:"))
      .map((l) => l.slice(5).trim())
      .join("\n");
    console.log(data);
  }
}

实际应用场景

AI 流式响应

Client ─── POST /api/chat (普通 HTTP 请求) ──▶ Server
Client ◀── text/event-stream                   Server

data: {"token": "你"}
data: {"token": "好"}
data: {"token": "，"}
data: {"token": "我"}
data: {"token": "是"}
data: {"token": "AI"}
data: [DONE]

其他常见场景