Queue、Worker 与 Job

使用 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 的连接和事件配置:

write-text.mjs
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,监听相同队列并调用上面的处理函数:

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 的分工啦!