Node.js API服务如何在客户端断开连接后取消仍在执行的异步任务?
当客户端在等待 API 响应时关闭页面、取消请求或触发了客户端超时,Node.js 服务端并不会自动停止已经开始执行的异步函数。await 只是等待 Promise 的结果,不能反向终止 Promise 对应的网络请求、定时器、数据库查询或业务计算。要实现真正的取消,需要同时完成两件事:监听连接是否已经断开,并把取消信号继续传递给实际执行任务的函数。
下面使用 Node.js 20+ 编写一个完整示例。示例接口会并行执行两个耗时阶段,客户端中途断开后,两个阶段都会收到 AbortSignal 并停止等待。
先区分“发现断开”和“停止任务”
客户端断开连接和异步任务取消是两个不同的问题。
服务端首先要知道连接状态发生了变化:
- 请求体还没有接收完时,
IncomingMessage可能触发aborted事件。 - 服务端正在准备响应时,
ServerResponse可能触发close事件。 res.finish只表示响应已经交给底层发送流程,并不代表客户端确实处理了响应,因此不适合作为取消任务的依据。
服务端发现连接断开后,还需要通过 AbortController 通知业务层:

HTTP 请求
├─ req.aborted / res.close
│ ↓
├─ AbortController.abort()
│ ↓
├─ fetch、定时器、流、数据库驱动等收到 signal
│ ↓
└─ 任务停止或尽快结束
AbortController 只能发出取消通知,不能强行杀死任意 JavaScript 函数。接收到 signal 的任务必须主动检查信号,或者调用本身支持 AbortSignal 的 API。
此外,控制器必须按请求创建,不能在模块级别复用:
// 不要这样做,所有请求会共享同一个取消状态
const controller = new AbortController();
如果其中一个客户端断开,所有使用这个控制器的请求都会受到影响。正确方式是每次进入接口处理函数时创建一个新的控制器。
一个可直接运行的 Node.js 20+ 示例
将下面代码保存为 server.mjs:
import http from 'node:http';
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
function createRequestCancellation(req, res) {
const controller = new AbortController();
let cause = null;
const onClientClose = () => {
// 正常调用 res.end() 后,close 事件也可能随后触发。
// 响应已经结束时,不应再把它当成客户端异常断开。
if (controller.signal.aborted || res.writableEnded) {
return;
}
cause = 'client_disconnect';
controller.abort(new Error('client disconnected'));
};
// 请求体尚未完整接收时,客户端可能触发 aborted。
req.once('aborted', onClientClose);
// 长时间业务处理阶段主要依靠响应 close 判断连接是否还在。
res.once('close', onClientClose);
return {
signal: controller.signal,
get cause() {
return cause;
},
abortForDeadline() {
if (controller.signal.aborted || res.writableEnded) {
return;
}
cause = 'deadline';
controller.abort(new Error('request deadline exceeded'));
},
cleanup() {
req.off('aborted', onClientClose);
res.off('close', onClientClose);
}
};
}
function sendJson(res, statusCode, payload) {
// 客户端已经断开时,不再尝试写响应。
if (res.writableEnded || res.destroyed) {
return false;
}
res.statusCode = statusCode;
res.setHeader('Content-Type', 'application/json; charset=utf-8');
res.end(JSON.stringify(payload));
return true;
}
async function runStage(name, durationMs, signal) {
// node:timers/promises 的 setTimeout 支持 AbortSignal。
await sleep(durationMs, undefined, { signal });
if (signal.aborted) {
throw signal.reason ?? new Error('operation aborted');
}
return {
name,
durationMs
};
}
async function buildReport({ signal }) {
// 两个阶段共享同一个 signal。
// 其中任何一个阶段因为取消而结束时,另一个阶段也会收到取消信号。
const [catalog, scoring] = await Promise.all([
runStage('catalog', 2500, signal),
runStage('scoring', 5000, signal)
]);
return {
generatedAt: new Date().toISOString(),
stages: [catalog, scoring]
};
}
const server = http.createServer(async (req, res) => {
const url = new URL(req.url ?? '/', 'http://localhost');
if (req.method !== 'GET' || url.pathname !== '/api/report') {
sendJson(res, 404, {
error: 'not_found'
});
return;
}
const requestId = randomUUID();
const cancellation = createRequestCancellation(req, res);
// 客户端即使不主动断开,服务端也要设置自己的最长执行时间。
const deadlineTimer = setTimeout(() => {
cancellation.abortForDeadline();
}, 10_000);
try {
console.log(`[${requestId}] request started`);
const result = await buildReport({
signal: cancellation.signal
});
// 业务任务完成后,发送响应前仍要再次检查连接状态。
// 客户端可能刚好在任务完成和写响应之间断开。
if (
cancellation.signal.aborted ||
res.writableEnded ||
res.destroyed
) {
if (
cancellation.cause === 'client_disconnect' ||
res.destroyed
) {
console.log(`[${requestId}] client disconnected`);
}
return;
}
sendJson(res, 200, {
requestId,
result
});
console.log(`[${requestId}] response sent`);
} catch (error) {
if (
cancellation.cause === 'client_disconnect' ||
res.destroyed
) {
// 客户端已经不在,无法再发送错误响应。
console.log(`[${requestId}] task canceled because client disconnected`);
return;
}
if (cancellation.cause === 'deadline') {
// 连接仍然存在时,可以告诉客户端服务端超时。
sendJson(res, 504, {
error: 'request_timeout',
requestId
});
return;
}
console.error(`[${requestId}] unexpected error`, error);
if (!res.writableEnded) {
sendJson(res, 500, {
error: 'internal_error',
requestId
});
}
} finally {
clearTimeout(deadlineTimer);
cancellation.cleanup();
}
});
server.listen(3000, () => {
console.log('API server listening on http://127.0.0.1:3000');
});
使用 .mjs 扩展名后,可以直接启动:
node server.mjs
正常请求:
curl -i http://127.0.0.1:3000/api/report
两个阶段是并行执行的,因此正常情况下大约需要等待较慢的 scoring 阶段完成,返回内容类似:

{
"requestId": "7c58d4f1-5cb7-4b15-a8e6-6e0ef5a43c17",
"data": {
"generatedAt": "2025-01-01T10:00:00.000Z",
"stages": [
{
"name": "catalog",
"durationMs": 2500
},
{
"name": "scoring",
"durationMs": 5000
}
]
}
}
可以使用 curl 的超时参数模拟客户端提前退出:
curl -i --max-time 1 http://127.0.0.1:3000/api/report
客户端通常会在 1 秒左右结束等待,服务端可能看到类似日志:
[7c58d4f1-5cb7-4b15-a8e6-6e0ef5a43c17] request started
[7c58d4f1-5cb7-4b15-a8e6-6e0ef5a43c17] task canceled because client disconnected
此时两个 sleep 都会因为同一个 AbortSignal 被中断,不会继续等待到 5 秒后才结束。
代码中几个关键位置的作用
为什么同时监听 req.aborted 和 res.close
这两个事件覆盖的阶段不同。
req.aborted 更适合处理请求输入阶段。例如客户端正在上传一个较大的 JSON、文件或表单数据,传输还没有完成就关闭了连接,此时服务端可能先在请求对象上观察到中止。
而接口通常是在请求体读取完成后才开始执行主要业务。业务执行期间,请求对象本身可能已经处于“读取完成”状态,因此不能只依赖 req.aborted。这时应监听响应对象的 close:
res.once('close', () => {
if (!res.writableEnded) {
controller.abort();
}
});
不能简单地把所有逻辑都绑定到 req.close。请求对象的连接关闭事件在不同 Node.js 版本和框架封装下容易与“请求体读取完成”混淆,单独使用可能把正常流程误判为异常断开。实际项目中,通常会同时关注请求中止和未完成响应的关闭。
为什么任务完成后还要检查一次
取消事件和业务函数完成之间存在竞争关系:
- 业务任务刚刚完成。
- 客户端正好在此时关闭连接。
- 服务端开始执行
res.end()。
因此监听器不能完全消除竞态。发送响应前再检查一次:
if (signal.aborted || res.writableEnded || res.destroyed) {
return;
}
这可以避免大量“任务已经完成,但仍然向已关闭响应写入数据”的情况。不过检查和写入之间仍可能发生极短的状态变化,所以代码还应该将客户端断开视为正常的可预期分支,而不是把它记录成应用故障。
为什么需要独立的服务端超时
客户端是否断开不一定能够及时被服务端观察到。浏览器、移动网络、反向代理和负载均衡器都可能改变连接关闭的传播时间。一个客户端已经放弃等待,并不代表 Node.js 进程马上就能得到事件。
因此服务端通常还需要自己的截止时间:
const deadlineTimer = setTimeout(() => {
cancellation.abortForDeadline();
}, 10_000);
客户端主动断开和服务端处理超时的结果不同:
- 客户端已经断开:无法再发送 HTTP 响应,只记录取消原因并释放资源。
- 服务端达到截止时间,但客户端仍在线:可以返回
504 Gateway Timeout。 - 上游返回业务错误:根据接口约定返回
4xx或5xx。
有些网关会使用 499 表示客户端提前关闭连接,但它更多是日志或监控中的约定,不是服务端在连接已关闭后还能可靠发送给客户端的状态码。
把同一个 signal 传进真实异步操作
只监听断开事件还不够。每一个可取消的异步操作都要接收同一个 signal,否则控制器虽然已经触发,底层任务仍会继续运行。
取消上游 HTTP 请求
Node.js 18+ 通常可以使用全局 fetch,示例按 Node.js 20+ 说明:
async function loadRemoteData(signal) {
const response = await fetch(
'https://api.example.com/items',
{
method: 'GET',
signal,
headers: {
Accept: 'application/json'
}
}
);
if (!response.ok) {
throw new Error(`upstream returned ${response.status}`);
}
return response.json();
}
在接口中调用时,必须把请求级别的信号继续传下去:
const remoteData = await loadRemoteData(cancellation.signal);
如果客户端断开,fetch 会收到中止信号,正在连接、等待响应头或读取响应体的操作会尽快结束。需要注意的是,这只能取消当前 Node.js 进程发出的请求。上游服务是否会停止它自己的内部计算,由上游服务的实现决定。
取消定时器和延迟任务
node:timers/promises 的定时器支持 AbortSignal:
import { setTimeout as sleep } from 'node:timers/promises';
async function waitForCacheRefresh(signal) {
await sleep(3000, undefined, { signal });
return 'cache refreshed';
}
如果只是使用传统回调形式的 setTimeout,则需要自行清理:
function waitWithCleanup(ms, signal) {
return new Promise((resolve, reject) => {
const timer = setTimeout(resolve, ms);
const onAbort = () => {
clearTimeout(timer);
reject(signal.reason ?? new Error('operation aborted'));
};
if (signal.aborted) {
onAbort();
return;
}
signal.addEventListener('abort', onAbort, { once: true });
});
}
自定义 Promise 封装时,必须处理三种情况:
- 注册监听前信号已经处于 aborted 状态。
- 执行期间收到 abort。
- 正常完成后移除不再需要的监听器。
取消流式处理
Node.js 的 stream/promises 中,pipeline 可以接收 signal:
import { pipeline } from 'node:stream/promises';
async function processStream(input, output, signal) {
await pipeline(
input,
output,
{ signal }
);
}
对于文件压缩、数据导出、上传转发等场景,取消信号应该传入整个流水线。只停止等待 pipeline 返回,而不关闭输入流、输出流或临时文件,仍然可能造成文件句柄和磁盘空间泄漏。
数据库操作不能一概而论
数据库驱动对 AbortSignal 的支持并不完全一致:
| 操作类型 | 是否通常可以直接传入 signal | 接入时需要确认的内容 |
|---|---|---|
fetch 上游请求 | 通常支持 | 请求是否已经发出、响应体是否正在读取 |
timers/promises 定时器 | 支持 | 取消后是否正确清理相关状态 |
stream.pipeline | 支持 | 输入流、输出流和临时资源是否关闭 |
| 数据库查询 | 取决于驱动和版本 | 是否支持取消查询、连接释放方式 |
| CPU 密集型同步计算 | 不会自动支持 | 是否分块、是否主动让出事件循环 |
| 外部命令或 Worker | 取决于启动方式 | 是协作退出还是强制终止 |
如果数据库驱动支持查询级别的取消,应按照驱动文档传递信号或调用取消接口。如果驱动不支持,就不能仅仅在外层写一个 Promise.race 来假装取消。
数据库连接池也不能因为一个请求取消就整体销毁。正确做法通常是:
- 取消当前查询或等待驱动结束。
- 在
finally中释放当前连接。 - 确保连接回到池中时没有残留事务、游标或未读取的数据。
- 按驱动要求处理取消后的连接状态。
CPU 密集型任务需要主动让出事件循环
下面的同步循环即使传入了 signal,也无法在循环中途自动停止:
function calculate(items, signal) {
let total = 0;
for (const item of items) {
total += expensiveCalculation(item);
}
return total;
}
如果 expensiveCalculation 连续运行几十秒,Node.js 事件循环没有机会处理 close 或 aborted 事件,服务端甚至无法及时知道客户端已经断开。
可以将计算拆成批次,在批次之间检查信号并让出事件循环:

import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
async function calculateInChunks(items, signal) {
let total = 0;
for (let index = 0; index < items.length; index += 1) {
if (signal.aborted) {
throw signal.reason ?? new Error('calculation aborted');
}
total += expensiveCalculation(items[index]);
if (index % 1000 === 0) {
await yieldToEventLoop();
}
}
return total;
}
批次大小要根据单次计算耗时调整。如果每批任务本身就会阻塞事件循环数秒,取消事件仍然无法及时处理。对于长时间 CPU 计算,可以考虑 Worker。收到取消信号后向 Worker 发送停止消息,或者调用 worker.terminate(),但强制终止可能留下半成品数据,因此需要提前设计临时文件、事务和恢复流程。
Express 接入时如何复用
Express 的 req 和 res 仍然基于 Node.js 的请求、响应对象,因此可以复用上面的取消封装。
import express from 'express';
const app = express();
app.get('/api/report', async (req, res, next) => {
const cancellation = createRequestCancellation(req, res);
const deadlineTimer = setTimeout(() => {
cancellation.abortForDeadline();
}, 10_000);
try {
const result = await buildReport({
signal: cancellation.signal
});
if (
cancellation.signal.aborted ||
res.writableEnded ||
res.destroyed
) {
return;
}
res.status(200).json(result);
} catch (error) {
if (
cancellation.cause === 'client_disconnect' ||
res.destroyed
) {
return;
}
if (cancellation.cause === 'deadline') {
if (!res.headersSent && !res.writableEnded) {
res.status(504).json({
error: 'request_timeout'
});
}
return;
}
next(error);
} finally {
clearTimeout(deadlineTimer);
cancellation.cleanup();
}
});
app.listen(3000, () => {
console.log('Express server listening on port 3000');
});
如果接口包含大文件上传或较大的请求体,取消监听最好尽早建立,而不是等到所有请求体经过解析中间件后才创建。可以在应用级中间件中初始化控制器,再把它挂到请求上下文中,但要确保每次请求都有独立实例。
不同框架对原始请求和响应对象的暴露方式不一样。接入 Fastify、NestJS 或其他框架时,应找到框架对应的原始 Node.js request、response 或底层连接事件,不要直接假设所有框架都有相同的 close API。
取消、超时与异常分支怎么处理
接口的异常分支至少要区分下面几种状态:
| 状态 | 是否继续业务任务 | 是否发送响应 | 推荐记录方式 |
|---|---|---|---|
| 正常完成且连接存在 | 否,任务已完成 | 发送 200 | 正常请求日志 |
| 客户端主动断开 | 立即取消可取消任务 | 不再发送 | 记录为 client_disconnect |
| 服务端达到截止时间 | 取消可取消任务 | 连接仍在时发送 504 | 记录为 deadline |
| 上游请求失败 | 按业务决定 | 返回相应错误码 | 记录上游状态和请求 ID |
| 数据库写入已经提交后断开 | 不能简单回滚 | 通常无法发送 | 记录提交结果,支持查询或幂等 |
客户端断开不应该被记录成普通的 500。它可能是用户主动离开页面,也可能是客户端自己的超时策略,不一定表示服务端代码出错。
同时,也不要把所有 AbortError 都简单归类为客户端断开。服务端自己的超时、管理员主动取消、上游取消,都可能使用同一种异常类型。更可靠的做法是像示例中一样,在调用 abort() 时额外记录取消原因。
不要用 Promise.race 冒充取消
下面的写法只能让调用方提前结束等待,不能停止 slowOperation:
await Promise.race([
slowOperation(),
sleep(5000).then(() => {
throw new Error('timeout');
})
]);
5 秒后外层 Promise 可能已经抛出异常,但 slowOperation() 仍然在后台运行。如果它占用连接、文件句柄、CPU 或远程请求,这些资源仍会继续消耗。
正确做法是让实际操作接收信号:
async function runWithSignal(signal) {
return slowOperation({ signal });
}
const controller = new AbortController();
setTimeout(() => {
controller.abort(new Error('timeout'));
}, 5000);
await runWithSignal(controller.signal);
前提是 slowOperation 内部确实实现了对 signal 的处理。如果它只是忽略参数,外层依然不能强行终止它。
有副作用的写操作要谨慎取消
读取接口通常适合在客户端断开后取消,但订单创建、扣款、消息发送、库存扣减等写操作不能只根据连接状态决定是否停止。
例如:
- 服务端已经向支付服务发起请求。
- 客户端在服务端收到结果前断开。
- 服务端调用
abort()停止等待。 - 支付服务实际上已经完成扣款。
此时客户端没有收到响应,并不代表业务操作没有发生。对于这类接口,应结合以下机制:
- 使用幂等键,避免客户端重试时重复提交。
- 将外部操作状态持久化。
- 给客户端提供按业务编号查询状态的接口。
- 对数据库事务明确提交点和回滚边界。
- 不把“HTTP 请求取消”当作“业务事务回滚”。
如果业务本质上是导出报表、生成视频、批量处理等长期任务,更适合创建后台任务后立即返回任务编号,而不是把整个任务绑定到 HTTP 连接:
POST /api/exports
↓
创建任务并写入队列
↓
返回 202 和 jobId
↓
GET /api/exports/:jobId 查询状态
这类任务应该继续由队列消费者执行,即使最初发起请求的客户端已经关闭页面。
用命令验证取消是否生效
启动服务后,先验证正常响应:
curl -i http://127.0.0.1:3000/api/report
然后用客户端超时模拟提前断开:
curl -i --max-time 1 http://127.0.0.1:3000/api/report
可以重点观察以下现象:
- 客户端不会等待完整的 5 秒。
- 服务端日志会出现客户端断开或任务取消记录。
- 不会在客户端断开后继续输出正常响应日志。
- Node.js 进程不会因为取消一个请求而停止整个 HTTP 服务。
- 其他同时访问接口的请求仍然可以独立执行。
还可以临时把示例中的服务端截止时间改为 3 秒:
const deadlineTimer = setTimeout(() => {
cancellation.abortForDeadline();
}, 3000);
再次请求时,较慢的阶段会在 3 秒左右被中止。如果客户端仍保持连接,应该收到:

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json; charset=utf-8
响应体类似:
{
"error": "request_timeout",
"requestId": "..."
}
在实际项目中,最好为每个请求记录请求编号、取消原因、任务阶段和耗时。例如:
requestId=... event=task_cancel reason=client_disconnect stage=scoring elapsedMs=1038
不要只统计 HTTP 500。客户端断开、服务端超时、上游失败和真正的代码异常应该分别统计,否则很难判断资源消耗来自用户行为、代理超时还是业务性能问题。
代理、连接复用和长期任务的边界
Node.js 服务只能观察它与直接上游之间的连接。如果客户端经过 CDN、反向代理或负载均衡器,实际链路可能是:
浏览器 → CDN → 反向代理 → Node.js
浏览器关闭页面后,Node.js 不一定立刻收到断开事件。代理也可能先向客户端返回超时页面,但与 Node.js 的上游连接仍在一段时间内保持。反过来,代理关闭上游连接时,Node.js 也可能把它观察成客户端断开。
因此需要同时设置多个层次的时间限制:
- 客户端请求超时。
- 反向代理的读取和连接超时。
- Node.js 接口自身的业务截止时间。
- 上游 HTTP、数据库和队列操作的独立超时。
这些超时不应互相矛盾。例如代理在 5 秒时关闭连接,而 Node.js 接口在 30 秒时才取消任务,那么服务端仍可能继续浪费 25 秒资源。具体数值要根据任务类型、上游响应时间和部署拓扑调整,不能直接套用固定值。
接入现有项目时,可以按以下顺序改造:
- 为每个长时间接口创建独立的
AbortController。 - 同时监听请求中止和未完成响应关闭。
- 把
signal传入fetch、定时器、流和支持取消的驱动调用。 - 对不支持取消的任务增加分块检查、资源清理或 Worker 隔离。
- 响应发送前再次检查连接状态。
- 在
finally中清理定时器、事件监听器、连接和临时文件。 - 将客户端断开、服务端超时和业务异常分别记录。
- 对订单、支付、写库等有副作用的操作增加幂等和状态查询设计。
这样处理后,客户端断开不再只是一个被动的连接事件,而是能够沿着请求上下文传递到具体异步任务的取消信号。对于可以安全中断的读取和计算任务,服务端能够更早释放资源;对于不应中断的持久化任务,则可以通过队列和任务状态接口与 HTTP 连接解耦。
对于需要长期运行的 Node.js API,A5idc数据可提供香港、美国、日本、新加坡等地区的物理服务器资源,并按业务负载选择相应的 CPU、内存、SSD 或 NVMe 存储,为接口处理、数据库访问及多任务计算提供运行环境。若服务需要对外开放,还可配套域名、SSL 证书与 CDN,用于 API 入口的 HTTPS 连接及静态资源的多地区分发,便于将客户端访问、服务端任务和交付链路分别组织。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9997.html



