跳到主要内容
Ed. notes

解析 SSE:不要假设一次 read 就是一条事件

长文 · 2026-11-12 · 合集第 4 / 10 篇

  • SSE
  • 流式编程
  • TypeScript
第 4 / 10 篇 · 查看全部章节 → 当前:解析 SSE:不要假设一次 read 就是一条事件

结论

SSE 解析器只做一件事:把任意切分的字节流还原成完整事件。它必须有缓冲区,按空行边界取事件,处理 \r\n,在流结束时清空残余,并且在取消时释放 reader。

不要写“读到一段文本就 split('\n\n')”的代码。第一次 reader.read() 可能只有半个 JSON,第二次可能包含三条事件。

问题与设计

假设服务端发了这一条:

event: token
data: {"text":"你好"}

浏览器实际收到的块可能是:

第 1 块:event: tok
第 2 块:en\ndata: {"te
第 3 块:xt":"你好"}\n\n

如果每块单独解析,三块都不合法。正确做法是先把块追加到 buffer,再从缓冲区里寻找完整的事件分隔符。

几个容易漏掉的细节:

  1. 字节不是字符。 中文可能被切在两个 UTF-8 字节之间。TextDecoder 要用 { stream: true },让不完整的多字节字符留在内部,等下一块补齐;流结束时再调用一次 decode() 冲掉剩余内容。
  2. 分隔符可能是 \n\n 或 \r\n\r\n。 不能只按 \n\n 查找,也不能假设服务端固定使用一种换行。
  3. 一个事件可以有多行 data:。 按 SSE 规范,多行 data 应该用换行拼起来再解析 JSON。当前后端只发单行,但解析器按规范处理,成本很低。
  4. 注释和未知事件要跳过。 以 : 开头的行是注释,常用于心跳;未知事件名不进入业务层。
  5. 流结束不等于事件完整。 正常结束时,缓冲区里可能还剩最后一条没有空行结尾的事件;要尝试解析一次。如果只剩空白,直接丢弃。
  6. 取消要释放 reader。 AbortController 触发后,除了停止 fetch,还要 reader.cancel(),否则底层流可能继续占用连接。

关键代码

解析器在 frontend/app/utils/chat-stream.ts。先看单事件解码:

function decodeEvent(block: string): ChatSseEvent | undefined {
  let eventName = ''
  const data: string[] = []

  for (const line of block.split(/\r?\n/)) {
    if (!line || line.startsWith(':')) continue
    const separator = line.indexOf(':')
    const field = separator === -1 ? line : line.slice(0, separator)
    const value = separator === -1 ? '' : line.slice(separator + 1).replace(/^ /, '')

    if (field === 'event') eventName = value
    if (field === 'data') data.push(value)
  }

  if (!supportedEvents.has(eventName)) return undefined
  if (data.length === 0) throw new Error(`SSE ${eventName} event has no data`)

  let parsed: unknown
  try {
    parsed = JSON.parse(data.join('\n'))
  } catch {
    throw new Error(`SSE ${eventName} event contains invalid JSON`)
  }

  // 省略:校验 parsed 是对象,以及 sources/token/done/error 各自的最小字段。
  return { event: eventName, data: parsed } as ChatSseEvent
}

再看主循环。核心是“追加、找边界、切出完整块、保留剩余”:

buffer += decoder.decode(value, { stream: true })

let boundary = buffer.search(/\r?\n\r?\n/)
while (boundary !== -1) {
  const block = buffer.slice(0, boundary)
  const delimiter = buffer.slice(boundary).match(/^\r?\n\r?\n/)?.[0] ?? '\n\n'
  buffer = buffer.slice(boundary + delimiter.length)

  const event = decodeEvent(block)
  if (event) yield event

  boundary = buffer.search(/\r?\n\r?\n/)
}

这里没有把 buffer 清空,而是只移除已经消费的事件。剩余部分可能是下一条事件的半截,必须留到下一次 read()。

取消路径单独处理:

const cancelOnAbort = () => {
  void reader.cancel().catch(() => undefined)
}
signal?.addEventListener('abort', cancelOnAbort, { once: true })

// 循环中每次 read 前检查 signal;finally 里移除监听、取消并释放锁。

reader.releaseLock() 放在 finally 里,保证正常结束、异常和取消三种路径都不会把流锁住。

验证

测试直接构造一个 ReadableStream,把事件切成不自然的块,其中包含 CRLF、跨块 JSON、注释和未知事件:

const stream = makeStream([
  'event: sources\r\ndata: {"sources":[{"n":1,',
  '"title":"笔记","url":"/notes/a","slug":"a","score":0.9}]}\r\n\r\n',
  'event: token\ndata: {"text":"你好"}\n\n',
  'event: done\ndata: {"finishReason":"stop"}',
])

断言事件顺序是 sources → token → done,并且最后一条没有 \n\n 结尾的 done 也能被解析出来。另一个用例只发注释和未知事件,结果应该是空数组;JSON 损坏或 token 载荷缺少 text 时,迭代器必须抛出可定位的错误。

取消测试用一个永远不会主动结束的流,调用 iterator.return() 后检查底层 cancel() 被调用。这比只看 fetch 是否 abort 更接近真实资源释放。

cd frontend
npm run test -- tests/nuxt/chat-stream.spec.ts

边界

  • 这是面向本项目的精简解析器,不覆盖 SSE 全部能力:没有 id、retry、自定义重连,也不处理 event 字段之外的扩展语义。
  • 如果未来后端采用 gzip 压缩,fetch 通常会自动解压,但代理层仍需确认没有把压缩流截断或缓冲。
  • 解析器只保证“协议层正确”,不保证事件顺序符合业务预期。终态校验在 useChat() 里完成。
  • 长时间没有数据时,连接可能被中间代理断开;当前没有心跳事件,部署时要确认反向代理的超时配置。

下一篇把解析出来的事件接进会话状态机。