当前位置：首页 > news >正文

Node.js 轻量任务队列：独立产品先把失败处理写清楚

news 2026/7/3 1:52:09

Node.js 轻量任务队列：独立产品先把失败处理写清楚

独立产品接入 AI、导出 PDF、发送邮件、同步文件后，很快就会遇到后台任务。很多人第一反应是上复杂队列系统，但早期产品未必需要那么重。真正要先写清楚的，是任务状态、失败重试、幂等和可观察性。

Node.js 做轻量任务队列，可以从数据库表加 worker 开始。它不时髦，但足够透明。小产品最需要的是可理解、可修复、可迁移，而不是一开始就把系统拆得很散。

一、任务队列的核心是状态机

后台任务不要只用一个done字段。至少要区分 pending、running、succeeded、failed、retrying、canceled。状态清楚，界面才能告诉用户发生了什么，开发者也能定位问题。

stateDiagram-v2 [*] --> pending pending --> running running --> succeeded running --> retrying retrying --> running running --> failed pending --> canceled failed --> [*] succeeded --> [*]

导出任务尤其需要状态。用户点击导出后，可能需要等待模型整理、渲染、上传文件。只显示一个转圈，会让人不安；显示“正在生成”“正在上传”“可下载”，体验会稳定很多。

二、用数据库表承载早期队列

早期可以用一张jobs表承载任务。关键是加锁领取任务，避免多个 worker 同时处理同一条。

CREATE TABLE jobs ( id TEXT PRIMARY KEY, type TEXT NOT NULL, payload JSONB NOT NULL, status TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, run_after TIMESTAMP NOT NULL DEFAULT now(), locked_at TIMESTAMP, last_error TEXT, created_at TIMESTAMP NOT NULL DEFAULT now(), updated_at TIMESTAMP NOT NULL DEFAULT now() );

Worker 轮询时只取pending或到期的retrying。如果数据库支持FOR UPDATE SKIP LOCKED，可以更安全地并发领取。小系统也要认真处理并发，不然上线后会出现重复导出、重复扣额度和重复发邮件。

三、失败重试要有上限和退避

AI 调用、对象存储、邮件服务都可能临时失败。重试是必要的，但不能无限重试。指数退避和最大次数是最低要求。

function nextRunAfter(attempts: number) { const seconds = Math.min(60 * 10, Math.pow(2, attempts) * 10); return new Date(Date.now() + seconds * 1000); } function shouldRetry(error: Error) { return !error.message.includes("invalid_api_key"); }

不是所有错误都适合重试。参数错误、权限错误、额度不足应该快速失败，并给用户可理解的提示。网络超时、第三方 5xx、临时限流才适合退避重试。

四、幂等比队列技术更重要

后台任务最容易被忽略的是幂等。一个任务可能因为超时被重试，也可能 worker 崩溃后重新执行。如果导出任务重复跑，只是浪费资源；如果支付或扣额度重复执行，就是事故。

idempotency_rules: export_markdown: key: project_id + export_format + content_version duplicate_behavior: return_existing_file ai_generation: key: request_id duplicate_behavior: return_previous_result billing_charge: key: provider_event_id duplicate_behavior: ignore_duplicate

每类任务都应定义幂等键。队列系统可以简单，但幂等策略不能空白。它是小产品从“能跑”走向“可靠”的分界线。