0Pricing
NestJS Enterprise Backend APIs · 课时

查询与读取模型投影

使用由优化的反规范化投影支持的 QueryBus 处理器分离读取操作。

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

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

Why a Separate Read Side?

In CQRS (Command Query Responsibility Segregation) you split the system into a write side (commands that mutate state) and a read side (queries that return data). The two have fundamentally different needs.

  • The write model is optimized for consistency and business invariants — normalized aggregates.
  • The read model is optimized for fast, shape-perfect reads — denormalized projections tailored to each screen or endpoint.

A projection is a precomputed, query-friendly view of your data, usually built by listening to domain events. Instead of joining six tables at request time, the query handler reads one already-shaped row.

Queries Are Not Commands

A query is a plain DTO describing what the caller wants to read. It carries no behavior and must never mutate state. In @nestjs/cqrs, queries flow through the QueryBus to a matching @QueryHandler.

Keep queries free of domain rules. Their only job is to name an intent and carry parameters (ids, filters, paging). All the heavy lifting lives in the handler against the read model.

export class GetOrderSummaryQuery {
  constructor(
    public readonly orderId: string,
    public readonly tenantId: string,
  ) {}
}

export class ListCustomerOrdersQuery {
  constructor(
    public readonly customerId: string,
    public readonly page = 1,
    public readonly pageSize = 20,
  ) {}
}

The QueryBus and QueryHandler

A @QueryHandler(SomeQuery) class implements IQueryHandler<SomeQuery, Result> and exposes an execute() method. Register handlers in the module's providers, then dispatch with queryBus.execute(new SomeQuery(...)).

Notice the handler reads directly from a projection table (here order_summary) — no aggregate rehydration, no event replay at request time.

import { IQueryHandler, QueryHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderSummaryView } from './order-summary.view';
import { GetOrderSummaryQuery } from './get-order-summary.query';

@QueryHandler(GetOrderSummaryQuery)
export class GetOrderSummaryHandler
  implements IQueryHandler<GetOrderSummaryQuery, OrderSummaryView> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async execute(query: GetOrderSummaryQuery): Promise<OrderSummaryView> {
    const row = await this.repo.findOne({
      where: { orderId: query.orderId, tenantId: query.tenantId },
    });
    if (!row) throw new Error('Order summary not found');
    return row;
  }
}

Designing the Projection Shape

A projection is denormalized on purpose. You duplicate data so the read is a single-row, single-table lookup. Design the shape around the consumer (the endpoint or UI), not around your domain model.

  • Flatten relationships: store the customer name inside the order summary row.
  • Precompute totals, counts, and labels so the API does zero arithmetic.
  • Add the indexes the query needs (e.g., (tenantId, customerId, placedAt)).

This entity maps to a read-only table that the write side never touches directly.

import { Entity, PrimaryColumn, Column, Index } from 'typeorm';

@Entity('order_summary')
@Index(['tenantId', 'customerId', 'placedAt'])
export class OrderSummaryView {
  @PrimaryColumn('uuid')
  orderId: string;

  @Column('uuid')
  tenantId: string;

  @Column('uuid')
  customerId: string;

  @Column()
  customerName: string; // denormalized copy

  @Column('int')
  lineItemCount: number; // precomputed

  @Column('numeric', { precision: 12, scale: 2 })
  totalAmount: string;

  @Column()
  status: string;

  @Column('timestamptz')
  placedAt: Date;
}

Building Projections from Events

Projections are kept up to date by projectors — event handlers that translate domain events into upserts on the read table. In @nestjs/cqrs a projector is an @EventsHandler.

Each event mutates exactly the columns it affects. The projector is the only writer of the projection table, which keeps ownership clear and avoids contention with the command side.

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderPlacedEvent } from '../events/order-placed.event';
import { OrderSummaryView } from './order-summary.view';

@EventsHandler(OrderPlacedEvent)
export class OrderPlacedProjector
  implements IEventHandler<OrderPlacedEvent> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async handle(event: OrderPlacedEvent): Promise<void> {
    await this.repo.upsert(
      {
        orderId: event.orderId,
        tenantId: event.tenantId,
        customerId: event.customerId,
        customerName: event.customerName,
        lineItemCount: event.lines.length,
        totalAmount: event.total,
        status: 'PLACED',
        placedAt: event.occurredAt,
      },
      ['orderId'],
    );
  }
}

Incremental Updates per Event

Most events do not rebuild the whole row — they patch a slice of it. An OrderShippedEvent only flips the status and stamps a ship date. Keep projectors small and event-specific.

Because the projector owns the table, an UPDATE by primary key is cheap and contention-free. Idempotency matters here — replaying the same event must not corrupt the row (more on that soon).

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { OrderShippedEvent } from '../events/order-shipped.event';
import { OrderSummaryView } from './order-summary.view';

@EventsHandler(OrderShippedEvent)
export class OrderShippedProjector
  implements IEventHandler<OrderShippedEvent> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async handle(event: OrderShippedEvent): Promise<void> {
    await this.repo.update(
      { orderId: event.orderId },
      { status: 'SHIPPED' },
    );
  }
}

Eventual Consistency Is the Trade-off

When the read model is updated asynchronously after the command commits, the projection is eventually consistent. For a brief window the query may return stale data — for example, an order that was just placed might not yet appear in its summary list.

  • Embrace it for dashboards, lists, reports, and search where small lag is fine.
  • Mitigate it in the UI: optimistic updates, or return the new id from the command and let the client poll the read side.
  • For strict read-your-writes needs, query the write model directly or update the projection synchronously inside the same transaction.

Document the consistency guarantee per endpoint so consumers know what to expect.

Idempotent Projectors

Event delivery is usually at-least-once, so a projector may receive the same event twice. Make handlers idempotent so reprocessing is harmless.

  • Use upsert / UPDATE by key rather than blind INSERT.
  • Track the last processed event position (a checkpoint) per projection and skip anything you've already seen.
  • Avoid relative math like count = count + 1 unless you also dedupe by event id.

This small helper shows the dedupe idea in pure TypeScript: a checkpoint set guards against double application.

type Event = { id: string; type: string; orderId: string };

class IdempotentProjection {
  private processed = new Set<string>();
  private rows = new Map<string, { orderId: string; status: string }>();

  apply(event: Event): boolean {
    if (this.processed.has(event.id)) return false; // already seen
    this.processed.add(event.id);
    const row = this.rows.get(event.orderId) ?? { orderId: event.orderId, status: 'NEW' };
    if (event.type === 'OrderShipped') row.status = 'SHIPPED';
    this.rows.set(event.orderId, row);
    return true;
  }

  status(orderId: string): string | undefined {
    return this.rows.get(orderId)?.status;
  }
}

const p = new IdempotentProjection();
const e = { id: 'evt-1', type: 'OrderShipped', orderId: 'ord-9' };
console.log(p.apply(e)); // true  -> applied
console.log(p.apply(e)); // false -> duplicate ignored
console.log(p.status('ord-9')); // SHIPPED

Paging and Filtering on the Read Side

List endpoints belong entirely to the read model. Because the projection is already flat and indexed, paging and filtering are simple WHERE + LIMIT/OFFSET (or keyset) queries — no joins, no N+1.

Return a small page DTO with the items plus total count. Keep sorting on indexed columns so the database can satisfy the order without a filesort.

@QueryHandler(ListCustomerOrdersQuery)
export class ListCustomerOrdersHandler
  implements IQueryHandler<ListCustomerOrdersQuery> {
  constructor(
    @InjectRepository(OrderSummaryView)
    private readonly repo: Repository<OrderSummaryView>,
  ) {}

  async execute(q: ListCustomerOrdersQuery) {
    const [items, total] = await this.repo.findAndCount({
      where: { customerId: q.customerId },
      order: { placedAt: 'DESC' },
      take: q.pageSize,
      skip: (q.page - 1) * q.pageSize,
    });
    return { items, total, page: q.page, pageSize: q.pageSize };
  }
}

Wiring It in the Controller

Controllers stay thin: translate the HTTP request into a query and hand it to the QueryBus. No business logic, no repository access in the controller.

This keeps the transport layer decoupled from how reads are served. You could later swap the projection store (Postgres → Elasticsearch) without touching the controller.

import { Controller, Get, Param, Query } from '@nestjs/common';
import { QueryBus } from '@nestjs/cqrs';
import { GetOrderSummaryQuery } from './get-order-summary.query';
import { ListCustomerOrdersQuery } from './list-customer-orders.query';

@Controller('orders')
export class OrdersQueryController {
  constructor(private readonly queryBus: QueryBus) {}

  @Get(':id/summary')
  getSummary(@Param('id') id: string, @Query('tenantId') tenantId: string) {
    return this.queryBus.execute(new GetOrderSummaryQuery(id, tenantId));
  }

  @Get()
  list(@Query('customerId') customerId: string, @Query('page') page = 1) {
    return this.queryBus.execute(
      new ListCustomerOrdersQuery(customerId, Number(page)),
    );
  }
}

Rebuilding Projections

A huge advantage of event-sourced read models: you can rebuild a projection from scratch by replaying the event stream. This lets you change the read shape, fix a projector bug, or add a brand-new view without migrating old data manually.

  • Truncate (or version) the projection table.
  • Replay every relevant event through the projector in order.
  • Track a checkpoint so you can resume and switch reads over when caught up.

Strategies like blue/green projections build the new version alongside the old, then flip readers atomically — zero-downtime read-model migrations.

Quick Check: Serving a Fast List Read

You need a high-traffic endpoint that lists a customer's orders with customer name, total, and item count per row. The data is spread across normalized orders, order_lines, and customers tables. Reads vastly outnumber writes and small staleness is acceptable.

What is the most appropriate CQRS approach?

Recap

You separated reads from writes with the query side of CQRS:

  • Queries are behavior-free DTOs dispatched via the QueryBus to @QueryHandler classes.
  • Projections are denormalized, indexed read tables shaped for the consumer, owned and updated by projectors (@EventsHandler) reacting to domain events.
  • Async projection brings eventual consistency — great for lists/dashboards; handle read-your-writes deliberately when needed.
  • Projectors must be idempotent (upsert by key, checkpoints) because delivery is at-least-once.
  • Read models can be rebuilt or migrated by replaying events, enabling blue/green, zero-downtime view changes.

The payoff: reads become single-row, single-table lookups — fast, scalable, and decoupled from your write-side aggregates.

常见问题解答

「查询与读取模型投影」课时是免费的吗？

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

「查询与读取模型投影」这节课中我会学到什么？

使用由优化的反规范化投影支持的 QueryBus 处理器分离读取操作。 你通过在浏览器中直接运行的动手代码来练习 NestJS Enterprise Backend APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

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

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

「查询与读取模型投影」课时需要多长时间？

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

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

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

此课程中的所有课时

  1. 命令、处理器与命令总线
  2. 查询与读取模型投影
  3. 领域事件与 AggregateRoot
  4. 使用 Saga 处理长时间运行的工作流
← 返回 NestJS Enterprise Backend APIs