在前端应用中,接口返回的数据并不总是很小。
例如,后台系统可能需要下载数十万条日志记录,数据分析页面需要读取大量文本,或者某些服务会持续返回新的业务事件。
如果等待全部响应下载完成后再调用 response.text() 或 response.json(),用户就必须等到整个响应结束才能看到结果。
对于数据量较大的场景,Streams API 提供了按数据块读取和处理响应的能力。
本文以一个实时日志查看器为例,介绍 Fetch API 的流式响应、TextDecoderStream、增量解析、取消请求和内存控制。
一、传统请求和流式请求的区别
普通 Fetch 请求经常采用以下写法:
async function loadLogs() {
const response = await fetch("/api/logs");
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
return response.text();
}
这种方式会等待完整响应内容被读取后,才返回文本结果。
对于小型接口来说,这通常没有问题。
但如果响应包含大量日志,页面可能长时间没有任何进度反馈,并且需要在内存中保存完整响应。
使用 Streams API,可以在数据到达时逐块处理,不必一次性读取全部内容。
二、创建日志查看器界面
首先定义一个日志面板,包括标题、操作按钮和日志显示区域。
<section class="log-viewer" data-log-viewer>
<h1>实时日志查看器</h1>
<div class="log-toolbar">
<button type="button" data-start>
开始读取
</button>
</div>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
日志查看器应当将数据处理与界面展示分离。
网络模块负责接收数据,解析模块负责还原记录,渲染模块只负责展示需要显示的日志。
这种结构能够避免网络读取逻辑与 DOM 更新紧密耦合。
三、理解 ReadableStream
当 Fetch 请求成功时,response.body 通常提供一个 ReadableStream。
可以通过 getReader() 获取读取器,并使用 read() 持续读取数据块。
async function readResponseStream(response) {
if (!response.body) {
throw new Error("当前响应不支持流式读取");
}
const reader = response.body.getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) {
break;
}
console.log("收到数据块:", value.byteLength);
}
} finally {
reader.releaseLock();
}
}
每次 read() 返回一个对象,包含 done 和 value。
当 done 为 true 时,表示数据流已经结束。
实际收到的数据块大小并不固定,也不保证与服务端每次写入的数据边界完全一致。
因此,应用不能假设一个数据块一定对应一条完整日志。
四、使用 TextDecoderStream 解码文本
Fetch 接收到的数据块通常是 Uint8Array。
如果业务需要处理 UTF-8 文本,可以使用 TextDecoderStream 将字节流转换为字符串流。
async function readTextStream(response, onChunk) {
if (!response.body) {
throw new Error("响应正文不可读取");
}
const textStream = response.body.pipeThrough(
new TextDecoderStream()
);
const reader = textStream.getReader();
try {
while (true) {
const result = await reader.read();
if (result.done) {
break;
}
onChunk(result.value);
}
} finally {
reader.releaseLock();
}
}
TextDecoderStream 能够正确处理跨数据块的 UTF-8 字符。
例如,一个中文字符的字节序列可能被拆分到两个不同的网络数据块中。
如果对每个字节块独立调用普通文本解码函数,可能出现字符解析异常。
流式解码能够处理这种情况。
五、实现日志实时展示
接下来增加一个日志展示容器。
<section class="log-output-panel">
<h2>日志输出</h2>
<div
class="log-output"
data-log-output
role="log"
aria-live="polite"
></div>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
这里使用 role="log" 描述持续更新的日志区域。
为了避免一次性创建大量 DOM 节点,可以先定义统一的日志追加函数。
const logOutput = document.querySelector(
"[data-log-output]"
);
const maxVisibleRows = 500;
function appendLogLine(text) {
const item = document.createElement("div");
item.className = "log-line";
item.textContent = text;
logOutput.appendChild(item);
while (logOutput.childElementCount > maxVisibleRows) {
logOutput.firstElementChild.remove();
}
}
这里使用 textContent 显示日志内容,避免日志中的 HTML 字符串被当作页面代码执行。
同时限制界面保留的日志条数,防止长时间运行后 DOM 节点无限增长。
实际项目中,保留数量可以由用户配置,并结合虚拟列表进一步优化。
六、正确处理跨数据块的换行
假设服务端按行返回日志:
2026-11-16 10:00:01 服务启动
2026-11-16 10:00:02 数据库连接成功
2026-11-16 10:00:03 开始处理任务
网络层可能把其中一行拆成多个数据块。
因此不能直接认为每次 read() 返回的字符串就是完整的一行。
可以使用一个缓冲区保存未完成的文本:
function createLineParser(onLine) {
let buffer = "";
return {
write(chunk) {
buffer += chunk;
const lines = buffer.split(/\r?\n/);
buffer = lines.pop() ?? "";
for (const line of lines) {
onLine(line);
}
},
flush() {
if (buffer) {
onLine(buffer);
}
buffer = "";
}
};
}
当新的数据块到达时,将其追加到缓冲区。
随后根据换行符拆分内容,完整的行立即处理,最后尚未完成的部分继续保留。
直到流结束,再调用 flush() 处理最后一行。
七、组合 Fetch 与行解析器
现在将网络读取和行解析组合起来。
增加一个加载状态区域:
<section class="stream-status-panel">
<h2>读取状态</h2>
<p
data-stream-status
role="status"
aria-live="polite"
>
尚未开始
</p>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
实现完整的读取函数:
const streamStatus = document.querySelector(
"[data-stream-status]"
);
async function streamLogs(signal) {
const response = await fetch("/api/logs/stream", {
signal,
cache: "no-store"
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const parser = createLineParser(appendLogLine);
await readTextStream(response, chunk => {
parser.write(chunk);
});
parser.flush();
streamStatus.textContent = "日志读取完成";
}
在这个示例中,网络读取只负责接收文本。
具体如何解释一行日志,由解析器决定。
如果服务端返回的是 JSON Lines 格式,也可以在 onLine 回调中对每一行分别调用 JSON.parse()。
不过,JSON Lines 与普通 JSON 数组不是同一种格式,解析逻辑不能混用。
八、增加取消功能
有些流式接口会持续发送数据,直到客户端主动断开。
例如,实时日志和持续事件通知服务可能不会主动结束响应。
此时需要支持用户取消。
先增加操作区域:
<section class="stream-actions">
<h2>读取控制</h2>
<button type="button" data-stop>
停止读取
</button>
<p data-control-message aria-live="polite"></p>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
然后使用 AbortController 控制请求生命周期:
let controller = null;
async function startStreaming() {
if (controller) {
return;
}
controller = new AbortController();
streamStatus.textContent = "正在读取日志";
try {
await streamLogs(controller.signal);
} catch (error) {
if (error.name === "AbortError") {
streamStatus.textContent = "读取已取消";
} else {
streamStatus.textContent = "读取失败";
console.error(error);
}
} finally {
controller = null;
}
}
function stopStreaming() {
controller?.abort();
}
绑定按钮:
document.querySelector(
"[data-start]"
).addEventListener("click", startStreaming);
document.querySelector(
"[data-stop]"
).addEventListener("click", stopStreaming);
AbortController 可以取消当前 Fetch 请求及相关的响应读取。
但是,它不能保证服务端已经执行的业务操作被撤销。
如果流式接口涉及任务执行、数据库写入或其他有状态操作,服务端仍然需要独立的任务取消机制。
九、如何显示下载进度?
对于具有确定长度的文件下载,可以通过已读取字节数计算进度。
页面中增加进度指示器:
<section class="download-progress">
<h2>传输进度</h2>
<progress
data-download-progress
value="0"
max="100"
></progress>
<output data-download-percent>
0%
</output>
</section>
<a href="https://www.yxtiktok.com/blog/guides/">
计算方式:
function calculateProgress(loadedBytes, totalBytes) {
if (!Number.isFinite(totalBytes) || totalBytes <= 0) {
return null;
}
return Math.min(
100,
Math.round((loadedBytes / totalBytes) * 100)
);
}
如果响应提供了有效的 Content-Length,就可以结合实际读取的字节数计算百分比。
但需要注意,部分接口使用分块传输或压缩响应,可能没有可用的总长度。
对于这些情况,应该显示“不确定进度”的加载状态,而不是伪造一个百分比。
十、避免长时间运行造成内存增长
流式读取并不意味着整个应用一定具有较低内存占用。
如果程序不断把数据块追加到一个无限增长的数组中,最终仍然可能耗尽浏览器可用内存。
例如,下面的做法并不适合无限数据流:
const chunks = [];
function collectChunk(chunk) {
chunks.push(chunk);
}
如果数据持续到达,chunks 会不断增长。
更合理的方式是根据业务需要立即处理数据,并限制内存中保留的历史记录数量。
对于大文件下载,还可以考虑浏览器支持的文件写入能力或其他分块保存方案,避免把完整文件全部缓存在内存中。
需要注意,Streams API 具备背压机制,但只有在生产者、转换器和消费者正确配合时,才能有效控制数据积压。
十一、Streams API 的适用场景
Streams API 比较适合以下需求:
- 大型文本文件分块读取。
- 服务器日志实时展示。
- 持续返回的 AI 生成内容。
- 大型数据导出。
- 网络传输进度显示。
- 持续处理 JSON Lines 数据。
但对于几十 KB 的普通 JSON 接口,直接使用 response.json() 往往更加简单。
并不是所有接口都需要流式处理。
此外,流式读取方式必须与服务端响应格式匹配。
例如,Server-Sent Events 具有自己的事件格式与重连语义,通常可以优先考虑 EventSource,而不是自行实现完整的 SSE 协议解析。
十二、总结
JavaScript Streams API 让前端能够在数据尚未全部下载完成时就开始处理内容。
通过 ReadableStream、TextDecoderStream、增量解析器和 AbortController,可以构建支持实时展示、取消请求和资源控制的数据处理组件。
在实际开发中,需要重点关注数据块边界、编码处理、DOM 数量、内存增长和异常恢复。
对于高吞吐量或长时间运行的前端系统,合理使用流式处理机制,能够减少等待完整响应的时间,并提供更加及时的用户反馈。