BullMQ 简介与快速入门
🎯 引言
学完本文,你能启动 BullMQ 所需的 Redis 服务,在 Node.js 中安装 BullMQ 并提交一项任务。
🧱 BullMQ 是什么
BullMQ 是一个用于管理 Node.js 后台任务的库。应用可以先把任务交给 BullMQ 保存,再由 Worker 在后台领取并执行。提交任务的程序和执行任务的程序可以分别运行。
BullMQ 主要提供任务的排队、延迟、状态与失败重试等能力。它不会替你完成任务本身,具体的文件处理、邮件发送等逻辑仍由你编写。
💡 BullMQ 常用在哪些地方
| 需求 | 后台任务的作用 |
|---|---|
| 生成较大的文件 | 用户先取得任务编号,文件生成后再查看结果 |
| 处理上传图片 | 上传完成后在后台压缩或生成缩略图 |
| 发送通知邮件 | 主要操作完成后异步发送,并在暂时失败时重试 |
| 定期整理数据 | 按计划执行清理或同步工作 |
如果用户必须立刻得到结果,例如校验密码,就应在当前操作中完成,不应先报告成功再等待后台判断。
🧱 BullMQ 与 Redis 的关系
Redis 是保存任务信息并响应读写的独立服务,BullMQ 是使用 Redis 保存和调度任务的 Node.js 库。安装 BullMQ 不会自动启动 Redis;运行 Worker 也必须能连接到保存任务的 Redis。
BullMQ 会在 Redis 中保存任务状态和调度信息,因此这个实例不能使用会随意淘汰键的缓存策略。Redis 的 noeviction 策略会在内存不足时拒绝新增写入,避免队列数据被缓存淘汰规则静默删除。
🛠 启动 Redis 并安装 BullMQ
本课程示例使用 Node.js 22.9.0、BullMQ 5.61.2、Redis 7.4.2。Docker 安装与容器操作见 Docker 课程。启动专用练习实例:
docker run -d --name bullmq-redis \
-p 127.0.0.1:6380:6379 \
-v bullmq-redis-data:/data \
redis:7.4.2 redis-server --appendonly yes --maxmemory-policy noeviction
6380 是本机连接端口,容器内 Redis 仍使用 6379。数据卷保存 Redis 文件,appendonly yes 开启 AOF 持久化。任务数据与可重建缓存用途不同,应使用专用实例或由运维明确配置隔离。
在练习目录安装指定版本:
npm install --save-exact bullmq@5.61.2
🧰 配置 BullMQ 连接
创建 queue-config.mjs,让后续 Queue 与 Worker 使用相同连接地址和队列名称:
export const connection = {
host: process.env.REDIS_HOST ?? '127.0.0.1',
port: Number(process.env.REDIS_PORT ?? 6380),
};
export const queueName = 'course-tasks';
host 和 port 指向 Redis 服务;queueName 标识一组任务,生产者与 Worker 必须使用同一个名称。真实部署时通过环境变量提供服务地址,避免把环境地址写死在项目中。
Queue 与 Worker 在 BullMQ 5 中有不同的 Redis 重试需求。提交方稍后会明确设置有限重试,Worker 则需要允许持续连接;连接选项会在各自第一次使用时说明。
🛠 提交第一项任务
创建 add-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('BullMQ 连接错误:', error.message));
try {
const job = await queue.add('write-text', { text: 'Hello BullMQ' });
console.log('已提交任务:', job.id);
} finally {
await queue.close();
}
queue.add() 的第一个参数是任务类型名称,第二个参数是传给处理函数的数据。任务编号由 BullMQ 生成,可用于后续查询。关闭 Queue 释放当前脚本的连接,不会删除已提交任务。
运行脚本:
node add-job.mjs
终端输出任务编号。由于还没有创建 Worker,任务会等待处理;下一篇会单独编写 Worker 并观察任务执行。
❓ 知识问答
Q1:BullMQ 是不是 Redis 的另一种叫法?
不是。BullMQ 是 Node.js 库,Redis 是单独运行的服务,BullMQ 使用 Redis 保存队列数据。
Q2:任务一提交就开始运行了吗?
不一定。需要有 Worker 连接相同 Redis 并监听相同队列,任务才会被处理。
Q3:开发缓存和 BullMQ 任务可以共用一个会淘汰键的 Redis 吗?
不应这样配置。缓存淘汰可能移除 BullMQ 的任务数据,应使用专用实例,或确保相关键不会被淘汰。
🧪 小练习
修改任务名称与 text 内容,再提交一次,观察任务编号是否变化。
// 请在这里编写代码
🎉 恭喜你已经准备好 BullMQ 与 Redis 的运行环境啦!
