事件

Event Emitter 包（@nestjs/event-emitter）提供了一个简单的观察者实现，允许你订阅和监听应用程序中发生的各种事件。事件是解耦应用程序各个方面的好方法，因为单个事件可以有多个互不依赖的监听器。

EventEmitterModule 在内部使用 eventemitter2 包。

入门

首先安装所需的包：

$ npm i --save @nestjs/event-emitter

安装完成后，将 EventEmitterModule 导入根 AppModule 并运行 forRoot() 静态方法，如下所示：

// app.module.ts
import { Module } from '@nestjs/common';
import { EventEmitterModule } from '@nestjs/event-emitter';

@Module({
  imports: [
    EventEmitterModule.forRoot()
  ],
})
export class AppModule {}

.forRoot() 调用初始化事件发射器并注册应用中存在的任何声明式事件监听器。注册发生在 onApplicationBootstrap 生命周期钩子触发时，确保所有模块都已加载并声明了任何计划的作业。

要配置底层的 EventEmitter 实例，请将配置对象传递给 .forRoot() 方法，如下所示：

EventEmitterModule.forRoot({
  // 设置为 `true` 以使用通配符
  wildcard: false,
  // 用于分隔命名空间的分隔符
  delimiter: '.',
  // 设置为 `true` 以发出 newListener 事件
  newListener: false,
  // 设置为 `true` 以发出 removeListener 事件
  removeListener: false,
  // 可以分配给事件的最大监听器数量
  maxListeners: 10,
  // 当分配的监听器超过最大数量时在内存泄漏消息中显示事件名称
  verboseMemoryLeak: false,
  // 如果发出错误事件且没有监听器，则禁用抛出 uncaughtException
  ignoreErrors: false,
});

分发事件

要分发（即触发）事件，首先使用标准的构造函数注入注入 EventEmitter2：

constructor(private eventEmitter: EventEmitter2) {}

提示

从 @nestjs/event-emitter 包导入 EventEmitter2。

然后在类中使用它，如下所示：

this.eventEmitter.emit(
  'order.created',
  new OrderCreatedEvent({
    orderId: 1,
    payload: {},
  }),
);

监听事件

要声明事件监听器，请使用 @OnEvent() 装饰器在方法定义前进行装饰，该方法包含要执行的代码，如下所示：

@OnEvent('order.created')
handleOrderCreatedEvent(payload: OrderCreatedEvent) {
  // 处理和处理 "OrderCreatedEvent" 事件
}

警告

事件订阅者不能是请求作用域的。

第一个参数可以是简单事件发射器的 string 或 symbol，在通配符发射器的情况下是 string | symbol | Array<string | symbol>。

第二个参数（可选）是一个监听器选项对象，如下所示：

export type OnEventOptions = OnOptions & {
  /**
   * 如果为 "true"，则将给定的监听器前置（而不是追加）到监听器数组中。
   *
   * @see https://github.com/EventEmitter2/EventEmitter2#emitterprependlistenerevent-listener-options
   *
   * @default false
   */
  prependListener?: boolean;

  /**
   * 如果为 "true"，onEvent 回调在处理事件时不会抛出错误。否则，如果为 "false" 则会抛出错误。
   *
   * @default true
   */
  suppressErrors?: boolean;
};

提示

从 eventemitter2 了解更多关于 OnOptions 选项对象的信息。

@OnEvent('order.created', { async: true })
handleOrderCreatedEvent(payload: OrderCreatedEvent) {
  // 处理和处理 "OrderCreatedEvent" 事件
}

要使用命名空间/通配符，请将 wildcard 选项传递给 EventEmitterModule#forRoot() 方法。当启用命名空间/通配符时，事件可以是由分隔符分隔的字符串（foo.bar）或数组（['foo', 'bar']）。分隔符也可以作为配置属性（delimiter）进行配置。启用命名空间功能后，你可以使用通配符订阅事件：

@OnEvent('order.*')
handleOrderEvents(payload: OrderCreatedEvent | OrderRemovedEvent | OrderUpdatedEvent) {
  // 处理和处理事件
}

请注意，这样的通配符只适用于一个块。参数 order.* 将匹配例如 order.created 和 order.shipped 事件，但不会匹配 order.delayed.out_of_stock。要监听此类事件，请使用 EventEmitter2 文档中描述的多级通配符模式（即 **）。

使用此模式，你可以例如创建一个捕获所有事件的事件监听器。

@OnEvent('**')
handleEverything(payload: any) {
  // 处理和处理事件
}

提示

EventEmitter2 类提供了几个有用的与事件交互的方法，如 waitFor 和 onAny。你可以在这里阅读更多关于它们的信息。

防止事件丢失

在 onApplicationBootstrap 生命周期钩子之前或期间触发的事件——例如来自模块构造函数或 onModuleInit 方法的事件——可能会被遗漏，因为 EventSubscribersLoader 可能尚未完成监听器的设置。

为避免此问题，你可以使用 EventEmitterReadinessWatcher 的 waitUntilReady 方法，该方法返回一个在所有监听器注册完成后解析的 promise。此方法可以在模块的 onApplicationBootstrap 生命周期钩子中调用，以确保所有事件都被正确捕获。

await this.eventEmitterReadinessWatcher.waitUntilReady();
this.eventEmitter.emit(
  'order.created',
  new OrderCreatedEvent({ orderId: 1, payload: {} }),
);

注意

这仅对在 onApplicationBootstrap 生命周期钩子完成之前发出的事件是必需的。

示例

一个可用的示例在这里。