Μια εντολή μέσα από κάθε επίπεδο
Αυτή η συνταγή ακολουθεί το POST /users του users-api, της παραδειγματικής εφαρμογής του repository. Κάθε
αρχείο παρακάτω είναι πραγματικός κώδικας της εφαρμογής, όπως ακριβώς κατασκευάζεται και ελέγχεται.
1. Η διαδρομή αντιστοιχίζει το body σε εντολή
Ενότητα με τίτλο «1. Η διαδρομή αντιστοιχίζει το body σε εντολή»Ο controller δηλώνει το schema του body με @Body({ schema: CreateUserDtoSchema }), το οποίο
το StandardSchemaValidationPipe του Nest επικυρώνει (δείτε Επικύρωση με το Zod), διαβάζει την προαιρετική κεφαλίδα Idempotency-Key, και παραδίδει
και τα δύο σε έναν mapper. Το createZodMapper μετατρέπει το DTO αιτήματος στην εντολή:
/* 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 }),};2. Η εντολή φέρει το δικό της schema
Ενότητα με τίτλο «2. Η εντολή φέρει το δικό της schema»Το createCommand δίνει στην κλάση της εντολής το δικό της Zod schema, εδώ δομημένο από τους κανόνες
μήκους του ίδιου του domain (User.rules). Το ZodValidationBehavior, δηλωμένο ως καθολικό behavior, αναλύει
κάθε εντολή έναντι αυτού του schema πριν εκτελεστεί ο handler της, οπότε μια εντολή που φτάνει στον
handler είναι έγκυρη όποιος κι αν την απέστειλε:
/* 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,) {}3. Ο handler δηλώνει το pipeline του
Ενότητα με τίτλο «3. Ο handler δηλώνει το pipeline του»Το @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()):
/* 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 του αιτήματος το ακολουθεί μέσα στην ουρά:
/* 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, }); }}