@cqrs-ddd/core
Από την έκδοση 0.5.0 το
@cqrs-ddd/coreαναπτύσσεται και δημοσιεύεται από το ddd-cqrs, με τεκμηρίωση στο aristoteliss.github.io/ddd-cqrs. Αυτός ο ιστότοπος τεκμηριώνει τη σειρά 0.4.x· οι εκδόσεις 0.1 έως 0.4 παραμένουν στο npm αμετάβλητες.
Δομικά στοιχεία ανεξάρτητα από framework για domain-driven design σε TypeScript: aggregates με versioned mutations, αποσυνδεδεμένα domain events, ένας command handler που δημοσιεύει αυτά τα συμβάντα, συμβόλαια repository, decorators κύκλου ζωής persistence, ένα revision-fenced repository cache, κλειδιά cache με tenant scope και αντιστοίχιση καταστάσεων HTTP για τα σφάλματά του.
Δεν εξαρτάται από κανένα framework και κανένα ORM. Οι adapters για το MikroORM βρίσκονται στο @cqrs-ddd/mikro-orm. Λειτουργεί σε μια απλή υπηρεσία Node, καθώς και σε μια εφαρμογή NestJS μέσω δομικής συμβατότητας: δείτε Χρήση από το NestJS.
Περιεχόμενα
Ενότητα με τίτλο «Περιεχόμενα »- Εγκατάσταση
- Entry points
- Aggregates
- Κανόνες τιμών (Value rules)
- Domain events
- Commands και δημοσίευση συμβάντων
- Write-side repositories
- Read-side repositories
- Το repository cache
- Κλειδιά cache με tenant scope
- Αντιστοίχιση HTTP status
- Χρήση από το NestJS
- Μετάβαση από το ddd/core
- Γνωστοί περιορισμοί
- Άδεια χρήσης
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση »pnpm add @cqrs-ddd/core# ornpm install @cqrs-ddd/coreΑπαιτεί Node.js 22.12 ή νεότερο. Εγκαθιστά τα @cqrs-ddd/uuidv7 και @cqrs-ddd/safe-stringify, τα οποία δεν έχουν εξαρτήσεις. Για persistence με το MikroORM, προσθέστε τα @cqrs-ddd/mikro-orm και @mikro-orm/core 7.
Δημοσιεύεται ως ES module· μια εφαρμογή CommonJS το φορτώνει με require(). Εάν προέρχεστε από την έκδοση 0.3.x, δείτε Αναβάθμιση από 0.3.x.
Entry points
Ενότητα με τίτλο «Entry points »Εισαγάγετε από το entry point που αντιστοιχεί στο επίπεδο (layer) που γράφετε. Κάθε ένα φορτώνει μόνο ό,τι χρειάζεται.
| Entry point | Περιέχει |
|---|---|
@cqrs-ddd/core/domain |
AggregateRoot, IAggregateRoot, ApplyEventOptions, RootEntity, RootEntitySnapshot, @Mutable, getMutableFields, @ApplyMutation, IEvent, DomainEvent, RootDomainEvent, deepCloneAndFreeze, textRule, numberRule, ValueViolation, και τα σφάλματα DomainException, InvalidValueException, EntityNotFoundException, ConcurrencyConflictError, TransientOperationError (με isTransientOperationError), MissingTenantContextError, UnknownMutableFieldError |
@cqrs-ddd/core/application |
BaseCommand, BaseQuery, IQueryOptions, CommandBaseHandler, τα ports (IDomainEventPublisher, ICommandRepository, IQueryRepository, IWriteSideAggregateRepository, ICache, IVersionedCache, isVersionedCache), requireTenant, setTenantResolver, και το deprecated requireTenantId |
@cqrs-ddd/core/persistence |
τους decorators κύκλου ζωής (@PersistedWrite, @Cache, @AcknowledgePersisted, @MapPersistenceErrors, @FromCache), QueryRepository, CommandRepository, MemoryCache και το injection token του CACHE_TOKEN, cacheKey, cacheKeyTemplate, isCacheNewer, toCacheSnapshot, τα βοηθητικά mutation-barrier, consoleCacheLogger, safeWarn, και το συμβόλαιο persistence dialect (IPersistenceDialect, setPersistenceDialect, persistenceDialect) |
@cqrs-ddd/core/http |
domainErrorHttpStatus |
@cqrs-ddd/core |
όλα τα παραπάνω, καθώς και τον τύπο Method |
Κανένα entry point δεν φορτώνει κάποιο ORM ή το NestJS.
Aggregates
Ενότητα με τίτλο «Aggregates »Ένα aggregate επεκτείνει το RootEntity<TSnapshot>. Αποκτά ένα UUIDv7 id, createdAt και updatedAt, ένα version για optimistic concurrency, και ένα buffer συμβάντων. Οι αλλαγές κατάστασης γίνονται μέσω domain μεθόδων διακοσμημένων με @ApplyMutation, οι οποίες γράφουν μόνο τα πεδία που έχουν δηλωθεί ως @Mutable:
import { ApplyMutation, DomainException, InvalidValueException, Mutable, RootEntity, type RootEntitySnapshot, textRule,} from '@cqrs-ddd/core/domain';
export class InvalidUsernameException extends InvalidValueException {}export class InvalidDepartmentException extends InvalidValueException {}export class EmptyUserUpdateException extends DomainException { constructor() { super('A user update needs at least one field.'); }}
export interface UserSnapshot extends Partial<RootEntitySnapshot> { readonly username: string; readonly email: string; readonly department?: string | null;}
export class User extends RootEntity<UserSnapshot> { static readonly aggregateName = 'user'; static readonly rules = { username: textRule({ field: 'username', minLength: 3, maxLength: 255, error: (violation) => new InvalidUsernameException(violation), }), department: textRule({ field: 'department', required: false, maxLength: 255, error: (violation) => new InvalidDepartmentException(violation), }), } as const;
@Mutable<string>({ normalize: (value) => User.rules.username.parse(value) }) private _username: string;
@Mutable<string | null>({ normalize: (value) => User.rules.department.parse(value) }) private _department: string | null;
readonly email: string;
private constructor(snapshot: UserSnapshot) { super(snapshot); this._username = User.rules.username.parse(snapshot.username); this._department = User.rules.department.parse(snapshot.department); this.email = snapshot.email; }
static create(username: string, email: string, department?: string | null): User { const user = new User({ username, email, department }); user.apply(new UserCreatedEvent(user)); return user; }
static fromJSON(snapshot: UserSnapshot): User { return new User(snapshot); }
get username(): string { return this._username; }
private set username(value: string) { this._username = User.rules.username.parse(value); }
get department(): string | null { return this._department; }
private set department(value: string | null) { this._department = User.rules.department.parse(value); }
@ApplyMutation<User>({ event: (user) => new UserUpdatedEvent(user) }) update(fields: { username?: string; department?: string | null }): this { if (fields.username === undefined && fields.department === undefined) { throw new EmptyUserUpdateException(); } this.applyPatch({ username: fields.username, department: fields.department }); return this; }
@ApplyMutation<User>({ event: (user) => new UserDeletedEvent(user) }) delete(): this { return this; }
toJSON(): UserSnapshot & RootEntitySnapshot { return this.freezeState({ id: this.id, username: this._username, department: this._department, email: this.email, createdAt: this.createdAt, updatedAt: this.updatedAt, version: this.version, }); }}Τα συμβάντα δηλώνονται στα Domain events. Χρήση του aggregate:
const user = User.create('alice', 'alice@example.test');user.version; // 1user.getUncommittedEvents(); // [UserCreatedEvent]
user.update({ department: 'Research' });user.version; // 2user.getExpectedVersion(); // 1: the version the next write must find in storage
user.update({}); // throws EmptyUserUpdateException; nothing is recordeduser.update({ username: 'a' }); // throws InvalidUsernameException before any field is written- Το
@Mutableκαταχωρίζει ένα πεδίο για τοapplyPatchυπό το όνομα της ιδιότητάς του χωρίς το αρχικό underscore (το_usernameενημερώνεται ωςusername)· τοas: 'name'ορίζει άλλο κλειδί, και τοnormalizeεπικυρώνει και μετατρέπει κάθε τιμή. - Το
applyPatch(patch)επικυρώνει και κανονικοποιεί (normalizes) κάθε παρεχόμενο πεδίο πριν γράψει οποιοδήποτε από αυτά, και αγνοεί τις τιμέςundefined. Ένα άγνωστο κλειδί πετάUnknownMutableFieldError. - Μετά από μια επιτυχημένη μέθοδο, το
@ApplyMutationπροωθεί ταversionκαιupdatedAtκαι καταγράφει το event. Μια μέθοδος που πετά σφάλμα δεν καταγράφει τίποτα. - Επικυρώστε πριν από το patching: μια αποτυχία αφού γραφτούν τα πεδία (μεταγενέστερος κώδικας μεθόδου, lifecycle hook, δημιουργία συμβάντος) δεν τα επαναφέρει (rollback). Απορρίψτε ή επαναφορτώστε το instance.
- Το
RootEntity.from(value)επαναενυδατώνει (rehydrates) ένα instance, ένα snapshot ή ένα nullish αποτέλεσμα βάσης δεδομένων, και πετάTypeErrorγια μη συμβατό aggregate. - Τα
id,createdAtκαιupdatedAtέχουν δημόσιους getters και ιδιωτικούς (private) setters. Το ORM εκτελεί hydration μέσω των setters (δείτε παρακάτω)· ο κώδικας της εφαρμογής δεν μπορεί να τους αναθέσει τιμές και αλλάζει την κατάσταση μέσω domain μεθόδων και factories. Ορίστε επίσης ιδιωτικούς setters για τα persisted πεδία μιας υποκλάσης, όπως ταusernameκαιdepartmentπαραπάνω. - Το
versionείναι η έκδοση στη μνήμη· τοgetExpectedVersion()είναι η έκδοση που διαβάστηκε τελευταία φορά από ή γράφτηκε στο storage, με την οποία συγκρίνεται μια version-conditioned εγγραφή. ΤοacknowledgePersisted()το προωθεί μετά από επιτυχή εγγραφή· το@PersistedWriteτο καλεί αυτόματα για εσάς.
Κανόνες τιμών (Value rules)
Ενότητα με τίτλο «Κανόνες τιμών (Value rules) »Τα textRule(options) και numberRule(options) ορίζουν τον κανόνα για ένα πεδίο μία φορά. Το aggregate χρησιμοποιεί το parse(value) του κανόνα για να κανονικοποιήσει την τιμή, και άλλα επίπεδα διαβάζουν τα όρια του κανόνα, ώστε το schema ενός request να μην αποκλίνει από το domain:
z.string().trim().min(User.rules.username.minLength).max(User.rules.username.maxLength);Το parse(value) επιστρέφει την κανονικοποιημένη τιμή ή πετά το σφάλμα του κανόνα. Είναι μια αυτόνομη συνάρτηση, και ο κανόνας είναι παγωμένος (frozen).
Επιλογή textRule |
Αποτέλεσμα |
|---|---|
field |
Όνομα που αναφέρεται στην παραβίαση και στο προεπιλεγμένο μήνυμα |
required |
Με false κανονικοποιεί τα null, undefined και κενό κείμενο σε null· από προεπιλογή απορρίπτονται |
minLength, maxLength |
Μήκος μετά την κανονικοποίηση, σε UTF-16 code units όπως τα .min() και .max() του Zod |
pattern |
Κανονική έκφραση (regex) με την οποία πρέπει να ταιριάζει το κείμενο· τα flags g ή y απορρίπτονται |
multiline |
Με true δέχεται tab, line feed και carriage return εντός του κειμένου |
error |
Κατασκευάζει το σφάλμα για μια παραβίαση· προεπιλογή το InvalidValueException |
Το κείμενο ελέγχεται ως προς τον τύπο και για μη συζευγμένα surrogates, στη συνέχεια μετατρέπεται σε μορφή Unicode NFC και αφαιρούνται τα κενά (trimmed). Οι χαρακτήρες ελέγχου (control characters) απορρίπτονται πάντα, όπως και τα tabs και οι αλλαγές γραμμής εκτός αν έχει οριστεί το multiline.
Επιλογή numberRule |
Αποτέλεσμα |
|---|---|
field, required, error |
Όπως και στο textRule (το required: false δέχεται null και undefined) |
integer |
Δέχεται μόνο ασφαλείς ακέραιους (safe integers) |
min, max |
Συμπεριληπτικά όρια (inclusive bounds) |
Ένας αριθμός πρέπει να είναι τύπου number και πεπερασμένος· μια αριθμητική συμβολοσειρά απορρίπτεται, δεν μετατρέπεται. Μια μη έγκυρη επιλογή, όπως minLength μεγαλύτερο από το maxLength, πετά TypeError κατά τον ορισμό του κανόνα.
Ένας παραβιασμένος κανόνας πετά error(violation). Το violation είναι ένα παγωμένο (frozen) ValueViolation: { field, rule }, συν το limit για κανόνα μήκους ή εύρους και το expected για κανόνα τύπου. Το InvalidValueException το μεταφέρει, κατασκευάζει το μήνυμα (username must be at least 3 characters.), και δεν διατηρεί την απορριφθείσα τιμή. Επεκτείνετέ το για τις δικές σας εξαιρέσεις, όπως στο παραπάνω παράδειγμα, ώστε όλες να μοιράζονται αυτή τη δομή.
Domain events
Ενότητα με τίτλο «Domain events »Ένα domain event επεκτείνει το RootDomainEvent<TEntity, TPayload>. Φέρει ένα UUIDv7 id, τα aggregateId και aggregateVersion κατά τον χρόνο του συμβάντος, και το payload: έναν βαθύ κλώνο (deep clone) του toJSON() του aggregate, αναδρομικά παγωμένο (frozen).
import { RootDomainEvent } from '@cqrs-ddd/core/domain';
export class UserCreatedEvent extends RootDomainEvent<User, UserSnapshot> { constructor(user: User) { super(user); }}Τα UserUpdatedEvent και UserDeletedEvent δηλώνονται με τον ίδιο τρόπο.
- Αποσυνδεδεμένο (Detached): μετέπειτα αλλαγές στο aggregate δεν φτάνουν ποτέ στο
payload. - Μόνο για ανάγνωση σε συνήθη πρόσβαση: οι ίδιες οι ιδιότητες είναι παγωμένες, και οι μέθοδοι μετάλλαξης (mutating methods) των κλωνοποιημένων τιμών
Date,MapκαιSetπετούν σφάλμα. - Όχι όριο ασφαλείας: Το
Object.freezeδεν καλύπτει την ενσωματωμένη εσωτερική κατάσταση, επομένως τοDate.prototype.setTime.call(payload.at, 0)εξακολουθεί να την αλλάζει, και κάθε καταναλωτής ενός συμβάντος μοιράζεται το ίδιοpayload. Τοevent.clonePayload()επιστρέφει ένα νέο παγωμένο αντίγραφο ανά κλήση όταν ένας καταναλωτής χρειάζεται το δικό του. - Όχι μορφή μεταφοράς (transport format): στείλτε ένα ρητό, serializable μήνυμα κατασκευασμένο από τα πεδία που χρειάζεστε.
Το deepCloneAndFreeze(value) είναι η συνάρτηση πίσω από το payload, χρησιμοποιήσιμη και αυτόνομα. Διαχειρίζεται αντικείμενα, πίνακες, Date, Map, Set, RegExp και κυκλικές αναφορές.
Commands και δημοσίευση συμβάντων
Ενότητα με τίτλο «Commands και δημοσίευση συμβάντων »Τα BaseCommand και BaseQuery είναι απλές βασικές κλάσεις για αντικείμενα command και query. Το BaseCommand διατηρεί ένα προαιρετικό sessionPrincipal (ή sessionUser) εκτός απαρίθμησης και toJSON(), ώστε να μην φτάνει ποτέ σε αποτύπωμα (fingerprint) ή log. Το getUpdateFields(fields) επιστρέφει τα αναφερόμενα πεδία που φέρει το command (το null υπολογίζεται, το undefined όχι), για εξουσιοδότηση σε επίπεδο πεδίου.
Το CommandBaseHandler εκτελεί ένα command και δημοσιεύει τα συμβάντα του aggregate που επιστρέφει:
import { BaseCommand, CommandBaseHandler, type IDomainEventPublisher, type IWriteSideAggregateRepository,} from '@cqrs-ddd/core/application';import { EntityNotFoundException } from '@cqrs-ddd/core/domain';
export class UpdateUserCommand extends BaseCommand { constructor( readonly id: string, readonly username?: string, readonly department?: string | null, ) { super(); }}
export class UpdateUserHandler extends CommandBaseHandler<UpdateUserCommand, User> { constructor( private readonly users: IWriteSideAggregateRepository<User>, eventBus: IDomainEventPublisher, ) { super(eventBus); }
async handle(command: UpdateUserCommand): Promise<User> { const user = await this.users.findById(command.id); if (!user) throw new EntityNotFoundException('User', command.id); user.update({ username: command.username, department: command.department }); await this.users.save(user); return user; }}
const handler = new UpdateUserHandler(users, { publishAll: async (events) => events.forEach((event) => emitter.emit('event', event)),});await handler.execute(new UpdateUserCommand(id, 'bob'));- Το
handle()επιστρέφει το aggregate, ή ένα αποτέλεσμα που το περιέχει ωςaggregate· οποιοδήποτεIAggregateRootείναι αποδεκτό. Τοexecute()το καλεί, δημοσιεύει τα αποθηκευμένα στο buffer συμβάντα μία φορά μεeventBus.publishAll(events, aggregate)(το aggregate αποτελεί το dispatcher context), εκκαθαρίζει το buffer και επιστρέφει το αποτέλεσμα αμετάβλητο. - Ένα απορριφθέν
handle()δεν δημοσιεύει τίποτα. Εάν τοpublishAll()πετάξει σφάλμα, το σφάλμα διαδίδεται και τα συμβάντα παραμένουν στο buffer. - Εάν το
publishAll()επιστρέφει υπόσχεση (promise), τοexecute()την περιμένει (awaits) μετά την εκκαθάριση του buffer. Η απόρριψή της απορρίπτει το command, παρόλο που το aggregate έχει ήδη αποθηκευτεί στο persistence storage· τα συμβάντα δεν δημοσιεύονται δεύτερη φορά. - Οποιοδήποτε αντικείμενο με
publishAll(events)αποτελείIDomainEventPublisher.
Το AggregateRoot.commit() δεν δημοσιεύει τίποτα από προεπιλογή. Παραδίδει ένα αντίγραφο του buffer στο hook publishAll του ίδιου του aggregate (το apply() καλεί το publish όσο το autoCommit είναι ενεργό), το οποίο δεν κάνει τίποτα μέχρι να συνδεθεί ένας publisher, και στη συνέχεια εκκαθαρίζει το buffer. Συνεπώς, η κλήση του commit() χωρίς συνδεδεμένο publisher απορρίπτει τα συμβάντα· το ίδιο ισχύει και για το autoCommit. Αφήστε το CommandBaseHandler να δημοσιεύσει, ή διαβάστε το getUncommittedEvents() και καλέστε το uncommit() εσείς οι ίδιοι.
Το commit(dispatcherContext?) περνά το context, όπως { transaction }, στο publishAll και επιστρέφει αυτό που εκείνο επιστρέφει. Το buffer εκκαθαρίζεται μόλις επιστρέψει το publishAll, πριν διευθετηθεί ένας ασύγχρονος publisher, επομένως το await aggregate.commit() περιμένει τον publisher και λαμβάνει το σφάλμα του χωρίς κίνδυνο δεύτερης δημοσίευσης· εάν το publishAll πετάξει σφάλμα, τα συμβάντα παραμένουν στο buffer.
Write-side repositories
Ενότητα με τίτλο «Write-side repositories »Ένας command handler φορτώνει το αυθεντικό aggregate μέσω του IWriteSideAggregateRepository<TEntity>.findById(id): πρέπει να διαβάζει το πρωτεύον storage, ποτέ cache. Το AggregateRepository του @cqrs-ddd/mikro-orm το υλοποιεί για το MikroORM.
Το save() δηλώνει τον κύκλο ζωής του με το @PersistedWrite. Με το @cqrs-ddd/mikro-orm, όπου το AggregateRepository παρέχει το findById() και το this.store:
import type { ICache } from '@cqrs-ddd/core/application';import { DomainException } from '@cqrs-ddd/core/domain';import { cacheKey, PersistedWrite } from '@cqrs-ddd/core/persistence';import { AggregateRepository, type IEntityManagerSource, mapPersistenceError, optimisticUpdate,} from '@cqrs-ddd/mikro-orm';
export class UniqueEmailException extends DomainException { constructor(readonly user: User) { super('This email is already registered.'); }}
export class UpdateUserRepository extends AggregateRepository<UserSnapshot, User, UserSnapshot> { constructor(cache: ICache<UserSnapshot>, store: IEntityManagerSource) { super(cache, store, User, User.aggregateName, User.fromJSON); }
@PersistedWrite<User>({ cache: { setKey: (user) => cacheKey(User.aggregateName, { id: user.id }), invalidateKeys: (user) => [cacheKey(User.aggregateName, { email: user.email })], }, unique: { email: (user) => new UniqueEmailException(user) }, otherwise: (error, user) => mapPersistenceError(error, `updating User ${user.id}`), }) async save(user: User): Promise<UserSnapshot> { const snapshot = user.toJSON(); await optimisticUpdate( this.store.em, User, user, { username: snapshot.username, department: snapshot.department ?? null, updatedAt: snapshot.updatedAt, }, 'User', ); return snapshot; }}Το optimisticUpdate προσθέτει το version στα εγγεγραμμένα πεδία· κάθε άλλη τροποποιημένη στήλη, συμπεριλαμβανομένου του updatedAt, αναφέρεται ρητά.
Το @PersistedWrite εφαρμόζει τρεις decorators. Όταν τοποθετούνται χειροκίνητα σε στοίβα, η σειρά είναι σταθερή, από τον εξωτερικό προς τον εσωτερικό:
@Cache(options): μετά από επιτυχή εγγραφή, γράφει το επιστρεφόμενο snapshot μέσω compare-and-set (isCacheNewerεκτός αν τοisNewerορίζει διαφορετικά), και εγκαθιστά barriers για ταinvalidateKeys. Όταν τοsave()επιλύεται σεnullήundefined, εγκαθιστά barriers για ταdeleteKeys. Τα σφάλματα cache καταγράφονται στα logs και ποτέ δεν μετατρέπουν μια επιβεβαιωμένη (committed) εγγραφή σε αποτυχία.@AcknowledgePersisted({ entity: ([aggregate]) => aggregate }): προωθεί την persisted έκδοση του επιλεγμένου aggregate μόνο αφού επιτύχει η εγγραφή.@MapPersistenceErrors({ entity, unique, dialect, otherwise }): μεταφράζει μια παραβίαση μοναδικότητας (unique violation) στο δικό σας domain error. Τοuniqueέχει ως κλειδί την ιδιότητα του entity που καλύπτει ο περιορισμός ({ email: ... }), ή το δηλωμένο όνομα ενός περιορισμού πολλαπλών στηλών (MapPersistenceErrors<Args, Entity, typeof NAME>), ώστε ένα repository να μην κατονομάζει ποτέ περιορισμό ή στήλη βάσης δεδομένων. Το ποιον περιορισμό παραβίασε ένα σφάλμα αναγιγνώσκεται από το persistence dialect:options.dialect, διαφορετικά αυτό που καταχωρίστηκε με τοsetPersistenceDialect()στο composition root. Το core δεν γνωρίζει καμία βάση δεδομένων· ένας adapter όπως τοMikroOrmDialectτου@cqrs-ddd/mikro-ormυλοποιεί τοIPersistenceDialect. Μια μέθοδος που δηλώνειuniqueχωρίς διαθέσιμο dialect πετάTypeErrorπριν εκτελεστεί. Τοotherwiseμεταφράζει τα υπόλοιπα, για παράδειγμα με τοmapPersistenceErrorτου@cqrs-ddd/mikro-orm, το οποίο μετατρέπει αποτυχίες οδηγού (driver) και δικτύου που επιδέχονται επανάληψη σεTransientOperationErrorκαι διατηρεί κάθε άλλο σφάλμα αμετάβλητο.
Οι διαγραφές δεν πραγματοποιούν acknowledgment, επομένως στοιβάζουν μόνο τα @Cache και @MapPersistenceErrors, και επιλύονται σε null ώστε το @Cache να εγκαταστήσει barriers για τα deleteKeys:
import { Cache, cacheKey, MapPersistenceErrors } from '@cqrs-ddd/core/persistence';import { mapPersistenceError, optimisticDelete } from '@cqrs-ddd/mikro-orm';
export class DeleteUserRepository extends AggregateRepository<UserSnapshot, User, null> { constructor(cache: ICache<UserSnapshot>, store: IEntityManagerSource) { super(cache, store, User, User.aggregateName, User.fromJSON); }
@Cache<User, null>({ deleteKeys: (user) => [ cacheKey(User.aggregateName, { id: user.id }), cacheKey(User.aggregateName, { email: user.email }), ], }) @MapPersistenceErrors<[User], User>({ entity: ([user]) => user, otherwise: (error, user) => mapPersistenceError(error, `deleting User ${user.id}`), }) async save(user: User): Promise<null> { await optimisticDelete(this.store.em, User, user, 'User'); return null; }}Η ίδια η εγγραφή πρέπει να εξαρτάται από την έκδοση (WHERE id = ? AND version = expected) και δεν πρέπει να εκτελείται εντός εξωτερικού transaction, του οποίου η επιτυχία δεν θα σήμαινε ανθεκτικό (durable) persistence. Το @cqrs-ddd/mikro-orm παρέχει τα optimisticUpdate και optimisticDelete για αυτόν τον σκοπό.
Read-side repositories
Ενότητα με τίτλο «Read-side repositories »Ένα query repository επεκτείνει το QueryRepository και διακοσμεί το find() με το @FromCache. Ο constructor δέχεται το cache (οποιοδήποτε ICache· δείτε Το repository cache για το γιατί το @FromCache χρειάζεται ένα IVersionedCache) και την προεπιλεγμένη ενυδάτωση (hydration) του repository:
import { BaseQuery, type ICache, type IQueryOptions } from '@cqrs-ddd/core/application';import { cacheKey, FromCache, QueryRepository } from '@cqrs-ddd/core/persistence';import type { IEntityManagerSource } from '@cqrs-ddd/mikro-orm';
export class GetUserQuery extends BaseQuery { constructor( readonly id: string, options?: IQueryOptions, ) { super(options); }}
export class GetUserRepository extends QueryRepository<GetUserQuery, User | null> { constructor( cache: ICache<UserSnapshot>, private readonly store: IEntityManagerSource, ) { super(cache, { hydrateFn: (cached) => User.fromJSON(cached as UserSnapshot) }); }
@FromCache<GetUserQuery, User | null>({ keyFn: (query) => cacheKey(User.aggregateName, { id: query.id }), }) async find(query: GetUserQuery): Promise<User | null> { return this.store.em.findOne(User, { id: query.id }, query.refresh ? { refresh: true } : undefined); }}
await users.find(new GetUserQuery(id)); // may be served from the cacheawait users.find(new GetUserQuery(id, { refresh: true })); // always reads the databaseΕπιλογές @FromCache: keyFn (επιστρέψτε null για παράκαμψη του cache στη συγκεκριμένη κλήση), hydrateFn, serializeFn, ttl σε χιλιοστά του δευτερολέπτου (ms), isNewer και logger.
- Κάθε επιτυχία (hit) επανενυδατώνεται όποτε εφαρμόζεται hydrator, ώστε ένα hit και ένα miss να επιστρέφουν τον ίδιο τύπο. Το
hydrateFnτης ίδιας της μεθόδου (ήhydrateFn: null) υπερισχύει αυτού του repository· τοserializeFnακολουθεί τον ίδιο κανόνα. - Χωρίς hydrator, αποθηκεύονται στο cache μόνο απλά δεδομένα (plain data)· ένα instance κλάσης επιστρέφεται χωρίς caching.
- Αποθηκεύονται μόνο μη-nullish αποτελέσματα. Ένα barrier ή ένα αποθηκευμένο
nullυπολογίζεται ως miss. - Ένα query με
refresh: trueπαρακάμπτει το cache. - Τα σφάλματα cache διαδίδονται από τις αναγνώσεις: ένα query αποτυγχάνει αντί να κάνει εικασίες.
Το repository cache
Ενότητα με τίτλο «Το repository cache »Το @Cache λειτουργεί με οποιοδήποτε ICache (get, set, delete). Το @FromCache απαιτεί ένα IVersionedCache, το οποίο προσθέτει ένα φράγμα αναθεώρησης (revision fence):
| Μέθοδος | Συμβόλαιο |
|---|---|
readState(key) |
η κατάσταση της εγγραφής (hit, miss, expired), η τιμή και η αδιαφανής αναθεώρηση (opaque revision) |
invalidate(key) |
αποβάλλει την τιμή και προωθεί την αναθεώρηση |
tryFill(key, observedRevision, value, options?) |
γράφει μόνο αν η αναθεώρηση παραμένει observedRevision· false διαφορετικά |
Το @FromCache παρατηρεί την αναθεώρηση πριν από την ανάγνωση της βάσης δεδομένων και συμπληρώνει με το tryFill, ώστε μια ανάγνωση που ήρθε σε race condition με μια ακύρωση ή διαγραφή να μην μπορεί να επανεγγράψει ένα παλιό snapshot. Ένα απορριφθέν fill ξαναδιαβάζει το κλειδί, επιστρέφει ένα αυστηρά νεότερο snapshot εάν υπάρχει, και σε αντίθετη περίπτωση επαναλαμβάνει για περιορισμένο αριθμό φορών πριν επιστρέψει το αποτέλεσμα της βάσης χωρίς caching. Ένας adapter που υλοποιεί μόνο το ICache παρακάμπτεται από το @FromCache τόσο για αναγνώσεις όσο και για fills, με μία προειδοποίηση να καταγράφεται στα logs: δεν μπορεί να διασφαλίσει fencing σε ένα fill.
Δύο adapters υλοποιούν το IVersionedCache:
MemoryCache({ defaultTtlMs = 60_000, maxEntries = 10_000 }): εντός της διεργασίας, εγγραφές κλωνοποιημένες μέσω JSON κατά την εγγραφή και ανάγνωση, για δοκιμές και μεμονωμένη διεργασία.MikroOrmCache, στο@cqrs-ddd/mikro-orm: μία γραμμή βάσης δεδομένων ανά κλειδί, κάθε εγγραφή συνιστά compare-and-set στο δικό της transaction.
Το CacheSetOptions.isNewer(cached, incoming) επιστρέφει true όταν η cached τιμή είναι νεότερη και δεν πρέπει να αντικατασταθεί· το isCacheNewer συγκρίνει το version, έπειτα το __gen, και μετά το updatedAt. Το toCacheSnapshot μετατρέπει ένα αποτέλεσμα σε αποσυνδεδεμένο (detached) snapshot: το cache δεν αποθηκεύει ποτέ ζωντανό aggregate.
Τα mutation barriers (CacheMutationBarrier) επισημαίνουν ένα διαγραμμένο ή ακυρωμένο κλειδί για διάστημα barrierTtl, 60 δευτερόλεπτα από προεπιλογή. Επιλέξτε μέγεθος μεγαλύτερο από τη μεγαλύτερη σε διάρκεια ανάγνωση σε εξέλιξη.
Η επιλογή logger. Τα @Cache και @FromCache δέχονται logger: { warn(message) } για τις λειτουργικές προειδοποιήσεις τους, όπως μια αποτυχημένη εγγραφή cache, έναν παρακαμφθέντα adapter ή ένα λάθος συνδεδεμένο repository. Ένας NestJS Logger ή το console ταιριάζουν άριστα. Χωρίς αυτόν, οι προειδοποιήσεις κατευθύνονται στο console.warn. Ένας logger που πετά σφάλμα δεν αλλάζει ποτέ ένα αποτέλεσμα. Ένας adapter αναφέρει τις δικές του προειδοποιήσεις με τον ίδιο τρόπο μέσω των consoleCacheLogger(context) και safeWarn(logger, message).
Κλειδιά cache με tenant scope
Ενότητα με τίτλο «Κλειδιά cache με tenant scope »Τα cacheKey(resource, conditions, tenant?) και cacheKeyTemplate(template, tenant?) θέτουν namespace σε κάθε κλειδί βάσει tenant. Το tenant προέρχεται, κατά σειρά προτεραιότητας, από:
- το ρητό όρισμα
tenant: string με το tenant id, ή αντικείμενο που φέρειtenantId, όπως το context ενός αιτήματος· - για το
cacheKeyTemplate, τοtenantIdμιας πηγής context· - τον resolver που καταχωρίζει η εφαρμογή μία φορά κατά την εκκίνηση με το
setTenantResolver(fn), μια συνάρτηση που επιστρέφει το tenant του τρέχοντος request ή job· - διαφορετικά,
MissingTenantContextError.
import { AsyncLocalStorage } from 'node:async_hooks';import { setTenantResolver } from '@cqrs-ddd/core/application';
const requestTenant = new AsyncLocalStorage<string>();setTenantResolver(() => requestTenant.getStore());
// Per request or job:requestTenant.run(tenantId, () => handle(request));Δεν υπάρχει κοινόχρηστο namespace: ένα ελλείπον ή κενό tenant, ή ένας resolver που δεν επιστρέφει τίποτα, πετά σφάλμα. Μια single-tenant εγκατάσταση περνά ένα σταθερό id ή καταχωρίζει setTenantResolver(() => 'single'). Η ίδια επίλυση είναι δημόσια διαθέσιμη ως requireTenant(purpose, source?), για οποιοδήποτε άλλο κλειδί πρέπει να διαχωρίζεται ανά tenant, όπως ένα κλειδί idempotency ή rate-limit, και για οποιονδήποτε κώδικα χρειάζεται το τρέχον tenant και πρέπει να αποτυγχάνει όταν δεν υπάρχει κανένα:
import { requireTenant } from '@cqrs-ddd/core/application';
requireTenant('access token issuance'); // the resolver's tenantrequireTenant('users.create idempotency key', ctx); // ctx.tenantId, else the resolver'sΤο requireTenantId(source, purpose) είναι deprecated: δέχεται τα ίδια ορίσματα με αντίστροφη σειρά και καλεί το requireTenant.
Τα κλειδιά cacheKey έχουν τη μορφή ${tenant}:${resource}:v1:${sha256}, υπολογισμένα με hash επί μιας key-sorted σειριοποίησης του [tenant, resource, conditions]. Η μορφή είναι παγωμένη (frozen), ώστε οι αποθηκευμένες εγγραφές να παραμένουν προσπελάσιμες μεταξύ διαφορετικών εκδόσεων.
Αντιστοίχιση HTTP status
Ενότητα με τίτλο «Αντιστοίχιση HTTP status »Το domainErrorHttpStatus(error) από το /http αντιστοιχίζει τα σφάλματα αυτού του πακέτου σε απλές τιμές { statusCode, error, message }, για οποιοδήποτε HTTP framework:
| Σφάλμα | Status |
|---|---|
ConcurrencyConflictError |
409 |
EntityNotFoundException |
404 |
MissingTenantContextError |
500, με γενικό μήνυμα: ένα αίτημα χωρίς tenant συνιστά σφάλμα server |
οποιοδήποτε άλλο DomainException, συμπεριλαμβανομένου του InvalidValueException |
400 |
Επιστρέφει undefined για οτιδήποτε άλλο. Αντιστοιχίστε πρώτα τις δικές σας εξαιρέσεις, και στη συνέχεια περάστε τα υπόλοιπα σε αυτό.
Χρήση από το NestJS
Ενότητα με τίτλο «Χρήση από το NestJS »Τίποτα σε αυτό το πακέτο δεν εισάγει το NestJS· η ενσωμάτωση είναι δομική (structural).
- Το
EventBusτου NestJS CQRS διαθέτειpublishAll(events, dispatcherContext), επομένως αποτελείIDomainEventPublisher: ένας handler περνά το injected bus του στοsuper(eventBus), και το bus παραδίδει το aggregate στον ρυθμισμένο publisher του ως dispatcher context. - Το
AggregateRootικανοποιεί τοIAggregateRootτου NestJS, και έναAggregateRootτου NestJS ικανοποιεί τοIAggregateRootαυτού του πακέτου. ΤοEventPublisher.mergeObjectContext(aggregate)συνδέει ένα aggregate με τοEventBus: τοcommit()στη συνέχεια δημοσιεύει με το aggregate ως context, τοcommit({ transaction })με αυτό το context, και τα δύο επιστρέφουν το αποτέλεσμα του bus. - Το
CommandBaseHandler.execute(command)είναι η μέθοδος που καλεί το command bus του NestJS, επομένως μια κλάση διακοσμημένη με@CommandHandlerτο επεκτείνει απευθείας. - Τα
BaseCommand,BaseQueryκαι τα domain events είναι απλές κλάσεις τις οποίες το NestJS αποστέλλει όπως κάθε άλλη.
@CommandHandler(UpdateUserCommand)export class UpdateUserHandler extends CommandBaseHandler<UpdateUserCommand, User> { constructor( @Inject(USER_WRITE_REPOSITORY) private readonly users: IWriteSideAggregateRepository<User>, eventBus: EventBus, ) { super(eventBus); } // handle() as above}Η εφαρμογή γράφει την υπόλοιπη διασύνδεση (glue):
-
providers για τα repositories και το cache, για παράδειγμα ένας
useFactoryprovider που κατασκευάζει έναMikroOrmCacheαπό το@cqrs-ddd/mikro-ormυπό το tokenCACHE_TOKEN:{ provide: CACHE_TOKEN, useValue: new MemoryCache({ defaultTtlMs: 30_000 }) } -
τον tenant resolver, καταχωρισμένο μία φορά πριν οποιοδήποτε lifecycle hook μπορέσει να ξεκινήσει εργασία που τον διαβάζει, για παράδειγμα στον constructor ενός module·
-
ένα exception filter που αντιστοιχίζει τα δικά του σφάλματα και στη συνέχεια καλεί το
domainErrorHttpStatus· -
έναν
loggerγια τους decorators cache, όπωςnew Logger('UserCache').
Μετάβαση από το ddd/core
Ενότητα με τίτλο «Μετάβαση από το ddd/core »Το μη δημοσιευμένο πακέτο workspace @nestjs-pipeline/ddd-core (φάκελος ddd/core) αντιστοιχίζεται σε αυτό το πακέτο ως εξής. Εξαρτιόταν από το NestJS και το MikroORM· αυτό το πακέτο δεν εξαρτάται από κανένα από τα δύο, και τα μέρη του MikroORM βρίσκονται στο @cqrs-ddd/mikro-orm.
ddd/core |
@cqrs-ddd/core |
|---|---|
import { … } from '@nestjs-pipeline/ddd-core' |
τα entry points επιπέδων: @cqrs-ddd/core/domain, /application, /persistence, /http |
@Mutate() σε μέθοδο μετάλλαξης, η οποία καλούσε το onUpdate() |
@ApplyMutation({ event }), το οποίο καταγράφει επίσης το event, καθώς και πεδία @Mutable γραμμένα μέσω του applyPatch() |
DomainOutcome, RootDomainOutcome που επιστρέφονταν από το handle() |
το handle() επιστρέφει το aggregate, ή αποτέλεσμα με ιδιότητα aggregate· τα καταγεγραμμένα συμβάντα του δημοσιεύονται |
CommandBaseHandler(eventBus: EventBus) από το @nestjs/cqrs |
CommandBaseHandler(eventBus: IDomainEventPublisher)· ένα NestJS EventBus εξακολουθεί να ταιριάζει |
CacheableEntity, ICacheKey, entity.cacheKey (prefix + id) |
RootEntity με στατικό aggregateName, κλειδιά κατασκευασμένα με cacheKey(User.aggregateName, { id }), πάντα με tenant scope |
CacheableEntity.fromStringify(data, fromJSON) |
RootEntity.from(value) ή το fromJSON του ίδιου του aggregate |
ICommandRepository.save(domainOutcome) |
ICommandRepository.save(entity), και IWriteSideAggregateRepository.findById(id) για φόρτωση |
@Cache(setKeyFn, deleteKeysFn) |
@Cache({ setKey, deleteKeys, invalidateKeys, ttl, isNewer, barrierTtl, logger }), συνήθως μέσω του @PersistedWrite |
@FromCache(keyFn, hydrateFn), ενυδάτωση όταν ορίζεται το query.hydrate |
@FromCache({ keyFn, hydrateFn, … }) με ένα IVersionedCache· τα hits επανενυδατώνονται πάντα όταν εφαρμόζεται hydrator |
QueryRepository(cache) |
QueryRepository(cache, { hydrateFn, serializeFn? }) |
ICache στο persistence/cache.interface |
ICache και IVersionedCache στο @cqrs-ddd/core/application |
UnixTimestampType |
UnixTimestampType στο @cqrs-ddd/mikro-orm |
RootEntity με αφηρημένο (abstract) afterUpdate() |
το afterUpdate() είναι προαιρετικό hook· το RootEntity επεκτείνει το AggregateRoot και προσθέτει version, getExpectedVersion(), το buffer συμβάντων και ιδιωτικούς hydration setters |
Τα παλιά imports και τα νέα δίπλα-δίπλα:
import { CacheableEntity, CommandBaseHandler, Mutate, RootDomainOutcome } from '@nestjs-pipeline/ddd-core';
// @cqrs-ddd/coreimport { ApplyMutation, Mutable, RootEntity } from '@cqrs-ddd/core/domain';import { CommandBaseHandler } from '@cqrs-ddd/core/application';import { cacheKey, PersistedWrite } from '@cqrs-ddd/core/persistence';import { AggregateRepository, optimisticUpdate, UnixTimestampType } from '@cqrs-ddd/mikro-orm';Γνωστοί περιορισμοί
Ενότητα με τίτλο «Γνωστοί περιορισμοί »- Το persistence και η δημοσίευση συμβάντων δεν είναι ατομικά (atomic). Μια κατάρρευση μεταξύ της εγγραφής και του
publishAll()χάνει τα συμβάντα· η ανθεκτική παράδοση απαιτεί transactional outbox. - Η συντήρηση του cache μετά από commit γίνεται με προσπάθεια βέλτιστης απόδοσης (best-effort). Εάν μια ακύρωση αποτύχει, η προηγούμενη εγγραφή παραμένει μέχρι να λήξει: το revision fence συντονίζει το cache με τον εαυτό του, όχι με τη βάση δεδομένων. Διαβάστε με
{ refresh: true }όπου μια απόφαση δεν πρέπει να βασίζεται σε cached τιμή. - Ένα mutation barrier προστατεύει μόνο για διάστημα
barrierTtl. Αποτελεί ένα περιορισμένο παράθυρο ανταγωνισμού (race window), όχι tombstone. - Τα βοηθητικά εργαλεία persistence απορρίπτουν εξωτερικά transactions· οι decorators δεν μπορούν να καταστήσουν πολλαπλές εγγραφές ατομικές. Μια γραμμή που πρέπει να γίνει commit μαζί με το aggregate, όπως μια εγγραφή audit ή ένα μήνυμα outbox, συνεπώς δεν μπορεί να μοιραστεί το transaction του ακόμη: αυτό απαιτεί commit hooks που εκτελούν acknowledgment και εργασίες cache μετά το commit.
- Το
@MapPersistenceErrorsαντιστοιχίζει μια παραβίαση μοναδικότητας μόνο στον βαθμό που το καταχωρισμένο persistence dialect τη διαβάζει· τοMikroOrmDialectδιαβάζει σφάλματα PostgreSQL και SQLite. - Ο tenant resolver λειτουργεί σε επίπεδο διεργασίας: ένας ανά διεργασία, για κάθε εγκατεστημένο αντίγραφο αυτού του πακέτου.
- Τα payloads συμβάντων είναι παγωμένα μόνο για συνήθη πρόσβαση· δείτε Domain events.
Άδεια χρήσης
Ενότητα με τίτλο «Άδεια χρήσης »Διπλή άδεια υπό AGPL-3.0-or-later ή Commercial License. Δείτε τα LICENSE και COMMERCIAL_LICENSE.txt στη ρίζα του repository.