Συμβατότητα της σύμβασης API

Γιατί Συμβατότητα σύμβασης

Συμβατότητα των συμβάσεων είναι η ικανότητα ενός ΑΡΙ να εξελίσσεται χωρίς να παραβιάζει υφιστάμενες ενοποιήσεις. Στα αναπτυσσόμενα συστήματα, οι API αλλάζουν συχνότερα από τον κώδικα πελατών. η συμβατότητα σας επιτρέπει να απελευθερώσετε χαρακτηριστικά επαναληπτικά, χωρίς να οργανώσετε «μεγάλες κινήσεις».

Η βασική ιδέα: η σύμβαση είναι πρωταρχικής σημασίας, οι αλλαγές πραγματοποιούνται σύμφωνα με τους κανόνες συμβατότητας και ελέγχονται αυτόματα.

Βασικές έννοιες

Σύμβαση - τυπική προδιαγραφή διεπαφής: πόροι/μέθοδοι/γεγονότα, σχήματα δεδομένων, κωδικοί σφάλματος, όρια, SLA, απαιτήσεις ασφαλείας.
Πάροχος - Ο ιδιοκτήτης του API. Καταναλωτής - Πελάτης/Ολοκλήρωση.

Συμβατότητα:

Οπισθοδρόμηση: Ο νέος προμηθευτής συνεργάζεται με τους παλαιούς καταναλωτές.
Μελλοντικά: Ο παλαιός προμηθευτής συνεργάζεται με νέους καταναλωτές (συνήθως επιτυγχάνεται με «ανεκτικούς αναγνώστες»).
Πλήρης: τόσο προς τα πίσω όσο και προς τα εμπρός (η ισχυρότερη επιλογή).
Προσθετικότητα - προσθήκη προαιρετικών στοιχείων χωρίς θραύση υφιστάμενων.

Πολιτική έκδοσης

Σημασιολογική έκδοση (συνιστάται):

MAJOR - αλλαγές θραύσης (μόνο όταν κυκλοφορεί νέα γραμμή API: '/v2 ',' υπηρεσία. v2 ').
MINOR - αλλαγές προσθέτων (νέα προαιρετικά πεδία/μέθοδοι).
PATCH - διορθώσεις χωρίς αλλαγή της σύμβασης.
Πολιτική απόρριψης: δήλωση παρωχημένων στοιχείων, παράθυρο υποστήριξης (ηλιοβασίλεμα), προειδοποιήσεις σε κεφαλίδες/μεταδεδομένα, σχέδιο απόσυρσης.

Ασφαλείς έναντι επικίνδυνων αλλαγών

Ασφαλής (συνήθως συμβατή προς τα πίσω)

Προσθήκη ενός προαιρετικού πεδίου στο JSON/Protobuf/Avro.
Προσθήκη νέου τελικού σημείου/μεθόδου/συμβάντος.
Επέκταση της ενότητας με νέες αξίες εάν οι καταναλωτές είναι ανεκτικοί σε άγνωστες αξίες.
Αύξηση των ορίων (για παράδειγμα, «maxPieces») χωρίς να καταστούν αυστηρότερα τα ελάχιστα.
Προσθήκη ακυρώσιμων με σωστές προεπιλογές.
Επεξεργασία περιγραφής/παραδείγματος κειμένου.

Επικίνδυνο (θραύσματα συμβατότητας)

Μετονομασία/διαγραφή πεδίων, αλλαγή τύπου ή υποχρεωτική.
Αλλαγή σημασιολογίας κατάστασης/σφάλματος (για παράδειγμα, ήταν '200', έγινε '204' ή '404').
Αλλαγή της μορφής των αναγνωριστικών (UUID → int).
Αυστηρότερη επικύρωση (αυστηρότερα ελάχιστα/πρότυπα) χωρίς έκδοση.
Αλλαγή της σειράς και της δομής σε ροές/γεγονότα gRPC.
Επαναχρησιμοποίηση αριθμών ετικετών στο Protobuf για νέα πεδία.

Διαλειτουργικότητα ανά στυλ αλληλεπίδρασης

REST/HTTP + JSON Schema

Προσθετικότητα: χαρακτηρίζουμε τα νέα πεδία ως «προαιρετικά »/« ακυρώσιμα».
Ανεκτικός αναγνώστης στον πελάτη: αγνοήστε άγνωστα πεδία. δεν βασίζεται στην τάξη.
Έκδοση: μείζονος σημασίας - καθ "οδόν ('/v2 ') ή στον τύπο πολυμέσων (' εφαρμογή/vnd. παράδειγμα. v2 + json ').
ETag/If-Match: για ασφαλείς επικαιροποιήσεις χωρίς αγώνες.
Σφάλματα: ενιαία μορφή ('type', 'code', 'title', 'detail', 'trace _ id'), δεν αλλάζουν την τιμή του 'code' χωρίς major.
Pagination: Οι δρομείς είναι προτιμότεροι από την αντιστάθμιση. προσθέστε πεδία 'next _ cursor', μην αλλάξετε την έννοια των υφιστάμενων.

gRPC/Protobuf

Η αρίθμηση ετικετών παραμένει αμετάβλητη. Οι διαγραμμένες ετικέτες δεν μπορούν να επαναχρησιμοποιηθούν.
Τα νέα πεδία είναι 'προαιρετικά '/' επαναλαμβανόμενα' με εύλογες προεπιλογές στον εξυπηρετητή.
Μη αλλάξετε τη σειρά και τα υποχρεωτικά μηνύματα στο streaming-RPC.
Οι καταστάσεις σφάλματος είναι σταθερές ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION' κ.λπ.), νέα σημασιολογία → μια νέα έκδοση της μεθόδου/υπηρεσίας.

Οδηγούμενο από συμβάντα (Kafka/NATS/Pulsar) + Avro/JSON Schema

Ονοματοδοσία γεγονότων: 'domain. δράση. v {major} '.
Τα νέα πεδία είναι προαιρετικά. απομονώνεται ο πυρήνας και ο εμπλουτισμός («.εμπλουτισμένος»).
Μητρώα Schema: κανόνες συμβατότητας (BACKWARD/FORWARD/FULL) για το θέμα/γεγονός.
Η επέκταση του enum ισχύει για τον αναγνώστη ανοχής από την πλευρά του καταναλωτή.
Αλλαγή κλειδιού κατάτμησης/σειράς για το σύνολο = μεταβολές θραύσης.

GraphQL

Η προσθήκη πεδίων/τύπων είναι ασφαλής. διαγραφή/μετονομασία - μόνο μέσω του @ detrected και του παραθύρου μετάβασης.
Μην αλλάζετε τύπους/μη εκμηδενίσιμους χωρίς μείζονα ανάγκη.
Πολυπλοκότητα/βάθος ελέγχου - τα όρια αποτελούν μέρος της σύμβασης.

Πρότυπα βιώσιμης εξέλιξης

Πρώτη προσθήκη: Να επεκταθεί χωρίς θραύση.
Διαπραγμάτευση δυνατοτήτων: οι πελάτες αναφέρουν ότι υποστηρίζουν (κεφαλίδες/παράμετροι/συμφωνίες), ο εξυπηρετητής προσαρμόζεται.
Όρια σύμβασης: Καθορισμός MGC (σύμβαση ελάχιστης εγγύησης) και χωριστές επεκτάσεις (μοντέλο αντίστροφης πυραμίδας).
Ανοχή εξ ορισμού: οι πελάτες αγνοούν τις περιττές και ορθά χειρίζονται άγνωστες τιμές enum (εφεδρικό).
Διπλή γραφή/διπλή εκπομπή: για σημαντικές αλλαγές, απελευθέρωση 'v1' και 'v2' παράλληλα για λίγο.
Κεφαλίδες ηλιοβασίλεμα/Γεγονότα: Ειδοποίηση εκ των προτέρων κατά την αφαίρεση των εκδόσεων.

Διακυβέρνηση και αυτοματοποίηση

API Linters:

OpenAPI/Spectral: ονομασία, σελιδοποίηση, κωδικοί σφάλματος, μορφότυποι πεδίου.
Buf/Protobuf: απαγόρευση επαναχρησιμοποίησης ετικετών, συμβολισμού πακέτων.
Μητρώο AsyncAPI/Schema: συμβατότητα σχήματος επιπέδου CI.
Κατάλογος συμβάσεων (SSOT): Κεντρικό σύστημα/μητρώο έκδοσης με διάχυτο ιστορικό.
Συντεχνία API: Συντεχνία/επιτροπή που εγκρίνει κανόνες, πρότυπα και αλλαγές επανεξέτασης.
Διαχείριση αλλαγών: RFC/ADR, σημειώσεις απελευθέρωσης, οδηγοί μετανάστευσης.

Έλεγχος συμβατότητας

Schema-diff σε CI: μπλοκάρει κέικ θραύσης (OpenAPI-diff, Buf breaking, SR συμβατότητα).
Συμβάσεις με γνώμονα τον καταναλωτή (ΚΕΕΛΠΝΟ): Σύμφωνο/Παρόμοιο - Προμηθευτής έναντι Συμβάσεων που αφορούν ειδικά τον καταναλωτή.
Χρυσά δείγματα: ερωτήματα αναφοράς/απαντήσεις και γεγονότα για παλινδρόμηση.
Κανάριος: κυλώντας στο μερίδιο της κυκλοφορίας/μεμονωμένες ομάδες καταναλωτών.
Χάος/καθυστέρηση: Timeout/Retray check - Μια αλλαγή καθυστέρησης-SLO θεωρείται αλλαγή σύμβασης.

Μετανάστευση και υποτίμηση

1. Σημειώστε το αντικείμενο, προσδιορίστε τον όρο ηλιοβασίλεμα και την εναλλακτική λύση.
2. Διατήρηση της περιόδου συμβατότητας: διπλή γραφή/διπλή εκπομπή, γέφυρες, προσαρμογείς.

3. Συλλογή τηλεμετρίας: ποιος άλλος χρησιμοποιεί το παλιό

4. Επικοινωνία: ταχυδρομικές αποστολές, σημειώσεις απελευθέρωσης, περίπτερα δοκιμής.
5. Αφαίρεση: μετά τη λήξη του παραθύρου - αφαίρεση με σταθερή απελευθέρωση.

Παραδείγματα αλλαγών

REST

Ήταν:

json
{ "id":"p1", "status":"authorized" }

Έγινε (πρόσθετο, ασφαλές):

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

Οι πελάτες που αγνοούν άγνωστα πεδία δεν σπάνε.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Γεγονός

"πληρωμή. έχει εγκριθεί. v1 '(βασικό) +' πληρωμή. εμπλουτισμένος. v1 '(εμπλουτισμός). Ο κρίσιμος δρόμος που ακολουθούν οι καταναλωτές είναι ο πυρήνας και δεν εξαρτώνται από τον εμπλουτισμό.

Αντιπατερίδια

Swagger-πλύση: υπάρχει επίσημα μια προδιαγραφή, αλλά η συμπεριφορά της υπηρεσίας είναι σε αντίθεση με αυτό.
Διακοπή με stealth: αλλαγή τύπου/κατάστασης/μορφής χωρίς νέο παράθυρο έκδοσης και μετάβασης.
Ακατέργαστες εκδηλώσεις CDC ως δημόσια σύμβαση: διαρροή συστημάτων DB, αδυναμία εξέλιξης.
Σκληρός πελάτης: σταγόνες σε άγνωστα πεδία/τιμές. απουσία ανεκτικού αναγνώστη.
Επαναχρησιμοποίηση ετικετών protobuf: αθόρυβη διαφθορά δεδομένων.
Η καθυστέρηση ως «μη συμβατική»: p95 ήταν απροσδόκητα παρατεταμένη - οι καταναλωτές κατέρρευσαν σε χρονικά περιθώρια.

Κατάλογος ελέγχου συμβατότητας (πριν από τη συγχώνευση)

Αλλαγές είναι η πρόσθετη ύλη (ή η κύρια έκδοση που παρασκευάζεται).
Έλεγχοι linters/diff, οι κανόνες συμβατότητας είναι πράσινοι.
Σφάλματα/κώδικες/καταστάσεις δεν άλλαξαν σημασιολογία.
Επέκταση του Enum χωρίς απαγόρευση παλαιών τιμών. πελάτες - ανεκτικοί.
Τα όρια της MGC παραμένουν αμετάβλητα.
Επικαιροποιημένα δείγματα/τεκμηρίωση/SDK.
Για μείζονα - διπλή γραφή/σχέδιο διπλής εκπομπής, ηλιοβασίλεμα, comm-plan.
Οι δοκιμές CDC/Golden/E2E περάσει.

ΣΥΧΝΈΣ ΕΡΩΤΉΣΕΙΣ

Πώς διαφέρει η οπισθοδρόμηση από τη μελλοντική συμβατότητα

Οπισθοδρόμηση - οι νέοι διακομιστές δεν σπάνε τους παλιούς πελάτες. Προς τα εμπρός - οι νέοι πελάτες δεν σπάνε τους παλαιούς διακομιστές (μέσω ανεκτικού αναγνώστη και τακτοποιημένων αθετήσεων).

Πότε κάνετε το '/v2 '

Όταν οι αναλλοίωτες/σημασιολογικές αλλαγές, τα πεδία/μέθοδοι διαγράφονται, απαιτείται ένα νέο μοντέλο ασφαλείας - είναι ευκολότερο και πιο ειλικρινές να ξεκινήσει μια νέα γραμμή.

Μπορείτε να ζήσετε χωρίς μητρώο/χιτώνια Schema

Θεωρητικά - ναι, πρακτικά - πρόκειται για συχνές οπισθοδρόμηση και «κρυφές» αναλύσεις. Η αυτοματοποίηση αποδίδει.

Το Enum μπορεί να επεκταθεί

Ναι, εάν οι πελάτες χειρίζονται σωστά άγνωστες τιμές (οπισθοδρόμηση/αγνόηση). Διαφορετικά - μείζονος σημασίας.

Σύνολο

Η συμβατότητα των συμβάσεων είναι κανόνες + πειθαρχία + αυτοματοποίηση. Πρόσθετα σχεδιασμού, αλλαγές θραύσης έκδοσης, εφαρμογή ανεκτικού αναγνώστη, αυτόματος έλεγχος των διαφορών και του CDC. Με αυτόν τον τρόπο οι API μπορούν να εξελιχθούν γρήγορα και η ολοκλήρωση μπορεί να παραμείνει σταθερή.