解析 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,再从缓冲区里寻找完整的事件分隔符。
几个容易漏掉的细节:
- 字节不是字符。 中文可能被切在两个 UTF-8 字节之间。
TextDecoder要用{ stream: true },让不完整的多字节字符留在内部,等下一块补齐;流结束时再调用一次decode()冲掉剩余内容。 - 分隔符可能是
\n\n或\r\n\r\n。 不能只按\n\n查找,也不能假设服务端固定使用一种换行。 - 一个事件可以有多行
data:。 按 SSE 规范,多行 data 应该用换行拼起来再解析 JSON。当前后端只发单行,但解析器按规范处理,成本很低。 - 注释和未知事件要跳过。 以
:开头的行是注释,常用于心跳;未知事件名不进入业务层。 - 流结束不等于事件完整。 正常结束时,缓冲区里可能还剩最后一条没有空行结尾的事件;要尝试解析一次。如果只剩空白,直接丢弃。
- 取消要释放 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()里完成。 - 长时间没有数据时,连接可能被中间代理断开;当前没有心跳事件,部署时要确认反向代理的超时配置。
下一篇把解析出来的事件接进会话状态机。