Μετάβαση στο περιεχόμενο
Από την έκδοση 0.5.0 τα πακέτα συνεχίζουν ως @cqrs-ddd, με τεκμηρίωση στο aristoteliss.github.io/ddd-cqrs· οι εφαρμογές NestJS προσθέτουν το @cqrs-ddd/nestjs. Αυτός ο ιστότοπος τεκμηριώνει τη σειρά 0.4.x.

Μια εντολή μέσα από κάθε επίπεδο

Αυτή η συνταγή ακολουθεί το POST /users του users-api, της παραδειγματικής εφαρμογής του repository. Κάθε αρχείο παρακάτω είναι πραγματικός κώδικας της εφαρμογής, όπως ακριβώς κατασκευάζεται και ελέγχεται.

1. Η διαδρομή αντιστοιχίζει το body σε εντολή

Ενότητα με τίτλο «1. Η διαδρομή αντιστοιχίζει το body σε εντολή»

Ο controller δηλώνει το schema του body με @Body({ schema: CreateUserDtoSchema }), το οποίο το StandardSchemaValidationPipe του Nest επικυρώνει (δείτε Επικύρωση με το Zod), διαβάζει την προαιρετική κεφαλίδα Idempotency-Key, και παραδίδει και τα δύο σε έναν mapper. Το createZodMapper μετατρέπει το DTO αιτήματος στην εντολή:

api/src/users/mappers/create-user.mapper.ts
/* Copyright (C) 2026-present Aristotelis — see repository license. */
import { createZodMapper } from '@cqrs-ddd/pipeline-zod';
import { z } from 'zod';
import { CreateUserCommand } from '../application/cqrs/commands/create-user.command.js';
import {
type CreateUserDto,
CreateUserDtoSchema,
} from '../dtos/create-user.dto.js';
const base = createZodMapper(
CreateUserDtoSchema.extend({
idempotencyKey: z.string().optional(),
}).transform(
({ name, email, department, idempotencyKey }) =>
new CreateUserCommand({
username: name,
email,
...(department !== undefined ? { department } : {}),
...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
}),
),
);
export const CreateUserMapper = {
...base,
map: (dto: CreateUserDto, idempotencyKey?: string) =>
base.map({ ...dto, idempotencyKey }),
};

Το createCommand δίνει στην κλάση της εντολής το δικό της Zod schema, εδώ δομημένο από τους κανόνες μήκους του ίδιου του domain (User.rules). Το ZodValidationBehavior, δηλωμένο ως καθολικό behavior, αναλύει κάθε εντολή έναντι αυτού του schema πριν εκτελεστεί ο handler της, οπότε μια εντολή που φτάνει στον handler είναι έγκυρη όποιος κι αν την απέστειλε:

api/src/users/application/cqrs/commands/create-user.command.ts
/* Copyright (C) 2026-present Aristotelis — see repository license. */
import { EmailSchema } from '@common/validation/email.schema.js';
import { IdempotencyKeySchema } from '@common/validation/idempotency-key.schema.js';
import { BaseCommand } from '@cqrs-ddd/core/application';
import { createCommand } from '@cqrs-ddd/pipeline-zod';
import { z } from 'zod';
import { User } from '../../../domain/models/user.entity.js';
export class CreateUserCommand extends createCommand(
z.object({
username: z
.string()
.trim()
.min(User.rules.username.minLength)
.max(User.rules.username.maxLength),
email: EmailSchema,
department: z
.string()
.trim()
.min(User.rules.department.minLength)
.max(User.rules.department.maxLength)
.optional(),
idempotencyKey: IdempotencyKeySchema.optional(),
}),
BaseCommand,
) {}

Το @UsePipeline στοιβάζει τα behaviors που χρειάζεται αυτή η εντολή. Εκτελούνται μετά τα καθολικά before behaviors και με τη σειρά που αναφέρονται (δείτε Μοντέλο εκτέλεσης pipeline):

Behavior Τι κάνει εδώ Πακέτο
logging Καταγράφει την εντολή· διπλότυπο email (UniqueEmailException) καταγράφεται ως warning, όχι error core
requires Έλεγχος επιπέδου τύπου: εάν ο καλών επιτρέπεται να εκτελέσει create σε User γενικά casl
featureFlag Απορρίπτει την εντολή όσο το flag user-registration είναι απενεργοποιημένο feature-flags
rateLimit Καταναλώνει RATE_LIMIT_COST.createUser πόντους από τον κάδο του καλούντος rate-limit
idempotent Αναπαράγει το αποτέλεσμα επαναληπτικής λειτουργίας με το ίδιο Idempotency-Key, για τον ίδιο καλούντα και δικαιώματα idempotency
audit Καταγράφει ποιος δημιούργησε ποιον χρήστη, και το αποτέλεσμα audit

Μέσα στο execute, το CaslAuthorizer.authorize ελέγχει τη νέα οντότητα και τα πεδία που εγγράφονται. Αυτός ο έλεγχος επιπέδου οντότητας ανήκει στον handler, αφού υπάρξει το aggregate· το requires επιπέδου τύπου παραπάνω δεν μπορεί να δει την οντότητα. Στη συνέχεια, ο EventPublisher του NestJS δημοσιεύει τα buffer συμβάντα του aggregate αφού αποθηκευτεί (publisher.mergeObjectContext(user).commit()):

api/src/users/application/cqrs/commands/create-user.handler.ts
/* Copyright (C) 2026-present Aristotelis — see repository license. */
import {
APP_ACTIONS,
APP_SUBJECTS,
AUDIT_ACTIONS,
RATE_LIMIT_COST,
} from '@common/constants/index.js';
import { sessionPrincipalKey } from '@common/context/session-principal.store.js';
import { operationIdempotencyKeyFactory } from '@common/idempotency/operation-key.js';
import { ICommandRepository } from '@cqrs-ddd/core/application';
import { logging, UsePipeline } from '@cqrs-ddd/pipeline';
import { AUDIT_SEVERITY, audit } from '@cqrs-ddd/pipeline-audit';
import {
CaslAuthorizer,
requireAbilityDigest,
requires,
} from '@cqrs-ddd/pipeline-casl';
import { featureFlag } from '@cqrs-ddd/pipeline-feature-flags';
import { idempotent } from '@cqrs-ddd/pipeline-idempotency';
import {
createPartitionedRateLimitKeyFactory,
rateLimit,
} from '@cqrs-ddd/pipeline-rate-limit';
import { Inject } from '@nestjs/common';
import {
CommandHandler,
EventPublisher,
type ICommandHandler,
} from '@nestjs/cqrs';
import { UniqueEmailException } from '../../../domain/models/errors/email.exception.js';
import { User, type UserSnapshot } from '../../../domain/models/user.entity.js';
import { COMMAND_REPOSITORY } from '../../../persistence/repository.tokens.js';
import { CreateUserCommand } from './create-user.command.js';
@CommandHandler(CreateUserCommand)
@UsePipeline(
logging({
mapLogLevel: new Map([[UniqueEmailException, 'warn']]),
}),
requires({ action: APP_ACTIONS.CREATE, subject: APP_SUBJECTS.USER }),
featureFlag({ flag: 'user-registration' }),
rateLimit({
keyFactory: createPartitionedRateLimitKeyFactory(sessionPrincipalKey),
points: RATE_LIMIT_COST.createUser,
}),
idempotent({
keyFactory: operationIdempotencyKeyFactory(
'user.create',
(ctx) => (ctx.request as CreateUserCommand).idempotencyKey,
),
replayScopeFactory: requireAbilityDigest,
}),
audit({
action: AUDIT_ACTIONS.USER_CREATE,
severity: AUDIT_SEVERITY.MEDIUM,
}),
)
export class CreateUserHandler
implements ICommandHandler<CreateUserCommand, User>
{
constructor(
@Inject(COMMAND_REPOSITORY.createUser)
private readonly commandRepository: ICommandRepository<User, UserSnapshot>,
private readonly authorizer: CaslAuthorizer,
private readonly publisher: EventPublisher,
) {}
async execute(command: CreateUserCommand): Promise<User> {
const { username, email, department } = command;
const user = User.create(username, email, department);
this.authorizer.authorize('create', user, [
'username',
'email',
...(department !== undefined ? ['department'] : []),
]);
await this.commandRepository.save(user);
await this.publisher.mergeObjectContext(user).commit();
return user;
}
}

4. Το event εκκινεί τις επακόλουθες εργασίες

Ενότητα με τίτλο «4. Το event εκκινεί τις επακόλουθες εργασίες»

Το User.create κατέγραψε ένα UserCreatedEvent. Ο handler του εισάγει στην ουρά το email καλωσορίσματος, και το deadLetter({ rethrow: false }) καταγράφει μια αποτυχία ως dead letter αντί να αποτύχει η εντολή που έχει ήδη ολοκληρωθεί επιτυχώς. Το Jobs που διατηρούν το context του αιτήματος το ακολουθεί μέσα στην ουρά:

api/src/users/application/cqrs/events/user-created.handler.ts
/* Copyright (C) 2026-present Aristotelis — see repository license. */
import { UsePipeline } from '@cqrs-ddd/pipeline';
import { deadLetter } from '@cqrs-ddd/pipeline-deadletter';
import { Inject } from '@nestjs/common';
import { EventsHandler, type IEventHandler } from '@nestjs/cqrs';
import { UserCreatedEvent } from '../../../domain/events/user-created.event.js';
import {
type IWelcomeEmailDispatcher,
WELCOME_EMAIL_DISPATCHER,
} from '../../ports/user-event-dispatcher.port.js';
@EventsHandler(UserCreatedEvent)
@UsePipeline(deadLetter({ rethrow: false }))
export class UserCreatedHandler implements IEventHandler<UserCreatedEvent> {
constructor(
@Inject(WELCOME_EMAIL_DISPATCHER)
private readonly welcomeEmailDispatcher: IWelcomeEmailDispatcher,
) {}
async handle(event: UserCreatedEvent): Promise<void> {
const { id: userId, username, email } = event.payload;
await this.welcomeEmailDispatcher.enqueueWelcomeEmail({
userId,
username,
email,
});
}
}