Nestjs框架: nestjs-bull的使用与相关queue的规划

关注

原创 2025-06-28 23:50:37 1.2k 阅读 AI 写同款· GEO 优化 ›

Nest.js实战——扫描application下的所有metadata 背景最近项目需要到一个基于事件驱动的一些业务模块，就封装一下类似@nestjs/bull一样的API去进行事件注册和触发，减少了一定的代码量。通过Nest Core的功能去完成全局扫描metadata 通过@nestjs/core，我们可以找到相应框架实现的功能和工具，去完成我们需要写业务逻辑前的工作 DiscoveryService —— 扫描所有app module注册到的controllers和services 首先我们需要扫描所有的controller和service，通过DiscoverySe 阅读详情

概述

在使用定时任务时，发现其只能处理简单任务，且由于定时任务是在 NestJS 运行过程中创建的
大量不同定时任务创建时可能会占用 NestJS 服务的内存
针对大量高并发任务场景和秒级任务应用场景，需要使用队列来创建此类任务
NestJS 官网提供了一个队列的官方应用方案叫做 nestjs-bull
它使用 Redis 作为存储方案来存储消息队列的数据，封装了生产者、消费者和监听者等好用的接口

规划的目录结构

conditional
- queue
  - queue.module.ts
  - services
    - tomic.consumer.ts
    - scheduled-tasks.consumer.ts
    - index.ts

1 ) 安装

$ npm i --save @nestjs/bull bull

2 ) 配置

# BULL任务队列
QUEUE_ON=false
QUEUE_REDIS_HOST=localhost
QUEUE_REDIS_PORT=6379
QUEUE_REDIS_PASSWORD=exmaple

注意，这里的 redis 只支持哨兵模式和单节点模式，
没有 cluster 的配置方式
但是 bull 本身对接的是 ioredis
可以使用 Connector 实现 redis 的 cluster 模式
cluster 是分布式的应用场景，绝大多数用单机或哨兵这样的高可用即可
参考官方配置文档
看下面的 defaultJobOptions 配置任务的选项
- 高级选项说明文档

没有用到就不必动这些配置项目

interface JobOpts {
  priority: number; // 优先级  从 1 (最高优先级) to MAX_INT  (最低优先级).

  delay: number; // 任务的延迟执行时间

  attempts: number; // 任务的尝试次数

  repeat: RepeatOpts; // 重复选项

  backoff: number | BackoffOpts; // 任务失败的 自动重试策略

  lifo: boolean; // 如果设置为 true, 则是后进先出的队列
  timeout: number; // 超时时间

  jobId: number | string; // 给任务设置一个具体的 id 默认是一个唯一的整数


  removeOnComplete: boolean | number; // 如果设置 true 成功之后删除
  // completes. A number specified the amount of jobs to keep. Default behavior is to keep the job in the completed set.

  removeOnFail: boolean | number; // 如果设置 true 则失败之后 删除

  stackTraceLimit: number; // 限制 记录 在堆栈中追踪的行数
}

3 ）创建模块，这是一个可选模块，所以

$ nest g mo conditional/queue --no-spec

conditional/queue/queue.module.ts

import { Module } from '@nestjs/common';
import { BullModule } from '@nestjs/bull';
import { QueueConsumers } from './services';
import { ConfigService } from '@nestjs/config';
import { getEnvs } from '@/utils/get-envs';
import { MailModule } from '../mail/mail.module';
import { toBoolean } from '@utils/format';

@Module({})
export class QueueModule {
	static register(): DynamicModule {
		const parsedConfig = getEnvs(); // 获取配置的方法
		const mailOn = parsedConfig['MAIL_ON'];
		const conditionalModuleImports = [];

		if (toBoolean(mailOn)) {
			conditionalModuleImports.push(MailModule);
		}

		return {
			module: QueueModule,
			imports: [
				...conditionalModuleImports,
				BullModule.forRootAsync({
					inject: [ConfigService],
					useFactory: (configService: ConfigService) => {
						const redisHost = configService.get('QUEUE_REDIS_HOST');
						const redisPort = configService.get('QUEUE_REDIS_PORT');
						const redisPassword = configService.get('QUEUE_REDIS_PASSWORD');
						return {
							redis: {
								host: redisHost,
								port: redisPort，
								password: redisPassword,
							},
							defaultJobOptions: {
								removeOnComplete: true,
								// 默认成功失败都删除
								// 如果，Fail了需要重试逻辑的话，这里设置为 false
								removeOnFail: false,
							}
						}
					}
				}),
				// 注册的时候，使用
				BullModule.registerQueue(
					{ name: 'tomic' }, 
					// {  name: 'email' }, // 邮件相关
					// { name: 'data-processing' }, // 数据处理
					// { name: 'real-time-messages' }, // 实时消息
					// { name: 'image-processing' }, // 图片上传、压缩
					{ name: 'scheduled-tasks' }, // 计划任务
					// { name: 'order-processing' }, //  订单处理，比如信用卡账单经过一个月才会入账
				),
			],
			providers: [QueueConsumers],
			exports: [BullModule],
		}
	}
}

4 ) 在一个测试模块中导入 QueueModule

	import { Module } from '@nestjs/common';
	import { BullModule } from '@nestjs/bull';
	
	@Module({
		imports: [
			QueueModule.register(),
		],
		controllers: [AuthController],
	})
	
	export class AuthModule {}

之后在测试模块的控制器下使用，如下

import { InjectQueue } from '@nestjs/bull';
import { Queue } from 'bull';
import { diffNow } from '../utils/time';

@Controller('auth')
export class AuthController {
	constructor(
		@InjectQueue('tomic') private queue: Queue,
		@InjectQueue('scheduled-tasks') private queue2: Queue,
	){}
	// 这里是 模拟 创建
	@Get('test')
	addQueue() {
		this.queue.add({
			foo: '123',
		});
		return 'ok';
	}
	@Get('test2')
	addQueue2() {
		// 选项版本
		this.queue2.add('sendMail', {}, {
			delay: diffNow('2025-07-01 00:00:05'), // 从当前时间来计算，需要延迟多久，单位 秒
		});
		return 'ok';
	}
}

这里 utils/time.ts 需要安装dayjs, $ pnpm install dayjs

import dayjs, { UnitType } from 'dayjs';
import utc from 'dayjs/plugin/utc';
dayjs.extend(utc);

export function diffNow (
	dateString: string,
	offset: number = 0,
	unit: UnitType = 'millisecond',
) {
	const now = dayjs().utc().add(offset, 'hour');
	const targetDate = dayjs(dateString).utc();

	const diff = targetDate.diff(now, unit);
	return diff;
}

5 ) 这里是模拟消费服务 tomic.consumer.ts

import { Processor, Process } from '@nestjs/bull';
import { Job } from 'bull';

@Processor('tomic')
export class TomicConsumer {
	@Process()
	async transcode(job: Job<unknown>) {
		let progress = 0;
		for (let i= 0; i < 10; i+) {
			console.log(`job data ${job.data} progress ${progress}`);
			progress += 1;
			await job.progress(progress);
		}
		return {};
	}
}

更多 process 方法查看
除了 process 方法，官方文档中还有很多 job 实例暴露出来的方法
如 log、getdate、update、remove、retry 等

7 ）queue/services/scheduled-tasks.consumer.ts

import { ISendMailOptions, MailerService } from '@nestjs-modules/mailer';
import { Processor, Process } from '@nestjs/bull';
import { Logger, Optional } from '@nestjs/common';
import { Job } from 'bull';

@Processor('scheduled-tasks')
export class ScheduledTasksConsumer{
	logger = new Logger('ScheduledTasksConsumer');
	// 这里注入 邮件服务 和 短信服务 TODO
	constructor(@Optional() private mailerService: MailerService) {}
	
	// 发送邮件单个任务
	@Process('sendMail')
	async sendMail(job: Job<ISendMailOptions>) {
		// 这里可以临时设置为 Job<unknown> 测试
		const { data } = job;
		if (!this.mailerService) {
			this.logger.warn('Mail配置异常，请检查配置文件!');
			return;
		}
		const res = await this.mailerService.sendMail(data);
		// TODO写到数据库
		console. log('~ScheduledTasksConsumer ~ sendMail ~ res:', res);
	}
	
	// 
	//发送短信单个任务
	@Process('sendSms')
	async sendSms(job: Job<unknown>) {
		console.log'~ScheduledTasksConsumer~ sendSms~job:';
	}
}

6 ）queue/services/index.ts

import { Provider } from '@nestjs/common';
import { ToimcConsumer } from './tomic.consumer';
import { ScheduledTasksConsumer } from './scheduled-tasks.consumer';

export const QueueConsumers: Provider[] = [
	ToimcConsumer,
	ScheduledTasksConsumer,
];

其他 queue 的消费模块都注入到这里

关于 defaultJobOptions.removeOnFail

上面 queue.module中的 defaultJobOptions 的配置项 removeOnFail 设置为 false
这里，引入生命周期方法 event-listeners-1

Local event listeners 和 Global event listeners 之间的区别

如果有多个处理进程，就需要用 Global event listeners
如果只是使用默认的处理进程，那么就可以使用 Local event listeners
因为我们的 ScheduledTasksConsumer 中有多个处理器，所以我们需要用到全局的

创建 conditional/queue/services/scheduled-tasks-events.service.ts 文件

import {
        OnGlobalQueueActive,
        OnGlobalQueueCleaned,
        OnGlobalQueueCompleted,
        OnGlobalQueueDrained,
        OnGlobalQueueError,
        OnGlobalQueueFailed,
        OnGlobalQueuePaused,
        OnGlobalQueueProgress,
        OnGlobalQueueRemoved,
        OnGlobalQueueResumed,
        OnGlobalQueueStalled,
        OnGlobalQueueWaiting,
        Processor,
        InjectQueue
    } from '@nestjs/bull';
    import { Job, Queue } from 'bull';

    @Processor('scheduled-tasks') // 这个名称 要和上面的保持一致
    export class ScheduledTasksEventsService {
		constructor(@InjectQueue('scheduled-tasks') private queue: Queue) {}
        @OnGlobalQueueError()
        handleGlobalError(error: Error){
            console.error(`Global Error:${error.message}`);
        }
        @OnGlobalQueueWaiting()
        handleGlobalWaiting(jobId: number | string) {
            console.log(`Job with ID ${jobId} is waiting.`);
        }
        @OnGlobalQueueActive()
        handleGlobalActive(job:Job) {
        	// 拿到下面的 失败job 列表后，可以调用 job 的 retry 逻辑
        	// 或者 moveToCompleted 或 moveToFailed
        	// 参考：https://github.com/OptimalBits/bull/blob/master/REFERENCE.md#job
            this.queue.getFailed().then((fails) => {
            	console.log(fails); // 这里是 失败 job 的列表
            });
            console.log('------);
            console.log(`Job ${job.id} is now active.`);
        }
        @OnGlobalQueueStalled()
        handleGlobalStalled(job: Job) {
            console.log(`Job ${job.id} has stalled.`);
        }
        @OnGlobalQueueProgress()
        handleGlobalProgress(job: Job, progress: number) {
            console.log(`Job ${job.id} progress: ${progress}`);
        }
        @OnGlobalQueueCompleted()
        handleGlobalCompleted(job: Job, result: any) {
            console.log(`Job ${job.id} completed with result: ${result}`);
        }
        @OnGlobalQueueFailed()
        handleGlobalFailed(job: Job, err: Error) {
            console.error(`Job ${job.id} failed with error: ${err.message}`);
        }
        @OnGlobalQueuePaused()
        handleGlobalPaused() {
            console.log(`The queue has been paused.`);
        }
        @OnGlobalQueueResumed()
        handleGlobalResumed() {
            console.log(`The queue has been resumed.`);
        }
        @OnGlobalQueueCleaned()
            handleGlobalCleaned(jobs: Job[], type: string) {
            console.log(`Jobs cleaned of type ${type}: ${jobs. length}`);
        }
        @OnGlobalQueueDrained()
        handleGlobalDrained() {
            console.log(`All waiting jobs have been processed.`);
        }
        @OnGlobalQueueRemoved()
        handleGlobalRemoved(job:Job){
            console.log(`Job ${job.id} was removed.`);
        }
}

注意，怎样在上面拿到执行失败的任务，来了解具体的详情呢？
关注上面的 constructor 以及 handleGlobalActive 也就是通过注入 queue 的实例
关注相关注释，这里可以做一些事情, 不做过多阐述

找到 queue/services/index.ts 在后面添加

import { Provider } from '@nestjs/common';
import { ScheduledTasksConsumer } from'./scheduled-tasks.consumer';
import { ScheduledTasksEventsService } from'./scheduled-tasks-events.service';

export const QueueConsumers: Provider[] = [
	ScheduledTasksConsumer,
	ScheduledTasksEventsService, // 添加
}