登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  文章 >  前端

Fetch 怎样逐块读取流式响应并处理完成信号

来源:17golang原创

时间:2026-11-17 00:45:52 107浏览 收藏

我在前端接入流式接口时,最容易遇到的现象不是“完全读不到”,而是页面先显示了一小段内容,随后既没有继续追加,也没有明确告诉用户已经结束。这个问题通常不是 Fetch 只返回了一块,而是代码没有持续调用 reader.read(),或者把最后一次返回的 done 信号漏掉了。

直接答案:先等待 fetch() 得到 Response,从 response.body 取得 ReadableStream,调用 getReader(),然后循环等待 reader.read()。每次 done 为 false 时处理 value;当 done 为 true 时,说明流自然结束。用户主动离开页面或点击停止,则用 AbortController 取消,不要把取消当成服务端正常完成。

官方资料:https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_streams

Fetch response.body 到 reader.read 的流式读取关系图
图1:Fetch 响应从 body 到 reader.read 的逐块读取结构图(原创说明图,不是运行截图)。

一、触发信号:为什么只显示第一块

fetch() 的 Promise 解决,通常只代表响应头已经可用,并不代表整个响应体已经读完。真正的响应体在 response.body 中,它是一个可读流;拿到流之后还要绑定 reader,并持续等待后续数据。

排查时我会先看下面三件事:

现象优先判断处理方向
body 为空当前响应没有可读取的流,或运行环境不提供记录状态并回退到普通响应处理
只处理了一次 read()只消费了第一块用循环再次调用 reader.read()
一直等不到“完成”把“收到一块”误当成“读取结束”只在 done === true 时收尾
停止后进入普通错误提示主动 abort 与网络错误没有分支通过 signal.aborted 区分用户取消

二、快速判断:response.body 和 reader 各自负责什么

response.body 是数据入口,getReader() 把这个入口交给一个 reader。reader 会锁定流,在锁释放前不能再用另一个 reader 读取同一条流。因此,代码里不要一边调用 response.text(),一边又调用 response.body.getReader();响应体只能按一种方式消费。

每次 read() 返回一个 Promise,解决值形如 { done, value }:

  • done: false:当前有一块数据,通常是 Uint8Array,交给业务处理。
  • done: true:流已经关闭,value 不再代表有效数据,执行一次收尾。
  • Promise 被拒绝:读取过程出错,进入异常分支;主动取消也可能从这里表现出来。

三、处理步骤:用 reader 循环逐块读取

下面这段函数适合把文本流追加到页面、日志面板或编辑器缓冲区。它把 HTTP 状态判断、分块读取、字符解码和 reader 清理放在同一条流程里。

async function readTextStream(url, { signal, onText }) {
  // 传入 signal,让调用方可以在页面离开时取消请求
  const response = await fetch(url, { signal });

  // HTTP 响应到了不代表业务成功,先处理状态码
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  // 某些响应没有可读 body,不能继续调用 getReader()
  if (!response.body) {
    throw new Error("响应没有可读取的 body");
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder("utf-8");

  try {
    while (true) {
      // 每次只等待下一块,完成时 done 会变成 true
      const { done, value } = await reader.read();

      if (done) {
        // flush 可能补出最后一个被暂存的多字节字符
        const tail = decoder.decode();
        if (tail) onText(tail);
        return;
      }

      // stream:true 允许 UTF-8 字符跨越两块数据边界
      onText(decoder.decode(value, { stream: true }));
    }
  } finally {
    // 不再读取时释放流锁,避免后续接管时遇到 locked 状态
    reader.releaseLock();
  }
}

const controller = new AbortController();

readTextStream("/api/report", {
  signal: controller.signal,
  // 收到一块就追加,不等待完整响应
  onText(chunk) {
    document.querySelector("#output").textContent += chunk;
  },
}).catch((error) => {
  // 主动取消是用户动作,不必显示成网络故障
  if (controller.signal.aborted) return;
  console.error("流读取失败", error);
});

// 停止按钮可以调用这句取消尚未完成的请求
// controller.abort();

这里有一个容易忽略的细节:文本解码器也有状态。一个汉字的 UTF-8 字节可能被拆到两块里,如果每次都直接创建新解码器,页面会出现替换字符。持续复用同一个 TextDecoder,并在中间块使用 { stream: true },最后在 done 分支调用一次无参数的 decode() 完成 flush。

四、处理完成信号:done、错误和取消必须分开

“完成”不是“这一块比较短”,也不是“服务端暂时没有新内容”。只有 reader 返回 done: true 才能结束自然读取流程。若 Promise 被拒绝,应该进入错误处理;如果请求由 AbortController.abort() 触发,则优先判断 signal.aborted,让界面显示“已停止”或静默收尾。

流式响应自然完成主动取消和读取错误三条结束路径
图2:done、abort 与读取错误的结束路径对比图(原创结构图,不是运行截图)。

如果希望用户点击停止,调用方可以保存 controller:

const stopController = new AbortController();

// 让请求和 reader 共享同一个取消信号
readTextStream("/api/report", {
  signal: stopController.signal,
  onText(chunk) {
    appendToOutput(chunk);
  },
}).then(() => {
  // 只有自然读到 done=true 才标记为完成
  markStatus("完成");
}).catch((error) => {
  if (stopController.signal.aborted) {
    // 取消是可预期操作,不覆盖已经展示的部分内容
    markStatus("已停止");
    return;
  }
  markStatus("读取失败");
  reportError(error);
});

document.querySelector("#stop").addEventListener("click", () => {
  // abort 会让 fetch/reader 的等待尽快结束
  stopController.abort();
});

五、回滚路径:不需要逐块展示时别强行使用 reader

流式读取适合逐字展示、长任务进度或希望尽早呈现首段内容的场景。如果业务只在完整 JSON 或完整文本到齐后处理,直接使用 response.json() 或 response.text() 更简单,也不会承担 reader 锁、增量解码和取消分支的维护成本。

另一种较简洁的流读取写法是异步迭代:

async function readByIteration(url, signal) {
  // 仍然把取消信号交给 fetch,而不是只在循环外设置变量
  const response = await fetch(url, { signal });
  if (!response.body) throw new Error("响应没有 body");

  for await (const chunk of response.body) {
    // 每次循环拿到一块 Uint8Array,按需解码或转存
    consumeChunk(chunk);
  }

  // 异步迭代自然结束后,表示流已经没有更多块
  markStatus("完成");
}

这个写法省去了手动的 while 和 releaseLock(),但当你需要精细控制每次 read()、做统一的 reader 清理,或要把“自然完成”和“取消”暴露给更复杂的状态机时,显式 reader 循环更容易排查。

六、上线确认:用三个信号判断流程是否健康

  1. 收到分块:每次 done === false 都有一条可追踪的追加路径,页面不会只处理首块。
  2. 自然完成:仅在 done === true 后标记完成,并完成 decoder flush。
  3. 主动取消:取消后不把预期操作当成网络故障,也不留下长期占用的 reader 锁。

我自己的取舍是:先用上面的显式 reader 版本把状态走通,再根据界面复杂度决定是否改成 for await...of。只要记住“fetch() 解决不等于 body 读完”“read() 要持续调用”“done 才是自然结束”,大多数只显示首段、无法收尾和取消误报的问题都能很快定位。

常见问题

response.body 为什么可能是 null?

当前响应可能没有可读取的 body,或者运行环境没有提供对应的流能力。代码应先判断,再选择错误提示或普通响应处理。

read() 返回 done=true 时还要处理 value 吗?

不应把它当作普通数据块处理。此时重点是完成 decoder flush、更新完成状态并退出读取循环。

为什么停止后 catch 会执行?

取消可能让等待中的 Fetch 或 reader Promise 以拒绝结束。通过同一个 AbortSignal 判断 signal.aborted,即可把主动取消和真正的读取错误分开。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>