用途:把用户请求中不需要同步完成的慢 I/O(邮件、PDF、缩略图、重同步、出站 webhook、嵌入等)改为入队后立即响应,并用 Worker 可靠执行。网络类工作如出站 webhook 走 webhooks,出站事件/outbox 走 event-driven-architecture,Redis broker 参考 redis-cache(队列键与缓存键要区分)。
主要能力与规则:保留仓库原有 runner(Bull/BullMQ、Sidekiq、River、Oban、Hangfire、pg-boss),不换库。入队条件为 I/O 超过约 200ms 且用户不需要同一响应、需要扇出、重试或定时(cron/every)。不要用异步掩盖竞态,涉及金额的不变量应在请求事务中处理。
任务契约:name/queue(如 email.send)、idempotency(如 email:send:{messageId})、payload 只放 ID 与类型,Worker 从数据库读取权威数据,不放 2MB blob;attempts 如 5 次、指数退避;timeout 如 30s。按紧急度/IO 分队列(default、critical、low),优先级仅在驱动支持时使用,否则用队列;调度用项目自带 scheduler,不要在 web 进程用 setInterval。
Worker 与失败处理:队列表可用 SELECT … FOR UPDATE SKIP LOCKED;每个任务一个效果,静默“半应用”要靠下一个任务补偿;日志记录 job_id、尝试次数、耗时,不记 payload 中的 PII;Worker 并发与数据库连接池要小于 API。网络/伙伴 5xx 重试退避;4xx/校验失败进 DLQ 不重试;超时按任务决定重试或 DLQ;重复投递按幂等 no-op。不要用宽泛 catch 标记成功;部署时 drain 或可中断任务。
反模式:已有 Worker 还在 HTTP 处理器 await sendEmail(),payload 放整个过期实体,无限重试已扣款场景,无 unique 的 cron 重复执行,Redis 队列无持久化却承载不可恢复的资金类任务(应使用 outbox + DB)。完成标准:任务有名称、payload 为 ID、有幂等键,定义重试/退避/超时/DLQ,用户 HTTP 不阻塞慢 I/O,Worker 有超时且日志无 PII,唯一约束防重复。其余平台、收费与价格信息暂未提供。