Ένα παράδειγμα DDD
Τα packages/ddd-core και το παράδειγμα api επιδεικνύουν το Domain-Driven Design με το @nestjs-pipeline.
packages/ddd-core — framework-neutral υποστήριξη DDD
Ενότητα με τίτλο «packages/ddd-core — framework-neutral υποστήριξη DDD »Το πακέτο @cqrs-ddd/core δεν έχει εξάρτηση από το NestJS και παρέχει τέσσερα ρητά entry points:
/domain— δομικά στοιχεία για aggregates/events/errors·/application— βασικές CQRS κλάσεις και ports για repositories/cache·/persistence— decorators/adapters/helpers για persistence·/http— αντιστοίχιση HTTP status για τα δικά του σφάλματα.
Ο κώδικας του domain και του application επιπέδου θα πρέπει να χρησιμοποιεί τα συγκεκριμένα entry points αντί για το barrel της ρίζας συμβατότητας.
| Εξαγωγή | Επίπεδο | Περιγραφή |
|---|---|---|
RootEntity |
/domain |
Αφηρημένη βασική οντότητα με ταυτότητα UUID v7, κύκλο ζωής createdAt/updatedAt, αντιστοιχίσεις accessor, και παρακολούθηση μεταβολών (mutations) |
RootEntitySnapshot |
/domain |
Interface για σειριοποίηση/επανυδάτωση (rehydrating) οντοτήτων |
DomainException |
/domain |
Αφηρημένη βασική κλάση για framework-agnostic εξαιρέσεις αμετάβλητων κανόνων domain |
DomainEvent |
/domain |
Αφηρημένη βασική κλάση για domain events (φέρει ένα UUID v7 id) |
RootDomainEvent |
/domain |
Domain event με αποσυνδεδεμένο αμετάβλητο payload και ID/version του aggregate κατά τον χρόνο του συμβάντος |
@ApplyMutation() |
/domain |
Ολοκληρώνει μια μεταβολή domain: καλεί το onUpdate() και καταγράφει events από το αποτέλεσμα |
@Mutable() |
/domain |
Δηλώνει ένα πεδίο του aggregate ως τροποποιήσιμο μέσω του applyPatch(...) |
CommandBaseHandler |
/application |
Βασικός CQRS command handler που αποστέλλει (dispatches) και εκκαθαρίζει μη καταχωρημένα events |
ICommandRepository |
/application |
Port για repositories εγγραφής (write repositories) |
IQueryRepository |
/application |
Port για repositories ανάγνωσης (read repositories) |
ICache<T> |
/application |
Interface για cache providers (get, set, delete) |
@Cache() |
/persistence |
Decorator για το save() — write-through cache στις εγγραφές, evict στη διαγραφή, ρητά κλειδιά |
@FromCache() |
/persistence |
Decorator για το find() — read-through cache με fail-closed σημασιολογία και επανυδάτωση (hydration) |
Οι adapters του MikroORM, όπως οι AggregateRepository, MikroOrmCache και UnixTimestampType,
βρίσκονται στο @cqrs-ddd/mikro-orm.
Κάντε import τα δομικά στοιχεία domain στο επίπεδο domain σας:
import { ApplyMutation, DomainException, RootDomainEvent, RootEntity } from '@cqrs-ddd/core/domain';api — Πλήρης Λειτουργική Εφαρμογή
Ενότητα με τίτλο «api — Πλήρης Λειτουργική Εφαρμογή »Ο κατάλογος api/ περιέχει μια πλήρη λειτουργική εφαρμογή:
cd apipnpm installpnpm build # build workspace dependenciescp .env.example .env # create local environment file (edit as needed)pnpm db:migrate # apply schema + data migrations (idempotent)pnpm dev # build, then rebuild and restart on source changesΡυθμίστε τη βάση δεδομένων μέσω μεταβλητών περιβάλλοντος (προεπιλογή σε τοπικό αρχείο):
| Μεταβλητή | Προεπιλογή | Περιγραφή |
|---|---|---|
DATABASE_URL |
file:src/persistence/local.db |
libSQL URL, χρησιμοποιείται αναλλοίωτο για έναν tenant |
SQLITE_TENANTS |
(κανένα) | Πρόσθετα ονόματα libSQL tenants· τα τοπικά αρχεία λαμβάνουν επίθημα tenant |
SQLITE_DATABASE_TEMPLATE |
(κανένα) | URL που περιέχει {tenant}· απαιτείται για πολλαπλούς απομακρυσμένους tenants |
AUTH_TOKEN |
(κανένα) | Auth token για απομακρυσμένες libSQL βάσεις δεδομένων (π.χ. Turso) |
Το DB_ENGINE=postgres μεταβαίνει σε PostgreSQL με ένα schema ανά tenant· το
api README παραθέτει κάθε μεταβλητή.
Και οι δύο μηχανές persistence απαιτούν το x-tenant-schema στα δρομολογημένα αιτήματα HTTP.
Η PostgreSQL επιλέγει ένα schema· το libSQL επιλέγει την αντίστοιχη βάση δεδομένων.
Λειτουργίες CRUD:
# Log in as the seeded admin, then copy `accessToken` from the JSON response.# The refresh token arrives as an HttpOnly cookie; POST /auths/refresh exchanges it.curl -X POST http://localhost:3000/auths/login -c cookies.txt \ -H 'Content-Type: application/json' \ -H 'x-tenant-schema: tenant' \ -d '{"email":"alice+tenant@seed.local","code":"secret-code"}'export TOKEN='<accessToken from login response>'
# Create a usercurl -X POST http://localhost:3000/users \ -H 'Content-Type: application/json' \ -H 'x-tenant-schema: tenant' \ -H "Authorization: Bearer $TOKEN" \ -H 'x-correlation-id: demo-123' \ -d '{"name": "Aristotelis", "email": "aristotelis@example.com"}'
# Get all userscurl -X GET http://localhost:3000/users \ -H 'x-tenant-schema: tenant' \ -H "Authorization: Bearer $TOKEN"
# Get by IDcurl http://localhost:3000/users/<id> \ -H 'x-tenant-schema: tenant' \ -H "Authorization: Bearer $TOKEN"
# Updatecurl -X PATCH http://localhost:3000/users/<id> \ -H 'Content-Type: application/json' \ -H 'x-tenant-schema: tenant' \ -H "Authorization: Bearer $TOKEN" \ -d '{"name": "NewName"}'
# Delete a usercurl -X DELETE http://localhost:3000/users/<user-id> \ -H 'x-tenant-schema: tenant' \ -H "Authorization: Bearer $TOKEN"
# Run with Fastify adapterADAPTER=fastify pnpm startΤι επιδεικνύει:
- Καθολικά (global) + ανά handler pipeline behaviors
- Αποσυνδεδεμένες αμετάβλητες domain με framework-agnostic
DomainException& presentation-boundaryDomainExceptionFilter(αντιστοίχιση σε 400, 409, 422) - Όρια persistence repository κατά το Clean Architecture: οι CQRS handlers κάνουν inject αποκλειστικά τα
ICommandRepositoryκαιIQueryRepository, πλήρως αποσυνδεδεμένα από κλάσεις ORM/database client (μηδενική διαρροήMIKRO_ORM_CLIENTστους handlers) - Μόνιμη ανάκληση token κατά την αποσύνδεση μέσω του
RevokeAuthCommand, φόρτωση δικαιωμάτων ανά αίτημα στοCaslPermissionSource, και ρητή κατηγοριοποίηση principal - Αισιόδοξος έλεγχος ταυτοχρονισμού (optimistic concurrency) με παρακολούθηση έκδοσης aggregate στις οντότητες
UserκαιRole. Οι persistence adapters μεταφράζουν τα διαγνωστικά συγκρούσεων driver/ORM στο transport-neutralConcurrencyConflictError· το φίλτρο HTTP presentation αντιστοιχίζει αυτό το σφάλμα σε409 Conflict. - Injectable
CaslAuthorizerσε CQRS command και query handlers:authorizeπριν από εγγραφές,projectγια read models και απαντήσεις - Δηλώσεις απαιτήσεων CASL ανά handler με το
requires(...) - Πηγή δικαιωμάτων CASL βασισμένη στο MikroORM (ρόλοι, δικαιώματα και απαγορεύσεις ανά χρήστη)
- Επίσημα MikroORM entity schemas με
accessor: trueπου συνδέουν ιδιωτικά πεδία του aggregate με δημόσιους accessors χωρίς παρακάμψεις του TypeScript - Αποσυνδεδεμένη αρχιτεκτονική CQRS caching με παραγωγή κλειδιών ασφαλή από συγκρούσεις (
cacheKey), fail-fast πρότυπα handlers (cacheKeyTemplate), και στατική ονοματοδοσία aggregates (User.aggregateName) - Versioned database migrations με καταγραφή (πίνακας
mikro_orm_migrations) - Commands και queries επικυρωμένα/αναλυμένα με Zod μέσω των
createCommand()καιcreateQuery()που εκθέτουν metadata του Standard Schema (['~standard']) - Επικύρωση σχημάτων σε επίπεδο controller μέσω του προεπιλεγμένου
StandardSchemaValidationPipeτου Nest - Zod transform mappers (αντιστοίχιση DTO → Command)
- OpenTelemetry tracing με το
TraceBehaviorκαι metrics με τοMetricsBehavior - Command- και event-scoped
DeadLetterBehaviorπου αποστέλλει αποτυχημένες εκτελέσεις σε ουρά BullMQdead-lettersγια έλεγχο και επανάληψη (περιορισμένο σε αποτυχίες μεταβολής commands και events, εξαιρώντας queries ανάγνωσης και σφάλματα validation, με τοUserCreatedHandlerνα επιλέγει{ rethrow: false }μόνο μετά από επιτυχή παράδοση)· οι αποτυχίες transport καταγράφονται και διατηρούν το αρχικό σφάλμα του handler - Ανά handler
RateLimitBehaviorπου περιορίζει τοCreateUserHandlerσε 5 εγγραφές / 60s ανά email (in-memory limiter), με τοErrorFilterνα αντιστοιχίζει τις υπερβάσεις σε HTTP 429 +Retry-After - Ανά handler
AuditBehaviorπου καταγράφει την ευαίσθητη ενέργειαuser.delete(actor, αποτέλεσμα, διάρκεια, redacted payload) στο προεπιλεγμένοLogAuditSink, με τον actor να επιλύεται από το ασύγχρονο session context - Ανά handler
IdempotencyBehaviorπου αποκλείει ατομικά ταυτόχρονα αντίγραφα για τοCreateUserHandlerανά tenant + principal + email και αναπαράγει ολοκληρωμένες επιτυχείς απαντήσεις· με την προεπιλογήreleaseOnError: true, μια αποτυχημένη εκτέλεση αποδεσμεύει το κλειδί ώστε μια μετέπειτα επανάληψη να μπορέσει να εκτελεστεί ξανά. ΤοErrorFilterαντιστοιχίζει αντίγραφα εν εξελίξει σε HTTP 409 και την επαναχρησιμοποίηση κλειδιού με μη συμβατό payload σε HTTP 422 - Οντότητες
UserκαιRoleσε στυλ DDD δομημένες πάνω στα primitives τουddd-core(RootEntity,RootDomainEvent) - Persistence με MikroORM (libSQL και PostgreSQL drivers) με απομόνωση βάσης δεδομένων/σχήματος ανά multi-tenant
- Συνδέσιμο
ICache<T>—MikroOrmCache(βασισμένο στο MikroORM, με επίγνωση TTL) ήMemoryCacheεναλλάξιμο μέσω ενός ενιαίου provider token - Διάδοση του Correlation ID σε HTTP middleware, handlers, processors, και events
- Υποστήριξη Express και Fastify adapters με ασφαλές session cookie και Bearer/API-key αυθεντικοποίηση