Next.js 流式接口如何取消请求并处理超时
文章用标准 Web API 的 AbortSignal.any 合并客户端断开信号与服务端截止信号,并区分首个令牌超时和整条流的时长上限。
AI 深度解读
用户点了「停止」,页面马上停字,上游模型却可能还在生成。反过来,用户一直等在页面上,模型卡了 45 秒,连接也未必会自己断开。作者给 Next.js App Router 的流式接口提供了一套只用 Web API 的处理方式,把客户端取消、服务端超时和前端收到的结束状态串起来。
这套做法最实用的地方,是把「迟迟等不到首块」「输出到一半卡住」「整条请求超时」分开处理。三种情况都需要收尾,但触发时机和页面该给出的提示各不相同。
用户点了停止,取消信号怎么传到模型?
Next.js 的 Route Handler 拿到的是标准 Request。作者用 AbortSignal.any([req.signal, timeoutController.signal]) 合并请求信号和服务端的超时信号,再把合并结果通过 signal 传给 callUpstreamModel。示例用 setTimeout 设置 30_000 ms 的总时限,从调用上游前开始计时,覆盖等待和输出两个阶段。
req.signal 和 ReadableStream 的 cancel() 都要接上。作者指出,有些运行时要等 socket 关闭才会触发 req.signal,取消流读取则可能走 cancel()。示例在 cancel() 里也中止上游,并和流处理的 finally 一样调用 clearTimeout(hardTimer)。这样,流正常结束、出错或被取消时,对应的计时器都能清理。
首块等多久,出字后又能停多久?
总预算给了 30 秒,第一块等到第 25 秒才来,页面就已经空等了 25 秒。作者用下面这段代码先限制首块等待,再把计时器切换成分块之间的空闲倒计时。
let idleTimer = setTimeout(() => {
timeoutController.abort(new Error("TTFT timeout"));
}, 8_000);
const resetIdleTimer = () => {
clearTimeout(idleTimer);
idleTimer = setTimeout(() => {
timeoutController.abort(new Error("Chunk stall timeout"));
}, 10_000);
};
要留意 clearTimeout(idleTimer) 这一行。第一次收到分块时,在 for await 循环里调用 resetIdleTimer(),原来的 8_000 ms 首块计时就被清掉。之后每收到一块,空闲计时都重新从 10_000 ms 开始。如果同时保留 30_000 ms 总时限,即使上游持续有输出,到点也会被中止。把两段示例合起来时,退出路径也要清理 idleTimer。
流到一半出错,页面怎么保住已有回答?
作者用 Content-Type: text/event-stream; charset=utf-8 和 Cache-Control: no-cache, no-transform 返回流。正常结束时发 data: [DONE]。如果流已经开始、上游抛错,同时客户端仍能接收,就尝试在 controller.close() 前发送 { error: "stream_interrupted" }。前端收到这帧后,可以保留已经渲染的文字,停掉加载状态,并显示「重试」。用户主动点「停止」时,则可以根据本地操作或 AbortError 更新界面。
如果调用上游时就失败,示例仍能返回 HTTP 响应。此时 req.signal 已取消就走 499,其余错误统一返回 504 和 { error: "upstream_failed" }。一旦流式响应已经开始,前端就要靠流里的终止事件判断结果。连接已经断开时,错误帧也送不到客户端。
我的判断
这套方案最适合拿来梳理流的生命周期。只设总时限,首块迟迟不来时,用户得一直等到总预算耗尽。只设空闲超时,上游只要持续发分块,就可能把请求拖得很长。原文给了 8_000、10_000、30_000 ms 作为示例,但没给实测或对照数据。阈值怎么设,要看实际的首块延迟、分块间隔和页面可接受的等待时间。
原文的示例还有一个会影响前端判断的细节。循环发现 combinedSignal.aborted 后会 break,随后仍会发 [DONE]。如果中止走的是这条分支,前端可能把半截回答标成已完成。另一个前提是 callUpstreamModel 和底层 SDK 确实响应 signal。原文没给这个函数的实现,因此无法确认发出取消信号后,供应商是否会立刻停止生成或计费。
能拿来做什么
- 在流式接口里分别记录等到首个分块的时间、分块间隔和总耗时,再用实际分布调整三个阈值。如果 SDK 会先吐元数据,先确认产品要衡量的是第一块数据,还是用户第一次看到文字。
- 给聊天页面明确区分正常完成、用户停止和流式错误。收到
stream_interrupted时保留半截回答并显示重试入口,只有确认正常跑完才发送[DONE]。 - 用当前的部署环境和模型 SDK 分别检查点击停止、关闭页面、首块超时和中途卡流四条路径,确认取消能传到上游,计时器能清理,页面也能退出加载状态。