Skip to content
Lv5AI 对话前端进度 3 / 10

第 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]

三个要点:

  1. 每帧只有一个 data: 行,内容是 JSON,不是纯文本;
  2. delta.content 才是文本,role、finish_reason 在别的字段里;
  3. [DONE] 不是 JSON,不能 JSON.parse,要单独判断。
原始字节 → 缓冲区 → 帧data:{"content":"你"} · data:{"content":"好"} · data:↑ chunk1 到这就断了:这一帧还没结束(· 表示空行,也就是分帧位置)chunk 边界≠帧边界缓冲区 bufferdata:{"content":"你"} · data:{"content":"好"} · data:{"content":"啊"} ·每次 read 都往后追加;只切"完整的"部分,剩下的留着帧队列帧1:content="你"帧2:content="好"帧3:content="啊"核心原则:只处理"已经完整"的帧,最后一段永远留在 buffer 里等下一片。

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、空帧
测试纯函数喂假流,三条用例
事故主因半帧被当完整帧,错误被静默吞掉

下一章 ​

数据到手了,接下来是"每秒几十次更新"怎么不把页面拖垮:流式渲染的取舍。

本文阅读--次|全站访问--次|访客--人