W2. 流式解析工程化

28 阅读23分钟

前言

W1. 从一个简单的Chat Demo开始

上一章节中我们跑通了一个最基本的Chat Demo,学习了流式解析。但是存在几大不足,是完全不能用到生产的:

  • 不可测试:解析逻辑与 React UI 强耦合,无法针对粘包、半包等边界场景进行 TDD 验证。
  • 无法跨项目复用:在 Node CLI、Electron、Web Worker 中使用需要反复拷贝粘贴。
  • 渲染性能粗放:逐 token 同步 setState,长文本生成时造成严重的 DOM 掉帧卡顿。
  • 厂商协议锁死:硬编码 OpenAI 数据结构,遇到 Anthropic Claude(或者自定义 SSE event 类型)、通义千问原生流时无法解析。
  • 缺乏网络弹性:缺少指数退避重试与平滑的中止控制。

所以在 W2 中我们要实现一个基于现代 Web Streams API(TransformStream / ReadableStream)构建的零第三方运行时依赖的流式 SSE 解析与 Token 调度工具库。

代码库地址:github.com/yuhano1937-…

进阶知识点

在 W1 中我们学习了部分基础的知识点,现在我们需要学习进阶的一些知识点,并在本章的实战项目中运用。

Web Streams API

Web Streams 是浏览器和 Node.js (v18+) 内置的流处理 API,包含三大件:ReadableStream(可读流)、WritableStream(可写流)、TransformStream(转换流)。在 W1 里只用了 ReadableStream.getReader(),这只是冰山一角,我们要深度掌握。为什么要深入学?  因为生产级的流式处理不是"读一个流然后 split"这么简单。需要理解:

  • 背压:当前端处理不过来时,如何让上游慢下来?比如用户切到后台 tab 了,你还在疯狂读流,内存就会爆。ReadableStream 的 pull 模式天然支持背压,你不读,它就不拉。但你得理解这个机制才能正确使用。
  • 管道 :readableStream.pipeThrough(transformStream).pipeTo(writableStream) 是 Streams API 最优雅的用法。你可以把"字节解码"、"SSE 切分"、"JSON 解析"、"token 攒批"分别做成 TransformStream,然后像乐高一样拼起来。每个环节可独立测试。
  • 分叉 :readableStream.tee() 可以把一个流分成两个。用途:一个交给 UI 渲染,一个交给日志系统记录原始数据。这在生产中很常见——出了 bug 你需要回放原始流来排查。
  • 内存管理:长对话的流可能持续几分钟,中间会积累大量的字符串拼接。你需要了解 TextDecoder 的 stream: true 选项为什么是必须的,以及何时该手动 release reader。
  • 取消传播:当你 reader.cancel() 时,取消信号如何沿着管道链向上游传播?每个 TransformStream 的 cancel 回调都会被依次调用。这和 AbortController 的 signal 传播机制互补。

SSE 协议精确解析

Server-Sent Events(SSE)是一个 HTML 标准协议,定义在 WHATWG 的 EventSource 规范中,规范的地址为:html.spec.whatwg.org/multipage/s…。它规定了事件的格式:每个事件由若干 field: value 行组成,事件之间用空行(\n\n)分隔。

为什么说上一章我们实现的SSE解析是不完善的?  因为只处理了 data: 字段,忽略了很多边界:

被忽略的细节正确行为错误处理的后果
多行 data:多行 data 用 \n 拼接成完整数据丢失数据
event: 字段指定事件类型,比如 Claude API 用了自定义事件类型无法解析 Claude 的流
id: 字段事件 ID,断线重连时发 Last-Event-ID无法实现断点续传
retry: 字段重连等待时间(毫秒)硬编码重连间隔
: 开头的注释行忽略(用作心跳)可能触发 JSON.parse 报错
BOM流首字节可能是 UTF-8 BOM 0xEF 0xBB 0xBF第一个事件解析失败
\r、\r\n、\n 三种换行都要识别为行终止符Windows 服务器下解析失败
data: 后无空格data:hello 和 data: hello 都合法,取值为 hello解析结果多一个前导空格

多协议适配架构

不同模型提供商返回的 SSE 内容格式差异很大。核心思路是将"SSE 字节流解析"和"业务语义提取"分成两层,底层的 SSE 解析只写一遍,上层通过可插拔的 Adapter 提取不同格式的业务数据。

在真实的生产环境中,大模型的流式输出格式主要分为三大阵营:OpenAI 兼容阵营(主流)、独立协议阵营(海外巨头为主)以及双轨制阵营(国内早期遗留)。

以下是以流式输出一个字 "你" 为例的完整格式对比:

一、OpenAI 兼容阵营

OpenAI、DeepSeek、智谱 GLM、月之暗面 (Kimi)、零一万物 (Yi)、字节豆包 (火山引擎)、Mistral、Meta Llama (官方API)、腾讯混元、讯飞星火 (v4.0+),这些厂商的 /v1/chat/completions 接口核心数据结构完全一致。但在工程落地时可能存在一些细微的差异,如 OpenAI 默认不返回 usage(需开启 stream_options),DeepSeek / Kimi:在最后一个 chunk 中默认注入 usage 字段。

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1726000000,"model":"model-name","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: [DONE]

二、 独立协议阵营

这些厂商坚持自有协议,数据结构与 OpenAI 完全不同:

  1. Claude 的流式输出不是简单的数据推送,而是一个状态机。它通过 event 字段区分生命周期,增量内容在 content_block_delta 中。
event: content_block_delta data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你"}}
  1. Google 原生 API 默认不使用 data: 前缀的 SSE 协议,而是直接返回换行分隔的 JSON (NDJSON),且字段嵌套极深。
{"candidates": [{"content": {"parts": [{"text": "你"}],"role": "model"},"finishReason": "STOP"}],"usageMetadata": {"promptTokenCount": 10, "candidatesTokenCount": 1}}

2024年以后Google增加了 OpenAI 兼容 API。

  1. 阿里通义千问 (DashScope)、腾讯混元 (腾讯云API)、讯飞星火 (早期版本)。
    这些厂商在发展早期设计了复杂的自有 RPC/REST 协议,后期为了融入生态又推出了 OpenAI 兼容接口。目前生产环境中 99% 的场景都应使用其兼容接口。

从上述的发展过程和现状来看,最终主要以 OpenAI 标准协议和 Anthropic Claude 协议两种。但很多国内厂商声称"兼容 OpenAI",在流式输出的细节上存在偏差:

  • 缺失 data: [DONE] :部分厂商(如某些版本的通义、讯飞早期版本)流结束时不发送 [DONE] 标记,仅靠 finish_reason: "stop" 结束。如果你的解析器严格依赖 [DONE] 来关闭连接,会导致超时挂起。
  • usage 字段位置不一致:OpenAI 默认不在流中返回 token 用量(需开启 stream_options),但 DeepSeek、Kimi 等会在最后一个 chunk 中自动注入 usage;而有些厂商则完全不支持流式 usage。
  • content 为 null 或者空字符串:当 delta 中没有内容时,OpenAI 返回 "delta":{} 或 "delta":{"content":""},但部分厂商可能返回 "delta":{"content":null},如果解析器未做 null-safe 处理会直接崩溃。

在后续的实战中我们都需要将这些情况考虑进去。

流式数据测试

为什么流式测试特别难? 因为你需要构造各种时序场景的 mock stream。正常的 HTTP 响应测试只需要 mock 一个返回值,但流式测试需要 mock 一个"随时间到达的数据序列"。

我们实战中必须覆盖的边界场景:

编号场景描述预期行为
T1正常流3 个事件正常到达依次解析出 3 个 token
T2粘包3 个事件粘在一个 chunk同上
T3半包1 个事件被切成 3 个 chunk拼接后正确解析
T4JSON 截断{"content":"你 和 好"} 分两个 chunk等完整后解析
T5心跳夹杂正常数据间插 : keep-alive\n\n忽略心跳
T6UTF-8 分割中文字符的 3 字节 UTF-8 被切成 [1B] + [2B]TextDecoder stream 模式正确拼接
T7空流连接后立刻 [DONE]正常结束,不报错
T8网络中断reader.read() reject触发 onError,释放资源
T9Adapter 不匹配Claude 流用 OpenAI adapter不崩溃,报格式错误
T10多行 data一个事件有 3 行 data:用 \n 拼接
T11BOM 开头流首字节是 BOM跳过 BOM
T12\r\n 换行Windows 风格换行正确识别

断线重连与错误恢复

流式请求持续时间可能很长(30 秒甚至数分钟),期间网络抖动很常见。浏览器原生的 EventSource 有自动重连能力(带 Last-Event-ID),但你手写的 fetch 没有。后续再 W7 的完整项目实战中在深入学习掌握。

项目实战

本章我们要实现一个可独立发布的流式 SSE 解析工具库,从 W1 的嵌入式代码"提纯"而来,具备完整的测试、多协议适配、性能优化、错误恢复能力。

1. 为什么必须做这个项目?

  • 学会"造轮子"的工程方法论——你以后在 AI 领域会反复遇到"官方 SDK 不满足需求"的场景,需要能自己造可测试的底层库
  • 巩固 Web Streams API——这个 API 在前端开发中使用频率低但在 AI 场景下是核心基础,不动手写管道链就学不会
  • TDD 能力——流式数据的 bug 在 UI 上几乎不可复现,只有 TDD 能保证正确性
  • 为 W3-W7 提供复用基础——后面每个项目都需要消费流式响应

2. 搭建项目

我们使用 Next.js 官方推荐的脚手架快速搭建工程骨架。在终端中执行以下命令:

npx create-next-app@14 w2-stream-parser \
  --ts --app --no-src-dir --eslint --no-tailwind --import-alias "@/*" --use-npm

参数解释:

  • --ts:强类型安全。大模型字段复杂且动态,类型收窄是防御 null / undefined 崩溃的底线。
  • --app:App Router。Next.js 14 的 App Router 基于 Web 标准 Request / Response 构建,原生完美支持 ReadableStream 流式传输。
  • --no-src-dir:采用扁平工程结构,降低不熟悉 Nextjs 同学的心智负担。
  • --no-tailwind:排除样式干扰,专注于大模型数据流与通信协议的核心知识点。
  • --import-alias "@/*":配置根路径别名,保证无论在哪个目录下引用公共模块都非常清晰。
  • --use-npm:指定标准 npm 包管理器。

引入 Vitest 搭建单元测试基础设施

Next.js 默认侧重于前端组件与页面,但对于工业级的流式解析器而言,测试驱动开发(TDD)是不可妥协的基石。我们引入轻量、闪速的 Vitest:

cd w2-stream-parser
npm install -D vitest

在项目根目录下新建 vitest.config.ts:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['__tests__/**/*.test.ts'],
    css: false, // 纯逻辑与数据流测试,禁用 CSS 扫描避免环境报错
  },
});

同时在根目录下创建最小化的 postcss.config.js,配置空的 plugins 对象(满足 Next.js 14 构建规范,同时防止 Vite 向上递归查找外部目录报错):

// postcss.config.js

module.exports = {

plugins: {},

};

在 package.json 的 scripts 中加入测试脚本:

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "start": "next start",
  "lint": "next lint",
  "test": "vitest run"
}

生产级代码架构目录规划

我们将项目划分为“底层通用解析库”与“上层 Next.js 业务全栈”两层结构:

w2-stream-parser/
├── lib/stream-parser/           # 核心流式解析库 (高内聚、零运行时依赖,可随时抽离为独立 npm 包)
│   ├── core/
│   │   ├── types.ts             # 规范数据契约 (SSEEvent, TokenUsage, ToolCallDelta)
│   │   ├── sse-parser.ts        # 高级管道入口 (createSSEStream, parseSSEStream)
│   │   └── transforms/
│   │       ├── byte-to-text.ts  # 转换流 1: 字节流安全解码 (UTF-8 stream:true + BOM 剥离)
│   │       ├── sse-split.ts     # 转换流 2: WHATWG 规范合规切分 (CRLF/多行 data/心跳过滤)
│   │       └── token-batch.ts   # 转换流 3: Token 攒批调度 (rAF 60fps 平滑渲染)
│   ├── adapters/
│   │   ├── adapter.ts           # ProviderAdapter 接口与 safeJsonParse 容错工具
│   │   ├── openai.ts            # OpenAI 兼容协议 (全防御型:防缺少[DONE]、防null崩溃等)
│   │   └── claude.ts            # Anthropic Claude 事件驱动协议
│   ├── consumer/
│   │   └── stream-consumer.ts   # Map 注册表驱动统一入口 (createStreamConsumer)
│   └── index.ts                 # 统一对外导出
├── app/
│   ├── api/chat/route.ts        # Next.js 服务端流式路由 (安全代理与密钥隔离)
│   └── page.tsx                 # 客户端 UI 交互页面 (一键消费并验证打字机效果)
└── __tests__/                   # 30 项严苛单元测试套件 (粘包、半包、乱码、4大暗坑测试)

3. 第一性原理:拆解数据流管道

项目已经搭建完毕,现在开始编码。大模型流式传输的物理本质是一连串被网络随意分包的二进制字节流。我们基于现代浏览器的 TransformStream 管道链,将其拆解为单向流动的流水线:

Uint8Array 字节流 ──► [ByteToText] ──► string 字符流 ──► [SSESplit] ──► SSEEvent 规范事件 ──► [Adapter] ──► 业务 Token

类型定义

先定义好不可变的数据契约:

// lib/stream-parser/core/types.ts

/** WHATWG 标准 SSE 事件结构 */
export interface SSEEvent {
  event: string;        // 事件名,默认 'message'
  data: string;         // 数据载荷 (多行 data 会用 \n 拼接)
  id?: string;          // 标识符 (用于断线重连)
  retry?: number;       // 重试等待时间 (毫秒)
}

/** 统一的 Token 使用量 */
export interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}

/** 流式工具调用分片 */
export interface ToolCallDelta {
  index: number;
  id?: string;
  name?: string;
  arguments?: string;
}

/** 厂商适配器策略接口 */
export interface ProviderAdapter {
  readonly name: string;
  extractTextDelta(event: SSEEvent): string | null;
  extractReasoningDelta?(event: SSEEvent): string | null; // DeepSeek R1 深度思考流
  extractToolCallDelta(event: SSEEvent): ToolCallDelta | null;
  isStreamEnd(event: SSEEvent): boolean;
  extractUsage(event: SSEEvent): TokenUsage | null;
}

字节流安全解码

根据我们拆解的数据流,我们先来实现一个 ByteToTextTransform 来完成字节流到字符流的安全解码。W1中我们学习了在解码的时候必须传递 { stream: true } 选项,让 TextDecoder 内部维护多字节状态机,留到下一个 chunk 自动拼合!此外,规范要求若流开头存在 0xFEFF(UTF-8 BOM),必须将其剥离。让我们看一下实现的代码:

// lib/stream-parser/core/transforms/byte-to-text.ts
export class ByteToTextTransform extends TransformStream<Uint8Array, string> {
  constructor() {
    const decoder = new TextDecoder('utf-8');
    let isFirstChunk = true;

    super({
      transform(chunk, controller) {
        // stream: true 保证多字节字符跨 chunk 不会解码为乱码
        let text = decoder.decode(chunk, { stream: true });

        // 规范处理:剥离流首字节可能存在的 UTF-8 BOM (\uFEFF)
        if (isFirstChunk) {
          isFirstChunk = false;
          if (text.charCodeAt(0) === 0xfeff) {
            text = text.slice(1);
          }
        }

        if (text.length > 0) {
          controller.enqueue(text);
        }
      },
      flush(controller) {
        // 流结束时冲刷 Decoder 内部残存的尾随字节
        const remaining = decoder.decode();
        if (remaining.length > 0) {
          controller.enqueue(remaining);
        }
      },
    });
  }
}

这里我们简单说一下TransformStream ,其内部由一个可写端(writable,接收输入)和一个可读端(readable,输出结果)组成。

传给 super({...}) 的对象实现了标准的 Transformer<I, O> 接口,包含以下 3 个生命周期钩子方法:

方法名是否必选触发时机核心职责
transform(chunk, controller)核心(绝大多数必写)每当上游推送一个新的 chunk 时触发执行转换计算,处理完成后调用 controller.enqueue(result) 推给下游。支持异步(返回 Promise)。
flush(controller)可选(但在有状态流中极为关键)上游流正常关闭(EOF)时触发仅此一次冲刷(清空)内部缓冲区残存的数据,防止丢尾巴。
start(controller)可选流刚刚完成初始化、准备好接收数据时触发适合做一些资源异步建立(如建立专用通道、初始化计数器)。

要注意的是 flush 是上游流正常关闭的时候才会执行,以下两种情况,flush 绝不会被调用:

  1. 网络报错崩溃(Errored) :比如大模型服务端突然挂掉、TCP 报文异常重置、或中间代码抛出未捕获异常。此时流直接进入 errored 状态中止。
  2. 前端主动掐断(Aborted / Cancelled) :用户点击了“停止生成”,执行了 reader.cancel() 或触发了 AbortController.abort()。此时流走的是取消通道,系统不会调用 flush。

所以上面的代码中,我们使用 flush 去冲刷正常传输下的尾随数据是没啥问题的。但如果涉及必须释放的全局系统资源(如定时器 clearTimeout),绝不能只指望 flush,必须同时监听 signal.addEventListener('abort', ...) 做好兜底。

事件切分

在 W1 中我们使用简单的 str.split('\n\n'),这是存在很多问题的。阅读 WHATWG 规范 9.2.5 & 9.2.6 会发现 4 个关键细节:

  1. 行终止符多样性:可以是 \r\n (CRLF)、单独的 \r (CR) 或 \n (LF);
  2. 字段切分与空格剥离:如果冒号 : 后面紧跟一个空格 (U+0020),该空格必须剥离(例如 data: hello 提取为 hello;data:hello 也提取为 hello);
  3. 多行 data 拼接:同一个事件块中如果出现多个 data: 行,必须用换行符 \n 串联;
  4. 注释行过滤:以冒号 : 开头的行代表注释(保活心跳包),必须静默过滤。

W2中我们实现一个覆盖规范的SSE事件切分:

// lib/stream-parser/core/transforms/sse-split.ts
import type { SSEEvent } from '../types';

export class SSESplitTransform extends TransformStream<string, SSEEvent> {
  constructor() {
    let buffer = '';
    let currentEvent = '';
    let currentData = '';
    let currentId = '';
    let currentRetry: number | undefined = undefined;

    // 派发当前组装好的事件块
    const dispatchCurrentEvent = (controller: TransformStreamDefaultController<SSEEvent>) => {
      if (currentData.length > 0 || currentEvent.length > 0) {
        controller.enqueue({
          event: currentEvent || 'message',
          data: currentData,
          id: currentId || undefined,
          retry: currentRetry,
        });
      }
      currentEvent = '';
      currentData = '';
    };

    const processLine = (line: string, controller: TransformStreamDefaultController<SSEEvent>) => {
      // 1. 空行:标志事件块结束,派发事件
      if (line === '') {
        dispatchCurrentEvent(controller);
        return;
      }
      // 2. 冒号注释行:保活心跳包,静默忽略
      if (line.startsWith(':')) return;

      // 3. 提取 field 与 value
      let field: string;
      let value: string;
      const colonIndex = line.indexOf(':');

      if (colonIndex !== -1) {
        field = line.slice(0, colonIndex);
        let raw = line.slice(colonIndex + 1);
        if (raw.startsWith(' ')) raw = raw.slice(1); // 剥离紧邻冒号的首空格
        value = raw;
      } else {
        field = line;
        value = '';
      }

      // 4. 根据字段处理
      switch (field) {
        case 'data':
          // 规范:多行 data 用 \n 拼接
          currentData = currentData.length > 0 ? `${currentData}\n${value}` : value;
          break;
        case 'event':
          currentEvent = value;
          break;
        case 'id':
          if (!value.includes('\u0000')) currentId = value;
          break;
        case 'retry':
          if (/^\d+$/.test(value)) currentRetry = parseInt(value, 10);
          break;
      }
    };

    super({
      transform(chunk, controller) {
        buffer += chunk; // 将新来的 chunk 拼接到历史残片缓冲区
        let pos = 0; // 双指针扫描游标:pos 记录当前行起始位置

        while (pos < buffer.length) {
          // 从当前游标 pos 开始,分别查找第一个 \r 和 \n 的位置
          const cr = buffer.indexOf('\r', pos);
          const lf = buffer.indexOf('\n', pos);
          let lineEnd = -1; // 本行文本的终止下标(不含换行符)
          let step = 0; // 换行符自身占用的字符长度(1 或 2)

          if (cr !== -1 && lf !== -1) {
            if (cr + 1 === lf) { lineEnd = cr; step = 2; } // CRLF
            else if (cr < lf) { lineEnd = cr; step = 1; }  // CR
            else { lineEnd = lf; step = 1; }              // LF
          } else if (cr !== -1) {
            if (cr === buffer.length - 1) break; // CR 恰好在 chunk 末尾,暂留等待下一 chunk
            lineEnd = cr; step = 1;
          } else if (lf !== -1) {
            lineEnd = lf; step = 1;
          } else {
            break;
          }
          // 截取当前行的文本内容,交给 processLine 处理字段
          processLine(buffer.slice(pos, lineEnd), controller);
          // 游标跃过这行文本 + 换行符的长度
          pos = lineEnd + step;
        }
        // 循环结束后,丢弃已解析完的数据,只在 buffer 中保留未拼装完整的残片
        buffer = buffer.slice(pos);
      },
      flush(controller) 
        // 1. 如果流关闭了,buffer 里还残存有字符,说明服务端最后一行没发换行符就断开了
        if (buffer.length > 0) processLine(buffer, controller);
        
        // 2. 强制把当前组装好的事件发射给下游
        dispatchCurrentEvent(controller);
      },
    });
  }
}

我们来逐步解读一下核心的if判断逻辑:

情况 1:同时找到了 \r 和 \n(cr !== -1 && lf !== -1)

if (cr !== -1 && lf !== -1) {
  if (cr + 1 === lf) { lineEnd = cr; step = 2; } // 命中 CRLF (\r\n)
  else if (cr < lf) { lineEnd = cr; step = 1; }  // 命中独立的 CR (\r)
  else { lineEnd = lf; step = 1; }              // 命中独立的 LF (\n)
}
  • cr + 1 === lf:\r 和 \n 紧挨着,说明是标准的 Windows 换行符 \r\n。行内容截止于 cr,跳过换行符需要走 2 步(step = 2)。
  • cr < lf:说明 \r 出现在 \n 前面,但它们没挨着(如 foo\rbar\n),先到先得,先结算前面以 \r 结尾的独立行,步长为 1。
  • cr > lf:说明 \n 在前面,先结算以 \n 结尾的独立行,步长为 1。

情况 2:只找到了 \r,没找到 \n(cr !== -1)

else if (cr !== -1) {
  if (cr === buffer.length - 1) break; // 全篇最精妙的一行
  lineEnd = cr; step = 1;
}

cr === buffer.length - 1 时要立即 break 退出循环,想象这个场景:

  • 当前 buffer 的内容是:"data: hello\r"(\r 恰好是最后一个字符)。
  • 此时你无法断定这个 \r 是一个独立的老 Mac 换行符,还是一个 \r\n 的前半截。因为 \n 可能就躺在 5 毫秒后到达的下一个 TCP 数据包里
  • 如果此时草率地把它当作独立的 \r 处理掉,下一个 chunk 带来的 \n 就会变成一个孤立的空行,导致多触发一次事件派发,逻辑被彻底破坏。
  • 因此 一旦发现 \r 落在 buffer 的最后一个字符,果断 break 暂停解析,将这包含 \r 的残片留在 buffer 中,等下一个 chunk 到来再定夺!

情况 3:只找到了 \n,没找到 \r(lf !== -1)

else if (lf !== -1) {
  lineEnd = lf; step = 1; // 纯正的 Unix/Linux 换行符 \n,步长为 1
}

情况 4:两者都没找到

else {
  break; // 从 pos 到末尾根本没有换行符,说明这行还没传完(半包),退出循环等待后续数据
}

最后再看看 flush 的逻辑:

flush(controller) {
  // 1. 如果流关闭了,buffer 里还残存有字符,说明服务端最后一行没发换行符就断开了
  if (buffer.length > 0) processLine(buffer, controller);
  
  // 2. 强制把当前组装好的事件发射给下游
  dispatchCurrentEvent(controller);
}

按照规范,只有收到一个“空行”(即连续两个换行符)时,才代表一个完整事件组装完毕并派发出去。

  • 但有些服务端在生成完最后一个 token(或者发完 data: [DONE])后,就直接关闭了 HTTP 连接,没有按规范补一个末尾空行。
  • flush 里的 dispatchCurrentEvent(controller) 就是最终的保底保险:即使服务端少发了收尾空行,在关流的一瞬间,也把最后拼装出来的有效事件强行推给下游,杜绝丢包

管道装配

Transform 我们已经实现完了,现在要用 pipeThrough 将转换流串联,并提供优雅的 for await 异步迭代器

// lib/stream-parser/core/sse-parser.ts
import { ByteToTextTransform } from './transforms/byte-to-text';
import { SSESplitTransform } from './transforms/sse-split';
import type { SSEEvent } from './types';

export function createSSEStream(byteStream: ReadableStream<Uint8Array>): ReadableStream<SSEEvent> {
  return byteStream
    .pipeThrough(new ByteToTextTransform())
    .pipeThrough(new SSESplitTransform());
}

export async function* parseSSEStream(
  byteStream: ReadableStream<Uint8Array>,
  signal?: AbortSignal
): AsyncGenerator<SSEEvent, void, unknown> {
  const eventStream = createSSEStream(byteStream);
  const reader = eventStream.getReader();

  try {
    while (true) {
      if (signal?.aborted) {
        await reader.cancel('Aborted');
        break;
      }
      const { done, value } = await reader.read();
      if (done) break;
      if (value) yield value;
    }
  } finally {
    reader.releaseLock();
  }
}

这里parseSSEStream的代码使用了异步迭代器来实现,有的同学会问:“那为什么不写成 parseSSEStream(byteStream, onEvent) 回调函数呢?”

异步生成器相比于回调函数,有 控制流反转 与 背压 的优势:

  • 回调函数的硬伤:数据一旦到来,回调就会被强制触发。如果你的 onEvent 内部要做一个耗时的异步操作(比如把 token 写入数据库或等待动画),回调函数无法阻止上游继续塞数据,最终导致内存爆仓。
  • 异步生成器的优势:for await 是拉取模式 。只有当前一轮循环体内的代码(即使包含 await)彻底执行完毕后,它才会去要下一个 yield。下游消费有多慢,上游就会天然被等停多久,天然实现全链路背压控制。

在后续的代码中消费的时候可以看到for await相关的代码,这里先提一嘴。

Adapter 策略层

在对接各大“兼容 OpenAI”的模型服务商与推理端点时,还隐藏着我们之前提到的3个暗坑,如果对接的是推理模型时还存在:

  • 模型在深度思考推导阶段(通常耗时 10~60 秒),流式分片只输出思维链,此时 delta.content 恒为 null 或未定义!如果前端依然沿用只读 content 的传统逻辑,用户将面对长达数十秒没有任何输出的空白界面,误以为服务卡死。若不进行语义分流,思考推导草稿会直接和正式答案混在同一个聊天气泡中,破坏 Markdown 排版且无法折叠。
  • 各聚合平台存在别名(如 reasoning),且部分严格校验 schema 的网关会静默丢弃未知的 reasoning_content。

在实现适配器之前,我们先在 lib/stream-parser/adapters/adapter.ts 中提供一个安全的 JSON 解析辅助函数,防止上游返回非法畸形字符串导致进程崩溃:

// lib/stream-parser/adapters/adapter.ts
export function safeJsonParse<T>(str: string): T | null {
  try {
    return JSON.parse(str) as T;
  } catch {
    return null;
  }
}

随后实现 OpenAIAdapter:

// lib/stream-parser/adapters/openai.ts
import type { ProviderAdapter, SSEEvent, TokenUsage, ToolCallDelta } from '../core/types';
import { safeJsonParse } from './adapter';

interface OpenAIStreamChunk {
  choices?: Array<{
    delta?: {
      content?: string | null;
      reasoning_content?: string | null; // 推理模型的深度思考内容
      tool_calls?: Array<{
        index: number;
        id?: string;
        type?: string;
        function?: {
          name?: string;
          arguments?: string;
        };
      }>;
    };
    finish_reason?: string | null;
  }>;
  usage?: {
    prompt_tokens?: number;
    completion_tokens?: number;
    total_tokens?: number;
    input_tokens?: number;  // 兼顾国内厂商别名
    output_tokens?: number;
  } | null;
}

export class OpenAIAdapter implements ProviderAdapter {
  readonly name = 'openai';

  isStreamEnd(event: SSEEvent): boolean {
    const trimmed = event.data.trim();
    if (trimmed === '[DONE]') return true;

    const payload = safeJsonParse<OpenAIStreamChunk>(trimmed);
    // 即使厂商漏发 [DONE],只要检测到合法的 finish_reason,立即双保险终结
    const reason = payload?.choices?.[0]?.finish_reason;
    return typeof reason === 'string' && reason.length > 0;
  }

  extractTextDelta(event: SSEEvent): string | null {
    if (event.data.trim() === '[DONE]') return null;
    const payload = safeJsonParse<OpenAIStreamChunk>(event.data);
    const content = payload?.choices?.[0]?.delta?.content;
    // 类型守卫严格收窄,防范 null、undefined 与空串
    return typeof content === 'string' && content.length > 0 ? content : null;
  }

  extractReasoningDelta(event: SSEEvent): string | null {
    if (event.data.trim() === '[DONE]') return null;
    const payload = safeJsonParse<OpenAIStreamChunk>(event.data);
    const delta = payload?.choices?.[0]?.delta;
    // 兼容事实标准 reasoning_content 与部分网关别名 reasoning
    const reasoning = delta?.reasoning_content ?? (delta as Record<string, unknown>)?.reasoning;
    return typeof reasoning === 'string' && reasoning.length > 0 ? reasoning : null;
  }

  extractToolCallDelta(event: SSEEvent): ToolCallDelta | null {
    if (event.data.trim() === '[DONE]') return null;
    const payload = safeJsonParse<OpenAIStreamChunk>(event.data);
    const rawToolCall = payload?.choices?.[0]?.delta?.tool_calls?.[0];
    if (!rawToolCall) return null;

    return {
      index: rawToolCall.index ?? 0,
      id: rawToolCall.id,
      name: rawToolCall.function?.name,
      arguments: rawToolCall.function?.arguments,
    };
  }

  extractUsage(event: SSEEvent): TokenUsage | null {
    if (event.data.trim() === '[DONE]') return null;
    const payload = safeJsonParse<OpenAIStreamChunk>(event.data);
    if (!payload?.usage) return null;

    // 兼顾标准字段与国内 input_tokens / output_tokens 别名
    const prompt = payload.usage.prompt_tokens ?? payload.usage.input_tokens ?? 0;
    const completion = payload.usage.completion_tokens ?? payload.usage.output_tokens ?? 0;
    return {
      promptTokens: prompt,
      completionTokens: completion,
      totalTokens: payload.usage.total_tokens ?? (prompt + completion),
    };
  }
}

Anthropic Claude 采用事件驱动的状态机流。它不使用 choices,而是通过 event: 字段标识生命周期:

// lib/stream-parser/adapters/claude.ts
import type { ProviderAdapter, SSEEvent, TokenUsage, ToolCallDelta } from '../core/types';
import { safeJsonParse } from './adapter';

export class ClaudeAdapter implements ProviderAdapter {
  readonly name = 'claude';

  isStreamEnd(event: SSEEvent): boolean {
    return event.event === 'message_stop';
  }

  extractTextDelta(event: SSEEvent): string | null {
    if (event.event !== 'content_block_delta') return null;
    const payload = safeJsonParse<{
      type?: string;
      delta?: { type?: string; text?: string };
    }>(event.data);

    return payload?.delta?.type === 'text_delta' && typeof payload.delta.text === 'string'
      ? payload.delta.text
      : null;
  }

  extractToolCallDelta(_event: SSEEvent): ToolCallDelta | null {
    return null;
  }

  extractUsage(event: SSEEvent): TokenUsage | null {
    if (event.event !== 'message_delta') return null;
    const payload = safeJsonParse<{ usage?: { output_tokens?: number } }>(event.data);
    if (!payload?.usage?.output_tokens) return null;
    return {
      promptTokens: 0,
      completionTokens: payload.usage.output_tokens,
      totalTokens: payload.usage.output_tokens,
    };
  }
}

为了避免在业务代码中写出又臭又长的 switch (provider),我们采用 Map 注册表模式 实现O(1)O(1)的别名分发,支持中美 20+ 款主流大模型服务商开箱即用:

// 供应商协议注册表 (lib/stream-parser/consumer/stream-consumer.ts)
export type SupportedProtocol = 'openai' | 'claude';

const PROVIDER_PROTOCOL_REGISTRY = new Map<string, SupportedProtocol>([
  // 1. 国际主流服务商 (OpenAI 兼容)
  ['openai', 'openai'],
  ['gemini', 'openai'],      // Google Gemini /v1beta/openai/ 兼容端点
  ['groq', 'openai'],        // Groq 极速推理
  ['mistral', 'openai'],
  ['together', 'openai'],

  // 2. 中国头部大模型服务商 (OpenAI 兼容)
  ['deepseek', 'openai'],    // 深度求索
  ['kimi', 'openai'],        // 月之暗面
  ['moonshot', 'openai'],
  ['qwen', 'openai'],        // 通义千问 /compatible-mode/v1 兼容端点
  ['doubao', 'openai'],      // 字节豆包
  ['volcengine', 'openai'],  // 火山引擎方舟
  ['ark', 'openai'],
  ['glm', 'openai'],         // 智谱 AI
  ['zhipu', 'openai'],
  ['yi', 'openai'],          // 零一万物
  ['minimax', 'openai'],     // MiniMax
  ['siliconflow', 'openai'], // 硅基流动聚合云

  // 3. 本地与私有化推理框架 (OpenAI 兼容)
  ['ollama', 'openai'],      // 本地部署事实标准
  ['vllm', 'openai'],        // 高性能推理服务
  ['local', 'openai'],

  // 4. Anthropic Claude 事件流
  ['claude', 'claude'],
  ['anthropic', 'claude'],
]);

/**
 * 协议分发工厂:根据厂商名称或自定义 Adapter 返回适配器实例
 */
export function resolveAdapter(provider: string | ProviderAdapter = 'openai'): ProviderAdapter {
  if (typeof provider !== 'string') {
    return provider;
  }

  const normalized = provider.toLowerCase().trim();
  const protocol = PROVIDER_PROTOCOL_REGISTRY.get(normalized);

  if (protocol === 'openai') return new OpenAIAdapter();
  if (protocol === 'claude') return new ClaudeAdapter();

  throw new Error(
    `[w2-stream-parser] Unknown provider: "${provider}".\n` +
    `Supported providers: ${Array.from(PROVIDER_PROTOCOL_REGISTRY.keys()).slice(0, 10).join(', ')}... (total ${PROVIDER_PROTOCOL_REGISTRY.size})`
  );
}

现在,我们已经具备了解析 SSE 的管道与标准化业务数据的适配器。但是在把数据交给 React UI 之前,还有一个极其关键的性能关卡必须跨越——渲染调度。

4. 渲染性能优化

当大模型以 60 tokens/s 的极速吐字时,如果我们每收到一个 token 就调用一次 React 的 setMessages((prev) => [...prev, token]):

  • 浏览器主线程严重阻塞:1 秒内触发 60 次 React 虚拟 DOM 树深度 Diff、组件重新渲染以及浏览器布局与重绘(Reflow / Repaint);
  • 用户体验崩溃:页面产生严重的掉帧感,此时用户若在页面输入框打字会出现明显卡顿,滚动条滚动生硬甚至卡死。

有的同学会想到防抖节流来进行优化,但我要在这里泼个冷水,都不行:

  • 防抖(Debounce) :每次来数据都重置定时器,会导致大模型在持续高速输出时页面完全一片空白,直到大模型说完了才瞬间刷出整段话,完全丧失了流式“打字机”的交互灵魂;
  • 普通节流(Throttle setTimeout) :setTimeout(fn, 16) 是由宏任务队列驱动的,其执行时机与显示器的硬件垂直同步信号(VSync)完全脱节,极易在帧间产生微抖动(Jank)。

最优解是使用 requestAnimationFrame(rAF)实现与显示器刷新周期(60Hz 即约 16.6ms)精准同步的 Token 攒批调度器。在同一个渲染帧内到达的所有 token 先缓存在内存中,等硬件垂直同步信号到来时,合并为单一批次一次性通知 React 渲染。

// lib/stream-parser/core/transforms/token-batch.ts
import type { BatchStrategy } from '../types';

export class TokenBatcher {
  private buffer = '';
  private timerId: ReturnType<typeof setTimeout> | null = null;
  private rafId: number | null = null;
  private readonly strategy: BatchStrategy;
  private readonly onFlush: (batch: string) => void;

  constructor(strategy: BatchStrategy, onFlush: (batch: string) => void) {
    this.strategy = strategy;
    this.onFlush = onFlush;
  }

  push(token: string): void {
    if (this.strategy === 'none') {
      this.onFlush(token);
      return;
    }

    this.buffer += token;

    if (this.strategy === 'raf') {
      // 浏览器环境优先使用 rAF,Node.js/单测环境平滑降级到 16ms 定时器
      if (typeof requestAnimationFrame === 'function') {
        if (this.rafId === null) {
          this.rafId = requestAnimationFrame(() => {
            this.rafId = null; // 任务自然触发出队,释放状态锁
            this.drainBuffer();
          });
        }
      } else {
        if (this.timerId === null) {
          this.timerId = setTimeout(() => {
            this.timerId = null;
            this.drainBuffer();
          }, 16);
        }
      }
      return;
    }

    if (typeof this.strategy === 'object' && typeof this.strategy.intervalMs === 'number') {
      if (this.timerId === null) {
        this.timerId = setTimeout(() => {
          this.timerId = null;
          this.drainBuffer();
        }, this.strategy.intervalMs);
      }
    }
  }

  /**
   * 立即冲刷并派发当前缓冲区中的所有 token (在流正常关闭或用户点击停止时调用)
   */
  flush(): void {
    // 外部主动插队时,撤回排队中尚未触发的帧任务
    if (this.rafId !== null) {
      if (typeof cancelAnimationFrame === 'function') {
        cancelAnimationFrame(this.rafId);
      }
      this.rafId = null;
    }
    if (this.timerId !== null) {
      clearTimeout(this.timerId);
      this.timerId = null;
    }

    this.drainBuffer();
  }

  /**
   * 遵循“先清后调”原则:清空缓冲区并交付业务层
   */
  private drainBuffer(): void {
    if (this.buffer.length > 0) {
      const batch = this.buffer;
      this.buffer = '';
      this.onFlush(batch);
    }
  }
}

5. 抽取可复用的前端消费逻辑

在前面的章节中,我们分别攻克了:

  1. 底层数据管道:parseSSEStream
  2. 多厂商适配器:resolveAdapter 
  3. 渲染调度优化:TokenBatcher

现在,是时候将所有零件严丝合缝地装配在一起,为前端业务层打造一个一键消费的函数createStreamConsumer。

// lib/stream-parser/consumer/stream-consumer.ts
export interface StreamConsumerHandle {
  /** 主动中止当前流式消费 */
  abort: () => void;
  /** 等待流完全读取并解析完毕的 Promise */
  done: Promise<void>;
}

这里是需要重点关注的地方。:我们是如何使用 for await...of 循环驱动消费前面封装的 parseSSEStream 的。

// lib/stream-parser/consumer/stream-consumer.ts
import { parseSSEStream } from '../core/sse-parser';
import type { ProviderAdapter, StreamConsumerOptions } from '../core/types';
import { TokenBatcher } from '../core/transforms/token-batch';
import { resolveAdapter } from './stream-consumer'; // 引入前面的工厂函数

export function createStreamConsumer(
  byteStream: ReadableStream<Uint8Array>,
  options: StreamConsumerOptions = {}
): StreamConsumerHandle {
  const {
    provider = 'openai',
    onToken,
    onReasoning,
    onToolCall,
    onUsage,
    onDone,
    onError,
    batchStrategy = 'none',
  } = options;

  // 1. 获取协议适配器
  const adapter = resolveAdapter(provider);
  const abortController = new AbortController();

  // 2. 初始化 Token 攒批调度器 (若未传 onToken 则无需初始化)
  const batcher = onToken
    ? new TokenBatcher(batchStrategy, (batch) => {
        if (!abortController.signal.aborted) {
          onToken(batch);
        }
      })
    : null;

  const abort = () => {
    abortController.abort();
  };

  // 3. 核心消费驱动任务
  const donePromise = (async () => {
    try {
      // 核心消费循环:使用 for await 持续消费底层 parseSSEStream 产出的规范事件
      for await (const event of parseSSEStream(byteStream, abortController.signal)) {
        if (abortController.signal.aborted) {
          break;
        }

        // ① 识别大模型终结信号 ([DONE] 或 finish_reason)
        if (adapter.isStreamEnd(event)) {
          break;
        }

        // ② 提取正文文本增量送入攒批调度器
        const textDelta = adapter.extractTextDelta(event);
        if (textDelta !== null) {
          if (batcher) {
            batcher.push(textDelta);
          } else if (onToken) {
            onToken(textDelta);
          }
        }

        // ③ 提取思维链增量 (针对 DeepSeek R1 / Kimi 等推理模型)
        if (onReasoning && adapter.extractReasoningDelta) {
          const reasoningDelta = adapter.extractReasoningDelta(event);
          if (reasoningDelta !== null) {
            onReasoning(reasoningDelta);
          }
        }

        // ④ 提取工具调用增量 (为 Week 3 Function Calling 预留通道)
        if (onToolCall) {
          const toolCallDelta = adapter.extractToolCallDelta(event);
          if (toolCallDelta !== null) {
            onToolCall(toolCallDelta);
          }
        }

        // ⑤ 提取 Token 消耗统计
        if (onUsage) {
          const usage = adapter.extractUsage(event);
          if (usage !== null) {
            onUsage(usage);
          }
        }
      }

      // 流正常读取完成:立即冲刷缓冲区残存 token,触发完成通知
      batcher?.flush();

      if (!abortController.signal.aborted) {
        onDone?.();
      }
    } catch (err) {
      if (!abortController.signal.aborted) {
        const error = err instanceof Error ? err : new Error(String(err));
        onError?.(error);
        throw error;
      }
    } finally {
      batcher?.flush();
    }
  })();

  return {
    abort,
    done: donePromise,
  };
}

这里的逻辑比较简单,值得一说的就是使用了 for await 遍历异步生成器,当前端正在处理复杂的逻辑时,如果不继续循环,上游 Web Streams 就不会拉取下一个分片,背压天然生效。

为了给企业内部自建的私有网关或新出炉的大模型预留扩展通道,我们在 consumer/stream-consumer.ts 中对外暴露动态注册函数:

/**

* 动态注册或覆盖供应商别名(为公司内部网关或新大模型提供零侵入扩展能力)

*/

export function registerProviderProtocol(alias: string, protocol: SupportedProtocol): void {

PROVIDER_PROTOCOL_REGISTRY.set(alias.toLowerCase().trim(), protocol);

}

6. 测试驱动开发(TDD)

大模型流式开发的 bug 几乎不可能在 UI 上通过肉眼稳定复现。要想确保在任何弱网丢包、半包切分场景下都能稳如泰山,必须手写一个可精确控制时序与切片大小的 createMockStream 测试工具:

// __tests__/helpers/mock-stream.ts
export function createMockStream(
  chunks: (string | Uint8Array)[],
  options: { delayMs?: number; errorAfterChunkIndex?: number; mockError?: Error } = {}
): ReadableStream<Uint8Array> {
  const encoder = new TextEncoder();
  let index = 0;

  return new ReadableStream<Uint8Array>({
    async pull(controller) {
      if (options.errorAfterChunkIndex !== undefined && index > options.errorAfterChunkIndex) {
        controller.error(options.mockError ?? new Error('Network Error'));
        return;
      }
      if (index >= chunks.length) {
        controller.close();
        return;
      }
      const item = chunks[index];
      controller.enqueue(typeof item === 'string' ? encoder.encode(item) : item);
      index++;
    },
  });
}

项目在 __tests__/ 目录下构建了覆盖全面的测试矩阵,覆盖各种极端边界场景,这里举几个例子:

// __tests__/sse-parser.test.ts

// T2: 粘包场景 (多个 SSE 数据块挤在同一个 TCP 数据包内)
it('T2: 粘包 - 多个事件在同一个 chunk 内紧挨着到达', async () => {
  const stream = createMockStream(['data: event1\n\ndata: event2\n\ndata: event3\n\n']);
  const events = await collectEvents(stream);
  expect(events.map(e => e.data)).toEqual(['event1', 'event2', 'event3']);
});

// T3: 半包场景 (单个 SSE 事件被硬生生切成多片)
it('T3: 半包 - 单个事件被切断跨 4 个 chunk 到达', async () => {
  const stream = createMockStream(['dat', 'a: hel', 'lo world\n', '\n']);
  const events = await collectEvents(stream);
  expect(events[0].data).toBe('hello world');
});

// T6: UTF-8 中文多字节截断 (彻底消灭乱码问号)
it('T6: UTF-8 分割 - 中文字符 3 字节跨分片硬性切割', async () => {
  // “你”的 UTF-8 编码为 [0xE4, 0xBD, 0xA0]
  const part1 = new Uint8Array([0x64, 0x61, 0x74, 0x61, 0x3a, 0x20, 0xe4]); // "data: " + 0xE4
  const part2 = new Uint8Array([0xbd, 0xa0, 0x0a, 0x0a]);                    // 0xBD, 0xA0 + "\n\n"
  const stream = createMockStream([part1, part2]);
  const events = await collectEvents(stream);
  expect(events[0].data).toBe('你');
});

我们在终端运行自动化测试命令:

npm test

终端即时输出如下:

 ✓ __tests__/adapters.test.ts (13 tests)
 ✓ __tests__/sse-parser.test.ts (12 tests)
 ✓ __tests__/consumer.test.ts (7 tests)

 Test Files  3 passed (3)
      Tests  32 passed (32)
   Duration  869ms

32 项测试用例都是通过了的。

7. 服务端路由与前端消费

最后一哆嗦,来完成服务端的接口以及前端的UI交互。在项目根目录预置了标准的 .env.example 模板。可以直接复制该文件为 .env.local 并配置:

cp .env.example .env.local

打开 .env.local 填入你的真实配置:

# .env.local
OPENAI_API_KEY=sk-xxxx                       # 密钥 (使用本地 Ollama / vLLM 时可随意填写,如 ollama)
OPENAI_BASE_URL=https://api.openai.com/v1     # 兼容端点 (或 https://api.deepseek.com/v1、http://localhost:11434/v1)
OPENAI_MODEL=gpt-5.6-soul            # 模型名称 (如 deepseek-chat、qwen-plus、llama3 等)

和W1的服务端逻辑基本一致,这里我们逐步完善逻辑,增加 apiKey 的校验:

// app/api/chat/route.ts
import { NextRequest } from 'next/server';

export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';

export async function POST(req: NextRequest) {
  const { messages } = await req.json();

  const apiKey = process.env.OPENAI_API_KEY;
  const baseUrl = (process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1').replace(/\/+$/, '');
  const model = process.env.OPENAI_MODEL || 'gpt-4o-mini';

  // 若未配 Key 则返回 401 提示
  if (!apiKey) {
    return new Response(
      JSON.stringify({
        error: '服务端未配置 OPENAI_API_KEY,请在 .env.local 中配置(若使用本地 Ollama/vLLM 可随意填写,如 ollama)',
      }),
      {
        status: 401,
        headers: { 'Content-Type': 'application/json' },
      }
    );
  }

  // 支持所有兼容 OpenAI 规范的端点
  const upstreamRes = await fetch(`${baseUrl}/chat/completions`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      model,
      messages,
      stream: true,
    }),
    signal: req.signal, // 前端用户点击“停止”,上游连接即刻掐断,避免浪费算力与费用
  });

  if (!upstreamRes.ok || !upstreamRes.body) {
    const errText = await upstreamRes.text().catch(() => '');
    return new Response(
      JSON.stringify({ error: `上游模型接口错误 (${upstreamRes.status}): ${errText}` }),
      {
        status: upstreamRes.status,
        headers: { 'Content-Type': 'application/json' },
      }
    );
  }

  // 透传 SSE 二进制流,配置 X-Accel-Buffering 杜绝 Nginx 缓存
  return new Response(upstreamRes.body, {
    headers: {
      'Content-Type': 'text/event-stream; charset=utf-8',
      'Cache-Control': 'no-cache, no-transform',
      'Connection': 'keep-alive',
      'X-Accel-Buffering': 'no',
    },
  });
}

借助我们在前面封装的消费函数 createStreamConsumer,前端消费代码从原本恶心脆弱的 60 行内嵌代码缩减为回调驱动的高阶调用(UI为基本演示,细节啥的不要在意):

// app/page.tsx
'use client';

import { useRef, useState } from 'react';
import { createStreamConsumer, type StreamConsumerHandle } from '@/lib/stream-parser';

export default function ChatPage() {
  const [messages, setMessages] = useState<Array<{ role: string; content: string }>>([]);
  const [thinking, setThinking] = useState('');
  const [input, setInput] = useState('');
  const [busy, setBusy] = useState(false);
  const consumerRef = useRef<StreamConsumerHandle | null>(null);

  async function handleSend() {
    const text = input.trim();
    if (!text || busy) return;

    const nextMessages = [...messages, { role: 'user', content: text }];
    setMessages([...nextMessages, { role: 'assistant', content: '' }]);
    setInput('');
    setThinking('');
    setBusy(true);

    const abortController = new AbortController();

    try {
      const res = await fetch('/api/chat', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ messages: nextMessages }),
        signal: abortController.signal,
      });

      if (!res.ok || !res.body) {
        let errorMsg = `网络请求异常 (${res.status})`;
        try {
          const errData = await res.json();
          if (errData?.error) errorMsg = errData.error;
        } catch {
          // 忽略非 JSON 格式的异常
        }
        throw new Error(errorMsg);
      }

      // 核心:一行代码启用生产级流式消费客户端!
      const consumer = createStreamConsumer(res.body, {
        provider: 'openai',   // 支持中美 20+ 主流厂商别名 (DeepSeek, Qwen 等)
        batchStrategy: 'raf', // 开启 requestAnimationFrame 60fps 平滑攒批调度

        onToken: (tokenChunk) => {
          setMessages((prev) => {
            const copy = [...prev];
            const last = copy[copy.length - 1];
            copy[copy.length - 1] = { ...last, content: last.content + tokenChunk };
            return copy;
          });
        },

        onReasoning: (reasoningChunk) => {
          // DeepSeek R1 深度思考流增量渲染
          setThinking((prev) => prev + reasoningChunk);
        },

        onError: (err) => {
          console.error('流式传输异常:', err);
        },
      });

      consumerRef.current = consumer;
      await consumer.done;
    } catch (e) {
      console.error(e);
      const errMsg = e instanceof Error ? e.message : '网络请求发生未知异常';
      setMessages((prev) => {
        const copy = [...prev];
        const last = copy[copy.length - 1];
        if (last && last.role === 'assistant') {
          copy[copy.length - 1] = {
            ...last,
            content: last.content ? `${last.content}\n\n[请求失败: ${errMsg}]` : `[请求失败: ${errMsg}]`,
          };
        }
        return copy;
      });
    } finally {
      setBusy(false);
      consumerRef.current = null;
    }
  }

  function handleStop() {
    consumerRef.current?.abort();
  }

  return (
    <main style={{ maxWidth: 800, margin: '40px auto', padding: '0 20px', fontFamily: 'sans-serif' }}>
      <h1>W2 · 生产级流式解析落地实战</h1>
      <p style={{ color: '#666', fontSize: 14 }}>
        基于原生 Web Streams API、WHATWG 规范合规切分、4 大生产暗坑防御与 rAF 攒批 60fps 渲染。
      </p>

      {/* 深度思考链展示面板 (针对 DeepSeek R1 等推理流) */}
      {thinking && (
        <details open style={{ background: '#f8fafc', padding: 12, borderRadius: 6, marginBottom: 16, border: '1px solid #e2e8f0' }}>
          <summary style={{ cursor: 'pointer', color: '#64748b', fontSize: 13, fontWeight: 'bold' }}>
            💭 DeepSeek 深度思考过程 (流式输出中...)
          </summary>
          <div style={{ color: '#475569', fontSize: 13, marginTop: 8, whiteSpace: 'pre-wrap', lineHeight: 1.6 }}>
            {thinking}
          </div>
        </details>
      )}

      {/* 消息对话列表 */}
      <div style={{ border: '1px solid #e2e8f0', borderRadius: 8, minHeight: 300, padding: 16, marginBottom: 16 }}>
        {messages.length === 0 && (
          <div style={{ color: '#94a3b8', textAlign: 'center', marginTop: 100 }}>
            输入消息体验平滑打字机效果...
          </div>
        )}
        {messages.map((m, i) => (
          <div key={i} style={{ marginBottom: 12, textAlign: m.role === 'user' ? 'right' : 'left' }}>
            <span style={{
              display: 'inline-block',
              padding: '8px 14px',
              borderRadius: 8,
              background: m.role === 'user' ? '#2563eb' : '#f1f5f9',
              color: m.role === 'user' ? '#fff' : '#0f172a',
              whiteSpace: 'pre-wrap',
            }}>
              {m.content || (m.role === 'assistant' && busy ? '...' : '')}
            </span>
          </div>
        ))}
      </div>

      {/* 输入与控制栏 */}
      <div style={{ display: 'flex', gap: 8 }}>
        <input
          style={{ flex: 1, padding: '10px 14px', borderRadius: 6, border: '1px solid #cbd5e1' }}
          value={input}
          placeholder="输入消息,体验 60fps 平滑打字机与思考流..."
          onChange={(e) => setInput(e.target.value)}
          onKeyDown={(e) => e.key === 'Enter' && handleSend()}
          disabled={busy}
        />
        {busy ? (
          <button style={{ padding: '10px 20px', background: '#ef4444', color: '#fff', border: 'none', borderRadius: 6, cursor: 'pointer' }} onClick={handleStop}>
            停止
          </button>
        ) : (
          <button style={{ padding: '10px 20px', background: '#2563eb', color: '#fff', border: 'none', borderRadius: 6, cursor: 'pointer' }} onClick={handleSend}>
            发送
          </button>
        )}
      </div>
    </main>
  );
}

总结

本章我们拒绝做浮躁的“调库侠”,一步步写出了生产级的流式解析逻辑。文章字数较长,也很干,建议拉取源码对照学习。最后自己动手搭建项目练习吧。

参考的规范地址:

html.spec.whatwg.org/multipage/s…

html.spec.whatwg.org/multipage/s…

html.spec.whatwg.org/multipage/s…

下一节 W3. 实现Agent工具调用引擎