@cqrs-ddd/nestjs
Ο adapter για NestJS των πακέτων @cqrs-ddd.
Μια εφαρμογή NestJS διατηρεί την ιδιωματική αρχιτεκτονική του NestJS: modules, dependency injection, controllers, και το επίσημο @nestjs/cqrs (CqrsModule, CommandBus, QueryBus, EventBus, @CommandHandler, @QueryHandler, @EventsHandler). Ο adapter παρέχει όσα λείπουν από το @nestjs/cqrs:
- Pipeline behaviors γύρω από handlers: κάνει compile και εκτελεί τα behaviors του
@cqrs-ddd/pipelineγύρω από κάθε instance command, query και event handler κατά το bootstrap της εφαρμογής. - Τυποποιημένο exception filtering: το
ErrorFilterμετατρέπει κάθε σφάλμα του@cqrs-ddd(domain errors, validation failures, άρνηση εξουσιοδότησης, rate limits, διενέξεις idempotency, feature flags) σε NestJSHttpExceptionμε το τυπικό response body του NestJS και τις κατάλληλες HTTP επικεφαλίδες. - Διάδοση correlation ID: το
CorrelationMiddlewareεκτελεί κάθε αίτημα με το correlation id από την επικεφαλίδαx-correlation-id(ή ένα νέο UUIDv7) και το επιστρέφει στην απάντηση. - Ασύγχρονο job context: το
JobContextModuleδιαδίδει tenants, correlation IDs και principals σε ουρές εργασίας (όπως BullMQ) και τα αποκαθιστά στους processors. - Ενσωμάτωση κύκλου ζωής aggregate: commands που επεκτείνουν το
CommandBaseHandlerδημοσιεύουν αυτόματα τα uncommitted domain events μέσω του NestJSEventBus.
Μια πλήρης λειτουργική εφαρμογή NestJS που παρουσιάζει όλα τα παραπάνω μοτίβα είναι διαθέσιμη στο nestjs-pipeline api/.
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση»Peer Dependencies
Ενότητα με τίτλο «Peer Dependencies»- Υποχρεωτικά peers:
@nestjs/common,@nestjs/coreκαι@nestjs/cqrs12, και@cqrs-ddd/pipelineκαι@cqrs-ddd/core0.5. Το ίδιο το NestJS απαιτείreflect-metadataκαιrxjs. - Προαιρετικά peers, εγκαθίστανται όταν τα χρησιμοποιεί η εφαρμογή:
@cqrs-ddd/pipeline-zod,@cqrs-ddd/pipeline-casl,@cqrs-ddd/pipeline-feature-flags,@cqrs-ddd/pipeline-rate-limitκαι@cqrs-ddd/pipeline-idempotency: τοErrorFilterμετατρέπει τα σφάλματα καθενός εξ αυτών αν είναι εγκατεστημένο.@cqrs-ddd/pipeline-correlation, για το@cqrs-ddd/nestjs/correlation.@cqrs-ddd/pipeline-job-context, για το@cqrs-ddd/nestjs/job-context.
Οποιοδήποτε άλλο πακέτο behavior (cache, resilience, audit, telemetry, dead letters) εκτελείται στα pipelines χωρίς να απαιτείται ειδική γνώση από τον adapter.
Ελάχιστη ρύθμιση
Ενότητα με τίτλο «Ελάχιστη ρύθμιση»Ένα πλήρες root module: το επίσημο CqrsModule, το PipelineModule, ένας provider για κάθε behavior που εκτελείται, και ένας handler. Σε μια εφαρμογή NestJS, εγκαταστήστε τον adapter και, για την επικύρωση, το @cqrs-ddd/pipeline-zod:
Κάθε behavior που εκτελείται είναι provider: το LoggingBehavior μέσω factory, επειδή δέχεται logger, και το ZodValidationBehavior ως κλάση. Ένα behavior που αναφέρεται σε pipeline και δεν παρέχεται από κανένα module σταματά την εφαρμογή κατά την εκκίνηση. Ένας controller, ή οποιοσδήποτε άλλος provider, εκτελεί το command μέσω του CommandBus του @nestjs/cqrs:
Ένα μη έγκυρο command απορρίπτεται με ZodValidationError πριν εκτελεστεί ο handler, και το ErrorFilter απαντά μέσω HTTP με 400 Bad Request. Το module αυτό είναι το integration/nestjs/invoices.ts του αποθετηρίου, που εκτελείται από το spec του· το integration/nestjs/app.ts είναι μια μεγαλύτερη εφαρμογή με controllers, εξουσιοδότηση και rate limiting, δοκιμασμένη μέσω HTTP σε Express και Fastify.
Αρχιτεκτονικός κύκλος ζωής (Architectural Lifecycle)
Ενότητα με τίτλο «Αρχιτεκτονικός κύκλος ζωής (Architectural Lifecycle)»Ο adapter λειτουργεί μέσω του PipelineBootstrap, μίας @Injectable() υπηρεσίας που καταχωρείται από το PipelineModule:
Βασικές εγγυήσεις runtime:
- Instance wrapping, όχι μετάλλαξη prototype: Μόνο τα provider instances της τρέχουσας εφαρμογής γίνονται wrap. Τα prototypes των κλάσεων δεν τροποποιούνται ποτέ, επιτρέποντας πολλαπλές απομονωμένες εφαρμογές στην ίδια διεργασία.
- Fail-fast επικύρωση: Ελλείποντες providers behaviors, αμφίσημοι διπλότυποι providers, request-scoped handlers ή σπασμένα contracts αποτυγχάνουν άμεσα κατά την εκκίνηση της εφαρμογής πριν ο HTTP listener αρχίσει να δέχεται κλήσεις.
- Καθαρός τερματισμός: Το
OnModuleDestroyεπαναφέρει τους αρχικούς method descriptors σε όλα τα wrapped handler instances.
Ρύθμιση Pipeline
Ενότητα με τίτλο «Ρύθμιση Pipeline»Εισάγετε το PipelineModule.forRoot() στο root module ή στο core infrastructure module της εφαρμογής σας:
PipelineModuleOptions
Ενότητα με τίτλο «PipelineModuleOptions»| Επιλογή | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
globalBehaviors |
GlobalBehaviorsOptions | GlobalBehaviorsOptions[] |
κανένα | Behaviors τοποθετημένα γύρω από handlers στα επιλεγμένα scopes ('all', 'commands', 'queries', 'events'). |
sources |
ContextSources |
κανένα | Από πού τα pipelines διαβάζουν και αποκαθιστούν τα tenantId και correlationId. |
diagnostics |
'strict' | 'warn' | 'off' |
'strict' |
Λειτουργία επικύρωσης των behavior contracts: το 'strict' ρίχνει PipelineConfigurationError στην εκκίνηση, το 'warn' καταγράφει προειδοποιήσεις, το 'off' παρακάμπτει τους ελέγχους. |
Καταχώριση Behaviors με Dependency Injection
Ενότητα με τίτλο «Καταχώριση Behaviors με Dependency Injection»Τα behaviors είναι απλές κλάσεις παραμετροποιημένες με εξαρτήσεις (loggers, Redis stores, connection pools, CASL loaders). Κάθε module παρέχει το instance του behavior υπό το class token του:
Κανόνες Providers
Ενότητα με τίτλο «Κανόνες Providers»- Απαιτείται singleton scope: Κάθε behavior provider και κάθε handler που εκτελεί behaviors οφείλει να είναι στατικό singleton (
Scope.DEFAULT). Αν ένας handler ή behavior είναι request-scoped (Scope.REQUEST), τοPipelineBootstrapαποτυγχάνει άμεσα κατά την εκκίνηση. Δεδομένα αιτήματος πρέπει να ανακτώνται μέσωAsyncLocalStorageή context sources. - Μοναδικός provider ανά behavior: Ακριβώς ένα module πρέπει να παρέχει κάθε class token ενός behavior. Αν δύο modules καταχωρίσουν providers για το ίδιο token, το
PipelineBootstrapρίχνει σφάλμα αναφέροντας και τα δύο modules προς αποφυγή ασάφειας.
Handlers και δηλώσεις (Declarations)
Ενότητα με τίτλο «Handlers και δηλώσεις (Declarations)»Command, query και event handlers χρησιμοποιούν τους κλασικούς decorators του @nestjs/cqrs. Χρησιμοποιήστε τα @UsePipeline και @SkipPipeline από το @cqrs-ddd/pipeline για τη δήλωση behaviors:
Ροή εκτέλεσης behaviors
Ενότητα με τίτλο «Ροή εκτέλεσης behaviors»Όταν ένας controller καλεί commandBus.execute(command), η κλήση εισέρχεται στο compiled pipeline του CreateOrderHandler. Τα behaviors σχηματίζουν ομόκεντρα στρώματα: πρώτα τα global before behaviors (logging), έπειτα τα behaviors του ίδιου του handler κατά τη σειρά δήλωσης (authorization, validation, idempotency, audit), και τέλος τα global after behaviors. Η μέθοδος execute(command) του handler εκτελείται στο εσωτερικό με το επικυρωμένο command. Κατά την επιστροφή, κάθε behavior παραλαμβάνει το αποτέλεσμα ή το σφάλμα. Ένα behavior που ρίχνει σφάλμα (π.χ. απόρριψη authorization) διακόπτει την εκτέλεση πριν εκτελεστούν τα εσωτερικά στρώματα.
Διαχείριση σφαλμάτων με το ErrorFilter
Ενότητα με τίτλο «Διαχείριση σφαλμάτων με το ErrorFilter»Το ErrorFilter αναχαιτίζει όλα τα σφάλματα του @cqrs-ddd και τα μεταφράζει σε τυποποιημένα NestJS HttpException instances που ταιριάζουν με το προεπιλεγμένο JSON error format του NestJS ({ statusCode, message, error }).
Καταχωρίστε το καθολικά (globally) στο AppModule:
Πίνακας αντιστοίχισης σφαλμάτων
Ενότητα με τίτλο «Πίνακας αντιστοίχισης σφαλμάτων»| Κλάση σφάλματος | Πακέτο προέλευσης | HTTP Status | Μορφή Response Body | Πρόσθετες επικεφαλίδες |
|---|---|---|---|---|
ZodValidationError |
@cqrs-ddd/pipeline-zod |
400 Bad Request | { statusCode: 400, error: 'Bad Request', message: ['field: error message'] } |
— |
UnauthorizedActionException |
@cqrs-ddd/pipeline-casl |
403 Forbidden | { statusCode: 403, error: 'Forbidden', message, action, subject } |
— |
FeatureDisabledError |
@cqrs-ddd/pipeline-feature-flags |
403 Forbidden | { statusCode: 403, error: 'Forbidden', message, flag } |
— |
RateLimitExceededError |
@cqrs-ddd/pipeline-rate-limit |
429 Too Many Requests | { statusCode: 429, error: 'Too Many Requests', message, retryAfter } |
Retry-After: <seconds> |
IdempotencyConflictError |
@cqrs-ddd/pipeline-idempotency |
409 Conflict (in_progress, replay_scope) / 422 Unprocessable Entity (key_reuse) |
{ statusCode, error, message, reason } |
— |
EntityNotFoundException |
@cqrs-ddd/core |
404 Not Found | { statusCode: 404, error: 'Not Found', message: 'Order not found' } |
— |
ConcurrencyConflictError |
@cqrs-ddd/core (μέσω @cqrs-ddd/mikro-orm) |
409 Conflict | { statusCode: 409, error: 'Conflict', message } |
— |
MissingTenantContextError |
@cqrs-ddd/core |
500 Internal Server Error | { statusCode: 500, error: 'Internal Server Error', message: 'Internal server error' } |
— |
οποιοδήποτε άλλο DomainException |
@cqrs-ddd/core ή η εφαρμογή |
400 Bad Request | { statusCode: 400, error: 'Bad Request', message } |
— |
Μη αναγνωρίσιμα σφάλματα προωθούνται στην προεπιλεγμένη συμπεριφορά του BaseExceptionFilter του NestJS.
Προσαρμοσμένα Exception Filters
Ενότητα με τίτλο «Προσαρμοσμένα Exception Filters»Για να διαχειριστείτε ειδικά σφάλματα της εφαρμογής σας διατηρώντας παράλληλα τις μετατροπές του @cqrs-ddd, επεκτείνετε το ErrorFilter ή χρησιμοποιήστε τα toHttpException και httpAnswer:
Middleware για Correlation ID
Ενότητα με τίτλο «Middleware για Correlation ID»Το CorrelationMiddleware αντλεί το correlation id κάθε αιτήματος από την επικεφαλίδα x-correlation-id (ή παράγει ένα UUIDv7 αν απουσιάζει), εκτελεί το αίτημα εντός αυτού στο AsyncLocalStorage, και επιστρέφει την επικεφαλίδα στην απάντηση. Αποτελεί το httpCorrelation() του @cqrs-ddd/pipeline-correlation ως NestJS middleware και λειτουργεί σε Express και Fastify.
Καταχώριση στο AppModule:
Background Jobs με το JobContextModule
Ενότητα με τίτλο «Background Jobs με το JobContextModule»Όταν ένα αίτημα εισάγει μια εργασία σε ουρά (BullMQ, SQS, κλπ.), ο worker που την εκτελεί δεν διαθέτει το αρχικό context του αιτήματος. Το JobContextModule καταχωρεί τη λίστα των tenants, τον principal resolver και τις πηγές context στο @cqrs-ddd/pipeline-job-context:
Εισαγωγή στην ουρά με withJobContext, και χρήση του @InJobContext() στους processors:
Ενσωμάτωση Domain-Driven Design
Ενότητα με τίτλο «Ενσωμάτωση Domain-Driven Design»Τα aggregates και domain events του @cqrs-ddd/core ενσωματώνονται άψογα με το @nestjs/cqrs.
CommandBaseHandler με το NestJS EventBus
Ενότητα με τίτλο «CommandBaseHandler με το NestJS EventBus»Το EventBus του @nestjs/cqrs υλοποιεί το IDomainEventPublisher (publishAll(events, dispatcherContext)). Command handlers που επεκτείνουν το CommandBaseHandler δημοσιεύουν αυτόματα τα uncommitted domain events των aggregates:
Πλήρες παράδειγμα παραγωγής
Ενότητα με τίτλο «Πλήρες παράδειγμα παραγωγής»Ακολουθεί ένας ολοκληρωμένος command handler εγγραφής χρήστη σε NestJS που συνδυάζει validation, idempotency, audit logging και δημοσίευση domain events: