@cqrs-ddd/pipeline-resilience
Πολιτικές ανοχής σφαλμάτων και αξιοπιστίας βασισμένες στο cockatiel, εφαρμοζόμενες σε δύο διακριτά αρχιτεκτονικά επίπεδα:
- Ανθεκτικότητα σε επίπεδο λειτουργίας (
ResilienceBehavior): Περιβάλλει ολόκληρους handlers ή μεμονωμένες λειτουργίες με απομόνωση retry, timeout και bulkhead. - Πολιτικές εξωτερικών εξαρτήσεων (
ResiliencePolicies): Ένα κεντρικό μητρώο επώνυμων πολιτικών ανθεκτικότητας (circuit breakers, retry, bulkhead, timeout, fallback) για κλήσεις RPC, payment APIs, database queries και εξωτερικά webhooks.
Επιβάλλει αυστηρούς ελέγχους κατά το startup προς αποφυγή επικίνδυνων επανεκτελέσεων εντολών με παρενέργειες.
Εγκατάσταση
Ενότητα με τίτλο «Εγκατάσταση»Απαιτεί Node.js 22.12 ή νεότερο. Περιλαμβάνει το cockatiel 4 ως εξάρτηση.
Δύο αρχιτεκτονικά επίπεδα
Ενότητα με τίτλο «Δύο αρχιτεκτονικά επίπεδα»Χρήση σε επίπεδο λειτουργίας (ResilienceBehavior)
Ενότητα με τίτλο «Χρήση σε επίπεδο λειτουργίας (ResilienceBehavior)»Invariants ασφαλείας & Έλεγχοι
Ενότητα με τίτλο «Invariants ασφαλείας & Έλεγχοι»Επειδή τα retries επανεκτελούν ολόκληρο το περιεχόμενο του behavior, το ResilienceBehavior επικυρώνει αυστηρούς κανόνες:
- Επιλεκτικό φίλτρο σφαλμάτων (
handle): Απαιτείται ρητή συνάρτησηhandle: (error) => booleanπου επιλέγει παροδικά σφάλματα (πτώσεις δικτύου, deadlocks). Για επανάληψη σε όλα τα σφάλματα, απαιτείταιhandleAllErrors: true. - Ασφάλεια επανάληψης σε Commands/Events (
retry.replaySafe): Commands και events μεταβάλλουν κατάσταση. Η ρύθμιση retry σε command χωρίς ρητόretry: { replaySafe: true }αποτυγχάνει κατά την εκκίνηση μεPipelineConfigurationError. - Στρατηγική Timeout (
timeout.strategy):'aggressive'(προεπιλογή): Απαντά άμεσα στον καλούντα με σφάλμα timeout ενώ ο handler συνεχίζει να εκτελείται στο background. Σε commands ή events απαιτείtimeout: { replaySafe: true }.'cooperative': Ακυρώνει τοAbortSignalαπό τοgetResilienceAbortSignal()και περιμένει τον handler να ολοκληρώσει πριν απαντήσει.
- Όχι Circuit Breakers σε Use Cases: Η δήλωση circuit breaker απευθείας σε έναν handler απορρίπτεται. Τα circuit breakers παρακολουθούν την υγεία εξωτερικών εξαρτήσεων και όχι τα εσωτερικά use cases. Δηλώνονται στο
ResiliencePolicies.
Πολιτικές εξωτερικών εξαρτήσεων (ResiliencePolicies)
Ενότητα με τίτλο «Πολιτικές εξωτερικών εξαρτήσεων (ResiliencePolicies)»Κεντρικό μητρώο επώνυμων πολιτικών για εξωτερικά συστήματα:
Όλοι οι handlers μοιράζονται την ίδια κατάσταση circuit breaker για το 'paymentGateway', προστατεύοντας τα εξωτερικά APIs από αλυσιδωτές αποτυχίες (cascading failures).
Ενσωμάτωση NestJS (@cqrs-ddd/nestjs)
Ενότητα με τίτλο «Ενσωμάτωση NestJS (@cqrs-ddd/nestjs)»Καταχωρίστε το ResiliencePolicies ως injectable provider:
Διακοσμήστε handlers με resilience():
Σειρά των επιπέδων (Layer Ordering)
Ενότητα με τίτλο «Σειρά των επιπέδων (Layer Ordering)»Το ResilienceBehavior συνθέτει τις πολιτικές με την ακόλουθη προεπιλεγμένη σειρά (από το εξωτερικό προς το εσωτερικό):
Μπορείτε να προσαρμόσετε τη σειρά μέσω της επιλογής order:
Τύποι σφαλμάτων & Guards
Ενότητα με τίτλο «Τύποι σφαλμάτων & Guards»Επανεξάγει τις κλάσεις σφαλμάτων του Cockatiel και αντίστοιχα guards:
BrokenCircuitError/isBrokenCircuitError(err): Ρίχνεται όταν μια κλήση μπλοκάρεται από ανοιχτό circuit breaker.BulkheadRejectedError/isBulkheadRejectedError(err): Ρίχνεται όταν τα όρια ταυτόχρονης εκτέλεσης και η ουρά εξαντληθούν.TaskCancelledError/isTaskCancelledError(err): Ρίχνεται όταν η εκτέλεση υπερβεί το timeout.