延迟任务与定时任务

使用 BullMQ 安排稍后执行和重复执行的任务,并管理调度规则。

🎯 引言

学完本文,你能提交一项延迟任务、建立定时规则,并在实验结束后删除规则。

沿用 BullMQ 快速入门 中的 Redis 配置、queue-config.mjs 和 write-text.mjs。本课程使用 BullMQ 5.61.2。


🧱 延迟任务与定时任务的作用

延迟任务是一项稍后才可执行的 Job;定时任务是一条按规则反复生成 Job 的调度规则。延迟任务只安排一次,定时规则则持续产生多次执行。

延迟任务适合稍后提醒或等待外部状态变化后再次检查;定时任务适合固定间隔同步和周期性整理。Worker 忙碌时,任务开始时间可能晚于计划时间,队列不等于精确计时器。


🕒 延迟任务

在 delayed-job.mjs 中创建一次延迟任务:

delayed-job.mjs
import { Queue } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';

const queue = new Queue(queueName, {
    connection: { ...connection, maxRetriesPerRequest: 1 },
});
queue.on('error', error => console.error(error.message));
try {
    const job = await queue.add('write-text', { text: '稍后生成的文本' }, {
        delay: 5000,
    });
    console.log('延迟任务编号:', job.id);
} finally {
    await queue.close();
}

delay 单位是毫秒,表示至少等待 5 秒后才进入可处理状态,不限制任务本身的执行时长。保持上一篇的 Worker 运行,再执行:

node delayed-job.mjs

提交后先显示任务编号,等待时间结束且 Worker 可用后,再生成文本文件。


🗓️ 定时任务与 Job Scheduler

Job Scheduler 是保存重复任务规则的对象。Worker 处理能力足够时,它按间隔生成后续 Job;规则与每次生成的 Job 是不同记录。

创建 schedule.mjs,配置每 10 秒生成一次文件的规则:

schedule.mjs
import { Queue } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';

const queue = new Queue(queueName, {
    connection: { ...connection, maxRetriesPerRequest: 1 },
});
queue.on('error', error => console.error(error.message));
try {
    await queue.upsertJobScheduler('text-every-10s', { every: 10000 }, {
        name: 'write-text',
        data: { text: '定期生成的文本' },
    });
    console.log('调度规则已保存');
} finally {
    await queue.close();
}

第一个参数是规则的唯一标识;同一标识重复调用会更新规则,不会另外创建一份。every 以毫秒指定重复间隔,后面的对象是每次 Job 的名称与数据。

node schedule.mjs

保持 Worker 运行,可以看到陆续生成的文件。BullMQ 5.19 及之后版本,新建调度规则时会尽快产生首个 Job,之后按规则继续生成;实际处理仍受 Worker 是否可用影响。参见 BullMQ Job Schedulers 文档。


🕘 按日历时间重复执行

需要按日历时间时,将 schedule.mjs 中的 upsertJobScheduler 调用替换为:

await queue.upsertJobScheduler('text-every-10s', {
    pattern: '0 0 9 * * *',
    tz: 'Asia/Shanghai',
}, {
    name: 'write-text',
    data: { text: '每天上午生成的文本' },
});

pattern 使用 Cron 表达式,六个位置依次表示秒、分、时、日、月、星期;这个表达式表示上海时区每天上午 9 点。tz 指定解释日历时间的时区,避免服务器时区不同导致执行时刻变化。


🧹 删除调度规则

实验结束后,创建 remove-schedule.mjs 删除规则:

remove-schedule.mjs
import { Queue } from 'bullmq';
import { connection, queueName } from './queue-config.mjs';

const queue = new Queue(queueName, {
    connection: { ...connection, maxRetriesPerRequest: 1 },
});
queue.on('error', error => console.error(error.message));
try {
    console.log(await queue.removeJobScheduler('text-every-10s'));
} finally {
    await queue.close();
}
node remove-schedule.mjs

返回 true 表示规则已删除。已创建或正在执行的 Job 不会因为删除规则而自动取消。


❓ 知识问答

Q1:delay 设置为 5 秒,任务一定在第 5 秒准时完成吗?

不一定。5 秒后任务才可以开始执行,Worker 繁忙或不可用时会继续等待。

Q2:定时规则和每次生成的 Job 是同一个对象吗?

不是。规则持续产生 Job;Job 记录某一次具体执行。

Q3:脚本退出后定时规则还有效吗?

有效。规则存储在 Redis 中,直到被删除或队列数据被清理。


🧪 小练习

将间隔从 10 秒改为 30 秒,运行后再调用删除脚本,观察已有 Job 与调度规则的区别。

// 请在这里编写代码

🎉 恭喜你已经学会安排延迟与定时任务啦!