NestJS & @cqrs-ddd: Ενσωμάτωση ή Μετάβαση
Ομάδες που χρησιμοποιούν NestJS έχουν δύο αρχιτεκτονικές επιλογές όταν υιοθετούν το @cqrs-ddd:
- Διατήρηση του NestJS και προσθήκη του adapter
@cqrs-ddd/nestjs: Διατηρείτε τους υπάρχοντες handlers, τα buses, τα modules, το dependency injection και τους controllers του@nestjs/cqrs. Ο adapter τυλίγει τους handlers σε pipelines συμπεριφορών (behaviors), παρέχει κεντρικό exception filtering και διαχειρίζεται το correlation και το job context. Τίποτα δεν αντικαθίσταται. - Μετάβαση σε CQRS χωρίς framework με το
@cqrs-ddd/cqrs: Δημιουργία εφαρμογών χωρίς NestJS σε απλό Node.js, Fastify ή Express, κατασκευάζοντας τους handlers μεnewκαι καταχωρίζοντάς τους στοcreateCqrs(). Καλύπτει handlers και buses, όχι κάθε δυνατότητα του@nestjs/cqrs: δείτε Τι δεν περιλαμβάνεται.
Οι δύο επιλογές είναι ανεξάρτητες. Μια υπάρχουσα εφαρμογή NestJS ακολουθεί την πρώτη και δεν χρειάζεται ποτέ τη δεύτερη. Μια εφαρμογή στα πακέτα @nestjs-pipeline/* 0.4.x ξεκινά από το Από το @nestjs-pipeline 0.4.x.
Σύγκριση Αρχιτεκτονικής
Ενότητα με τίτλο «Σύγκριση Αρχιτεκτονικής»| Διάσταση | Καθαρό @nestjs/cqrs |
NestJS + @cqrs-ddd/nestjs |
@cqrs-ddd/cqrs χωρίς framework |
|---|---|---|---|
| Handler Decorators | @CommandHandler, @QueryHandler, @EventsHandler |
Ίδιοι decorators του @nestjs/cqrs + @UsePipeline, @SkipPipeline |
Ίδια ονόματα από το @cqrs-ddd/cqrs + @UsePipeline, @SkipPipeline |
| Buses | CommandBus, QueryBus, EventBus |
Ίδια buses του @nestjs/cqrs |
Ίδια ονόματα buses, από το createCqrs() |
| Pipeline Behaviors | Κανένα (απαιτούνται interceptors) | Μεταγλωττίζει και εκτελεί το @cqrs-ddd/pipeline γύρω από handlers |
Μεταγλωττίζει και εκτελεί το @cqrs-ddd/pipeline γύρω από handlers |
| DI & Containers | IoC container του NestJS | IoC container του NestJS παρέχει behaviors και handlers | Χωρίς container: ρητή χρήση new στο composition root |
| Exception Handling | Χειροκίνητα exception filters | Αυτόματο ErrorFilter που μετατρέπει σφάλματα σε HttpException |
Framework-neutral: το HTTP επίπεδο αντιστοιχίζει σφάλματα (domainErrorHttpStatus) |
| Διαγνωστικοί έλεγχοι εκκίνησης | Σιωπηρή επικάλυψη σε διπλότυπους handlers | Επαληθεύει singleton scope, μοναδικότητα providers, συμβόλαια behaviors | Αποτυγχάνει σε διπλότυπους handlers, ελλιπείς decorators, παραβιάσεις συμβολαίων |
| Runtime | NestJS | NestJS | Χωρίς framework: μόνο τα buses και τα pipelines |
Επιλογή 1: Ενσωμάτωση στο NestJS μέσω του @cqrs-ddd/nestjs
Ενότητα με τίτλο «Επιλογή 1: Ενσωμάτωση στο NestJS μέσω του @cqrs-ddd/nestjs»Εάν εργάζεστε ήδη σε NestJS ή επιθυμείτε το οικοσύστημα controllers και dependency injection του Nest, εγκαταστήστε το @cqrs-ddd/nestjs:
Τι διατηρείτε
Ενότητα με τίτλο «Τι διατηρείτε»- Όλους τους ορισμούς
@Module(),@Injectable(),@Controller(). - Τα επίσημα imports του
@nestjs/cqrs:CqrsModule,CommandBus,QueryBus,EventBus,@CommandHandler,@QueryHandler,@EventsHandler. - Οι handlers υλοποιούν τα
ICommandHandler,IQueryHandler,IEventHandler. - Οι controllers κάνουν inject τα
CommandBusκαιQueryBusόπως συνήθως.
Τι προσθέτετε
Ενότητα με τίτλο «Τι προσθέτετε»Η Ελάχιστη ρύθμιση είναι ένα πλήρες root module με κάθε import και provider, που εκτελείται από test. Τα παρακάτω βήματα δείχνουν τα μέρη του.
-
PipelineModule.forRoot()στοAppModule: -
Δηλώσεις pipeline σε handlers:
Κάθε behavior που αναφέρει ένας handler είναι provider κάποιου module: εδώ το
ZodValidationBehavior, και τοIdempotencyBehaviorκατασκευασμένο με το store του. -
Δημοσίευση Domain Events: Κληρονομήστε από τον
CommandBaseHandlerτου@cqrs-ddd/core/applicationκαι περάστε το injectedEventBusτου@nestjs/cqrs. Όταν ηhandle(command)επιστρέφει έναAggregateRoot, τα μη καταχωρισμένα domain events δημοσιεύονται αυτόματα μέσω τουeventBus.publishAll()και καθαρίζονται. Η παράδοση παραμένει ό,τι παρέχει αυτό τοEventBus: ο adapter δεν προσθέτει ανθεκτική παράδοση μηνυμάτων ούτε outbox.
Επιλογή 2: Μετάβαση από το NestJS στο @cqrs-ddd/cqrs
Ενότητα με τίτλο «Επιλογή 2: Μετάβαση από το NestJS στο @cqrs-ddd/cqrs»Εάν ο στόχος σας είναι η κατάργηση του NestJS για μια αρχιτεκτονική χωρίς framework σε απλό Node.js, Express ή Fastify, χρησιμοποιήστε το @cqrs-ddd/cqrs:
Τι μεταφέρεται αυτούσιο
Ενότητα με τίτλο «Τι μεταφέρεται αυτούσιο»Οι decorators των handlers, τα interfaces των handlers και τα ονόματα των buses ταιριάζουν με το @nestjs/cqrs:
@nestjs/cqrs |
@cqrs-ddd/cqrs |
|---|---|
@CommandHandler(Command) |
@CommandHandler(Command) από το @cqrs-ddd/cqrs |
@QueryHandler(Query) |
@QueryHandler(Query) από το @cqrs-ddd/cqrs |
@EventsHandler(...Events) |
@EventsHandler(...Events) από το @cqrs-ddd/cqrs |
ICommandHandler<TCommand> |
ICommandHandler<TCommand> από το @cqrs-ddd/cqrs |
IQueryHandler<TQuery> |
IQueryHandler<TQuery> από το @cqrs-ddd/cqrs |
IEventHandler<TEvent> |
IEventHandler<TEvent> από το @cqrs-ddd/cqrs |
CommandBus, QueryBus, EventBus |
Επιστρέφονται από το createCqrs() |
Τι δεν περιλαμβάνεται
Ενότητα με τίτλο «Τι δεν περιλαμβάνεται»Το @cqrs-ddd/cqrs δεν αντικαθιστά κάθε δυνατότητα του @nestjs/cqrs. Δεν έχει sagas, RxJS pipes με ofType, AsyncContext ούτε μηχανισμούς συγχώνευσης του EventPublisher· τα aggregates δημοσιεύουν events μέσω του CommandBaseHandler. Το EventBus του παραδίδει in-process: δεν είναι ανθεκτική παράδοση μηνυμάτων ούτε outbox. Μια εφαρμογή που βασίζεται σε κάποιο από αυτά διατηρεί το NestJS και ακολουθεί την Επιλογή 1.
Τι αναλαμβάνει η ίδια η εφαρμογή
Ενότητα με τίτλο «Τι αναλαμβάνει η ίδια η εφαρμογή»| Ευθύνη NestJS | Ισοδύναμο @cqrs-ddd |
|---|---|
@Module(), @Injectable(), providers |
Μια απλή συνάρτηση composition root που δημιουργεί εξαρτήσεις με new |
NestFactory.create(AppModule) |
const cqrs = createCqrs(options); cqrs.register(...handlers); |
| Lifecycle hooks τερματισμού | await cqrs.close(), και στη συνέχεια κλείσιμο των pools βάσης και συνδέσεων redis |
| Controllers, guards, interceptors, pipes | Εγγενείς διαδρομές και middleware του HTTP framework· δείτε HTTP με Express και Fastify |
| Request-scoped providers | AsyncLocalStorage μέσω των context sources (tenantId, correlationId) |
Παράδειγμα σε Απλό Node.js
Ενότητα με τίτλο «Παράδειγμα σε Απλό Node.js»Διαφορές στη Συμπεριφορά Runtime
Ενότητα με τίτλο «Διαφορές στη Συμπεριφορά Runtime»- Αυστηρή καταχώριση handlers: Η καταχώριση δεύτερου handler για την ίδια εντολή ή ερώτημα αποτυγχάνει αμέσως στο
cqrs.register(). Το NestJS σιωπηρά αντικαθιστά τους προηγούμενους με τον τελευταίο καταχωρισμένο. - Ασύγχρονα σφάλματα απόντος handler: Στο
@cqrs-ddd/cqrs, ταcommandBus.execute()καιqueryBus.execute()απορρίπτουν ασύγχρονα μεCommandHandlerNotFoundExceptionήQueryHandlerNotFoundException. Το@nestjs/cqrsεκτοξεύει σύγχρονα. - Ομαλός τερματισμός (Graceful Shutdown): Το
cqrs.close()περιμένει την ολοκλήρωση όλων των ασύγχρονων event handlers πριν επιλυθεί. Στο NestJS, τοapp.close()δεν παρακολουθεί την ολοκλήρωση των παρασκηνιακών event handlers. - Απομόνωση σφαλμάτων events: Όπως στο
@nestjs/cqrs, η αποτυχία ενός event handler αποστέλλεται στοUnhandledExceptionBusκαι ο handler συνεχίζει να λαμβάνει μεταγενέστερα events· το@cqrs-ddd/cqrsεπιπλέον την καταγράφει, ή την εκτοξεύει ξανά μεrethrowUnhandled: true.
Επιλέγοντας τη Σωστή Προσέγγιση
Ενότητα με τίτλο «Επιλέγοντας τη Σωστή Προσέγγιση»- Επιλέξτε την Επιλογή 1 (
@cqrs-ddd/nestjs) όταν εργάζεστε σε υπάρχουσα βάση κώδικα NestJS, χρησιμοποιείτε NestJS microservices ή GraphQL, ή βασίζεστε έντονα στο οικοσύστημα controllers και DI modules του Nest. - Επιλέξτε την Επιλογή 2 (
@cqrs-ddd/cqrs) όταν χτίζετε μια νέα υπηρεσία σε απλό Node.js, Express ή Fastify, ή όταν θέλετε ρητή κατασκευή χωρίς dependency-injection container και καμία από τις δυνατότητες της ενότητας Τι δεν περιλαμβάνεται.