@cqrs-ddd/nestjs
Ο NestJS adapter για τα πακέτα @cqrs-ddd.
Οι εφαρμογές διατηρούν το επίσημο module @nestjs/cqrs (CommandBus, QueryBus, EventBus, @CommandHandler, @QueryHandler, @EventsHandler, EventPublisher). Αυτό το πακέτο παρέχει τη διασύνδεση μεταξύ του dependency injection του NestJS και του @cqrs-ddd/pipeline:
- Το
PipelineModule.forRoot({ globalBehaviors, sources, diagnostics })εντοπίζει κάθε@nestjs/cqrshandler κατά το bootstrap και τυλίγει την εκτέλεσή του με τη μεταγλωττισμένη αλυσίδα behaviors του. - Το
ErrorFilter(APP_FILTER) μετατρέπει σφάλματα πακέτου και domain σε τυπικάHttpExceptioninstances του NestJS με το κανονικό payload{ statusCode, error, message }και τα κατάλληλα headers (π.χ.Retry-After). - Το
@cqrs-ddd/nestjs/correlationπαρέχει τοCorrelationMiddlewareγια τη δέσμευση των HTTP correlation IDs στο ασύγχρονο context και στα headers απόκρισης. - Το
@cqrs-ddd/nestjs/job-contextπαρέχει τοJobContextModule.forRoot(...)για τη διάδοση context tenant, correlation και principal σε επεξεργαστές παρασκηνιακών εργασιών (background job processors).
Περιεχόμενα
Ενότητα με τίτλο «Περιεχόμενα »- Εγκατάσταση
- Αρχιτεκτονική & Μηχανισμοί
- PipelineModule
- Διαχείριση Σφαλμάτων
- Correlation Middleware
- Job Context Module
- Παράδειγμα Πλήρους Ρύθμισης
- Πρόσοψη Πακέτου (@nestjs-pipeline/cqrs-ddd)
- Άδεια χρήσης
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση »pnpm add @cqrs-ddd/nestjs @cqrs-ddd/pipeline @cqrs-ddd/core# ornpm install @cqrs-ddd/nestjs @cqrs-ddd/pipeline @cqrs-ddd/corePeer Dependencies
Ενότητα με τίτλο «Peer Dependencies »- Απαιτούμενα:
@nestjs/common(>=12.0.0),@nestjs/core(>=12.0.0),@nestjs/cqrs(>=12.0.0),@cqrs-ddd/pipeline(^0.5.0),@cqrs-ddd/core(^0.5.0), Node.js >= 22.12.0. - Προαιρετικά peers (μετατρέπονται αυτόματα από το
ErrorFilterόταν είναι παρόντα):@cqrs-ddd/pipeline-zod@cqrs-ddd/pipeline-casl@cqrs-ddd/pipeline-feature-flags@cqrs-ddd/pipeline-rate-limit@cqrs-ddd/pipeline-idempotency@cqrs-ddd/pipeline-correlation@cqrs-ddd/pipeline-job-context
Αρχιτεκτονική & Μηχανισμοί
Ενότητα με τίτλο «Αρχιτεκτονική & Μηχανισμοί »Το NestJS διαχειρίζεται το dependency injection, το routing, τη σύνθεση των modules και την αποστολή (dispatch) μέσω CQRS. Το @cqrs-ddd/nestjs ενσωματώνει τα behaviors του pipeline σε αυτό το μοντέλο εκτέλεσης:
HTTP / Job Ingress │ [CorrelationMiddleware] │ [CommandBus / QueryBus] │ ┌────────────┴────────────┐ │ Handler Instance │ │ (Wrapped at Startup) │ ├─────────────────────────┤ │ Behavior 1 (Logging) │ │ Behavior 2 (Idempotency)│ │ Behavior 3 (CASL Auth) │ │ ... │ │ Handler.execute() │ └────────────┬────────────┘ │ [Domain Exceptions] │ [ErrorFilter] │ Standard NestJS BodyΠώς Τυλίγονται οι Handlers
Ενότητα με τίτλο «Πώς Τυλίγονται οι Handlers »- Κατά το bootstrap της εφαρμογής (
OnApplicationBootstrap), τοPipelineBootstrapαναζητά μέσω τουDiscoveryServiceτου NestJS όλους τους καταχωρισμένους providers. - Εντοπίζει τους handlers που είναι διακοσμημένοι με
@CommandHandler,@QueryHandlerκαι@EventsHandler. - Για κάθε handler, επιθεωρεί τα metadata του pipeline που επισυνάπτονται μέσω των
@UsePipelineκαι@SkipPipeline. - Μεταγλωττίζει ένα ενιαίο πλάνο pipeline χρησιμοποιώντας το
compilePipelinePlanαπό το@cqrs-ddd/pipeline, συνδυάζοντας καθολικά behaviors και behaviors ειδικά για τον handler. - Επιλύει το singleton instance κάθε απαιτούμενου behavior από το module container.
- Τυλίγει τη μέθοδο
executeστους command και query handlers (ή τηhandleστους event handlers) απευθείας στο εντοπισμένο instance του handler χρησιμοποιώντας τοcreatePipelineRunner. - Όταν η εφαρμογή τερματίζεται (
OnModuleDestroy), οι αρχικές μέθοδοι των handlers αποκαθίστανται καθαρά.
PipelineModule
Ενότητα με τίτλο «PipelineModule »Δήλωση Module
Ενότητα με τίτλο «Δήλωση Module »Καταχωρίστε το PipelineModule.forRoot στο root ή στο infrastructure module σας:
import { Module } from '@nestjs/common';import { CqrsModule } from '@nestjs/cqrs';import { PipelineModule } from '@cqrs-ddd/nestjs';import { LoggingBehavior } from '@cqrs-ddd/pipeline';import { correlationSource } from '@cqrs-ddd/pipeline-correlation';import { tenantSource } from '@cqrs-ddd/pipeline-tenant';
@Module({ imports: [ CqrsModule.forRoot(), PipelineModule.forRoot({ sources: { tenantId: tenantSource, correlationId: correlationSource, }, globalBehaviors: [ { scope: 'all', before: [LoggingBehavior] }, ], diagnostics: 'strict', // 'strict' (default) | 'warn' | 'off' }), ],})export class AppModule {}PipelineOptions
Ενότητα με τίτλο «PipelineOptions »| Επιλογή | Τύπος | Περιγραφή |
|---|---|---|
globalBehaviors |
GlobalBehaviorsOptions | GlobalBehaviorsOptions[] |
Behaviors που τοποθετούνται καθολικά για 'all', 'commands', 'queries', ή 'events'. |
sources |
ContextSources |
Πηγές για γνωρίσματα context του pipeline (tenantId, correlationId, principalId, κ.λπ.). |
diagnostics |
'strict' | 'warn' | 'off' |
Λειτουργία διαγνωστικών. Προεπιλογή: 'strict'. |
Εντοπισμός Handlers
Ενότητα με τίτλο «Εντοπισμός Handlers »Οι handlers δηλώνουν τα behaviors του pipeline χρησιμοποιώντας τον τυπικό decorator @UsePipeline:
import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';import { UsePipeline } from '@cqrs-ddd/pipeline';import { IdempotencyBehavior } from '@cqrs-ddd/pipeline-idempotency';import { CaslBehavior } from '@cqrs-ddd/pipeline-casl';import { ZodValidationBehavior } from '@cqrs-ddd/pipeline-zod';
@CommandHandler(CreateUserCommand)@UsePipeline( ZodValidationBehavior, IdempotencyBehavior, CaslBehavior,)export class CreateUserHandler implements ICommandHandler<CreateUserCommand, User> { async execute(command: CreateUserCommand): Promise<User> { // Handler business logic executes inside the compiled pipeline return user; }}Παροχή Behaviors στα Modules
Ενότητα με τίτλο «Παροχή Behaviors στα Modules »Τα behaviors δημιουργούνται ως singleton providers εντός των modules που κατέχουν τις εξαρτήσεις τους. Το token του provider πρέπει να είναι η ίδια η κλάση του behavior:
import { Module, Logger } from '@nestjs/common';import { LoggingBehavior } from '@cqrs-ddd/pipeline';import { IdempotencyBehavior, MemoryIdempotencyStore } from '@cqrs-ddd/pipeline-idempotency';
@Module({ providers: [ { provide: LoggingBehavior, useFactory: () => new LoggingBehavior(new Logger('Pipeline')), }, { provide: IdempotencyBehavior, useFactory: () => new IdempotencyBehavior(new MemoryIdempotencyStore()), }, ], exports: [LoggingBehavior, IdempotencyBehavior],})export class ReliabilityModule {}Αυστηροί Διαγνωστικοί Έλεγχοι
Ενότητα με τίτλο «Αυστηροί Διαγνωστικοί Έλεγχοι »Όταν είναι ενεργοποιημένο το diagnostics: 'strict' (η προεπιλογή), το PipelineBootstrap επιβάλλει κανόνες αρχιτεκτονικής ασφάλειας κατά την εκκίνηση και διακόπτει την αρχικοποίηση με αναλυτικά σφάλματα εάν αποτύχει οποιοσδήποτε έλεγχος:
- Ελλείπων Behavior Provider: Εάν ένας handler απαιτεί ένα behavior αλλά κανένα module δεν το καταχώρισε ως provider υπό την κλάση του, το bootstrap αποτυγχάνει:
Error: IdempotencyBehavior runs in the pipeline of CreateUserHandler, but no module provides it. Register it as a provider of the module that configures it.
- Διπλότυπος Behavior Provider: Εάν πολλαπλά modules καταχωρίσουν provider για το ίδιο token behavior, το bootstrap αποτυγχάνει για να αποφευχθεί ασάφεια στη σειρά εισαγωγής:
Error: LoggingBehavior is provided by ObservabilityModule and SharedModule; exactly one module provides each behavior, otherwise which instance a handler gets would depend on import order.
- Απαγόρευση Request-Scoped Handlers: Εάν ένας handler ή οποιαδήποτε εξάρτησή του έχει scope αιτήματος (
Scope.REQUEST), το bootstrap πετά εξαίρεση αμέσως. Οι handlers που εκτελούν pipeline behaviors πρέπει να είναι singletons· η πρόσβαση σε contextual πληροφορίες αιτήματος πρέπει να γίνεται μέσω πηγών context ασύγχρονου local storage:Error: CreateUserHandler runs pipeline behaviors but is request-scoped, itself or through a dependency; Nest builds it per request, so its pipeline would never run. Make it a singleton and read request data from async context. - Συμβόλαια Behaviors: Οι αναλλοίωτες συμβολαίου (όπως περιορισμοί σειράς, απαιτούμενες εξαρτήσεις ή τοποθέτηση caching behavior) επικυρώνονται μέσω του
validateBehaviorContracts.
Διαχείριση Σφαλμάτων
Ενότητα με τίτλο «Διαχείριση Σφαλμάτων »ErrorFilter
Ενότητα με τίτλο «ErrorFilter »Το ErrorFilter είναι ένα καθολικό NestJS exception filter που επεκτείνει το BaseExceptionFilter. Συλλαμβάνει όλες τις εξαιρέσεις, ελέγχει αν το σφάλμα προέρχεται από το @cqrs-ddd, το αντιστοιχίζει στο κατάλληλο HttpException, εφαρμόζει τα απαραίτητα headers απόκρισης HTTP (όπως το Retry-After), και το προωθεί στο NestJS:
import { Module } from '@nestjs/common';import { APP_FILTER } from '@nestjs/core';import { ErrorFilter } from '@cqrs-ddd/nestjs';
@Module({ providers: [ { provide: APP_FILTER, useClass: ErrorFilter, }, ],})export class AppModule {}Μπορείτε επίσης να επεκτείνετε το ErrorFilter για να προσθέσετε μετασχηματισμούς σφαλμάτων ειδικούς για την εφαρμογή:
import { Catch, ArgumentsHost } from '@nestjs/common';import { ErrorFilter } from '@cqrs-ddd/nestjs';
@Catch()export class DomainExceptionFilter extends ErrorFilter { override catch(exception: unknown, host: ArgumentsHost): void { // Custom handling if needed, then delegate to ErrorFilter super.catch(exception, host); }}Βοηθητικά Εργαλεία Άμεσης Μετατροπής
Ενότητα με τίτλο «Βοηθητικά Εργαλεία Άμεσης Μετατροπής »Το @cqrs-ddd/nestjs εξάγει αυτόνομες βοηθητικές συναρτήσεις για τη μετατροπή domain σφαλμάτων χωρίς τη διέλευση από το φίλτρο:
import { httpAnswer, toHttpException, validationMessages } from '@cqrs-ddd/nestjs';
// 1. toHttpExceptionconst exception = toHttpException(domainError);if (exception) { throw exception;}
// 2. httpAnswer (includes headers)const answer = httpAnswer(new RateLimitExceededError({ limit: 10, windowMs: 60000, retryAfterMs: 5000 }));if (answer) { console.log(answer.exception.getStatus()); // 429 console.log(answer.headers); // { 'Retry-After': '5' }}
// 3. validationMessagesconst messages = validationMessages({ formErrors: ['Submission rejected'], fieldErrors: { email: ['Must be a valid email'], name: ['Required'] },});// ['Submission rejected', 'email: Must be a valid email', 'name: Required']Τυποποιημένα Payloads Σφαλμάτων
Ενότητα με τίτλο «Τυποποιημένα Payloads Σφαλμάτων »Όλα τα μετατρεπόμενα σφάλματα ταιριάζουν με το τυπικό περίβλημα (envelope) HTTP σφάλματος του NestJS:
{ "statusCode": 400, "error": "Bad Request", "message": ["email: Must be a valid email"]}Πίνακας Αντιστοιχιών
Ενότητα με τίτλο «Πίνακας Αντιστοιχιών »| Σφάλμα Πακέτου | Status Code | HTTP Status | Headers |
|---|---|---|---|
ZodValidationError |
400 | Bad Request | — |
InvalidValueException |
400 | Bad Request | — |
MissingTenantContextError |
400 | Bad Request | — |
UnauthorizedActionException |
403 | Forbidden | — |
FeatureDisabledError |
403 / 404 | Forbidden / Not Found | — |
EntityNotFoundException |
404 | Not Found | — |
ConcurrencyConflictError |
409 | Conflict | — |
IdempotencyConflictError |
409 | Conflict | — |
RateLimitExceededError |
429 | Too Many Requests | Retry-After: <seconds> |
TransientOperationError |
503 | Service Unavailable | — |
Correlation Middleware
Ενότητα με τίτλο «Correlation Middleware »Το @cqrs-ddd/nestjs/correlation παρέχει το CorrelationMiddleware, το οποίο διαβάζει τα εισερχόμενα correlation headers (π.χ. x-correlation-id), παράγει ένα UUIDv7 correlation ID εάν απουσιάζει, το δεσμεύει στο ασύγχρονο context εκτέλεσης, και ορίζει το correlation header στην εξερχόμενη απόκριση.
Καταχωρίστε το middleware στη μέθοδο configure του root module σας:
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';import { CorrelationMiddleware } from '@cqrs-ddd/nestjs/correlation';
@Module({})export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(CorrelationMiddleware) .forRoutes('*'); }}Job Context Module
Ενότητα με τίτλο «Job Context Module »Το @cqrs-ddd/nestjs/job-context παρέχει το JobContextModule για την απρόσκοπτη ενσωμάτωση background workers (όπως επεξεργαστές BullMQ ή καταναλωτές Kafka) με το @cqrs-ddd/pipeline-job-context. Καταχωρίζει το principal του job, τη λίστα tenants, και τις πηγές context κατά το bootstrap της εφαρμογής και τα αποκαταχωρίζει κατά τον τερματισμό:
import { Module } from '@nestjs/common';import { JobContextModule } from '@cqrs-ddd/nestjs/job-context';import { AuthsModule } from '../auths/auths.module.js';import { SessionJobPrincipal } from '../auths/session-job-principal.js';import { correlationSource } from '@cqrs-ddd/pipeline-correlation';import { tenantSource } from '@cqrs-ddd/pipeline-tenant';
@Module({ imports: [ JobContextModule.forRoot({ imports: [AuthsModule], principal: SessionJobPrincipal, tenants: ['tenant_a', 'tenant_b'], sources: { tenantId: tenantSource, correlationId: correlationSource, }, }), ],})export class BackgroundWorkerModule {}Παράδειγμα Πλήρους Ρύθμισης
Ενότητα με τίτλο «Παράδειγμα Πλήρους Ρύθμισης »Ακολουθεί ένα πλήρες παράδειγμα ρύθμισης που παρουσιάζει τα PipelineModule, ErrorFilter και CorrelationMiddleware:
import { Module, NestModule, MiddlewareConsumer, Logger } from '@nestjs/common';import { APP_FILTER } from '@nestjs/core';import { CqrsModule } from '@nestjs/cqrs';import { PipelineModule, ErrorFilter } from '@cqrs-ddd/nestjs';import { CorrelationMiddleware } from '@cqrs-ddd/nestjs/correlation';import { LoggingBehavior } from '@cqrs-ddd/pipeline';import { CaslBehavior, CaslAuthorizer } from '@cqrs-ddd/pipeline-casl';import { tenantSource } from '@cqrs-ddd/pipeline-tenant';import { correlationSource } from '@cqrs-ddd/pipeline-correlation';
@Module({ imports: [ CqrsModule.forRoot(), PipelineModule.forRoot({ sources: { tenantId: tenantSource, correlationId: correlationSource, }, globalBehaviors: [ { scope: 'all', before: [LoggingBehavior] }, ], diagnostics: 'strict', }), ], providers: [ { provide: LoggingBehavior, useFactory: () => new LoggingBehavior(new Logger('Pipeline')), }, { provide: CaslBehavior, useFactory: (authorizer: CaslAuthorizer) => new CaslBehavior(authorizer), inject: [CaslAuthorizer], }, { provide: APP_FILTER, useClass: ErrorFilter, }, ],})export class AppModule implements NestModule { configure(consumer: MiddlewareConsumer) { consumer .apply(CorrelationMiddleware) .forRoutes('*'); }}Πρόσοψη Πακέτου (@nestjs-pipeline/cqrs-ddd)
Ενότητα με τίτλο «Πρόσοψη Πακέτου (@nestjs-pipeline/cqrs-ddd) »Για συμβατότητα με προηγούμενες εκδόσεις και ενιαία ονοματοδοσία στο monorepo, παρέχεται επίσης το πακέτο @nestjs-pipeline/cqrs-ddd. Αποτελεί μια πρόσοψη μηδενικού κώδικα (zero-code facade) που επανεξάγει απευθείας το @cqrs-ddd/nestjs:
// Equivalent imports:import { PipelineModule, ErrorFilter } from '@cqrs-ddd/nestjs';import { PipelineModule, ErrorFilter } from '@nestjs-pipeline/cqrs-ddd';Άδεια χρήσης
Ενότητα με τίτλο «Άδεια χρήσης »Αυτό το πακέτο αποτελεί μέρος του monorepo nestjs-pipeline. Δείτε τις λεπτομέρειες άδειας χρήσης του repository.