第 3 章:自己解析 SSE
服务端发来的是"字节",你要的是"事件"。中间这一步——分帧——是全课最容易写错、也最值得写对的地方。
学习目标
- 看懂 SSE 的帧结构,知道
\n\n为什么是分隔符 - 会写一个能处理半帧的分帧器,而不是靠
split - 认出
[DONE]、注释行、CRLF 这三种特殊情况 - 会用假流给分帧器写测试
3.1 一帧长什么样
event: message\n
id: 42\n
data: {"choices":[{"delta":{"content":"你"}}]}\n
\n| 字段 | 作用 | 对话场景里常用吗 |
|---|---|---|
data: | 负载。可以出现多行,按 \n 拼接 | 必用 |
event: | 事件类型,默认 message | 少见(多数只发 data) |
id: | 事件 ID,重连时用 Last-Event-ID 续传 | 少见 |
retry: | 重连间隔(毫秒) | 少见 |
: 开头 | 注释行,如 : ping,用来保活 | 常见 |
空行是帧的边界:两个换行(\n\n)表示"这一帧结束了"。
3.2 OpenAI 兼容流的真实形状
data: {"id":"chatcmpl-1","choices":[{"delta":{"role":"assistant"}}]}
data: {"choices":[{"delta":{"content":"你好"}}]}
data: {"choices":[{"delta":{"content":",我是"}}]}
data: [DONE]三个要点:
- 每帧只有一个
data:行,内容是 JSON,不是纯文本; delta.content才是文本,role、finish_reason在别的字段里;[DONE]不是 JSON,不能JSON.parse,要单独判断。
3.3 分帧器
ts
// sse.ts
export class SSEParser {
private buffer = "";
/** 喂一段新文本,吐出这一轮能确定的完整帧 */
push(text: string): string[] {
this.buffer += text;
const frames: string[] = [];
// 帧之间可能是 \n\n,也可能是 \r\n\r\n
let idx: number;
while ((idx = this.buffer.search(/\r?\n\r?\n/)) !== -1) {
const raw = this.buffer.slice(0, idx);
frames.push(raw);
this.buffer = this.buffer.slice(idx).replace(/^\r?\n\r?\n/, "");
}
return frames;
}
/** 取出 data 字段(多行拼接) */
static dataOf(raw: string): string | null {
const lines = raw.split(/\r?\n/);
const parts = lines
.filter(l => l.startsWith("data:"))
.map(l => l.slice(5).replace(/^ /, ""));
return parts.length ? parts.join("\n") : null;
}
}两个容易写错的地方:
| 写法 | 问题 |
|---|---|
split("\n\n") 直接切 | 最后一段是半帧,会被当成有效帧 |
slice(idx + 2) | 遇到 \r\n\r\n 时偏移错了 |
为什么用 search 不用 indexOf:要同时兼容 \n\n 与 \r\n\r\n 两种换行。
3.4 三种特殊情况
| 情况 | 样子 | 处理 |
|---|---|---|
| 注释/保活 | : ping | 丢掉,dataOf 返回 null 时跳过 |
| 结束标记 | data: [DONE] | 直接判结束,不要 JSON.parse |
| 空帧 | 连续空行 | 跳过,不计入 |
ts
const data = SSEParser.dataOf(raw);
if (!data) continue; // 注释或空帧
if (data === "[DONE]") { finish(); break; }
const evt = JSON.parse(data);
const delta = evt.choices?.[0]?.delta?.content ?? "";
if (delta) append(delta);3.5 分帧流程
3.6 怎么测:喂假流
不要等真实接口来测。分帧器是纯函数,可以直接喂字符串:
ts
import { SSEParser } from "./sse";
test("半帧要留到下一片", () => {
const p = new SSEParser();
expect(p.push('data: {"a":1}\n\nda')).toEqual(['data: {"a":1}']);
expect(p.push('ta: {"b":2}\n\n')).toEqual(['data: {"b":2}']);
});
test("CRLF 也要认", () => {
const p = new SSEParser();
expect(p.push('data: {"x":1}\r\n\r\n')).toHaveLength(1);
});
test("注释行不算数据", () => {
expect(SSEParser.dataOf(": ping")).toBeNull();
});这三条用例覆盖了线上 90% 的解析事故。
3.7 一个真实事故的样子
现象:回答末尾总是多出半句话,或者突然变成一个奇怪的字符。
原因链:网络把 你 的 UTF-8 字节切成了两半 → TextDecoder 没开 stream: true → 输出半个字符 → 分帧器把半帧当完整帧 → JSON.parse 失败 → 落到 catch 里被吞掉。
修法就是第 2 章那四件事:stream: true、自己维护 buffer、只切完整帧、JSON.parse 失败要能看见。
本章小结
| 要点 | 说明 |
|---|---|
| 帧结构 | data: 多行,空行分帧 |
| OpenAI 形状 | 每帧一个 JSON,末尾 [DONE] |
| 分帧器 | buffer 累积,只切完整帧,兼容 CRLF |
| 特殊情况 | 注释行、DONE、空帧 |
| 测试 | 纯函数喂假流,三条用例 |
| 事故主因 | 半帧被当完整帧,错误被静默吞掉 |
下一章
数据到手了,接下来是"每秒几十次更新"怎么不把页面拖垮:流式渲染的取舍。