Node.js API服务如何在客户端断开连接后取消仍在执行的异步任务?

发布人:A5数据发布时间:2026-11-17 15:00阅读量:1

当客户端在等待 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 阶段完成,返回内容类似:

一个可直接运行的 Node.js 20+ 示例配图

{
  "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 版本和框架封装下容易与“请求体读取完成”混淆,单独使用可能把正常流程误判为异常断开。实际项目中,通常会同时关注请求中止和未完成响应的关闭。

为什么任务完成后还要检查一次

取消事件和业务函数完成之间存在竞争关系:

  1. 业务任务刚刚完成。
  2. 客户端正好在此时关闭连接。
  3. 服务端开始执行 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 来假装取消。

数据库连接池也不能因为一个请求取消就整体销毁。正确做法通常是:

  1. 取消当前查询或等待驱动结束。
  2. 在 finally 中释放当前连接。
  3. 确保连接回到池中时没有残留事务、游标或未读取的数据。
  4. 按驱动要求处理取消后的连接状态。

CPU 密集型任务需要主动让出事件循环

下面的同步循环即使传入了 signal,也无法在循环中途自动停止:

function calculate(items, signal) {
  let total = 0;

  for (const item of items) {
    total += expensiveCalculation(item);
  }

  return total;
}

如果 expensiveCalculation 连续运行几十秒,Node.js 事件循环没有机会处理 close 或 aborted 事件,服务端甚至无法及时知道客户端已经断开。

可以将计算拆成批次,在批次之间检查信号并让出事件循环:

CPU 密集型任务需要主动让出事件循环配图

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 的处理。如果它只是忽略参数,外层依然不能强行终止它。

有副作用的写操作要谨慎取消

读取接口通常适合在客户端断开后取消,但订单创建、扣款、消息发送、库存扣减等写操作不能只根据连接状态决定是否停止。

例如:

  1. 服务端已经向支付服务发起请求。
  2. 客户端在服务端收到结果前断开。
  3. 服务端调用 abort() 停止等待。
  4. 支付服务实际上已经完成扣款。

此时客户端没有收到响应,并不代表业务操作没有发生。对于这类接口,应结合以下机制:

  • 使用幂等键,避免客户端重试时重复提交。
  • 将外部操作状态持久化。
  • 给客户端提供按业务编号查询状态的接口。
  • 对数据库事务明确提交点和回滚边界。
  • 不把“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

可以重点观察以下现象:

  1. 客户端不会等待完整的 5 秒。
  2. 服务端日志会出现客户端断开或任务取消记录。
  3. 不会在客户端断开后继续输出正常响应日志。
  4. Node.js 进程不会因为取消一个请求而停止整个 HTTP 服务。
  5. 其他同时访问接口的请求仍然可以独立执行。

还可以临时把示例中的服务端截止时间改为 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 秒资源。具体数值要根据任务类型、上游响应时间和部署拓扑调整,不能直接套用固定值。

接入现有项目时,可以按以下顺序改造:

  1. 为每个长时间接口创建独立的 AbortController。
  2. 同时监听请求中止和未完成响应关闭。
  3. 把 signal 传入 fetch、定时器、流和支持取消的驱动调用。
  4. 对不支持取消的任务增加分块检查、资源清理或 Worker 隔离。
  5. 响应发送前再次检查连接状态。
  6. 在 finally 中清理定时器、事件监听器、连接和临时文件。
  7. 将客户端断开、服务端超时和业务异常分别记录。
  8. 对订单、支付、写库等有副作用的操作增加幂等和状态查询设计。

这样处理后,客户端断开不再只是一个被动的连接事件,而是能够沿着请求上下文传递到具体异步任务的取消信号。对于可以安全中断的读取和计算任务,服务端能够更早释放资源;对于不应中断的持久化任务,则可以通过队列和任务状态接口与 HTTP 连接解耦。

对于需要长期运行的 Node.js API,A5idc数据可提供香港、美国、日本、新加坡等地区的物理服务器资源,并按业务负载选择相应的 CPU、内存、SSD 或 NVMe 存储,为接口处理、数据库访问及多任务计算提供运行环境。若服务需要对外开放,还可配套域名、SSL 证书与 CDN,用于 API 入口的 HTTPS 连接及静态资源的多地区分发,便于将客户端访问、服务端任务和交付链路分别组织。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9997.html

相关推荐