Web Streams API 如何把搜索结果增量渲染到页面：ReadableStream 与 backpressure 边界

搜索页最让人焦虑的不是接口慢，而是接口已经返回了第一条结果，页面却要等完整 JSON 到齐才开始显示。浏览器的 Response.body 本身就是一个 ReadableStream，只要服务端按换行输出 JSON，前端就能在每个数据块到达时解析一条结果并更新列表。

先把一次性 JSON 改成逐行结果

示例协议采用 NDJSON：服务端每输出一条搜索结果就写一行 JSON，例如 {"title":"Web Streams API","url":"/docs/streams"}。这不是浏览器强制要求的格式，而是为了让边界明确；如果一条 JSON 被拆成两个网络块，前端也要等到换行出现后再解析。

async function streamSearch(url, renderItem, signal) {
  const response = await fetch(url, { signal });
  if (!response.ok || !response.body) {
    throw new Error(`search response unavailable: ${response.status}`);
  }

  const reader = response.body
    .pipeThrough(new TextDecoderStream())
    .getReader();
  let pending = '';

  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      pending += value;
      const lines = pending.split('\n');
      pending = lines.pop() ?? '';
      for (const line of lines) {
        if (line.trim()) renderItem(JSON.parse(line));
      }
    }
    if (pending.trim()) renderItem(JSON.parse(pending));
  } finally {
    reader.releaseLock();
  }
}

这里的调用链是 fetch → response.body → TextDecoderStream → reader.read。pending 专门保存当前块最后那段不完整文本；把它直接交给 JSON.parse，恰好会在网络分块位置随机报错。

为什么 TextDecoderStream 要放在解析器前面

response.body 读取到的是字节块，不保证一个中文字符刚好落在一个块里。TextDecoderStream 将跨块的 UTF-8 字节接续成字符串，之后的换行切分才有可靠输入。解析器只关心换行和 JSON，不需要自己维护字节级解码状态。

如果运行环境没有 TextDecoderStream，可以在 reader.read 循环中复用同一个 TextDecoder，并传入 { stream: true }。关键是不能每次收到块都新建解码器，否则多字节字符被拆开时仍会损坏。

把结果追加到页面，而不是反复重建列表

const results = document.querySelector('#results');
const controller = new AbortController();

function renderItem(item) {
  const li = document.createElement('li');
  li.textContent = `${item.title} — ${item.url}`;
  results.append(li);
}

document.querySelector('#cancel').addEventListener('click', () => {
  controller.abort();
});

streamSearch('/api/search?q=streams', renderItem, controller.signal)
  .catch(error => {
    if (error.name !== 'AbortError') console.error(error);
  });

renderItem 每次只创建一个 li，不会因为新结果到达就把已有节点全部重绘。取消按钮调用 AbortController.abort 后，reader.read 的等待会结束并进入 finally，页面可以把“已取消”状态和已显示结果保留下来。

自定义 ReadableStream 时看懂 desiredSize

网络响应是现成的可读流；当你需要把分页请求、Worker 消息或本地缓存封装成流时，才会直接创建 ReadableStream。生产端的 pull() 在消费者需要更多数据时获得机会，controller.desiredSize 反映内部队列距离高水位还有多少空间。

function resultStream(loadPage) {
  let page = 1;
  return new ReadableStream({
    async pull(controller) {
      if (controller.desiredSize 

这段代码里，pull() 先检查 controller.desiredSize，再把页面结果通过 controller.enqueue 放入队列。当下游消费变慢，期望大小降到零或更低，生产端就进入 backpressure 边界，不应继续无条件加载下一页。真实项目还要加“加载中”状态，避免一次 pull() 尚未完成时又启动同一页请求。

三个容易被忽略的验收边界

• 半条 JSON：人为让服务端在字符串中间断开输出，确认 pending 会跨块拼接，而不是提前解析。
• 慢消费者：让 renderItem 排队处理，观察生产端是否仍按 desiredSize 控制读取节奏。
• 取消与坏数据：中途点击取消，并让一行变成非法 JSON，确认既不会吞掉取消，也不会把错误行悄悄当成成功结果。

浏览器 Streams 标准还定义了锁定、管道和错误传播语义。一个流被 getReader() 锁定后，不能同时交给另一个 reader 或随意再次 pipeTo()；读取结束、异常和取消应当在同一条链路里设计。

常见问题

Response.body 和 response.json() 能同时调用吗？

不能把同一个响应体当成两条独立输入。选择增量读取就使用 response.body，需要完整对象时才调用 response.json()。

为什么 JSON.parse 偶尔遇到 Unexpected end of JSON input？

常见原因是网络块刚好截断了一条 JSON。保留 pending，只在收到换行或流结束时解析完整记录即可。

desiredSize 小于等于零时应该立刻关闭流吗？

不应该。它表示下游暂时承受不了更多入队数据，生产端应暂停或等待下一次 pull()；只有业务确认没有更多数据时才调用 controller.close()。

把增量显示做成可恢复的用户体验

增量渲染的价值不是把接口拆成更多小请求，而是让“第一条结果可见”早于“最后一条结果到达”。用 Response.body 读取字节流，用 TextDecoderStream 处理跨块文本，用 pending 守住记录边界，再用 desiredSize 约束自定义生产端，搜索列表才会在快、慢、取消和坏数据四种场景下都保持可解释。