交互与用户体验 / 系统课时
通过 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 是业务失败原因。服务器实际发送的成功流如下:
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() 且没有已处理的终止事件 |
保留片段,标记已停止接收 |

网络的一次读取可能只含半帧,甚至把一个中文字符的 UTF-8 字节拆开。要先解码并缓存,直到完整空行分隔符出现再解析 JSON;连接关闭不等于收到 done。
用 Node.js 模拟 SSE 服务端
准备 Node.js 20 或更高版本。在同一文件夹保存下面的 server.mjs 与下一节的 index.html。服务端每 500 毫秒发送一次事件;mode=fail 会在两个片段后发送业务错误,mode=drop 则提前断流,供验收使用。
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 帧。
<!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 恢复按钮,让生成结束后不再能触发取消。同一时间只允许一个活动请求,防止多个流写入同一条消息。
运行并验收四种收尾
在这两个文件所在的目录执行:
node server.mjs预期输出:
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 且有可读正文才显示完整回答;其余退出路径都可辨认,并保留可解释的已生成片段。