AI SSE 技术文档

UI Message Stream 技术文档

1. 概述

1.1 什么是 UI Message Stream

UI Message Stream 是一个基于 Web Streams API 和 Server-Sent Events (SSE) 的实时消息流处理系统，旨在为服务器到客户端的实时通信提供高效、可靠的解决方案。该系统通过流式传输机制，允许服务器主动向客户端推送 UI 更新，特别适用于需要低延迟、高吞吐量的场景，例如 AI 模型响应流式展示、实时聊天、任务进度更新、多用户协作编辑等。

1.2 核心价值

实时性：通过 SSE 实现服务器主动推送，消除客户端轮询的延迟。
高效性：基于流式数据处理，逐块传输数据，显著降低内存占用。
可靠性：内置完善的错误处理、自动重连和状态恢复机制。
跨平台支持：兼容浏览器和 Node.js 环境，适应多种部署场景。
模块化设计：支持功能扩展和定制，满足不同业务需求。
易用性：提供简洁的 API，降低开发者使用门槛。

1.3 应用场景

AI 模型推理：流式展示大语言模型的生成结果，逐字或逐段更新 UI。
实时聊天系统：支持即时消息传输，适用于社交应用或客服系统。
任务进度更新：实时显示长时间运行任务的进度，如文件上传、数据处理。
多用户协作：支持文档编辑、实时白板等场景的同步更新。
数据监控：构建实时仪表盘，展示服务器监控数据、股票行情等。

1.4 技术背景

UI Message Stream 结合了现代 Web 技术的两大支柱：

Web Streams API：提供高效的流式数据处理能力，允许开发者以声明式方式操作数据流。
Server-Sent Events (SSE) ：基于 HTTP 协议的单向推送技术，简化服务器到客户端的实时通信。

2. 核心功能详解

2.1 消息流创建与管理

流初始化 ：通过 ReadableStream 创建可读流，配合控制器管理消息生成和推送。
消息写入 ：提供 safeEnqueue 方法，确保在流关闭或错误时不会引发异常。
流合并：支持将多个子流合并为单一输出流，适合多源数据聚合。
错误处理：捕获同步和异步错误，转换为结构化消息，保持流稳定性。
生命周期管理 ：通过 Promise 管理异步操作，确保流正确关闭并释放资源。

2.2 JSON 到 SSE 格式转换

数据格式化：将任意 JSON 对象转换为符合 SSE 规范的字符串格式。
分隔符处理 ：使用双换行符 \n\n 分隔消息，确保客户端正确解析。
结束信号 ：流结束时发送 [DONE] 标记，通知客户端流已完成。
字符编码 ：通过 TextEncoderStream 处理特殊字符，确保数据完整性。

2.3 响应构建与处理

跨环境支持 ：兼容浏览器环境（Response）和 Node.js 环境（ServerResponse）。
响应头管理 ：自动设置 SSE 所需的 Content-Type: text/event-stream 等头部。
流分支 ：通过 tee() 方法支持流的并行消费，例如同时用于响应和日志记录。
内容编码 ：使用 TextEncoderStream 将字符串流转换为二进制流，符合 HTTP 响应要求。

2.4 消息 ID 管理与状态跟踪

消息 ID 生成：为每条消息生成唯一标识符，确保消息追踪和恢复。
ID 注入：在流处理过程中动态注入消息 ID，保持数据一致性。
状态跟踪：记录消息状态（如新消息、续传消息），支持断点续传。
完成回调：流结束时提供完整的消息列表，便于持久化或分析。

2.5 扩展功能

自定义事件 ：支持 SSE 的 event 字段，允许定义特定类型的事件（如 progress、error）。
重连机制 ：通过 Last-Event-ID 实现断点续传，增强用户体验。
流压缩：支持 gzip 压缩，降低带宽占用（需客户端支持）。
异步任务支持 ：通过 Promise 和 async/await 管理复杂的异步流操作。

3. 模块架构与实现

3.1 模块关系图

lua 复制代码

+---------------------------+
| create-ui-message-stream  | ← 核心流创建与管理
+-------------+-------------+
              |
              ↓
+---------------------------+
| handle-ui-message-stream- | ← 消息 ID 注入与状态管理
| finish                    |
+-------------+-------------+
              |
              ↓
+---------------------------+
| JsonToSseTransformStream  | ← JSON 到 SSE 格式转换
+-------------+-------------+
              |
              ↓
+-------------+-------------+    +---------------------------+
| create-ui-message-stream- |    | pipe-ui-message-stream-to-|
| response                  |    | response                  |
+-------------+-------------+    +-------------+-------------+
              |                                  |
              ↓                                  ↓
     +------------------+              +------------------+
     | 浏览器环境 (Response) |              | Node.js 环境 (ServerResponse) |
     +------------------+              +------------------+

3.2 JsonToSseTransformStream

文件路径 : d:/ai/packages/ai/src/ui-message-stream/json-to-sse-transform-stream.ts

功能描述

JsonToSseTransformStream 将 JSON 数据转换为 SSE 格式，确保数据符合协议规范。

完整代码实现

typescript 复制代码

export class JsonToSseTransformStream extends TransformStream<unknown, string> {
  constructor() {
    super({
      transform(part, controller) {
        try {
          const serialized = JSON.stringify(part);
          controller.enqueue(`data: ${serialized}\n\n`);
        } catch (error) {
          controller.enqueue(`event: error\ndata: ${JSON.stringify({ error: 'Serialization failed', message: error.message })}\n\n`);
        }
      },
      flush(controller) {
        controller.enqueue('data: [DONE]\n\n');
      },
    });
  }
}

代码解析

继承 TransformStream：输入为任意类型，输出为字符串。
transform 方法：序列化 JSON 数据，添加 SSE 格式前缀和分隔符。
错误处理：捕获序列化错误，发送错误事件。
flush 方法 ：发送 [DONE] 标记通知流结束。

3.3 createUIMessageStream

文件路径 : d:/ai/packages/ai/src/ui-message-stream/create-ui-message-stream.ts

功能描述

createUIMessageStream 创建和管理消息流，负责初始化、写入、合并和生命周期管理。

完整代码实现

typescript 复制代码

import { InferUIMessageStreamPart } from './types';

export function createUIMessageStream<UI_MESSAGE>({
  execute,
  onError,
  onFinish,
}: {
  execute: (params: { writer: { write: (data: InferUIMessageStreamPart<UI_MESSAGE>) => void; merge: (stream: ReadableStream) => void }) => Promise<void>;
  onError: (error: unknown) => string;
  onFinish?: (result: { messages: UI_MESSAGE[] }) => void;
}) {
  let controller: ReadableStreamDefaultController;
  const ongoingStreamPromises: Promise<void>[] = [];

  const stream = new ReadableStream({
    start(controllerArg) {
      controller = controllerArg;
    },
  });

  function safeEnqueue(data: InferUIMessageStreamPart<UI_MESSAGE>) {
    try {
      if (controller.desiredSize === null) return;
      controller.enqueue(data);
    } catch (error) {
      console.warn('Stream closed or errored:', error);
    }
  }

  function merge(streamArg: ReadableStream) {
    ongoingStreamPromises.push(
      (async () => {
        const reader = streamArg.getReader();
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          safeEnqueue(value);
        }
      })().catch(error => {
        safeEnqueue({
          type: 'error',
          errorText: onError(error),
        } as InferUIMessageStreamPart<UI_MESSAGE>);
      }),
    );
  }

  const waitForStreams: Promise<void> = new Promise(async resolve => {
    await execute({ writer: { write: safeEnqueue, merge } });
    while (ongoingStreamPromises.length > 0) {
      await ongoingStreamPromises.shift();
    }
    resolve();
  });

  waitForStreams.finally(() => {
    try {
      controller.close();
    } catch (error) {
      console.warn('Error closing stream:', error);
    }
    if (onFinish) {
      onFinish({ messages: [] }); // 简化示例，实际应收集所有消息
    }
  });

  return stream;
}

3.4 createUIMessageStreamResponse

文件路径 : d:/ai/packages/ai/src/ui-message-stream/create-ui-message-stream-response.ts

功能描述

为浏览器环境创建 SSE 响应，处理流转换和响应头。

完整代码实现

typescript 复制代码

import { JsonToSseTransformStream } from './json-to-sse-transform-stream';

export interface UIMessageStreamResponseInit {
  status?: number;
  statusText?: string;
  headers?: HeadersInit;
  consumeSseStream?: (params: { stream: ReadableStream }) => void;
}

export function createUIMessageStreamResponse({
  status = 200,
  statusText = 'OK',
  headers,
  stream,
  consumeSseStream,
}: UIMessageStreamResponseInit & { stream: ReadableStream<any> }): Response {
  let sseStream = stream.pipeThrough(new JsonToSseTransformStream());

  if (consumeSseStream) {
    const [stream1, stream2] = sseStream.tee();
    sseStream = stream1;
    consumeSseStream({ stream: stream2 });
  }

  const responseHeaders = new Headers(headers);
  responseHeaders.set('Content-Type', 'text/event-stream');
  responseHeaders.set('Cache-Control', 'no-cache');
  responseHeaders.set('Connection', 'keep-alive');

  return new Response(sseStream.pipeThrough(new TextEncoderStream()), {
    status,
    statusText,
    headers: responseHeaders,
  });
}

3.5 pipeUIMessageStreamToResponse

文件路径 : d:/ai/packages/ai/src/ui-message-stream/pipe-ui-message-stream-to-response.ts

功能描述

为 Node.js 环境处理 SSE 响应，将流数据写入 ServerResponse。

完整代码实现

typescript 复制代码

import { ServerResponse } from 'http';
import { JsonToSseTransformStream } from './json-to-sse-transform-stream';

export interface UIMessageStreamResponseInit {
  status?: number;
  statusText?: string;
  headers?: Record<string, string>;
  consumeSseStream?: (params: { stream: ReadableStream }) => void;
}

export function pipeUIMessageStreamToResponse({
  response,
  status = 200,
  statusText = 'OK',
  headers = {},
  stream,
  consumeSseStream,
}: { response: ServerResponse; stream: ReadableStream<any> } & UIMessageStreamResponseInit): void {
  let sseStream = stream.pipeThrough(new JsonToSseTransformStream());

  if (consumeSseStream) {
    const [stream1, stream2] = sseStream.tee();
    sseStream = stream1;
    consumeSseStream({ stream: stream2 });
  }

  response.writeStatusCode = status;
  response.statusMessage = statusText;
  response.setHeader('Content-Type', 'text/event-stream');
  response.setHeader('Cache-Control', 'no-cache');
  response.setHeader('Connection', 'keep-alive');
  Object.entries(headers).forEach(([key, value]) => response.setHeader(key, value));

  const reader = sseStream.pipeThrough(new TextEncoderStream()).getReader();
  (async () => {
    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        response.end();
        break;
      }
      response.write(value);
    }
  })();
}

3.6 handleUIMessageStreamFinish

文件路径 : d:/ai/packages/ai/src/ui-message-stream/handle-ui-message-stream-finish.ts

功能描述

处理消息流完成阶段，包括消息 ID 注入和状态管理。

完整代码实现

ini 复制代码

import { TransformStream } from 'stream/web';

export function handleUIMessageStreamFinish<UI_MESSAGE>({
  stream,
  messageId,
  lastMessage,
  originalMessages,
  onFinish,
}: {
  stream: ReadableStream;
  messageId: string;
  lastMessage?: UI_MESSAGE;
  originalMessages: UI_MESSAGE[];
  onFinish: (result: { isContinuation: boolean; responseMessage: UI_MESSAGE; messages: UI_MESSAGE[] }) => void;
}): ReadableStream {
  const state = { message: {} as UI_MESSAGE };

  return stream.pipeThrough(
    new TransformStream({
      transform(chunk, controller) {
        if (chunk.type === 'start' && chunk.messageId == null) {
          chunk.messageId = messageId;
        }
        controller.enqueue(chunk);
      },
      flush() {
        const isContinuation = state.message.id === lastMessage?.id;
        onFinish({
          isContinuation,
          responseMessage: state.message,
          messages: [
            ...(isContinuation ? originalMessages.slice(0, -1) : originalMessages),
            state.message,
          ],
        });
      },
    }),
  );
}

4. 技术原理深度解析

4.1 Web Streams API 详解

Web Streams API 提供高效的流式数据处理能力，适合处理大文件、实时数据等。

4.1.1 核心流类型

ReadableStream：数据生产者。
WritableStream：数据消费者。
TransformStream：数据转换器。

4.1.2 背压管理

通过 desiredSize 和 pull 方法协调生产者和消费者速度。

4.1.3 流操作

管道：pipeTo 和 pipeThrough 连接流。
分支：tee() 创建流的两个副本。
取消/关闭 ：cancel 和 close 管理流生命周期。

4.1.4 使用示例

javascript 复制代码

const readable = new ReadableStream({
  start(controller) {
    controller.enqueue('Hello');
    controller.enqueue('World');
    controller.close();
  },
});

const writable = new WritableStream({
  write(chunk) {
    console.log(chunk);
  },
});

readable.pipeTo(writable); // 输出: Hello, World

4.2 Server-Sent Events (SSE) 协议

SSE 是基于 HTTP 的单向推送技术，适合实时更新场景。

4.2.1 协议规范

MIME 类型 ：text/event-stream。
消息格式 ：支持 data、event、id 和 retry 字段。
重连机制 ：通过 Last-Event-ID 实现断点续传。

4.2.2 客户端 API

EventSource 用于接收 SSE 消息：

ini 复制代码

const es = new EventSource('/stream');
es.onmessage = (event) => console.log(event.data);
es.onerror = () => console.log('错误');

4.3 Node.js Streams 详解

Node.js Streams 是 Node.js 核心模块之一，用于处理流式数据，特别适合处理大文件、网络请求和实时数据传输。Node.js Streams 与 Web Streams API 不同，主要基于事件驱动模型，提供更细粒度的控制，广泛应用于服务器端开发。

4.3.1 核心流类型

Node.js Streams 分为四种类型：

Readable：数据生产者，如读取文件或网络请求响应。
Writable：数据消费者，如写入文件或 HTTP 响应。
Duplex：同时可读可写的流，如 TCP 套接字。
Transform：在读写过程中转换数据的流，如压缩或加密。

4.3.2 流的工作模式

Node.js Streams 支持两种模式：

流动模式 (Flowing) ：数据自动从源头流向消费者，通过事件监听（如 data 事件）处理。
暂停模式 (Paused) ：需要显式调用 read() 方法获取数据，适合背压管理。

4.3.3 常用方法与事件

以下是 Node.js Streams 的常用方法和事件，分为 Readable、Writable 和 Transform 流：

4.3.3.1 Readable Stream

方法：
- stream.read([size])：从流中读取指定大小的数据，返回 Buffer 或字符串。
- stream.pipe(destination, [options])：将可读流管道传输到可写流。
- stream.unpipe([destination])：取消管道传输。
- stream.pause()：暂停数据流动，切换到暂停模式。
- stream.resume()：恢复数据流动，切换到流动模式。
- stream.setEncoding(encoding)：设置数据编码（如 'utf8'），返回字符串而非 Buffer。
- stream.on(event, callback)：监听流事件。
事件：
- data：当有新数据可用时触发（流动模式）。
- readable：当流有数据可读时触发（暂停模式）。
- end：流数据读取完成时触发。
- error：流发生错误时触发。
- close：流关闭时触发。

示例：读取文件流

javascript 复制代码

const fs = require('fs');

const readableStream = fs.createReadStream('example.txt', { encoding: 'utf8' });

// 流动模式
readableStream.on('data', (chunk) => {
  console.log('收到数据块:', chunk);
});

readableStream.on('end', () => {
  console.log('读取完成');
});

readableStream.on('error', (error) => {
  console.error('流错误:', error.message);
});

// 暂停模式
readableStream.pause();
readableStream.on('readable', () => {
  let chunk;
  while ((chunk = readableStream.read()) !== null) {
    console.log('读取数据块:', chunk);
  }
});

注释：

createReadStream 创建一个读取文件的 Readable Stream。
on('data') 在流动模式下处理数据块。
pause() 和 readable 事件用于暂停模式，显式读取数据。
on('error') 捕获文件读取错误（如文件不存在）。

4.3.3.2 Writable Stream

方法：
- stream.write(chunk, [encoding], [callback])：写入数据块。
- stream.end([chunk], [encoding], [callback])：结束流并可选写入最后数据。
- stream.cork()：缓冲写入数据，直到 uncork() 或 end()。
- stream.uncork()：刷新缓冲区，写入所有缓冲数据。
- stream.setDefaultEncoding(encoding)：设置默认编码。
事件：
- drain：当流可以接受更多数据时触发（背压缓解）。
- finish：流写入完成且调用 end() 后触发。
- error：写入错误时触发。
- close：流关闭时触发。

示例：写入文件流

javascript 复制代码

const fs = require('fs');

const writableStream = fs.createWriteStream('output.txt');

writableStream.write('你好, ');
writableStream.write('世界!\n', 'utf8', () => {
  console.log('数据块已写入');
});

writableStream.end(() => {
  console.log('写入完成');
});

writableStream.on('error', (error) => {
  console.error('写入错误:', error.message);
});

writableStream.on('finish', () => {
  console.log('流已完成');
});

注释：

createWriteStream 创建一个写入文件的 Writable Stream。
write 写入数据块，可指定编码和回调。
end 结束流，触发 finish 事件。
on('error') 捕获写入错误（如磁盘满）。

4.3.3.3 Transform Stream

方法：
- stream.transform(chunk, encoding, callback)：转换数据块。
- stream.flush(callback)：流结束时执行清理操作。
- 继承 Readable 和 Writable 流的方法。
事件：与 Readable 和 Writable 流的事件相同。

示例：创建转换流

scss 复制代码

const { Transform } = require('stream');

const upperCaseTransform = new Transform({
  transform(chunk, encoding, callback) {
    // 将输入数据转换为大写
    this.push(chunk.toString().toUpperCase());
    callback();
  },
});

process.stdin
  .pipe(upperCaseTransform)
  .pipe(process.stdout);

注释：

Transform 继承 Readable 和 Writable，适合数据转换。
transform 方法处理每个数据块，调用 push 输出转换后的数据。
pipe 连接标准输入、转换流和标准输出，实现实时大写转换。

4.3.3.4 Duplex Stream

特性：同时支持 Readable 和 Writable 接口。
示例：TCP 套接字（net.Socket）是典型的 Duplex 流。

示例：TCP 服务器

ini 复制代码

const net = require('net');

const server = net.createServer((socket) => {
  socket.write('回显服务器\r\n');
  socket.pipe(socket); // 回显客户端发送的数据
});

server.listen(1337, '127.0.0.1');

注释：

socket 是一个 Duplex 流，可同时读写。
pipe(socket) 将客户端发送的数据回显回去。

4.3.4 背压管理

Node.js Streams 自动管理背压：

write() 返回 false 表示缓冲区满，触发背压。
等待 drain 事件后再继续写入。

示例：处理背压

ini 复制代码

const fs = require('fs');

const readable = fs.createReadStream('input.txt');
const writable = fs.createWriteStream('output.txt');

readable.on('data', (chunk) => {
  if (!writable.write(chunk)) {
    readable.pause(); // 暂停读取
  }
});

writable.on('drain', () => {
  readable.resume(); // 恢复读取
});

readable.on('end', () => {
  writable.end();
});

注释：

write 返回 false 时暂停读取，防止内存溢出。
drain 事件表示缓冲区清空，可继续写入。

4.3.5 管道操作

pipe 方法是 Node.js Streams 的核心功能，简化流连接：

ini 复制代码

const fs = require('fs');
const zlib = require('zlib');

fs.createReadStream('input.txt')
  .pipe(zlib.createGzip()) // 压缩
  .pipe(fs.createWriteStream('output.txt.gz'));

注释：

pipe 连接 Readable、Transform 和 Writable 流。
自动处理背压和错误传播。

4.3.6 错误处理

Node.js Streams 通过 error 事件捕获错误：

javascript 复制代码

const fs = require('fs');

const stream = fs.createReadStream('nonexistent.txt');
stream.on('error', (error) => {
  console.error('流错误:', error.message); // 捕获文件不存在错误
});

4.3.7 流的高级操作

自定义流 ：通过继承 stream.Readable、stream.Writable 等创建自定义流。
流组合 ：使用 pipeline 方法简化多流连接并处理错误。

javascript 复制代码

const { pipeline } = require('stream');
const fs = require('fs');
const zlib = require('zlib');

pipeline(
  fs.createReadStream('input.txt'),
  zlib.createGzip(),
  fs.createWriteStream('output.txt.gz'),
  (error) => {
    if (error) {
      console.error('管道失败:', error);
    } else {
      console.log('管道成功');
    }
  }
);

注释：

pipeline 确保所有流正确关闭，简化错误处理。

4.3.8 集成到 UI Message Stream

在 UI Message Stream 中，Node.js Streams 用于 pipeUIMessageStreamToResponse 将数据写入 ServerResponse：

javascript 复制代码

const { pipeline } = require('stream');
const { ServerResponse } = require('http');

function pipeUIMessageStreamToResponse({ response, stream }) {
  const reader = stream.pipeThrough(new JsonToSseTransformStream()).getReader();
  pipeline(
    {
      [Symbol.asyncIterator]: async function* () {
        while (true) {
          const { done, value } = await reader.read();
          if (done) break;
          yield value;
        }
      },
    },
    response,
    (error) => {
      if (error) console.error('流管道错误:', error);
      response.end();
    }
  );
}

注释：

使用异步迭代器将 Web Stream 转换为 Node.js Stream。
使用 pipeline 处理数据传输和清理。

4.3.9 最佳实践

始终处理 error 事件以防止崩溃。
使用 pipeline 处理复杂流链。
通过 drain 事件监控背压。
使用 end() 或 destroy() 显式关闭流。

4.4 Node.js 与 Web 流适配

差异：Node.js 流基于事件，Web 流基于 Promise。
适配：
- 使用 ReadableStream.from 将 Node.js Readable 转换为 Web ReadableStream。
- 使用 TextEncoderStream/TextDecoderStream 处理编码兼容性。
- 示例：

ini 复制代码

const { Readable } = require('stream');
const nodeStream = Readable.from(['data1', 'data2']);
const webStream = ReadableStream.from(nodeStream);

4.5 错误与恢复机制

错误捕获：通过 try/catch 和 Promise.catch。
重连：结合 SSE retry 字段与指数退避。

5. 使用指南

5.1 基本使用流程

5.1.1 创建消息流

javascript 复制代码

import { createUIMessageStream } from './create-ui-message-stream';

const stream = createUIMessageStream({
  async execute({ writer }) {
    writer.write({ type: 'start', messageId: 'msg-123' });
    await new Promise(resolve => setTimeout(resolve, 1000));
    writer.write({ type: 'content', text: 'Hello, World!' });
  },
  onError: (error) => `错误: ${error.message}`,
  onFinish: ({ messages }) => console.log('消息:', messages),
});

5.1.2 浏览器环境响应

csharp 复制代码

import { createUIMessageStreamResponse } from './create-ui-message-stream-response';

self.addEventListener('fetch', (event) => {
  if (event.request.url.endsWith('/stream')) {
    event.respondWith(
      createUIMessageStreamResponse({
        stream: createUIMessageStream(/* 配置 */),
        status: 200,
      }),
    );
  }
});

5.1.3 Node.js 环境响应

javascript 复制代码

import { createServer } from 'http';
import { pipeUIMessageStreamToResponse } from './pipe-ui-message-stream-to-response';

createServer((req, res) => {
  if (req.url === '/stream') {
    pipeUIMessageStreamToResponse({
      response: res,
      stream: createUIMessageStream(/* 配置 */),
      status: 200,
    });
  }
}).listen(3000);

5.2 客户端实现

5.2.1 原生 EventSource

ini 复制代码

const es = new EventSource('/stream');
es.onmessage = (event) => {
  if (event.data === '[DONE]') {
    es.close();
    return;
  }
  console.log('消息:', JSON.parse(event.data));
};
es.onerror = () => setTimeout(() => new EventSource('/stream'), 3000);

5.2.2 React 组件

javascript 复制代码

import { useEffect, useState } from 'react';

function StreamComponent() {
  const [messages, setMessages] = useState([]);
  useEffect(() => {
    const es = new EventSource('/stream');
    es.onmessage = (event) => {
      if (event.data === '[DONE]') {
        es.close();
        return;
      }
      setMessages((prev) => [...prev, JSON.parse(event.data)]);
    };
    es.onerror = () => setTimeout(() => new EventSource('/stream'), 3000);
    return () => es.close();
  }, []);
  return (
    <div>
      {messages.map((msg, i) => (
        <p key={i}>{JSON.stringify(msg)}</p>
      ))}
    </div>
  );
}

6. 常见问题与解决方案

6.1 流数据不完整或中断

问题描述 ：客户端接收到的消息流不完整，数据提前中断。
解决方案：

背压管理：

kotlin 复制代码

function safeEnqueue<T>(controller: ReadableStreamDefaultController, data: T): boolean {
  if (controller.desiredSize === null || controller.desiredSize <= 0) {
    console.warn('检测到背压或流已关闭');
    return false;
  }
  try {
    controller.enqueue(data);
    return true;
  } catch (error) {
    console.error('无法写入数据:', error);
    return false;
  }
}

注释：检查 desiredSize 以管理背压。

指数退避重连：

ini 复制代码

function connectWithRetry(streamUrl, maxAttempts = 5) {
  let attempts = 0;
  let lastEventId = '';
  function attemptConnect() {
    const es = new EventSource(`${streamUrl}?lastEventId=${lastEventId}`);
    es.onmessage = (event) => {
      lastEventId = event.lastEventId;
      console.log('收到:', JSON.parse(event.data));
    };
    es.onerror = () => {
      es.close();
      if (attempts < maxAttempts) {
        const delay = Math.min(1000 * Math.pow(2, attempts), 30000);
        setTimeout(attemptConnect, delay);
        attempts++;
      }
    };
  }
  attemptConnect();
}

心跳机制：

javascript 复制代码

import { ServerResponse } from 'http';
function setupHeartbeat(response: ServerResponse, intervalMs = 15000) {
  const heartbeat = setInterval(() => {
    if (response.writableEnded) {
      clearInterval(heartbeat);
      return;
    }
    response.write(': ping\n\n');
  }, intervalMs);
  response.on('close', () => clearInterval(heartbeat));
}

6.2 内存泄漏

问题描述 ：长时间运行导致内存占用增加。
解决方案：

清理流资源：

ini 复制代码

useEffect(() => {
  const es = new EventSource('/stream');
  return () => es.close();
}, []);

避免大对象引用：

ini 复制代码

const stream = new ReadableStream({
  transform(chunk, controller) {
    const tempObject = getLargeObject();
    controller.enqueue(process(chunk, tempObject));
  },
});

监控流状态：

javascript 复制代码

function monitorStream(stream: ReadableStream, maxQueueSize = 100) {
  const reader = stream.getReader();
  let queueSize = 0;
  async function monitor() {
    while (true) {
      const { done } = await reader.read();
      if (done) break;
      queueSize++;
      if (queueSize > maxQueueSize) {
        await new Promise(resolve => setTimeout(resolve, 500));
      }
    }
  }
  monitor().catch(error => console.error('流监控失败:', error));
}

6.3 跨域问题

问题描述 ：客户端收到 CORS 错误。
解决方案：

服务器端 CORS：

lua 复制代码

app.use((req, res, next) => {
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  res.setHeader('Access-Control-Allow-Credentials', 'true');
  if (req.method === 'OPTIONS') res.status(200).end();
  else next();
});

客户端 withCredentials：

ini 复制代码

const es = new EventSource('/stream', { withCredentials: true });

6.4 浏览器连接限制

问题描述 ：浏览器并发连接限制导致阻塞。
解决方案：

域名分片：

ini 复制代码

const subdomains = ['stream1.example.com', 'stream2.example.com'];
const streamUrl = `https://${subdomains[Math.floor(Math.random() * subdomains.length)]}/stream`;
const es = new EventSource(streamUrl);

连接池：

kotlin 复制代码

class ConnectionPool {
  private connections: EventSource[] = [];
  private maxConnections = 3;
  addConnection(url: string): EventSource | null {
    if (this.connections.length >= this.maxConnections) return null;
    const es = new EventSource(url);
    this.connections.push(es);
    es.onclose = () => {
      this.connections = this.connections.filter(c => c !== es);
    };
    return es;
  }
  closeAll() {
    this.connections.forEach(es => es.close());
    this.connections = [];
  }
}

WebSocket 替代：

ini 复制代码

const ws = new WebSocket('wss://example.com/stream');
ws.onmessage = (event) => console.log('收到:', event.data);

6.5 消息解析失败

问题描述 ：客户端无法解析 SSE 消息。
解决方案：

服务器端 JSON 验证：

typescript 复制代码

function safeStringify(data: any): string {
  try {
    JSON.stringify(data);
    return `data: ${JSON.stringify(data)}\n\n`;
  } catch (error) {
    return `event: error\ndata: ${JSON.stringify({ error: '无效 JSON', message: error.message })}\n\n`;
  }
}

客户端多行数据处理：

ini 复制代码

const es = new EventSource('/stream');
let buffer = '';
es.onmessage = (event) => {
  buffer += event.data;
  if (buffer.endsWith('\n\n')) {
    const messages = buffer.split('\n\n').filter(m => m.startsWith('data:'));
    for (const msg of messages) {
      const data = msg.replace(/^data:\s*/, '');
      if (data) console.log('解析:', JSON.parse(data));
    }
    buffer = '';
  }
};

6.6 流处理性能瓶颈

问题描述 ：流处理速度慢，导致延迟。
解决方案：

优化数据块大小：

ini 复制代码

const stream = new ReadableStream({
  async start(controller) {
    const largeData = generateLargeData();
    const chunkSize = 1024;
    for (let i = 0; i < largeData.length; i += chunkSize) {
      controller.enqueue({ type: 'content', data: largeData.slice(i, i + chunkSize) });
      await new Promise(resolve => setTimeout(resolve, 10));
    }
    controller.close();
  },
});

客户端批量渲染：

ini 复制代码

function StreamComponent() {
  const [messages, setMessages] = useState([]);
  const batch = useRef([]);
  useEffect(() => {
    const es = new EventSource('/stream');
    const batchInterval = setInterval(() => {
      if (batch.current.length > 0) {
        setMessages((prev) => [...prev, ...batch.current]);
        batch.current = [];
      }
    }, 100);
    es.onmessage = (event) => {
      if (event.data === '[DONE]') {
        es.close();
        clearInterval(batchInterval);
        return;
      }
      batch.current.push(JSON.parse(event.data));
    };
    return () => {
      es.close();
      clearInterval(batchInterval);
    };
  }, []);
  return (
    <div>
      {messages.map((msg, i) => (
        <p key={i}>{JSON.stringify(msg)}</p>
      ))}
    </div>
  );
}

7. 性能优化建议

7.1 数据分块策略

块大小：1KB-4KB，平衡网络效率和处理速度。
批处理：合并小消息，减少传输次数。
动态调整：根据网络状况调整块大小。

7.2 背压优化

监控 desiredSize，在队列满时暂停生产者。
设置合理的 highWaterMark。
使用异步 pull 方法响应消费者需求。

7.3 服务器优化

使用集群模式利用多核 CPU。
实现连接复用。
设置空闲连接超时。
集成监控工具（如 Prometheus）。

7.4 客户端优化

批量更新 UI，减少重绘。
缓存已接收消息。
实现指数退避重连。

8. 未来发展与扩展

8.1 功能扩展

多协议支持：支持 WebSocket 和 gRPC。
消息优先级：为消息分配优先级。
数据压缩：集成 Brotli 压缩。
流加密：支持端到端加密。

8.2 性能提升

并行处理：使用 Web Workers 进行流处理。
流分区：按主题或用户分区流。
动态背压：根据客户端性能调整背压。

8.3 生态集成

框架支持：为 React、Vue、Angular 提供钩子。
监控集成：与 Sentry 集成以报告错误。
测试工具：开发流模拟器以便测试。

9. 总结

UI Message Stream 结合 Web Streams API 和 SSE 协议，提供高效、可靠的实时通信解决方案。通过集成 Node.js Streams，利用事件驱动的流处理提升服务器端效率。其模块化设计、跨平台支持和完善的错误处理使其适用于多种实时应用场景。开发者可以通过优化和扩展功能进一步提升性能和用户体验。

AI SSE 技术文档

UI Message Stream 技术文档

目录

1. 概述

1.1 什么是 UI Message Stream

1.2 核心价值

1.3 应用场景

1.4 技术背景

2. 核心功能详解

2.1 消息流创建与管理

2.2 JSON 到 SSE 格式转换

2.3 响应构建与处理

2.4 消息 ID 管理与状态跟踪

2.5 扩展功能

3. 模块架构与实现

3.1 模块关系图

3.2 JsonToSseTransformStream

功能描述

完整代码实现

代码解析

3.3 createUIMessageStream

功能描述

完整代码实现

3.4 createUIMessageStreamResponse

功能描述

完整代码实现

3.5 pipeUIMessageStreamToResponse

功能描述

完整代码实现

3.6 handleUIMessageStreamFinish

功能描述

完整代码实现

4. 技术原理深度解析

4.1 Web Streams API 详解

4.1.1 核心流类型

4.1.2 背压管理

4.1.3 流操作

4.1.4 使用示例

4.2 Server-Sent Events (SSE) 协议

4.2.1 协议规范

4.2.2 客户端 API

4.3 Node.js Streams 详解

4.3.1 核心流类型

4.3.2 流的工作模式

4.3.3 常用方法与事件

4.3.3.1 Readable Stream

4.3.3.2 Writable Stream

4.3.3.3 Transform Stream

4.3.3.4 Duplex Stream

4.3.4 背压管理

4.3.5 管道操作

4.3.6 错误处理

4.3.7 流的高级操作

4.3.8 集成到 UI Message Stream

4.3.9 最佳实践

4.4 Node.js 与 Web 流适配

4.5 错误与恢复机制

5. 使用指南

5.1 基本使用流程

5.1.1 创建消息流

5.1.2 浏览器环境响应

5.1.3 Node.js 环境响应

5.2 客户端实现

5.2.1 原生 EventSource

5.2.2 React 组件

6. 常见问题与解决方案

6.1 流数据不完整或中断

6.2 内存泄漏

6.3 跨域问题

6.4 浏览器连接限制

6.5 消息解析失败

6.6 流处理性能瓶颈

7. 性能优化建议

7.1 数据分块策略

7.2 背压优化

7.3 服务器优化

7.4 客户端优化

8. 未来发展与扩展

8.1 功能扩展

8.2 性能提升