任务状态、进度与事件监听

查询 BullMQ Job 状态与结果,记录处理进度,并监听 Worker 和队列事件。

🎯 引言

学完本文,你能从任务编号查询执行状态和结果,让 Worker 上报进度,并监听任务完成与失败事件。

沿用前两篇的 BullMQ 5.61.2、Redis 配置和 queue-config.mjs。


🧱 查询任务状态与结果

Job 状态表示它当前处于等待、处理中还是已经结束。提交程序保存任务编号后,可以再次查询该 Job,不必依赖 Worker 的控制台日志。

创建 inspect-job.mjs,将任务编号作为终端参数:

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:

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:

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 输出的信息。

// 请在这里编写代码

🎉 恭喜你已经能够查询任务并观察执行进度啦!