任务状态、进度与事件监听
🎯 引言
学完本文,你能从任务编号查询执行状态和结果,让 Worker 上报进度,并监听任务完成与失败事件。
沿用前两篇的 BullMQ 5.61.2、Redis 配置和 queue-config.mjs。
🧱 查询任务状态与结果
Job 状态表示它当前处于等待、处理中还是已经结束。提交程序保存任务编号后,可以再次查询该 Job,不必依赖 Worker 的控制台日志。
创建 inspect-job.mjs,将任务编号作为终端参数:
import { Queue } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';
const jobId = process.argv[2];
if (!jobId) throw new Error('请传入任务编号');
const queue = new Queue(queueName, {
connection: { ...connection, maxRetriesPerRequest: 1 },
});
queue.on('error', error => console.error(error.message));
try {
const job = await queue.getJob(jobId);
if (!job) {
console.log('任务不存在或已清理');
} else {
console.log('状态:', await job.getState());
console.log('结果:', job.returnvalue);
console.log('失败原因:', job.failedReason);
}
} finally {
await queue.close();
}
用第一篇提交任务时输出的编号查询:
node inspect-job.mjs 任务编号
常见状态包括 waiting、active、completed 和 failed。任务被清理后,查询会返回不存在;不能把不存在当作成功。
📊 上报与读取任务进度
任务进度是处理函数写入 Job 的当前进展值,常用于较长工作向调用方报告已完成的阶段。进度由 Worker 更新,其他程序可通过 Job 读取。
新建 progress-worker.mjs:
import { Worker } from 'bullmq';
import { setTimeout as delay } from 'node:timers/promises';
import { connection, queueName } from './queue-config.mjs';
const worker = new Worker(queueName, async job => {
for (const progress of [25, 50, 75, 100]) {
await delay(500);
await job.updateProgress(progress);
}
return { message: '处理完成' };
}, { connection: { ...connection, maxRetriesPerRequest: null } });
worker.on('completed', job => console.log('完成:', job.id));
worker.on('error', error => console.error(error.message));
process.once('SIGINT', async () => { await worker.close(); });
updateProgress() 的值可以是数字或对象,本文使用百分比整数。把此 Worker 运行后,向相同队列提交任务;Worker 每半秒更新一次进度,结束时返回结果。
进度由程序自行定义,不会自动换算成剩余时间。只有任务步骤确实能估算时,百分比才有意义。
📣 Worker 本地事件
Worker 事件由创建该 Worker 的进程接收,适合在本机记录任务完成、失败或运行错误。
常见事件有 completed、failed 和 error。前两者针对任务处理结果,error 通常表示 Worker 自身运行或连接错误,日志内容应区分。
在 Worker 创建后注册监听:
worker.on('completed', (job, result) => {
console.log('任务完成:', job.id, result);
});
worker.on('failed', (job, error) => {
console.error('任务失败:', job?.id, error.message);
});
worker.on('error', error => console.error('Worker 错误:', error.message));
这些监听只能观察当前 Worker 接收到的事件,不适合让独立 Web 服务查询全队列变化。
🌐 QueueEvents 队列事件
QueueEvents 用于从队列层面接收任务事件,可以由与 Worker 不同的进程监听。适合 Web 服务需要响应任务完成通知,或独立监控进程记录队列变化的情况。
创建 queue-events.mjs:
import { QueueEvents } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';
const events = new QueueEvents(queueName, { connection });
events.on('completed', ({ jobId, returnvalue }) => {
console.log('队列任务完成:', jobId, returnvalue);
});
events.on('failed', ({ jobId, failedReason }) => {
console.error('队列任务失败:', jobId, failedReason);
});
events.on('error', error => console.error('事件监听错误:', error.message));
await events.waitUntilReady();
console.log('开始监听队列事件');
process.once('SIGINT', async () => { await events.close(); });
QueueEvents 使用 Redis Stream 收集队列事件,因此监听启动前已经发生的事件不会自动作为新事件重放。需要当前任务结果时,仍应按 Job 编号查询。
先运行监听脚本,再在另一个终端运行 add-job.mjs。事件监听终端会显示完成的 Job 编号和结果。事件机制见 BullMQ Events 文档。
🧹 监听结束与资源释放
事件监听器会保持进程运行。脚本退出时调用 close(),停止监听并释放连接;Worker 退出时使用 Worker 自己的 close()。两者是不同对象,各自负责自己的连接资源。
❓ 知识问答
Q1:completed 事件没有触发,能证明任务失败了吗?
不能。监听可能启动得太晚、进程可能断开,或任务记录已经被清理;按 Job 编号查询状态更适合确认单项任务。
Q2:进度设为 80,就代表还剩 20% 时间吗?
不一定。进度表示处理函数报告的值,不是时间预测。
Q3:QueueEvents 与 Worker 的 completed 监听有什么区别?
Worker 事件由本地 Worker 接收;QueueEvents 可在其他进程监听队列事件。
🧪 小练习
让 Worker 每处理一个步骤就更新一次进度,比较 Worker 本地事件和 QueueEvents 输出的信息。
// 请在这里编写代码
🎉 恭喜你已经能够查询任务并观察执行进度啦!
