SuperAPI AI 工具集

bullmq-game-queues

编程与开发

查看项目

更新于 11-15 03:09

技能介绍

本技能面向使用 BullMQ 和 Redis 构建游戏后端后台任务的开发者,提供在 BullMQ 6.7.6 下可编译的示例代码(位于 boilerplate/ 与 templates/ 目录),未覆盖的 API 需查阅 BullMQ 官方文档。

安装方式为执行 bun add bullmq ioredis。BullMQ 6 默认通过 ioredis 连接,但仅将其列为可选 peer 依赖,因此需自行安装。之后按 Files 部分的编号顺序复制文件。

按领域拆分队列:matchmaking(find-match、cancel)、game-event(比赛结果、动作结算)、reward(发放、每日登录、成就)、notification(推送、游戏内邮件、邮件)、analytics(追踪、聚合)。拆分后可独立扩缩容、暂停与排空某一领域而不影响其他领域。优先级只在单个队列内部生效,数字越小越先执行;无优先级的任务会先于所有有优先级的任务,因此在启用优先级的队列中应为每个任务都设置优先级。不同队列之间不存在优先级排序,例如 matchmaking 始终领先于 analytics,是因为它们各自拥有独立的工作线程。每个队列的工作线程并发数(templates/queue-config.ts 中的 concurrencySettings)按其自身负载设定,若 analytics 与 matchmaking 争抢 CPU,应放到不同进程运行。

幂等处理:BullMQ 会重试失败任务并重跑停滞任务,因此任何任务都可能执行多次。所有改变玩家状态的任务都携带 idempotencyKey,工作线程在同一数据库事务内校验、应用变更并记录该键,避免两次写入之间崩溃导致重复支付。要防止同一任务重复入队,可设置自定义 jobId(如 season-end-${seasonId}),该 id 不得包含冒号或为纯整数。每个任务只做一次状态变更,后续的奖励与通知通过派生任务完成;任务数据传 id 而非完整记录,由工作线程从数据库读取当前状态。

奖励发放:发放一律走 reward 队列,不在请求处理函数内联执行。rewardWorker 会先构建键,再调用 applyRewardOnce(key, (tx) => ...),在同一事务中记录键并发放货币、物品与经验,若键已存在则全部跳过,提交后再记录分析日志。广播奖励(BROADCAST_PLAYER_ID)仅作为触发器,工作线程为每个符合条件的玩家各入队一个奖励任务,键为 <run key>:<playerId>,自身不发放任何内容。支付流程记录购买后将奖励投递任务入队,以 checkout session id(一次性购买)或 invoice id(订阅周期)为键,与购买记录的唯一键一致,从而防止重放的 webhook 重复发放。

调度器:周期性任务使用 queue.upsertJobScheduler(id, { pattern, tz: 'UTC' }, template)。BullMQ 6 已移除 repeat.utc 和旧的 Queue.add(..., { repeat }) API。每次服务器启动时执行 upsert,可原地更新、不产生重复。模板中的数据在 upsert 时固定并被每次运行继承,不得放入日期或 Date.now();rewardWorker 从生成任务的 id 构建每次运行的键。调度器仅在上一个任务开始时才添加下一个任务,若午夜时奖励队列积压,每日发放会延迟,需按峰值设置并发。赛季结束与活动开始属于一次性延迟任务(delay 加 jobId),延迟任务在指定时间或之后运行而非精确准点,关闭赛季应以存储的结束时间为准。

连接与故障:生产者(API 处理函数)使用 maxRetriesPerRequest: 1,使 Redis 故障时向玩家返回错误而非挂起;工作线程使用 maxRetriesPerRequest: null,否则 BullMQ 会抛出异常。所有 Queue、Worker 与 QueueEvents 使用相同的 prefix,否则 QueueEvents 监听默认 bull 前缀而收不到事件。不要设置 ioredis 的 keyPrefix(BullMQ 有自己的前缀)。耗尽重试的任务进入 failed 集合,用 removeOnFail 至少保留 7 天,并对 failed 事件告警后在该集合中排查。CPU 密集的处理逻辑无法续期锁,任务会被标记为停滞并重跑,应将重型模拟移出工作线程的事件循环。

常见陷阱:按玩家的限流不应放在 BullMQ 中(工作线程的限流器对整个队列全局生效),应在 API 层结合 Redis 限流实现。在 matchmaking 中抛出异常以“稍后重试”会以相同条件重跑相同负载,若需随时间扩大搜索范围,应基于 queuedAt 在处理逻辑中计算范围。仪表盘与告警应使用 QueueEvents(worker.on(...) 只能看到本进程)。

文件说明:templates/job-types.ts(队列名、任务负载与结果类型、任务名、Priority 枚举)、templates/queue-config.ts(生产者与工作线程连接、共享前缀、重试、限流、并发)、boilerplate/queues.ts(每个领域一个类型化 Queue 及用于监控的 QueueEvents)、boilerplate/workers.ts(每个队列一个 Worker,替换底部占位函数)、boilerplate/scheduler.ts(每日奖励、赛季结束、定时事件或周期快照,复用 queues.ts 中的队列,closeAllQueues() 会一并关闭)、references/sources.md(各规则对应的文档页面与原文)。

相关技能包括 redis-game-patterns、postgres-game-schema、matchmaking-system、stripe-game-payments、game-backend-architecture、monitoring-game-ops。检查清单涵盖依赖安装、按领域分队列与并发设定、状态变更任务的幂等键、调度器使用 UTC 且模板无每次运行的值、生产者快速失败与工作线程连接参数、统一前缀、失败与停滞告警、关闭时清理全部队列与工作线程。