1. 从“等全部”到“来一点”:为什么我们需要流式渲染?
不知道你有没有遇到过这种场景:你打开一个网页,页面中间有个大大的加载圈,转啊转,转了十几秒,内容才“唰”的一下全部显示出来。或者,你在使用一些AI对话工具,问了一个复杂的问题,然后你就盯着光标,等了半天,它才把一整段答案吐给你。这种体验,说实话,挺糟糕的。用户会焦虑,会怀疑是不是卡住了,甚至可能直接关掉页面。
这就是传统“一次性请求-一次性渲染”模式的痛点。前端一次性从后端拿到所有数据,然后一次性渲染到页面上。数据量小还好,一旦数据量大,或者生成速度慢(比如大语言模型生成长文本、实时日志流),用户就只能干等着。
而流式渲染,就是为了解决这个“等待焦虑”而生的。它的核心思想很简单:别等饭全做好了再上菜,厨师炒好一个菜,你就先吃一个。对应到技术上,就是服务器一边生成数据,一边通过网络流(Stream)一点点地发送给浏览器;浏览器收到一点,就解析一点,渲染一点。用户几乎在请求发出去的同时,就能看到内容开始“生长”出来。
这种体验的提升是巨大的。对于内容生成类应用(如AI写作、代码补全),用户能看到思考过程,更有掌控感;对于监控类应用(如服务器日志、实时数据看板),信息能近乎实时地更新,决策更及时。
那么,在前端,我们用什么技术来接住服务器“涓涓细流”般的数据呢?答案就是 ReadableStream API,而 getReader() 方法,就是我们握住这根“水管”,开始接水的关键动作。它能让我们以异步、非阻塞的方式,一块一块地读取流中的数据,并随时可以关上水龙头——这就是“中断控制”。接下来,我就带你一步步拆解,如何用这个强大的API,打造流畅可控的流式渲染体验。
2. 核心武器拆解:读懂ReadableStream与getReader
在动手写代码之前,我们得先搞清楚手里的工具到底是怎么回事。很多人一上来就复制代码,结果遇到问题一头雾水。我把我的理解掰开揉碎了讲给你听,保证你能听懂。
2.1 ReadableStream:它到底是什么?
你可以把 ReadableStream 想象成一条传送带。这条传送带连接了服务器和你的浏览器。服务器那边,有一个“生产者”在不断把数据块(比如一段文本、一行日志)放到传送带起点;浏览器这边,你这个“消费者”就站在传送带终点,准备把过来的数据块拿走处理。
这条传送带有几个关键特性:
- 异步的:数据什么时候来,来多少,你不知道,也不用一直等着。你只需要告诉传送带:“有货来了就叫我”。
- 有序的:数据块按照服务器放上去的顺序依次到达,不会乱序。
- 一次性的:通常,一条流的数据被读取完后,就不能再读第二次了(当然,你可以通过某些技术实现“重播”,但那不是标准用法)。
在Web开发中,最常见的 ReadableStream 来源就是 Fetch API 的 Response 对象。当你用 fetch() 请求一个支持流式传输的接口时,response.body 属性就是一个 ReadableStream 对象。这就是我们操作的入口。
2.2 getReader():如何从传送带上取货?
传送带有了,你怎么把上面的货拿下来呢?用手直接抓吗?不行,那样不标准,也可能出错。ReadableStream 提供了一个标准方法:getReader()。
调用 response.body.getReader() 会发生两件重要的事:
- 创建一个读取器(Reader):这个读取器就是你的“机械手”,专门用来从这条传送带上抓取数据块。
- 锁定这个流:这条传送带被你“独占”了。在你释放这个读取器(比如读取完成,或者主动取消)之前,其他任何代码都不能再从这个流里读取数据。这保证了数据消费的有序性和安全性,避免多个消费者抢数据导致混乱。
创建好读取器后,你就可以使用它的 read() 方法了。这个方法返回一个 Promise。当传送带上有新的数据块到达,或者到达了尽头(所有数据发送完毕),这个 Promise 就会完成,并返回一个结果对象。
这个结果对象长这样:{ done: boolean, value: Uint8Array }
done:一个布尔值。如果为true,表示传送带已经走到头了,所有数据都传送完毕,流已经关闭。此时value是undefined。value:一个Uint8Array类型的值。这就是你抓取到的“数据块”。但注意,它通常是经过编码的字节数据,对于文本数据,我们需要解码才能看懂。
2.3 实战第一步:创建一个最简单的流式读取
光说不练假把式,我们直接看一段最基础的代码,感受一下这个过程。假设我们有一个返回流式文本的接口 /api/stream。
async function fetchStream() {
// 1. 发起fetch请求
const response = await fetch('/api/stream');
// 2. 从response中获取ReadableStream并创建读取器
const reader = response.body.getReader();
// 3. 创建一个TextDecoder,用于将字节数据解码成字符串
const decoder = new TextDecoder('utf-8');
// 4. 定义一个递归函数来持续读取
function read() {
// reader.read() 返回一个Promise
return reader.read().then(({ done, value }) => {
// 情况A:流结束了
if (done) {
console.log('Stream finished.');
return;
}
// 情况B:收到了数据块
// value 是 Uint8Array,需要解码
const chunk = decoder.decode(value);
console.log('Received chunk:', chunk);
// 在这里!你可以把chunk渲染到页面上
// 例如:document.getElementById('output').innerHTML += chunk;
// 递归调用read,继续读取下一个数据块
return read();
});
}
// 5. 开始读取
read().catch(error => {
console.error('Stream reading failed:', error);
});
}
// 调用函数
fetchStream();
这段代码就是一个最核心的流式读取骨架。它做了以下几件事:发起请求、锁定流、创建解码器、然后进入一个“读取-处理-再读取”的循环,直到流结束。你现在可以尝试把注释掉的渲染行打开,就能看到文字一段一段出现的效果了。
3. 实现动态渲染:让数据在屏幕上“流”起来
掌握了基础的读取方法,我们现在要解决核心问题:如何把读取到的数据块,流畅地、动态地更新到网页上?这里面的门道,可不仅仅是 innerHTML += 那么简单。
3.1 基础渲染:拼接与展示
最直接的方法,就像上面代码注释里写的,找到一个DOM元素,然后不断把新的文本块(chunk)追加进去。
const outputEl = document.getElementById('output');
function renderChunk(chunkText) {
outputEl.innerHTML += chunkText;
}
这种方法简单粗暴,在数据块是纯文本且顺序追加的场景下,勉强可用。但它有严重问题:每次 innerHTML += 操作都会导致整个元素的重排(Reflow)和重绘(Repaint)。如果数据流很快,频繁的DOM更新会严重消耗性能,页面可能会卡顿。而且,如果输出区域内容很多,频繁的全文替换也可能导致滚动位置跳动,体验很差。
3.2 进阶优化:使用文档片段与文本节点
为了提升性能,我们可以采用更精细的DOM操作方式。
方案一:使用 DocumentFragment(文档片段)
文档片段是一个存在于内存中的轻量级DOM容器。我们可以先把多次更新累积在片段里,最后一次性地插入到真实DOM中,从而减少重排次数。
const outputEl = document.getElementById('output');
const fragment = document.createDocumentFragment();
let buffer = ''; // 用于累积较小的数据块
function flushBufferToFragment() {
if (buffer) {
const textNode = document.createTextNode(buffer);
fragment.appendChild(textNode);
buffer = '';
}
}
function renderChunkOptimized(chunkText) {
buffer += chunkText;
// 假设我们每累积100个字符,或者每收到5个数据块,刷新一次
if (buffer.length > 100) {
flushBufferToFragment();
// 将文档片段一次性追加到页面
outputEl.appendChild(fragment);
}
}
// 在流读取结束时,确保清空缓冲区
function onStreamFinish() {
flushBufferToFragment();
outputEl.appendChild(fragment);
console.log('渲染完毕。');
}
方案二:直接操作文本节点 如果我们只是追加纯文本,更高效的方法是直接找到最后一个文本节点进行修改,或者持续向同一个文本节点追加内容。
const outputEl = document.getElementById('output');
// 确保outputEl初始有一个空的文本节点
outputEl.textContent = '';
let textNode = outputEl.firstChild || document.createTextNode('');
if (!outputEl.firstChild) {
outputEl.appendChild(textNode);
}
function renderChunkToTextNode(chunkText) {
// 直接修改文本节点的内容
textNode.nodeValue += chunkText;
}
这种方法性能极好,因为它只修改了单个节点的文本内容,触发的重排重绘范围最小。对于纯文本流式渲染,这是我个人最推荐的方法。
3.3 处理结构化数据:JSON序列与复杂UI
很多时候,服务器返回的不是纯文本,而是结构化的数据块,比如你提供的例子:一个包含 code 和 chunk 的JSON对象数组。我们需要先解析,再渲染。
async function readAndRenderStream() {
const response = await fetch('/api/stream-json');
const reader = response.body.getReader();
const decoder = new TextDecoder();
const outputEl = document.getElementById('output');
function read() {
return reader.read().then(({ done, value }) => {
if (done) {
console.log('Stream finished.');
return;
}
// 1. 解码字节流得到JSON字符串
const jsonString = decoder.decode(value);
try {
// 2. 解析JSON字符串
const dataChunk = JSON.parse(jsonString);
// 3. 根据数据结构进行渲染
// 假设 dataChunk 是 { "header": { "code": "200" }, "chunk": "一段文字" }
if (dataChunk.header && dataChunk.header.code === '200') {
const chunkText = dataChunk.chunk;
// 使用优化的文本节点方式渲染
renderChunkToTextNode(chunkText);
} else {
console.error('Received error chunk:', dataChunk);
// 这里可以处理错误,比如显示错误信息,甚至中断流
}
} catch (e) {
console.error('Failed to parse chunk JSON:', e, 'Raw string:', jsonString);
}
// 4. 继续读取
return read();
});
}
await read();
}
对于更复杂的UI,比如每个数据块要渲染成一个独立的列表项(<li>)或者消息气泡,思路也是一样的:解析数据 -> 创建对应的DOM元素 -> 插入到容器中。为了性能,同样可以考虑使用 DocumentFragment 进行批量插入。
4. 掌控流程:实现用户主动中断(cancel)
流式渲染的魅力不仅在于“流进来”,更在于可以“停下来”。想象一下,AI生成了你不想要的内容,或者日志刷得太快你想仔细看某一段,这时一个“停止生成”或“暂停”按钮就至关重要。这就是 ReadableStream 和 getReader() 带给我们的另一个强大能力:中断控制。
4.1 cancel()方法的工作原理
还记得我们通过 getReader() 获得的那个 reader 对象吗?它有一个 cancel(reason) 方法。调用这个方法,就等于你对着传送带喊:“停!后面的货我不要了!”
它的行为非常明确:
- 立即关闭流:流会被标记为已取消,之后
reader.read()返回的 Promise 会立刻解决,且done为true。 - 丢弃未读数据:传送带上还没被读取的数据块会被丢弃。浏览器也会通知服务器这边消费端已经关闭,服务器理论上应该停止生成和发送数据(这取决于后端实现)。
- 返回一个Promise:
cancel()方法本身返回一个 Promise,当流确认被取消后,这个 Promise 会兑现。
4.2 在前端实现中断按钮
结合一个简单的UI按钮,我们可以轻松实现中断功能。关键在于,我们需要让 reader 变量在渲染函数的作用域之外也能被访问到。
// 在组件或模块的顶层作用域声明reader变量
let currentStreamReader = null;
// 开始流式请求和渲染的函数
async function startStreaming() {
const response = await fetch('/api/stream');
const reader = response.body.getReader();
currentStreamReader = reader; // 将reader赋值给外部变量
const decoder = new TextDecoder();
const outputEl = document.getElementById('output');
outputEl.textContent = '';
let textNode = document.createTextNode('');
outputEl.appendChild(textNode);
function read() {
// 每次读取前,可以检查一个外部状态标志
if (isStreamCancelled) {
console.log('Stream was cancelled, stopping read loop.');
return Promise.resolve(); // 直接返回一个已解决的Promise,跳出循环
}
return reader.read().then(({ done, value }) => {
if (done) {
console.log('Stream finished naturally.');
currentStreamReader = null; // 清理引用
return;
}
const chunkText = decoder.decode(value);
textNode.nodeValue += chunkText;
// 继续递归读取
return read();
});
}
try {
await read();
} catch (error) {
console.error('Error during streaming:', error);
currentStreamReader = null;
}
}
// 中断流的函数
function cancelStreaming() {
if (currentStreamReader) {
console.log('User requested to cancel the stream.');
// 调用cancel方法
currentStreamReader.cancel('User cancelled').then(() => {
console.log('Stream has been successfully cancelled.');
currentStreamReader = null;
// 可以在这里更新UI状态,比如把按钮文字从“停止”变回“开始”
document.getElementById('stopBtn').disabled = true;
document.getElementById('startBtn').disabled = false;
}).catch(err => {
console.error('Error cancelling stream:', err);
});
}
}
// 绑定按钮事件
document.getElementById('startBtn').addEventListener('click', startStreaming);
document.getElementById('stopBtn').addEventListener('click', cancelStreaming);
4.3 处理中断后的状态与清理
中断流不仅仅是调用一个方法。良好的用户体验需要我们处理好中断后的状态:
- UI状态同步:停止按钮应该变灰或消失,开始按钮恢复可用。可以显示“已停止”的提示。
- 清理工作:将
currentStreamReader置为null,防止内存泄漏。如果使用了辅助变量(如isStreamCancelled标志),也要重置。 - 错误处理:
cancel()也可能失败(比如网络突然断开)。我们需要在.catch中处理这种异常,并给用户适当的反馈。 - 与后端的协作:理想情况下,前端调用
cancel()后,浏览器会向服务器发送一个信号。一个设计良好的后端接口应该在收到这个信号后,停止后续的计算和传输,节省服务器资源。但这需要前后端协议的支持。
5. 避坑指南与高级技巧
在实际项目中摸爬滚打几年,我踩过不少流式渲染的坑。这里分享几个关键点和进阶思路,希望能帮你绕开这些弯路。
5.1 常见问题与解决方案
问题一:流意外中断或网络错误
网络是不稳定的。流在传输过程中可能因为网络波动而断开。单纯的 reader.read() 循环在出错时会抛出异常,导致整个流程崩溃。
解决方案:用 try...catch 包裹整个读取逻辑,或者在 read().then().catch() 中处理错误。发生错误时,可以尝试重连(对于可重试的流),或者至少给用户一个友好的错误提示,而不是白屏或卡死。
function readWithRetry(reader, maxRetries = 3) {
let retryCount = 0;
function attemptRead() {
return reader.read().then(({ done, value }) => {
// 重置重试计数,因为本次读取成功了
retryCount = 0;
if (done) return;
// ... 处理value ...
return attemptRead(); // 继续读
}).catch(error => {
console.error('Read error:', error);
if (retryCount < maxRetries) {
retryCount++;
console.log(`Retrying... (${retryCount}/${maxRetries})`);
// 等待一段时间后重试
return new Promise(resolve => setTimeout(resolve, 1000 * retryCount))
.then(() => attemptRead());
} else {
// 重试次数用尽,向上抛出错误或进行最终处理
throw new Error(`Failed after ${maxRetries} retries: ${error.message}`);
}
});
}
return attemptRead();
}
问题二:数据解码乱码
TextDecoder 默认使用 UTF-8,但如果服务器返回的是其他编码(如 GBK),就会产生乱码。
解决方案:明确指定解码器的编码。你需要和后端确认数据流的编码格式。
// 如果后端明确使用GBK编码
const decoder = new TextDecoder('gbk');
问题三:内存增长 如果流非常长(比如一个巨大的文件),不断将数据块拼接成一个巨大的字符串可能会导致内存占用过高。 解决方案:采用“处理即丢弃”的策略。如果不需要保留完整的历史数据,可以在渲染后丢弃已处理的数据块引用。对于需要历史数据的场景,可以考虑分段存储或使用虚拟列表等技术,只渲染可视区域附近的内容。
5.2 性能优化:防抖、节流与渲染策略
即使使用了文本节点优化,极端高频的流(比如每毫秒一个数据块)仍然可能导致渲染线程过忙。
- 防抖(Debounce):不适合流式渲染,因为它会延迟最终输出,失去“实时”感。
- 节流(Throttle):一个更好的选择。我们可以设定一个最小时间间隔(比如50ms),在这个间隔内,累积收到的所有数据块,然后一次性渲染。这能在保持相对实时性的同时,大幅减少DOM操作频率。
let renderBuffer = '';
let renderScheduled = false;
const OUTPUT_EL = document.getElementById('output');
let outputTextNode = OUTPUT_EL.firstChild;
function scheduleRender(chunkText) {
renderBuffer += chunkText;
if (!renderScheduled) {
renderScheduled = true;
// 使用requestAnimationFrame在下一次浏览器绘制前渲染,效果更平滑
requestAnimationFrame(() => {
outputTextNode.nodeValue += renderBuffer;
renderBuffer = '';
renderScheduled = false;
});
}
// 如果不用requestAnimationFrame,用setTimeout做节流也可以
// if (!renderScheduled) {
// renderScheduled = true;
// setTimeout(() => {
// outputTextNode.nodeValue += renderBuffer;
// renderBuffer = '';
// renderScheduled = false;
// }, 50); // 每50ms渲染一次
// }
}
5.3 结合现代前端框架(Vue/React)
在Vue或React中,原理完全一样,只是状态管理和DOM更新的方式需要遵循框架的规则。
Vue 3 示例(使用Composition API):
<template>
<div>
<div ref="outputEl">{{ displayedText }}</div>
<button @click="startStream">开始</button>
<button @click="cancelStream" :disabled="!reader">停止</button>
</div>
</template>
<script setup>
import { ref, onUnmounted } from 'vue';
const displayedText = ref('');
const reader = ref(null); // 存储reader引用
async function startStream() {
displayedText.value = '';
const response = await fetch('/api/stream');
const streamReader = response.body.getReader();
reader.value = streamReader; // 存储起来以便取消
const decoder = new TextDecoder();
function read() {
return streamReader.read().then(({ done, value }) => {
if (done) {
reader.value = null;
return;
}
const chunk = decoder.decode(value);
// 在Vue中,直接更新响应式变量即可
displayedText.value += chunk;
return read();
}).catch(err => {
console.error(err);
reader.value = null;
});
}
read();
}
function cancelStream() {
if (reader.value) {
reader.value.cancel();
reader.value = null;
}
}
// 组件卸载时,自动取消流,防止内存泄漏
onUnmounted(() => {
cancelStream();
});
</script>
React 示例(使用函数组件与Hooks):
import { useState, useRef } from 'react';
function StreamRenderer() {
const [text, setText] = useState('');
const readerRef = useRef(null); // 使用ref存储reader,避免state更新导致丢失
const startStream = async () => {
setText('');
const response = await fetch('/api/stream');
const reader = response.body.getReader();
readerRef.current = reader;
const decoder = new TextDecoder();
const read = () => {
reader.read().then(({ done, value }) => {
if (done) {
readerRef.current = null;
return;
}
const chunk = decoder.decode(value);
// React中,使用函数式更新确保拿到最新状态
setText(prevText => prevText + chunk);
read(); // 继续读取
}).catch(err => {
console.error(err);
readerRef.current = null;
});
};
read();
};
const cancelStream = () => {
if (readerRef.current) {
readerRef.current.cancel();
readerRef.current = null;
}
};
return (
<div>
<div>{text}</div>
<button onClick={startStream}>开始</button>
<button onClick={cancelStream} disabled={!readerRef.current}>
停止
</button>
</div>
);
}
框架的核心思路是:将流读取的逻辑(包括 reader 的存储)与框架的响应式系统解耦。reader 通常用 ref(Vue)或 useRef(React)来存储,因为它本身不是需要触发视图更新的数据。而流的内容则通过更新响应式状态(ref/reactive 或 useState)来驱动UI变化。在组件销毁时,务必记得在生命周期钩子(如 onUnmounted、useEffect 的清理函数)中调用 cancel(),这是一个非常好的编程习惯,能有效避免潜在的内存泄漏和错误。
311



被折叠的 条评论
为什么被折叠?



