NestJS Enterprise Backend APIs · Ders

Komutlar, İşleyiciler ve Komut Veri Yolu

Yazma işlemlerini, CommandBus üzerinden özel işleyicilere gönderilen komutlar olarak modelleyin.

Komutlar, İşleyiciler ve Komut Veri Yolu, CoddyKit'te ücretsiz bir NestJS Enterprise Backend APIs dersidir. Bu, 4 dersinin 1. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, NestJS Enterprise Backend APIs öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. NestJS Enterprise Backend APIs kursu toplamda 4 dersten oluşur.

Bu dersin bazı bölümleri henüz çevrilmemiş olup İngilizce olarak gösterilmektedir.

Why Commands Exist

In a CQRS system we split the model into two halves: the write side that changes state and the read side that returns data. A Command represents an intent to change state, for example CreateOrder or CancelSubscription.

A command is a plain DTO carrying the data needed to perform the write.
It is named in the imperative (do this) and describes a single business action.
It returns at most an identifier or acknowledgment, never a full read model.

NestJS ships @nestjs/cqrs, which gives us a CommandBus to dispatch commands to exactly one handler.

Modeling a Command

A command is just a class. It holds the input data as readonly properties so it stays immutable once created. There is no logic inside it.

Below, CreateOrderCommand captures everything a handler needs to create an order. Notice it carries no NestJS decorators and no behavior.

export class CreateOrderCommand {
  constructor(
    public readonly customerId: string,
    public readonly items: { sku: string; quantity: number }[],
    public readonly currency: string,
  ) {}
}

The Command Handler Contract

Each command is processed by exactly one handler. In NestJS you implement ICommandHandler<TCommand> and decorate the class with @CommandHandler(TCommand).

@CommandHandler registers the link between a command type and its handler.
The interface forces an execute(command) method.
The handler is a normal provider, so it can inject repositories and services.

import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
import { CreateOrderCommand } from './create-order.command';

@CommandHandler(CreateOrderCommand)
export class CreateOrderHandler
  implements ICommandHandler<CreateOrderCommand>
{
  async execute(command: CreateOrderCommand): Promise<{ orderId: string }> {
    const orderId = crypto.randomUUID();
    // persist order, charge, etc.
    return { orderId };
  }
}

Dispatching Through the CommandBus

Controllers and other entry points do not call handlers directly. They build a command and hand it to the CommandBus via execute(). The bus finds the registered handler and runs it.

This indirection means the controller stays thin and knows nothing about persistence, validation rules, or side effects.

import { Body, Controller, Post } from '@nestjs/common';
import { CommandBus } from '@nestjs/cqrs';
import { CreateOrderCommand } from './create-order.command';

@Controller('orders')
export class OrdersController {
  constructor(private readonly commandBus: CommandBus) {}

  @Post()
  async create(@Body() dto: CreateOrderDto) {
    return this.commandBus.execute(
      new CreateOrderCommand(dto.customerId, dto.items, dto.currency),
    );
  }
}

Wiring It Up with CqrsModule

For the bus to discover handlers, you must import CqrsModule in the feature module and register every handler as a provider. NestJS scans providers for the @CommandHandler metadata at startup and binds them to the bus.

Forget to list the handler in providers and the bus throws an unhandled command error at dispatch time.
CqrsModule supplies CommandBus, QueryBus, and EventBus.

import { Module } from '@nestjs/common';
import { CqrsModule } from '@nestjs/cqrs';
import { OrdersController } from './orders.controller';
import { CreateOrderHandler } from './create-order.handler';

@Module({
  imports: [CqrsModule],
  controllers: [OrdersController],
  providers: [CreateOrderHandler],
})
export class OrdersModule {}

One Command, One Handler

The CommandBus enforces a strict one-to-one mapping: a single command type resolves to a single handler. This is the core distinction from events.

Commands express an instruction that may be rejected and have exactly one handler.
Events announce that something already happened and may have zero or many handlers.

If you register two handlers for the same command, the last one registered wins and the bus silently overrides the earlier binding, which is almost always a bug.

Returning Results from a Command

Strict CQRS purists return nothing from a command. In practice, returning a small acknowledgment such as the new aggregate id is pragmatic and common in NestJS APIs.

CommandBus.execute<TCommand, TResult>() is generic, so you can type the return value precisely. Keep the payload tiny: an id, a status, never a full read model. If the client needs the whole resource, it issues a separate query afterward.

const result = await this.commandBus.execute<
  CreateOrderCommand,
  { orderId: string }
>(new CreateOrderCommand(customerId, items, currency));

return { id: result.orderId };

Validation Belongs at the Edge

Keep handlers focused on business behavior. Structural validation (required fields, types, formats) belongs on the incoming DTO using class-validator and the global ValidationPipe, before a command is ever constructed.

Business invariants that need data from the database, such as 'customer must not exceed credit limit', belong inside the handler where you have access to repositories.

import { IsArray, IsString, Length } from 'class-validator';

export class CreateOrderDto {
  @IsString()
  customerId: string;

  @IsArray()
  items: { sku: string; quantity: number }[];

  @IsString()
  @Length(3, 3)
  currency: string;
}

Composing Side Effects in a Handler

A handler typically orchestrates several steps: load state, mutate it, persist, then publish domain events. Injected providers make this clean and testable.

Here the handler persists the order and then publishes an event so other parts of the system can react asynchronously, keeping the write path decoupled from downstream concerns like email or analytics.

@CommandHandler(CreateOrderCommand)
export class CreateOrderHandler
  implements ICommandHandler<CreateOrderCommand>
{
  constructor(
    private readonly orders: OrderRepository,
    private readonly eventBus: EventBus,
  ) {}

  async execute(command: CreateOrderCommand) {
    const order = Order.create(command.customerId, command.items);
    await this.orders.save(order);
    this.eventBus.publish(new OrderCreatedEvent(order.id));
    return { orderId: order.id };
  }
}

Testing the Pure Logic

Because a command is a plain immutable object, the dispatch-and-handle pattern is easy to reason about. The snippet below is framework-free: it models a tiny command bus, registers a handler, and dispatches a command, demonstrating the exact one-command-one-handler contract you saw earlier.

type Handler<C, R> = (command: C) => R;

class MiniCommandBus {
  private handlers = new Map<string, Handler<any, any>>();

  register<C, R>(name: string, handler: Handler<C, R>): void {
    this.handlers.set(name, handler);
  }

  execute<R>(name: string, command: unknown): R {
    const handler = this.handlers.get(name);
    if (!handler) throw new Error(`No handler for ${name}`);
    return handler(command);
  }
}

class CreateOrderCommand {
  constructor(public readonly customerId: string) {}
}

const bus = new MiniCommandBus();
bus.register('CreateOrder', (c: CreateOrderCommand) => ({
  orderId: 'ord_' + c.customerId,
}));

const result = bus.execute<{ orderId: string }>(
  'CreateOrder',
  new CreateOrderCommand('42'),
);
console.log(result.orderId);

Error Handling and Idempotency

Commands can fail, and callers need a clear contract. Throw domain exceptions from the handler and let a NestJS exception filter map them to HTTP status codes.

Throwing inside execute() rejects the promise returned by commandBus.execute().
For at-least-once delivery (retries, message queues), make commands idempotent: include a client-supplied key so re-processing the same command is safe.

Never swallow errors silently in a handler; an undelivered write looks like success to the client.

Quick Check

Test your understanding of the command dispatch model.

Recap

You now know how to model write operations as commands in NestJS CQRS:

A command is an immutable DTO expressing an intent to change state, named imperatively.
A handler implements ICommandHandler and is bound via @CommandHandler; it holds the business logic and injected dependencies.
The CommandBus dispatches each command to its single handler; controllers stay thin and never call handlers directly.
Import CqrsModule and register handlers in providers so the bus can discover them.
Structural validation lives on the DTO at the edge; business invariants live in the handler. Return only a tiny acknowledgment, and make commands idempotent when delivery may retry.

Sıkça Sorulan Sorular

“Komutlar, İşleyiciler ve Komut Veri Yolu” dersi ücretsiz mi?

Evet — “Komutlar, İşleyiciler ve Komut Veri Yolu” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve NestJS Enterprise Backend APIs kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. NestJS Enterprise Backend APIs kursu toplamda 4 dersten oluşur.

“Komutlar, İşleyiciler ve Komut Veri Yolu” dersinde ne öğreneceğim?

Yazma işlemlerini, CommandBus üzerinden özel işleyicilere gönderilen komutlar olarak modelleyin. NestJS Enterprise Backend APIs ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

NestJS Enterprise Backend APIs öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te NestJS Enterprise Backend APIs, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 1. dersidir.

“Komutlar, İşleyiciler ve Komut Veri Yolu” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu NestJS Enterprise Backend APIs dersinde kod yazıp çalıştırabilir miyim?

Evet. Her NestJS Enterprise Backend APIs dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

Komutlar, İşleyiciler ve Komut Veri Yolu
Sorgular ve Okuma Modeli Projeksiyonları
Alan Olayları ve AggregateRoot
Uzun Süren İş Akışları için Saga'lar

← NestJS Enterprise Backend APIs Sayfasına Dön