Queue、Worker 与 Job
🎯 引言
学完本文,你能提交一项任务、在独立 Worker 中执行它,并观察任务从等待到完成的过程。
沿用上一篇安装的 Node.js 22.9.0、BullMQ 5.61.2、Redis 7.4.2 及 queue-config.mjs。
🧱 Queue、Worker 与 Job 的分工
Queue 是提交和查询任务的入口,Worker 负责领取并执行任务,Job 表示一次具体的任务记录。Queue 和 Worker 使用相同队列名称,才能看到同一批 Job。
| 对象 | 作用 | 本文中的例子 |
|---|---|---|
| Queue | 添加和查询任务 | course-tasks 队列 |
| Worker | 调用处理函数完成工作 | 把文本写入文件 |
| Job | 保存单次任务名称、编号与数据 | 一次文件写入请求 |
这种分工适合让 Node.js Web 服务快速提交任务,由另一个常驻进程消化任务。Queue 负责管理,不会自动创建处理函数。
🧰 Job 的生命周期
Job 通常从等待 Worker 领取开始,领取后处于处理中,处理函数正常返回后完成;处理函数抛出错误时进入失败处理。延迟、重试等状态会在后续章节讲解。
Job 数据会序列化后保存在 Redis,因此应传递 JSON 可表示的数据,如字符串、数字和普通对象。不要传函数、文件句柄或连接池。
🛠 创建任务处理函数
创建 write-text.mjs,让处理逻辑独立于 Worker 的连接和事件配置:
import { mkdir, writeFile } from 'node:fs/promises';
export async function writeText(job) {
if (job.name !== 'write-text' || typeof job.data.text !== 'string') {
throw new Error('任务名称或文本数据无效');
}
await mkdir('./output', { recursive: true });
const filePath = `./output/${encodeURIComponent(job.id)}.txt`;
await writeFile(filePath, job.data.text, 'utf8');
return { filePath };
}
Worker 调用 writeText(job)。正常返回的对象成为 Job 的结果;抛出错误表示处理失败。文件名使用 Job 编号,使不同任务生成不同文件。
🛠 使用 Worker 消费任务
创建 worker.mjs,监听相同队列并调用上面的处理函数:
import { Worker } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';
import { writeText } from './write-text.mjs';
const worker = new Worker(queueName, writeText, {
connection: { ...connection, maxRetriesPerRequest: null },
});
worker.on('completed', (job, result) => {
console.log('任务完成:', job.id, result.filePath);
});
worker.on('failed', (job, error) => {
console.error('任务失败:', job?.id, error.message);
});
worker.on('error', error => console.error('Worker 连接错误:', error.message));
process.once('SIGINT', async () => { await worker.close(); });
Worker 需要持续等待 Redis 恢复,所以连接选项允许命令持续重试。completed 和 failed 由这个 Worker 进程接收;error 表示 Worker 自身连接或运行错误。停止时 close() 会等待正在执行的任务。
先启动 Worker:
node worker.mjs
保持这个终端运行,再在另一个终端提交任务:
node add-job.mjs
Worker 应输出任务编号和生成文件路径。打开 output 目录中的文件,可看到 Hello BullMQ。
如果先提交后启动 Worker,Job 会留在等待状态,Worker 启动后再处理。生产者与 Worker 可以在不同进程甚至不同机器,只要它们连接同一个 Redis 和队列。
🧰 Queue 的关闭与任务保留
Queue 在脚本退出前应调用 close(),释放连接。关闭 Queue 不会删除队列,也不会清除 Job;任务记录会根据队列清理设置保留,清理规则在可靠性篇讲解。
Worker 则用 close() 等待已领取的任务结束。进程被强制终止时,处理中任务后续可能重新领取,因此任务处理应能承受重复执行。
❓ 知识问答
Q1:Queue 和 Worker 必须放在同一个文件吗?
不需要。实际常将提交任务的应用与执行任务的 Worker 分开运行。
Q2:Worker 没有任务时会退出吗?
不会。它会保持运行并等待新任务,直到调用 close() 或进程结束。
Q3:Job 的返回值在哪里?
Worker 的处理函数返回值保存在 Job 结果中,可在后续文章里通过 Job 查询。
🧪 小练习
停止 Worker 后提交两项任务,再重新启动 Worker,观察它依次生成的文件内容。
// 请在这里编写代码
🎉 恭喜你已经掌握 Queue、Worker 与 Job 的分工啦!
