1. 背景：SSE 数据格式 {背景}
在理解代码之前，必须先理解 SSE 协议的原始数据格式。
1.1 服务端发送的原始字节流
服务端发送:
POST /api/ai/chat → 服务端开始流式返回
原始字节流（服务端连续发送）:
┌─────────────────────────────────────────────┐
│ event: delta\n │
│ data: {"content":"你","done":false}\n │
│ \n │ ← 空行，表示一个事件结束
│ event: delta\n │
│ data: {"content":"好","done":false}\n │
│ \n │
│ event: delta\n │
│ data: {"content":"","done":true}\n │
│ \n │
└─────────────────────────────────────────────┘
1.2 SSE 协议规范
┌─────────────────────────────────────────────────┐
│ SSE 事件格式（RFC 规范）: │
│ │
│ [field]: [value]\n │
│ [field]: [value]\n │
│ \n │ ← 空行 = 事件分隔符
│ │
│ field 只有 4 种：data / event / id / retry │
│ │
│ 示例： │
│ event: delta\n ← event 字段 │
│ data: {"content":"你"}\n ← data 字段 │
│ \n ← 事件结束 │
└─────────────────────────────────────────────────┘
1.3 浏览器接收到的是什么
HTTP 响应体（ReadableStream<Uint8Array>）:
chunk 1: [101 118 101 110 116 ...] ← Uint8Array 字节数组
chunk 2: [100 97 116 97 58 ...]
chunk 3: [123 34 99 111 110 116 ...] ← 可能被任意截断！
注意：TCP 数据包的边界与 SSE 事件边界完全无关
这就是为什么需要 手动——将乱序、任意截断的字节流，解析成业务可用的结构化数据。
2. EventSource 的工作方式
EventSource 是浏览器内置的专用 API，专门用来消费 SSE。EventSource 是浏览器专为 SSE 封装的高级 API，能够自动解析data/event/id/retry、自动分行、自动解码，服务器可指定重连间隔，断网自动重试。
简单示例：
const es = new EventSource('/time');
es.onmessage = (e) => console.log('收到时间：', e.data);
es.onerror = (e) => console.log('出错了');
你只需要关心业务逻辑，连接管理和协议解析都由浏览器搞定。
但是有一个关键的缺点，不支持传递自定义请求头，只能用 GET。因此，对于大型项目，我们只能使用更加原生流式请求fetch + ReadableStream的方式。fetch 是通用流式传输，不仅能做 SSE，还能处理文件下载、视频流、自定义二进制流。
3. fetch + ReadableStream 的工作方式
首先来一段代码，下面是使用了EventSource实现的流式对话的一个方法，我们直接监听onmessage方法取到数据，这个数据已经是格式化后的数据，将这个数据追加到message中就可以实现流式的效果。现在，我们需要将它改造为fetch + ReadableStream的方式。
export const connectSSE = (message: string, options: SSEOptions) => {
let currentAttempt = 0;
let delay = 1000;
let timeoutId: NodeJS.Timeout | null = null;
let isClosed = false;
let eventSource: EventSource | null = null;
const closeConnection = () => {
isClosed = true;
if (eventSource) {
eventSource.close();
eventSource = null;
}
if (timeoutId) {
clearTimeout(timeoutId);
timeoutId = null;
}
};
const connect = () => {
eventSource = new EventSource(
`/api/ai/chat?message=${encodeURIComponent(message)}`,
);
eventSource.onmessage = (event) => {
try {
const data = JSON.parse(event.data);
if (data.done) {
eventSource?.close();
options.onDone();
closeConnection();
} else {
options.onChunk(data.content);
}
} catch (error) {
options.onError(new Error("解析SSE数据失败"));
}
};
eventSource.onerror = () => {
if (isClosed) return;
eventSource?.close();
options.onError(new Error("SSE连接错误"));
if (currentAttempt < DEFAULT_RETRY_CONFIG.maxRetries) {
currentAttempt++;
timeoutId = setTimeout(() => {
connect();
}, delay);
} else {
options.onError(new Error(`SSE连接失败，已重试${currentAttempt}次`));
closeConnection();
}
};
};
connect();
return closeConnection;
};
fetch 返回的 Response 对象中的 body 是一个 ReadableStream（可读流）。它只提供最原始的字节数据，不解析任何格式，你需要手动处理：
-
发起请求：可以自定义 method、headers、body，不限于 GET。
-
获取流：
response.body 是一个 ReadableStream<Uint8Array>。
-
读取数据：通过
getReader() 获得读取器，循环读取数据块（chunk）。
-
解析协议：需要自己将二进制 chunk 解码为字符串，按行分割，检测 SSE 格式（
data:、\n\n 等）。
-
处理重连：如果需要自动重连，必须自己实现逻辑。
-
取消连接：可以调用
reader.cancel() 或 abortController.abort()。
简单示例：
const response = await fetch('/time', { method: 'GET' });
const reader = response.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 });
// 解析 buffer 中的 SSE 消息...
// 检测 data: ...\n\n，提取数据，然后清空已处理部分
}
上面的value就是最新返回的数据流，通过解码后就是我们的文本块了，应该怎么处理呢。
EventSource 方式：
Server SSE → EventSource 解析 → onmessage 回调
Fetch + Stream 方式：
Server SSE → ReadableStream
↓
TextDecoder（字节→文本）
↓
行缓冲（处理分割）
↓
SSE 行解析（data: 前缀）
↓
JSON.parse
↓
onChunk 回调
首先，解码后的值赋值给buffer，此时buffer是一个字符串，它可能含有多条语句，因此需要进行切割。buffer.split("\n")将buffer分割为含有多个语句的数组，需要注意的是数组的最后一个元素可能并不是以\n结束的因此先不要处理。
为了处理这种分块，我们需要维护一个累积的缓冲区（buffer 变量），将每次新收到的 chunk 追加到缓冲区末尾，然后再一起处理。
export const connectSSEFetch = async (
message: string,
options: SSEOptions
) => {
const abortController = new AbortController();
try {
const response = await fetch(
`/api/ai/chat?message=${encodeURIComponent(message)}`,
{ signal: abortController.signal }
);
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { done, value } = await reader.read();
if (done) {
options.onDone();
break;
}
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop() || ""; // 保留最后一行
for (const line of lines) {
if (line.startsWith("data: ")) {
const data = JSON.parse(line.slice(6));
if (data.done) {
options.onDone();
return;
}
options.onChunk(data.content);
}
}
}
} catch (err) {
options.onError(err as Error);
}
return () => abortController.abort();
};
举个例子- 例如，当前缓冲区内容为：
data: Hello\n
data: Wor
这里 "data: Wor" 没有换行符结尾，它只是单词 "World" 的一部分，下一个 chunk 可能会带来 "ld\n\n"。 split('\n') 会得到：
["data: Hello", "data: Wor"]
其中 "data: Wor" 是最后一项，它不是以换行符结尾的完整行，而是一个不完整的行。如果现在处理这一行，就会得到错误的数据。
所以，我们不能处理最后一行，必须把它留到下一次，等后续数据到来拼完整后再处理。
到现在为止，逻辑还是比较清晰的，对比之下，Fetch只是多了一些流数据处理的逻辑，是不是可以把这部分抽取出来呢。
// 高阶函数：创建 SSE 行处理器
// buffer 和 decoder 在闭包中维持状态，跨 chunk 使用
const createSSELineProcessor = () => {
let buffer = "";
const decoder = new TextDecoder();
return {
// 处理单个数据 chunk
processChunk: (chunk: Uint8Array): boolean => {
// if (dataEndReceived) return false;
// 1. 转换字节为文本（stream: true 表示可能是多字节字符的中间部分）
buffer += decoder.decode(chunk, { stream: true });
// 2. 按换行符分割成行
const lines = buffer.split("\n");
// 3. 最后一行可能不完整，保留到下一个 chunk
buffer = lines.pop() || "";
// 4. 处理完整的行
for (const line of lines) {
// 空行是 SSE 中的消息分隔符，跳过
if (!line.trim()) continue;
const data = parseSSELine(line);
if (!data) continue; // 不是 data 行，跳过
if (data.done) {
options.onDone();
return false; // 返回 false 表示应该停止处理
}
// 处理数据块
options.onChunk(data.content);
}
return true; // 返回 true 表示继续处理
},
// 处理流结束时的剩余数据
flush: (): void => {
// 最终解码（处理任何待处理的多字节字符）
const finalText = decoder.decode();
if (finalText.trim()) {
const data = parseSSELine(finalText);
if (data && !data.done) {
options.onChunk(data.content);
}
}
},
};
};
这里我们对流数据处理逻辑进行了抽取，buffer作为闭包保存，使用的时候只需要p=createSSELineProcessor,然后调用p.processChunk即可。依旧是每轮判断有没有done,有的话就退出。
while (true) {
const { done, value } = await reader.read();
if (done) {
break;
}
const shouldContinue = processor.processChunk(value);
if (!shouldContinue) {
break;
}
}
}
还有两个细节，原来的函数有flush，这个函数是干嘛的，什么时候调用呢。
TextDecoder 是浏览器原生 API，用于将 二进制字节流（Uint8Array） 解码为文本字符串，它有两种解码模式，对应两种调用方式：
带参数 + stream: true（流式解码，核心用法）
decoder.decode(chunk, { stream: true })
-
作用：分片、连续解码二进制流（比如 SSE / 文件流，数据是一块块传输的）；
-
关键特性：如果遇到不完整的多字节字符（比如中文、 emoji，UTF-8 占 3 字节），解码器不会强行解码，而是把残留字节缓存在解码器内部，等待下一块数据拼接完整后再解码；
- 不会出现乱码，专门处理流式分片数据。
不带参数（刷新 / 收尾解码，最终调用）
decoder.decode()
-
官方定义：结束流式解码，刷新解码器内部的所有残留字节；
-
作用：把之前流式解码时缓存的未完成字节，一次性全部解码成字符串；
-
副作用：清空解码器的内部缓冲区，标志着整个解码流程结束。
SSE 流是分块传输的，当服务器关闭流、传输彻底结束时，会存在两个残留数据问题：
-
解码器内部残留：
TextDecoder 用 stream: true 缓存了不完整的多字节字符，没有新 chunk 了，必须手动调用 decode() 刷新；
-
缓冲区残留：闭包中的
buffer 可能还剩最后一行不完整文本，没有后续换行符触发处理。
如果不调用 flush()，这部分数据会直接丢失，flush() 是流传输结束后的收尾方法，专门处理最后残留的、未被解码 / 未被处理的数据，防止数据丢失。
还有一个细节，reader最后注意释放， cancel主动终止整个可读流（ReadableStream）。调用后，流会被关闭，后续无法再从该流读取任何数据，并且任何挂起的读请求都会立即完成或失败。 releaseLock释放当前读取器对流的锁定，但不关闭流。调用后，该读取器不再关联任何流，流可以被其他读取器（或异步迭代器）再次锁定。
比如
// 假设已经用 reader 读了一部分
const firstChunk = await reader.read();
// 处理 firstChunk...
// 释放锁，然后才能用 for await 或 XStream
reader.releaseLock();
// 现在可以安全地使用 for await
for await (const chunk of response.body) {
// ...
}
如果中间没有释放，机会报错，一个流被两个代码读取了。
再补充一点，mdn对于流的读取还提到了这样一个例子：
const response = await fetch("https://www.example.org");
let total = 0;
// Iterate response.body (a ReadableStream) asynchronously
for await (const chunk of response.body) {
// Do something with each chunk
// Here we just accumulate the size of the response.
total += chunk.length;
}
// Do something with the total
console.log(total);
for await...of 本质上就是异步迭代的语法糖，它与手动 while 循环实现的是完全相同的流式处理效果。ReadableStream从2024年开始逐步实现了异步可迭代协议。Chrome 124（2024年4月稳定版）正式增加了对ReadableStream的异步迭代支持。区别在于代码风格：for await...of 更简洁、更符合直觉，而手动循环则暴露了更多的底层控制细节。
手动 while 循环通常是这样写的：
const reader = stream.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
// 处理 value
}
现在还可以采用更加优雅的方式。
if (stream[Symbol.asyncIterator]) {
for await (const chunk of stream) {
const shouldContinue = processor.processChunk(chunk);
// 如果接收到 done 信号，继续消耗流直到结束
if (!shouldContinue ) {
break;
}
}
} else {
throw new Error("浏览器不支持 for await...of");
}
4. XStream 整体架构与逻辑链路
根据官网，@ant-design/x-sdk 提供了一系列的工具API，旨在帮助开发人员开箱即用的管理AI对话应用数据流，其中的XStream用于转换可读数据流。先看看用法
import { XStream } from '@ant-design/x';
async function request() {
const response = await fetch();
// .....
for await (const chunk of XStream({
readableStream: response.body,
})) {
console.log(chunk);
}
}
是不是跟上面的很像，其实就是做了进一步的底层封装和优化，逻辑都差不多，下方看看怎么实现的。
源代码
4.1 数据流转图
服务端 HTTP 响应
│
▼
ReadableStream<Uint8Array> ← 原始字节流（TCP 数据包）
│
│ .pipeThrough(decoderStream)
▼
ReadableStream<string> ← UTF-8 文本流（可能在字符中间截断）
│
│ .pipeThrough(splitStream('\n\n'))
▼
ReadableStream<string> ← SSE 事件字符串流（按 \n\n 分割）
│
│ .pipeThrough(splitPart('\n', ':'))
▼
ReadableStream<SSEOutput> ← 结构化 SSE 对象流
│
│ stream[Symbol.asyncIterator]
▼
AsyncGenerator<SSEOutput> ← 支持 for await...of 消费
4.2 实际数据转换示例
输入（Uint8Array 字节）:
[101, 118, 101, 110, 116, 58, 32, 100, 101, 108, 116, 97, ...]
─── decoderStream ───→
输入（string，可能不完整）:
"event: delta\ndata: {\"con" ← chunk 1
"tent\":\"你好\"}\n\n" ← chunk 2
─── splitStream('\n\n') ───→
输出（完整事件，按 \n\n 分割）:
"event: delta\ndata: {\"content\":\"你好\"}"
─── splitPart('\n', ':') ───→
输出（SSEOutput 对象）:
{
event: "delta",
data: "{\"content\":\"你好\"}"
}
5. 核心 API 讲解
5.1 ReadableStream
ReadableStream 是浏览器中表示"可读数据流"的原生 API。
// 创建一个自定义 ReadableStream
const stream = new ReadableStream<string>({
start(controller) {
// 流启动时调用
controller.enqueue('Hello'); // 推入数据
controller.enqueue(' World');
controller.close(); // 关闭流
},
cancel(reason) {
// 消费者取消时调用
console.log('流被取消:', reason);
}
});
// 消费方式1: getReader()
const reader = stream.getReader();
const { done, value } = await reader.read(); // { done: false, value: 'Hello' }
reader.releaseLock();
// 消费方式2: for await...of（需要 asyncIterator 支持）
for await (const chunk of stream) {
console.log(chunk); // 'Hello', ' World'
}
关键特性：
- 流只能被读取一次（single-consumer）
- 一次只能有一个 reader
-
enqueue 将数据推入内部队列
-
close 发出 done 信号
5.2 TransformStream
TransformStream 是可读流和可写流的组合，专门用来转换数据。
// 基本结构
const transform = new TransformStream<Input, Output>({
transform(chunk, controller) {
// 每次有 chunk 时调用
// controller.enqueue() 将转换后的数据推入输出流
// controller.error() 报错
},
flush(controller) {
// 流结束时调用，处理剩余缓冲数据
// 对应 TextDecoder 的 decode() 无参版本
},
start(controller) {
// 初始化时调用（可选）
}
});
// 使用示例：大写转换器
const upperCaseTransform = new TransformStream<string, string>({
transform(chunk, controller) {
controller.enqueue(chunk.toUpperCase());
}
});
// 消费
const writer = upperCaseTransform.writable.getWriter();
const reader = upperCaseTransform.readable.getReader();
writer.write('hello');
const { value } = await reader.read(); // 'HELLO'
与 上文 中 createSSELineProcessor 的对比:
// sse.ts：手动管理状态的处理器（命令式）
const createSSELineProcessor = () => {
let buffer = '';
const decoder = new TextDecoder();
return {
processChunk(chunk: Uint8Array): boolean {
buffer += decoder.decode(chunk, { stream: true });
// ... 手动处理 buffer 和行分割
return true;
},
flush(): void {
// 手动处理剩余数据
}
};
};
// XStream：使用 TransformStream（声明式，职责更清晰）
new TransformStream<string, string>({
transform(streamChunk, controller) {
// 只关注转换逻辑，不关注如何读写流
buffer += streamChunk;
// ...
},
flush(controller) {
// 框架自动调用，无需手动触发
}
});
5.3 pipeThrough
pipeThrough 将一个 ReadableStream 接入 TransformStream，返回新的 ReadableStream。
// 基本用法
const outputStream = inputStream.pipeThrough(transformStream);
// 链式调用（XStream 的精华）
const processedStream = rawStream
.pipeThrough(decoderStream) // Uint8Array → string
.pipeThrough(splitStream()) // string → SSE事件块
.pipeThrough(splitPart()); // SSE事件块 → {event, data}
// 类比：Linux 管道
// cat file.txt | grep "error" | awk '{print $1}'
// ↓ ↓ ↓
// ReadableStream pipeThrough pipeThrough
关键特性：
- 自动处理背压（backpressure）：下游消费慢时，自动暂停上游写入
- 惰性求值：不消费就不处理
- 返回新的 ReadableStream，原始流不可再用
// pipeThrough 内部等价于：
readable
.pipeTo(transform.writable) // 原流连接到 transform 的可写端
.then(/* 完成 */);
return transform.readable; // 返回 transform 的可读端
5.4 TextDecoderStream
专门用于字节→字符串转换的原生 TransformStream。
// 原生 TextDecoderStream（现代浏览器支持）
const nativeDecoder = new TextDecoderStream('utf-8');
// 等价于：
const polyfillDecoder = new TransformStream({
transform(chunk, controller) {
controller.enqueue(decoder.decode(chunk, { stream: true }));
},
flush(controller) {
controller.enqueue(decoder.decode()); // 处理剩余字节
}
});
// 使用场景：正确处理被切断的多字节字符
const chineseChar = '你'; // UTF-8: [E4 BD A0]（3字节）
// 不用 stream: true 的问题：
decode([0xE4]) // 错误：'?'（字节不完整）
decode([0xBD, 0xA0]) // 错误：'??'
// 用 stream: true 的正确处理：
decode([0xE4], { stream: true }) // ''（等待后续字节）
decode([0xBD, 0xA0], { stream: true }) // '你'（完整输出）
createDecoderStream 的兼容处理：
function createDecoderStream() {
// 优先使用原生 API（性能更好）
if (typeof TextDecoderStream !== 'undefined') {
return new TextDecoderStream();
}
// 降级到 polyfill（Safari 旧版等不支持的环境）
const decoder = new TextDecoder('utf-8');
return new TransformStream({ /* ... */ });
}
5.5 Symbol.asyncIterator
让对象支持 for await...of 语法。
// 基本用法
const asyncIterable = {
[Symbol.asyncIterator]: async function*() {
yield 1;
yield 2;
yield 3;
}
};
for await (const value of asyncIterable) {
console.log(value); // 1, 2, 3
}
// XStream 的实现：给 ReadableStream 附加异步迭代器
stream[Symbol.asyncIterator] = async function*() {
const reader = this.getReader(); // this = stream
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (!value) continue;
yield value; // 每次 yield 一个已转换好的 SSEOutput
}
};
// 使用效果：
const xStream = XStream({ readableStream: response.body });
for await (const event of xStream) {
console.log(event); // { event: 'delta', data: '{"content":"你好"}' }
}
6. XStream 各函数详解
6.1 splitStream：SSE 事件块分割器
function splitStream(streamSeparator = '\n\n') {
let buffer = ''; // 闭包维持跨 chunk 状态
return new TransformStream<string, string>({
transform(streamChunk, controller) {
buffer += streamChunk;
const parts = buffer.split(streamSeparator); // 按 \n\n 分割
parts.slice(0, -1).forEach(part => {
if (isValidString(part)) controller.enqueue(part); // 推出完整事件
});
buffer = parts[parts.length - 1]; // 保留最后不完整的部分
},
flush(controller) {
if (isValidString(buffer)) controller.enqueue(buffer); // EOF 时推出最后数据
}
});
}
执行过程追踪：
输入 chunk 1: "event: delta\ndata: {\"con"
buffer = "event: delta\ndata: {\"con"
parts = ["event: delta\ndata: {\"con"] ← 只有1部分，无完整事件
enqueue: 无
buffer = "event: delta\ndata: {\"con"
输入 chunk 2: "tent\":\"你\"}\n\nevent: de"
buffer = "event: delta\ndata: {\"content\":\"你\"}\n\nevent: de"
parts = [
"event: delta\ndata: {\"content\":\"你\"}", ← 完整事件！
"event: de" ← 不完整
]
enqueue: "event: delta\ndata: {\"content\":\"你\"}" ✅
buffer = "event: de"
flush 时:
buffer = "event: de"（如有剩余）
enqueue: "event: de"
6.2 splitPart：键值对解析器 {#splitpart}
function splitPart(partSeparator = '\n', kvSeparator = ':') {
return new TransformStream<string, SSEOutput>({
transform(partChunk, controller) {
// 输入: "event: delta\ndata: {\"content\":\"你好\"}"
const lines = partChunk.split(partSeparator);
const sseEvent = lines.reduce<SSEOutput>((acc, line) => {
const separatorIndex = line.indexOf(kvSeparator); // 找第一个 ':'
if (separatorIndex === -1) return acc;
const key = line.slice(0, separatorIndex).trim();
if (!isValidString(key)) return acc; // 跳过注释行（: 开头）
const value = line.slice(separatorIndex + 1).trim();
return { ...acc, [key]: value };
}, {});
if (Object.keys(sseEvent).length === 0) return;
controller.enqueue(sseEvent);
}
});
}
细节：为什么用 indexOf 而不是 split(':')？
// 假设 data 内容中包含冒号：
const line = 'data: {"url":"https://example.com"}';
// ❌ split(':') 会把 URL 中的冒号也切割
line.split(':') // ['data', ' {"url"', '"https', '//example.com"}']
// ✅ indexOf 只找第一个冒号
const i = line.indexOf(':'); // 4
const key = line.slice(0, 4).trim(); // 'data'
const value = line.slice(5).trim(); // '{"url":"https://example.com"}'
执行过程追踪：
输入: "event: delta\ndata: {\"content\":\"你好\"}"
lines = [
"event: delta",
"data: {\"content\":\"你好\"}"
]
reduce 过程：
line "event: delta":
separatorIndex = 5
key = "event"
value = "delta"
acc = { event: "delta" }
line "data: {\"content\":\"你好\"}":
separatorIndex = 4
key = "data"
value = "{\"content\":\"你好\"}"
acc = { event: "delta", data: "{\"content\":\"你好\"}" }
enqueue: { event: "delta", data: "{\"content\":\"你好\"}" }
6.3 createDecoderStream：兼容性解码器 {#createdecoderstream}
function createDecoderStream() {
// 优先使用原生 API
if (typeof TextDecoderStream !== 'undefined') {
return new TextDecoderStream();
}
// 降级 polyfill：手动实现相同逻辑
const decoder = new TextDecoder('utf-8');
return new TransformStream({
transform(chunk, controller) {
controller.enqueue(decoder.decode(chunk, { stream: true }));
},
flush(controller) {
controller.enqueue(decoder.decode()); // 确保最后字节被正确输出
},
});
}
兼容性说明：
-
TextDecoderStream：Chrome 71+, Firefox 105+, Safari 14.1+
- polyfill：理论上覆盖所有支持
TransformStream 的浏览器
6.4 XStream 主函数 {#xstream-main}
function XStream<Output = SSEOutput>(options: XStreamOptions<Output>) {
const { readableStream, transformStream, streamSeparator, partSeparator, kvSeparator } = options;
const decoderStream = createDecoderStream();
// 构建管道链（两种模式）
const stream = (
transformStream
? // 模式A：自定义 transformStream（用户完全自控解析逻辑）
readableStream
.pipeThrough(decoderStream) // Uint8Array → string
.pipeThrough(transformStream) // string → Output（用户定义）
: // 模式B：默认 SSE 解析（三段式管道）
readableStream
.pipeThrough(decoderStream) // Uint8Array → string
.pipeThrough(splitStream(...)) // string → SSE事件块
.pipeThrough(splitPart(...)) // SSE事件块 → SSEOutput
) as XReadableStream<Output>;
// 给流对象附加 AsyncIterator，让其支持 for await...of
stream[Symbol.asyncIterator] = async function*() {
const reader = this.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (!value) continue;
yield value;
}
};
return stream;
}
自定义 TransformStream 的场景：
// 场景：服务端返回 JSON Lines 格式而非标准 SSE
// {"content":"Hello","type":"text"}\n
// {"content":"World","type":"text"}\n
const jsonLinesTransform = new TransformStream<string, MyOutput>({
transform(chunk, controller) {
// 手动处理每行 JSON
chunk.split('\n').filter(Boolean).forEach(line => {
try {
controller.enqueue(JSON.parse(line));
} catch {}
});
}
});
const stream = XStream({
readableStream: response.body,
transformStream: jsonLinesTransform, // 替换默认的 SSE 解析管道
});
7. 与 上文实现 的对比分析
7.1 架构对比
自己实现 (命令式) XStream (声明式/管道式)
───────────────────────── ──────────────────────────
connectSSE() XStream()
│ │
├─ EventSource (高层API) ├─ ReadableStream (底层)
│ └─ 自动处理SSE协议 │
│ │ .pipeThrough(decoderStream)
└─ connectSSEWithFetch() │ .pipeThrough(splitStream)
│ │ .pipeThrough(splitPart)
├─ fetch() │
├─ createSSELineProcessor() │ for await...of
│ ├─ buffer (闭包) │
│ ├─ decoder (闭包) └─ 返回流对象（延迟消费）
│ ├─ processChunk()
│ └─ flush()
└─ readStream()
7.2 数据处理对比
自己实现（命令式，紧耦合业务逻辑）：
// 解析和业务回调混在一起
const processChunk = (chunk: Uint8Array) => {
buffer += decoder.decode(chunk, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() || '';
for (const line of lines) {
if (!line.trim()) continue;
const data = parseSSELine(line);
if (!data) continue;
if (data.done) {
options.onDone(); // ← 业务逻辑耦合在解析中
return false;
}
options.onChunk(data.content); // ← 业务回调耦合在解析中
}
};
XStream（声明式，关注点分离）：
// splitStream 只关心按 \n\n 分割
new TransformStream({ transform(chunk) { /* 只分割 */ } })
// splitPart 只关心解析键值对
new TransformStream({ transform(chunk) { /* 只解析 */ } })
// 业务逻辑完全在消费侧
for await (const event of stream) {
if (event.data) {
const data = JSON.parse(event.data);
if (data.done) onDone();
else onChunk(data.content);
}
}
7.3 buffer 处理对比
// sse.ts：手动管理 buffer（需要理解流式处理细节）
const createSSELineProcessor = () => {
let buffer = ''; // 跨 chunk 维持
const decoder = new TextDecoder(); // 手动创建
return {
processChunk(chunk: Uint8Array) {
buffer += decoder.decode(chunk, { stream: true }); // 手动解码
const lines = buffer.split('\n');
buffer = lines.pop() || ''; // 手动保留最后行
// ...
},
flush() {
decoder.decode(); // 手动 flush
}
};
};
// XStream：TransformStream 框架自动处理 flush
new TransformStream({
transform(chunk, controller) {
buffer += chunk;
// ...buffer 处理...
},
flush(controller) {
// 框架在流结束时自动调用这个方法，不需要手动触发
if (buffer) controller.enqueue(buffer);
}
});
7.4 主要差异表
| 维度 |
自己实现 |
XStream |
| 设计思想 |
命令式，手动控制流程 |
声明式，管道组合 |
| 关注点分离 |
解析与业务耦合 |
每层只做一件事 |
| 可组合性 |
低，硬编码解析逻辑 |
高，可替换任意管道环节 |
| 可测试性 |
需模拟整个连接 |
每个 TransformStream 可单独测试 |
| 背压处理 |
手动/无 |
pipeThrough 自动处理 |
| 重连逻辑 |
内置 |
不含（需外部处理） |
| 格式灵活性 |
固定 SSE 格式 |
支持自定义 transformStream |
| 学习曲线 |
低，容易理解 |
较高，需理解流 API |
| flush 触发 |
手动调用 |
框架自动调用 |
7.5 联系：相同的核心解题思路
两者都解决了同一个核心问题：TCP 数据包不按照 SSE 事件边界切割。
同一 buffer 策略：
sse.ts: XStream:
───────────────── ─────────────────────────────
buffer = '' let buffer = '' (在 splitStream 中)
buffer += decode(chunk) buffer += streamChunk
lines = buffer.split('\n') parts = buffer.split('\n\n')
buffer = lines.pop() buffer = parts[parts.length - 1]
7.6 结合使用建议
实际上，可以把 XStream 用于 sse.ts 中：
// 用 XStream 替代 createSSELineProcessor
export const connectSSEWithFetch = (message, options) => {
// ... 重连逻辑保留 ...
const connect = async () => {
const response = await fetch(url, { signal: abortController.signal });
// ✅ 用 XStream 处理解析，用 sse.ts 处理重连
const stream = XStream({ readableStream: response.body });
for await (const event of stream) {
if (!event.data) continue;
const data = JSON.parse(event.data);
if (data.done) {
options.onDone();
closeConnection();
break;
}
options.onChunk(data.content);
}
};
};
8. 总结
8.1 流 API 知识体系
浏览器 Streams API 体系：
ReadableStream 可读流（数据来源）
├─ .getReader() 获取 reader（锁定流）
│ ├─ .read() 逐块读取
│ └─ .releaseLock() 释放锁
├─ .pipeThrough(ts) 接入 TransformStream
└─ .pipeTo(ws) 接入 WritableStream
TransformStream<I, O> 转换流（数据中转站）
├─ .readable 可读端（输出侧）
├─ .writable 可写端（输入侧）
└─ new TransformStream({
transform(chunk, ctrl) { ctrl.enqueue(data) }
flush(ctrl) { /* EOF 处理 */ }
})
WritableStream 可写流（数据消费者）
管道链：
ReadableStream
.pipeThrough(TransformStream1) → ReadableStream
.pipeThrough(TransformStream2) → ReadableStream
.pipeTo(WritableStream) → Promise<void>
8.2 XStream 管道链的优雅之处
// 每一层只做一件事，清晰可维护
readableStream // Uint8Array（二进制）
.pipeThrough(createDecoderStream()) // → string（解码）
.pipeThrough(splitStream('\n\n')) // → string（按事件分割）
.pipeThrough(splitPart('\n', ':')) // → SSEOutput（解析键值）
// 想换成 JSON Lines 格式？只替换最后两层
.pipeThrough(jsonLinesTransform)
// 想加压缩？在最前面加一层
readableStream
.pipeThrough(decompressionStream) // → Uint8Array（解压）
.pipeThrough(createDecoderStream())
// ...
8.3 快速参考
// ① 创建最简单的 XStream 消费
const stream = XStream({ readableStream: response.body });
for await (const event of stream) {
console.log(event); // { event: 'delta', data: '...' }
}
// ② 自定义格式
const stream = XStream({
readableStream: response.body,
transformStream: myCustomTransform,
});
// ③ 自定义分隔符
const stream = XStream({
readableStream: response.body,
streamSeparator: '\r\n\r\n', // Windows 换行
kvSeparator: '=', // key=value 格式
});
// ④ 使用 splitStream/splitPart 单独测试
const splitTransform = splitStream('\n\n');
const writer = splitTransform.writable.getWriter();
const reader = splitTransform.readable.getReader();
writer.write("event: test\n\n");
const { value } = await reader.read(); // "event: test"
9. 感想
其实一步步做下来会发现，sse看起来只是一个协议，但是涉及到的前端知识挺多的，从浏览器自己封装的EventSource接口再到自己基于fetch封装更加灵活的接口，再到xStream的源码实现，其中有许多流的相关概念，同时还涉及到了闭包、断连重试等JS基础，总而言之，好好看看还是有不少收获的。
登录