Έκδοση API και συμβατότητα των συμβάσεων

TL, DR

Η συμβατότητα είναι πειθαρχία, όχι τύχη. Κρατήστε μια σαφή πολιτική έκδοσης (SemVer), αλλάξτε μαθηματικά (τι «διαλείμματα», τι όχι), δοκιμές συμβάσεων, μητρώα σχημάτων και διαδικασίες Sunset. Για χρήματα και συμμόρφωση - αυστηρή REST/gRPC με vN, για UI ομαδοποιήσεις - εξελικτικό GraphQL με '@ deprecredated'. Πάντοτε: κίνηση καναρινιού, συμβατότητα προς τα πίσω ≥ έναν κύκλο απελευθέρωσης, οδηγοί μετανάστευσης, τηλεμετρία πεδίου.

1) Βασικές έννοιες και στόχοι

Συμβατό προς τα πίσω (BC): οι παλιοί πελάτες είναι κατάλληλοι για το νέο εξυπηρετητή.
Συμβατό προς τα εμπρός (FC): νέοι πελάτες είναι κατάλληλοι για τον παλαιό εξυπηρετητή (περιορισμένοι).
Συμβατότητα σύρματος: η μορφή στο «σύρμα» δεν θραυστεί (ιδιαίτερα σημαντική για το gRPC/Protobuf).
SemVer: 'MAJOR. MINOR. PATCH '- διακοπή της σύμβασης → αύξηση MAJOR.

Ο στόχος είναι να ελαχιστοποιηθούν οι διαταρακτικές αλλαγές και να παρασχεθούν προβλέψιμα παράθυρα μετανάστευσης.

2) Αλλαγή πίνακα: Τι μπορείτε και τι όχι

Είδος μεταβολής	ΑΝΆΠΑΥΣΗ	gRPC (Protobuf)	GraphQL
Προσθήκη πεδίου (απόκριση)	+ ασφαλής	+ ασφαλής (νέος αριθμός πεδίου)	+ ασφαλής
Προσθήκη προαιρετικού πεδίου (αίτηση)	εάν ο διακομιστής ανέχεται την απουσία	+ ασφαλής	+ ασφαλής
Διαγραφή πεδίου	- σπάσιμο	- εάν ξαναχρησιμοποιήσετε τον αριθμό	μετά το '@ detrected' διαγραφή μετά το παράθυρο
Μετονομασία πεδίου	- σπάσιμο	- (αλλαγή ονόματος, αριθμός φυλής)	ψευδώνυμο/δύο χρονικά πεδία
Αλλαγή τύπου/μορφότυπου	- σπάσιμο	- κατά την αλλαγή τύπου σύρματος	- εάν σπάσει το κύκλωμα
Αλλαγή κατάστασης/σημασιολογία σφάλματος	- σπάσιμο	- κωδικοί/μέρη - σύμβαση	- διαλείμματα πελατών
Αλλαγή σειράς σε Enum	κατά αξία είναι ασφαλής	εάν οι αριθμοί enum είναι σταθεροί	+ κατά όνομα ασφαλής
Νέο τελικό σημείο/μέθοδοι	+ ασφαλής	+ ασφαλής	+ ασφαλής
Αλλαγή σελιδοδεικτών/φίλτρων	προσεκτικά, προσθέστε επιλογές	+ μέσω νέων πεδίων	+ μέσω νέων επιχειρημάτων

3) Πολιτικές για διάφορα είδη API

3. 1 ΑΝΑΠΑΥΣΗ

Έκδοση σε URI ('/v1/... ") ή τομέα ('api-v1. '). Έκδοση κεφαλίδας - μόνο για εσωτερικές περιπτώσεις.
Προσθέστε, μην διαγράψετε: νέα πεδία - εντάξει, παλιά - σημειώστε ως "απενεργοποιημένο 'στο διάγραμμα και αφήστε το για τουλάχιστον έναν κύκλο.
Κατάσταση/σφάλματα: μην αλλάξετε τους κωδικούς και τη δομή. κωδικός/σφάλμα. μήνυμα/σφάλμα. λεπτομέρειες ".
Η ταυτότητα είναι αμετάβλητη: μην μετατρέπετε ένα ασφαλές «POST» με το «Idempotency-Key» σε μια «συμπεριφορικά διαφορετική» πρόκληση.

3. 2 gRPC/Protobuf

Οι αριθμοί πεδίου είναι ιεροί: μην ξαναχρησιμοποιείτε διαγραφόμενους αριθμούς, σημειώστε ως «δεσμευμένοι».
Προσθήκη μόνο νέων προαιρετικών/επαναληπτικών πεδίων. «σκληρά υποχρεωτική» - μέσω επικύρωσης, όχι «αναζωογονημένη».
Πακέτα έκδοσης: 'πληρωμές. v1 ',' πληρωμές. v2 '.
Συμβατότητα υπηρεσιών: νέα RPC → νέα μέθοδος. Δεν αλλάζουμε τη συμπεριφορά των παλαιών.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

Εξέλιξη χωρίς v2: προσθήκη πεδίων/τύπων. διαγραφή - μέσω '@ deprecated (λόγος)' με την ανακοίνωση του παραθύρου.
Επίμονα Ερωτήματα: Για τους δημόσιους πελάτες, χρησιμοποιήστε μια λευκή λίστα ερωτήσεων - είναι ευκολότερο να ελέγξετε τη συμβατότητα.
AuthZ και τηλεμετρία σε επίπεδο πεδίου: να γνωρίζετε ποια πεδία χρησιμοποιούνται στην πραγματικότητα πριν από τη διαγραφή.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 Webhooks

Έκδοση σε διαδρομή ('/webhooks/v1/πληρωμές) και φάκελο σταθερού γεγονότος ('event _ i ,' type ',' ts ',' data ').
Διατήρηση αμετάβλητων υπογραφών/NMAS. νέους αλγόριθμους - ως επιλογή με σημαία.
Επεκτάσεις - μόνο μέσω των δεδομένων των νέων πεδίων. "και" κεφαλίδες "- χωρίς διαγραφή των παλαιών.

4) Πύλη API και δρομολόγηση έκδοσης

Δρομολόγηση βασισμένη σε κανόνες: με πρόθεμα '/v1 ', με κεφαλίδα' X-Api-Version ', ανά τομέα.
Σκιά/Κανάριος: Αναλογιστείτε κάποια από την κίνηση παραγωγής στη νέα έκδοση «στις σκιές», συγκρίνετε τις απαντήσεις.
Ποσοστό/ποσοστώσεις ανά έκδοση: Προστατεύει τους ηλικιωμένους κατά τη μετάβαση.

Κεφαλίδες ηλιοβασίλεμα για REST:

'Ηλιοβασίλεμα: <ημερομηνία RFC>' - ημερομηνία λήξης έκδοσης
'Υποτίμηση: αλήθεια' - η έκδοση καθίσταται παρωχημένη
"Σύνδεσμος: , rel = «υποτίμηση» '- σχετικά με το changelog/οδηγός μετανάστευσης

Παράδειγμα (στυλ Nginx, απλοποιημένο):

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) Μητρώα και συμβάσεις

OpenAPI/JSON Schema для REST; περιγραφές Protobuf для gRPC· Μητρώο SDL для GraphQL.
Έλεγχοι CI: linters + «έλεγχος αλλαγών θραύσης» στις δημόσιες σχέσεις.
Συμβάσεις με γνώμονα τον καταναλωτή (ΚΕΕΛΠΝΟ): Δοκιμές καταναλωτών (Σύμφωνο/Αναλογικό) - προστασία από ασυνήθιστα διαλείμματα.
Changelog: αναγνώσιμο μηχάνημα (για παράδειγμα, 'CHANGELOG. md '+ σημειώσεις απελευθέρωσης στο μητρώο).

6) Εξέλιξη πεδίων: κανόνες του αντίχειρα

Ταυτότητα/κλειδιά: μην αλλάξετε τη μορφή (UUID↔int) χωρίς νέο πεδίο '_ v2' και μεταβατική περίοδο.
Χρόνος/νόμισμα: διατήρηση UTC ISO-8601/epoch και amount_minor + νόμισμα· μη κλίμακα (πένες/λεπτά).
Enum: προσθήκη τιμών - ok; Μην αλλάζετε το νόημα των παλαιών. Για REST, δώστε τιμές συμβολοσειράς, όχι ίντσες.
Πιο σταθερή με βάση τον δρομέα. δεν αλλάζουν τη σημασιολογία του δρομέα.

7) Διαδικασία εξάντλησης και «Sunset»

1. Ανακοίνωση (T-90/60): changelog, αποστολή μηνυμάτων σε συνεργάτες, τίτλοι 'Deprecation/Sunset'.
2. Διπλή περίοδος: V1 και V2 λειτουργούν παράλληλα. Το V1 είναι εξοπλισμένο με προειδοποιήσεις σε απαντήσεις/αρχεία καταγραφής.
3. Τηλεμετρία χρήσης: Ποιος άλλος αποκαλεί V1 επαφές σημείων.
4. Κατάψυξη V1: μόνο διορθώσεις σφαλμάτων/κανένα χαρακτηριστικό.
5. Έφυγε ή σελίδα μπλοκ οδηγιών μετανάστευσης.

8) Απελευθερώσεις χωρίς πόνο: στρατηγικές καθορισμού

Μπλε/πράσινο ή σταθμισμένο δρομολόγιο: 1-5-25-50-100% κυκλοφορία.
Παράθυρο συμβατότητας: τουλάχιστον 1-2 ελάσσονες κυκλοφορίες, συχνότερα 6-12 μήνες για εξωτερικούς API.
Σημαίες χαρακτηριστικών που περιλαμβάνουν νέα λογικά πεδία/κλάδους χωρίς αναβάθμιση.
Διαβάστε/γράψτε-split: πρώτα προσθέστε υποστήριξη για την ανάγνωση ενός νέου πεδίου και μετά αρχίστε να το γράφετε.

9) Δοκιμές διαλειτουργικότητας (σουίτα πρακτικής)

Χρυσές δοκιμές για απαντήσεις από παλαιότερες εκδόσεις.
Δοκιμές diff κυκλωμάτων: καμία θραύση του CI.
Η παραγωγή Replay τρέχει στη σκηνή για V2 (σκιά).
Σενάρια Back/Forward: νέος πελάτης στον παλιό διακομιστή και αντίστροφα (όπου η FC είναι έγκυρη).
Δοκιμές συμβάσεων για webhooks: επαλήθευση υπογραφής, μορφότυπου, χρόνου.

10) Μετρήσεις και SLO της διαδικασίας έκδοσης

% των πελατών της τελευταίας MINOR (στόχος ≥ 80% πριν από τη Sunset).
Σφάλματα συμβατότητας/μη διαθεσιμότητας ανά απελευθέρωση (στόχος 0).
Μερίδιο κληροδοτημένων κλήσεων (μείωση σε ηλιοβασίλεμα).
Χρόνος μετάβασης του πελάτη (διάμεσος/p95).
Δέλτα καθυστέρησης/παλινδρόμησης μεταξύ εκδόσεων (όχι χειρότερο από το βασικό).

11) Παραδείγματα αντικειμένων

OpenAPI (θραύσμα, απέλαση πεδίου):

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

Protobuf (δεσμευμένο και v2 πακέτο):

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

GraphQL (εξάντληση):

graphql type Query { payout(id: ID!): Payout }

12) Έκδοση παρακείμενων διαύλων

SDK/CLI: εξάρτηση έκδοσης SemVer + API, συμβατότητα που ορίζεται στο README.
Εκδηλώσεις/ρεύματα (WS/Kafka): έκδοση in 'envelope. έκδοση "· νέα χαρακτηριστικά - προαιρετικά· Η αφαίρεση και η συνέχιση της εργασίας είναι οι ίδιες μεταξύ των εκδόσεων.
Αναφορά/CSV: έκδοση στο όνομα/κεφαλίδα αρχείου. Προσθήκη στηλών στα δεξιά μην αλλάξετε τη σειρά/τους τύπους.

13) Διακυβέρνηση και ρόλοι

Ιδιοκτήτης συμβολαίου (ιδιοκτήτης τομέα), API Steward (κανόνες και γραμμές), διαχειριστής ελευθέρωσης (Sunset/communications).
Διαδικασία RFC για την παραβίαση αλλαγών: επιχειρηματική αιτιολόγηση, σχέδιο μετάβασης, τεχνουργήματα, ημερομηνίες.
Ενοποιημένος κατάλογος API: όπου είναι ορατά διαγράμματα, εκδόσεις, ημερολόγιο Sunset, επικοινωνία.

14) Αντι-μοτίβα

Διαλείμματα «ηρεμίας»: αλλαγή κατάστασης/σφάλματος/τύπου πεδίου χωρίς έκδοση.
Επαναχρησιμοποίηση των αριθμών protobuf - καταστρέφει την αναπαραγωγή και τους παλιούς πελάτες.
GraphQL χωρίς τηλεμετρία πεδίου - αφαίρεση αφής.
Global v2 total - megamigration αντί για point evolution.
Η έκδοση στην παράμετρο της ερώτησης για τη δημόσια API είναι ένα μη προφανές και ευάλωτο σύστημα.
Δεν υπάρχουν οδηγοί μετανάστευσης και παραδείγματα - οι εταίροι καθυστερούν, οι προθεσμίες διαταράσσονται.

15) Έκδοση της νέας έκδοσης της λίστας ελέγχου

Επικαιροποιημένο σχήμα (OpenAPI/Protobuf/SDL), περασμένα χιτώνια και έλεγχοι θραύσης.
Προστέθηκαν δοκιμές ενσωμάτωσης και συμβάσεων (CDC).
SDK/κωδικός δείγματος/οδηγός μετανάστευσης και Changelog έτοιμο.
Απερήμωση/Ηλιοβασίλεμα ενεργοποιημένη (παλιά έκδοση) + Πώς να μεταναστεύσετε σελίδα.
Canary/Shadow plan, ειδοποιήσεις και ταμπλό που συγκρίνουν μετρήσεις.
Η οπισθοδρομική συμβατότητα διατηρείται για συμφωνημένο χρονικό διάστημα.
Συμφωνήθηκε σχέδιο αναστροφής και πίνακας κινδύνου.

Περίληψη

Μια σταθερή API είναι μια διαδικασία, όχι "μια για πάντα. "Live by the rules: SemVer + add-only evolution + circuit register + contract tests + sunset procedures. Ξεχωριστά στυλ (REST/gRPC/GraphQL) και πολιτικές τους, εκδόσεις διαδρομής προς το API Gateway, ανάπτυξη καναρινιών, μέτρηση του αποτελέσματος. Με αυτόν τον τρόπο θα αποφύγετε τις «εκπλήξεις», θα επιταχύνετε την ολοκλήρωση των εταίρων και θα διατηρήσετε την προβλεψιμότητα για νομισματικούς και κρίσιμους για τη συμμόρφωση τομείς.

Έκδοση API και συμβατότητα των συμβάσεων

TL, DR

Περίληψη

Επικοινωνήστε μαζί μας

Γρήγορη επικοινωνία

Το βίντεο θα ενημερωθεί σύντομα

Αυτή τη στιγμή είμαστε πολύ απασχολημένοι με έργα