交互与用户体验 / 系统课时

通过 SSE 渲染逐步生成的回复

通过 SSE 渲染逐步生成的回复

本课用 Node.js 模拟返回 SSE 的聊天接口,在浏览器中把 delta 片段拼成一条回复。完成后可以验证正常结束、服务端报错、意外断流和主动取消,避免把半截答案误标为成功。

学习目标

  • 识别 SSE 的 delta、done、error 事件,区分事件帧与网络读取块。
  • 使用 fetch、TextDecoderStream 和 AbortController 实现增量渲染与取消。
  • 验收完成、服务端错误、连接中断和用户取消四种收尾状态。

定义事件协议与消息状态

SSE 响应的媒体类型为 text/event-stream。本例只解析配套服务端产生的 LF 行尾子集。接入一般 SSE 来源时,解析器还要支持 CR、CRLF、注释、多行数据与字段规则。本例约定每帧由 event: 事件名、data: JSON 数据及末尾空行组成;delta.text 是新增内容,done 是成功终止信号,error.message 是业务失败原因。服务器实际发送的成功流如下:

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

event: delta
data: {"text":",世界"}

event: done
data: {}

前端为每条助手消息单独保留 content、status、error。五种状态必须有明确进入条件:

状态 进入条件 界面动作
pending 请求发起、首片段未到 显示等待,允许取消
streaming 收到首个 delta 将新文本追加到当前消息
completed 明确收到 done 且有可读正文 停止加载,标记完整回答
failed error、HTTP 错误、解析异常或无 done 断流 保留已收到内容,显示失败原因
cancelled 用户调用 abort() 且没有已处理的终止事件 保留片段,标记已停止接收

浏览器、SSE 服务端与消息状态在正常完成、错误和取消时的交互时序

网络的一次读取可能只含半帧,甚至把一个中文字符的 UTF-8 字节拆开。要先解码并缓存,直到完整空行分隔符出现再解析 JSON;连接关闭不等于收到 done。

用 Node.js 模拟 SSE 服务端

准备 Node.js 20 或更高版本。在同一文件夹保存下面的 server.mjs 与下一节的 index.html。服务端每 500 毫秒发送一次事件;mode=fail 会在两个片段后发送业务错误,mode=drop 则提前断流,供验收使用。

js
import { createServer } from 'node:http';
import { readFile } from 'node:fs/promises';

const server = createServer(async (req, res) => {
  if (req.method === 'GET' && req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
    res.end(await readFile(new URL('./index.html', import.meta.url)));
    return;
  }
  if (req.method !== 'POST' || !req.url?.startsWith('/stream')) {
    res.writeHead(404).end('Not Found');
    return;
  }

  // 本地读取提问;真实服务应接入模型输出而非定时器。
  const parts = [];
  let size = 0;
  for await (const chunk of req) {
    size += chunk.length;
    if (size > 16_384) {
      res.writeHead(413).end('Request too large');
      return;
    }
    parts.push(chunk);
  }
  const raw = Buffer.concat(parts).toString('utf8');
  let prompt;
  try { prompt = JSON.parse(raw).prompt; }
  catch { res.writeHead(400).end('Bad JSON'); return; }
  if (typeof prompt !== 'string' || !prompt.trim()) {
    res.writeHead(400).end('Prompt required');
    return;
  }

  const mode = new URL(req.url, 'http://localhost').searchParams.get('mode');
  res.writeHead(200, {
    'Content-Type': 'text/event-stream; charset=utf-8',
    'Cache-Control': 'no-cache, no-transform',
    'Connection': 'keep-alive',
    'X-Accel-Buffering': 'no'
  });
  res.flushHeaders();
  const chunks = ['收到问题:', prompt.trim().slice(0, 80), '\n这是模拟生成的回答。'];
  let i = 0;
  const send = (event, data) => res.write(
    `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
  );
  const timer = setInterval(() => {
    if (mode === 'fail' && i === 2) {
      send('error', { message: '模拟上游服务失败' });
      clearInterval(timer);
      res.end();
    } else if (mode === 'drop' && i === 2) {
      clearInterval(timer);
      res.end(); // 故意缺少 done,模拟意外断流。
    } else if (i < chunks.length) {
      send('delta', { text: chunks[i++] });
    } else {
      send('done', {});
      clearInterval(timer);
      res.end();
    }
  }, 500);
  // 浏览器停止读取时清理定时器,避免继续写已关闭的连接。
  res.on('close', () => clearInterval(timer));
});
server.listen(3000, '127.0.0.1', () => {
  console.log('http://127.0.0.1:3000');
});

这里的 Cache-Control: no-cache, no-transform 与 X-Accel-Buffering: no 用于减少中间层缓冲;代理是否实际透传仍需在部署环境验证。res.on('close') 清理演示定时器,真实模型服务还应向上游传播取消信号。

在浏览器中解析并增量渲染

把下面代码保存为 index.html。示例用 fetch 发起 POST,适合携带提问正文并使用 AbortController;原生 EventSource 则主要面向 GET,遇到断线还会尝试自动重连。这里使用 TextDecoderStream 处理 UTF-8,再以空行拆出 SSE 帧。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>SSE 流式回答</title>
</head>
<body>
  <input id="prompt" value="SSE 有什么用?" aria-label="提问">
  <button id="start">开始</button>
  <button id="fail">模拟服务端错误</button>
  <button id="drop">模拟断流</button>
  <button id="cancel" disabled>取消</button>
  <p id="status" role="status">未开始</p>
  <pre id="answer" style="white-space:pre-wrap"></pre>
  <script>
    const $ = id => document.getElementById(id);
    const buttons = ['start', 'fail', 'drop'].map($);
    const labels = {
      pending: '等待首段', streaming: '生成中', completed: '已完成',
      failed: '失败', cancelled: '已停止接收'
    };
    let active = null;
    let message = { content: '', status: 'idle', error: '' };
    function render() {
      $('answer').textContent = message.content;
      const status = (labels[message.status] || '未开始')
        + (message.error ? ':' + message.error : '');
      if ($('status').textContent !== status) $('status').textContent = status;
    }

    async function generate(mode = '') {
      if (active) return;
      const controller = new AbortController();
      active = controller;
      message = { content: '', status: 'pending', error: '' };
      buttons.forEach(button => button.disabled = true);
      $('cancel').disabled = false;
      render();
      let terminal = false;
      try {
        const url = '/stream' + (mode ? '?mode=' + mode : '');
        const response = await fetch(url, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ prompt: $('prompt').value }),
          signal: controller.signal
        });
        if (!response.ok) throw new Error('HTTP ' + response.status);
        if (!response.body) throw new Error('响应不支持流式读取');
        const mediaType = response.headers.get('Content-Type')?.split(';', 1)[0].trim().toLowerCase();
        if (mediaType !== 'text/event-stream') {
          throw new Error('不是 SSE 响应');
        }

        let buffer = '';
        // 网络字节块可能拆开一个事件帧,先缓存到空行边界。
        stream: for await (const text of response.body.pipeThrough(new TextDecoderStream())) {
          buffer += text;
          let boundary;
          while ((boundary = buffer.indexOf('\n\n')) >= 0) {
            const frame = buffer.slice(0, boundary);
            buffer = buffer.slice(boundary + 2);
            const lines = frame.split('\n');
            const name = lines.find(line => line.startsWith('event:'))
              ?.slice(6).trim();
            const json = lines.filter(line => line.startsWith('data:'))
              .map(line => line.slice(5).trimStart()).join('\n');
            if (!name || !json) continue;
            const data = JSON.parse(json);
            if (name === 'delta') {
              if (typeof data.text !== 'string') throw new Error('delta.text 无效');
              message.content += data.text;
              message.status = 'streaming';
              render(); // textContent 防止片段内容被当作 HTML 执行。
            } else if (name === 'done' || name === 'error') {
              if (name === 'done' && !message.content.trim()) throw new Error('未收到可读回复');
              terminal = true;
              message.status = name === 'done' ? 'completed' : 'failed';
              message.error = name === 'error' ? data.message || '生成失败' : '';
              render();
              break stream;
            }
          }
        }
        // 连接结束不代表生成成功,必须有终止事件。
        if (!terminal) throw new Error('流提前结束,未收到 done');
      } catch (error) {
        // 已收到终止事件后,不让迟到的取消覆盖最终状态。
        if (!terminal) {
          message.status = controller.signal.aborted ? 'cancelled' : 'failed';
          message.error = controller.signal.aborted ? '' : error.message;
          render();
        }
      } finally {
        active = null;
        buttons.forEach(button => button.disabled = false);
        $('cancel').disabled = true;
      }
    }
    $('start').onclick = () => generate();
    $('fail').onclick = () => generate('fail');
    $('drop').onclick = () => generate('drop');
    $('cancel').onclick = () => {
      if (active && ['pending', 'streaming'].includes(message.status)) active.abort();
    };
  </script>
</body>
</html>

收到 delta 时只追加 data.text,使用 textContent 防止生成文本被当作 HTML 执行;收到 done 或业务 error 立即结束当前轮。catch 将用户取消与真正失败区分开,finally 恢复按钮,让生成结束后不再能触发取消。同一时间只允许一个活动请求,防止多个流写入同一条消息。

运行并验收四种收尾

在这两个文件所在的目录执行:

bash
node server.mjs

预期输出:

text
http://127.0.0.1:3000

在浏览器打开该本地地址,默认输入为“SSE 有什么用?”。按下面顺序检查:

操作 应观察到的结果
点击“开始” “等待首段”变为“生成中”,文字逐段出现,最后“已完成”
点击“模拟服务端错误” 出现两个片段后显示“失败:模拟上游服务失败”
点击“模拟断流” 出现两个片段后显示“失败:流提前结束,未收到 done”
点击“开始”后立即点击“取消” 显示“已停止接收”;保留已收到的片段

可以在浏览器开发者工具的 Network 面板查看 /stream 请求:HTTP 200 只表示连接建立成功,不表示回答已完成。若点击时浏览器已经处理了有效的完成事件,最终状态保持“已完成”。停止接收时界面不推断远端任务的执行结果。

接入真实模型接口的边界

本例是受控的 LF(\n)换行 SSE 演示解析器。真实接口可能使用 CRLF 换行、注释心跳、多行 data:、id: 和重连语义;接入时应使用经过测试的 SSE 解析器或补齐协议兼容处理,不能假定 read() 每次返回一个事件。若遇到大量高频细片段,可把内容先加入缓冲,再用 requestAnimationFrame 合并 DOM 更新。

生产环境还要核对网关是否启用响应缓冲、客户端取消后上游生成是否真的停止、断流后是否允许重试。重试应创建新消息轮次或依据服务端事件 ID 去重,不应把重放的 delta 直接拼到旧内容末尾。验收标准是:只有明确收到 done 且有可读正文才显示完整回答;其余退出路径都可辨认,并保留可解释的已生成片段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

通过 SSE 渲染逐步生成的回复

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通