NestJS Enterprise Backend APIs · 课时

领域事件与 AggregateRoot

使用 EventBus 和 mergeObjectContext，从聚合根发出并发布领域事件。

领域事件与 AggregateRoot 是 CoddyKit 上的免费 NestJS Enterprise Backend APIs 课时。这是第 3 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 NestJS Enterprise Backend APIs 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Domain Events?

In an event-driven CQRS system, a domain event records something meaningful that already happened inside your domain: OrderPlaced, PaymentCaptured, UserDeactivated. They are named in the past tense because they are facts, not requests.

Domain events let you decouple side effects from the core write logic. Instead of an order service directly calling email, inventory, and analytics code, it simply emits OrderPlaced, and independent handlers react.

Command: an intent to change state (PlaceOrderCommand).
Event: a record of a change that occurred (OrderPlacedEvent).

NestJS provides first-class support for this through @nestjs/cqrs, the AggregateRoot base class, and the EventBus.

The AggregateRoot Base Class

An aggregate root is the entry point to a cluster of domain objects that change together and must stay consistent. In @nestjs/cqrs, you make a class an aggregate by extending AggregateRoot.

This base class gives you two key methods:

apply(event) — record a domain event that happened in this aggregate.
commit() — publish all recorded events to the EventBus.

The aggregate buffers events internally until you explicitly commit them. This separation lets you mutate state first and publish only after the change is safely persisted.

import { AggregateRoot } from '@nestjs/cqrs';

export class OrderPlacedEvent {
  constructor(
    public readonly orderId: string,
    public readonly total: number,
  ) {}
}

export class Order extends AggregateRoot {
  constructor(public readonly id: string) {
    super();
  }

  place(total: number) {
    // mutate state here, then record the fact
    this.apply(new OrderPlacedEvent(this.id, total));
  }
}

apply() Buffers, commit() Publishes

When you call this.apply(event), the event is pushed onto an internal array on the aggregate. Nothing is published yet.

Only when you call aggregate.commit() does NestJS iterate that buffer and hand each event to the publisher, which forwards them to the EventBus for handlers to consume.

This two-phase flow is intentional:

You can apply several events during one operation.
You persist the new state to the database.
Then you commit so events fire after a successful save, avoiding side effects on a transaction that later rolls back.

The Missing Publisher Problem

There is a catch. If you simply new Order(...) in a command handler and call commit(), nothing happens. The aggregate has no reference to the real EventBus — its default publisher is a no-op.

The aggregate must be wired to a publisher that knows how to push events onto the bus. That wiring is exactly what EventPublisher.mergeObjectContext (and mergeClassContext) provides.

Forgetting this step is the single most common reason newcomers report that their domain events "never fire" in NestJS CQRS.

mergeObjectContext: Wiring the EventBus

EventPublisher.mergeObjectContext(aggregate) takes an existing aggregate instance and injects the real publisher into it, so that a later commit() actually dispatches events to the EventBus.

Use it inside a command handler:

Build or load your aggregate.
Wrap it: const order = this.publisher.mergeObjectContext(rawOrder).
Run domain behavior (which calls apply internally).
Persist, then call order.commit().

Inject EventPublisher from @nestjs/cqrs through the constructor.

import { CommandHandler, ICommandHandler, EventPublisher } from '@nestjs/cqrs';
import { PlaceOrderCommand } from './place-order.command';
import { Order } from './order.aggregate';
import { OrderRepository } from './order.repository';

@CommandHandler(PlaceOrderCommand)
export class PlaceOrderHandler implements ICommandHandler<PlaceOrderCommand> {
  constructor(
    private readonly repository: OrderRepository,
    private readonly publisher: EventPublisher,
  ) {}

  async execute(command: PlaceOrderCommand): Promise<void> {
    const order = this.publisher.mergeObjectContext(
      new Order(command.orderId),
    );

    order.place(command.total); // applies OrderPlacedEvent
    await this.repository.save(order);
    order.commit(); // now events reach the EventBus
  }
}

mergeClassContext for Factories

Sometimes you reconstruct aggregates inside a factory or repository rather than newing them directly in the handler. For that, mergeClassContext returns a publisher-aware subclass.

Every instance created from the merged class is automatically context-bound, so you do not have to call mergeObjectContext on each one.

Use mergeObjectContext for a single instance you already hold; use mergeClassContext when a factory will produce many instances.

import { EventPublisher } from '@nestjs/cqrs';
import { Order } from './order.aggregate';

export class OrderFactory {
  constructor(private readonly publisher: EventPublisher) {}

  create(orderId: string): Order {
    // Order becomes a publisher-aware subclass
    const ContextOrder = this.publisher.mergeClassContext(Order);
    return new ContextOrder(orderId);
  }
}

Defining a Domain Event

A domain event in NestJS is just a plain class — typically implementing the marker interface IEvent. Keep events immutable and carry only the data handlers need.

Use readonly fields populated in the constructor.
Name in past tense: OrderPlacedEvent, not PlaceOrder.
Include identifiers and the minimal payload, not entire entities.

Because events may be serialized (for event sourcing or message brokers), avoid putting behavior or service references on them.

import { IEvent } from '@nestjs/cqrs';

export class OrderPlacedEvent implements IEvent {
  constructor(
    public readonly orderId: string,
    public readonly customerId: string,
    public readonly total: number,
    public readonly occurredAt: Date = new Date(),
  ) {}
}

Handling the Event

An @EventsHandler(OrderPlacedEvent) class subscribes to the event on the bus. Its handle method runs the side effect: sending email, updating a read model, decrementing inventory.

Handlers should be idempotent where possible, because at-least-once delivery (in distributed setups) can replay an event. Keep them small and focused — one handler per concern.

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { OrderPlacedEvent } from './order-placed.event';

@EventsHandler(OrderPlacedEvent)
export class OrderPlacedHandler implements IEventHandler<OrderPlacedEvent> {
  handle(event: OrderPlacedEvent): void {
    // side effect: e.g. enqueue a confirmation email
    console.log(`Order ${event.orderId} placed for ${event.total}`);
  }
}

Wiring the CqrsModule

To use any of this, import CqrsModule and register your handlers and aggregates' collaborators as providers. The module sets up the CommandBus, QueryBus, and EventBus, and exposes EventPublisher for injection.

Add command handlers, event handlers, and factories to providers.
Import CqrsModule in imports.

Without this import, injecting EventPublisher or EventBus fails at startup with an unresolved-dependency error.

import { Module } from '@nestjs/common';
import { CqrsModule } from '@nestjs/cqrs';
import { PlaceOrderHandler } from './place-order.handler';
import { OrderPlacedHandler } from './order-placed.handler';
import { OrderRepository } from './order.repository';

@Module({
  imports: [CqrsModule],
  providers: [PlaceOrderHandler, OrderPlacedHandler, OrderRepository],
})
export class OrdersModule {}

Commit After Persistence, Not Before

Order of operations matters. The recommended pattern is:

1. Merge context onto the aggregate.
2. Execute domain behavior (events are buffered via apply).
3. Persist the aggregate inside a transaction.
4. Call commit() only after the transaction succeeds.

If you commit before saving and the save fails, you have already published events for a state change that never persisted — leaving handlers acting on phantom data. For stronger guarantees, teams adopt the transactional outbox pattern, writing events to an outbox table in the same transaction and relaying them afterward.

Modeling the Buffer-Then-Publish Flow

The core idea — buffer events with apply, flush them with commit — can be reproduced in plain TypeScript to build intuition, with no NestJS at all. Here a tiny aggregate records events and a publisher drains them only when committed.

Run it and watch the handler fire only after commit() is called.

type DomainEvent = { name: string; payload: unknown };

class MiniAggregate {
  private events: DomainEvent[] = [];
  private publish: (e: DomainEvent) => void = () => {};

  setPublisher(fn: (e: DomainEvent) => void) {
    this.publish = fn; // mimics mergeObjectContext
  }

  apply(event: DomainEvent) {
    this.events.push(event); // buffer only
  }

  commit() {
    this.events.forEach((e) => this.publish(e));
    this.events = [];
  }
}

const order = new MiniAggregate();
order.apply({ name: 'OrderPlaced', payload: { id: 'A1', total: 50 } });
console.log('before commit: nothing published yet');

order.setPublisher((e) => console.log('handled:', e.name, e.payload));
order.commit();
console.log('after commit: buffer flushed');

Quick Check

You created an aggregate with new Order(id), called a method that uses this.apply(new OrderPlacedEvent(...)), then called order.commit() — but no event handler ever runs. What is the most likely cause?

Recap

You learned how NestJS CQRS turns aggregates into event emitters:

AggregateRoot gives apply() (buffer an event) and commit() (flush to the EventBus).
A direct new uses a no-op publisher — wire the real one with EventPublisher.mergeObjectContext for a single instance, or mergeClassContext for factory-produced instances.
Domain events are immutable past-tense classes implementing IEvent, carrying only the needed payload.
@EventsHandler classes react to events; keep them small and idempotent.
Import CqrsModule and register handlers in providers.
Commit after persistence so events never describe a state that failed to save; consider a transactional outbox for stronger delivery guarantees.

常见问题解答

「领域事件与 AggregateRoot」课时是免费的吗？

是的 — 「领域事件与 AggregateRoot」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 NestJS Enterprise Backend APIs 课程的其余内容，请升级到 CoddyKit PRO。 NestJS Enterprise Backend APIs 课程共包含 4 节课。

「领域事件与 AggregateRoot」这节课中我会学到什么？

使用 EventBus 和 mergeObjectContext，从聚合根发出并发布领域事件。你通过在浏览器中直接运行的动手代码来练习 NestJS Enterprise Backend APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 NestJS Enterprise Backend APIs 需要有经验吗？

无需任何先前经验。CoddyKit 上的 NestJS Enterprise Backend APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 3 节课，共 4 节。

「领域事件与 AggregateRoot」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 NestJS Enterprise Backend APIs 课中编写并运行代码吗？

能。每节 NestJS Enterprise Backend APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 NestJS Enterprise Backend APIs