Στρατηγικές έκδοσης API

Γιατί χρειάζεται η έκδοση

Η API αλλάζει ταχύτερα από τους πελάτες. Η έκδοση σας επιτρέπει να απελευθερώσετε χαρακτηριστικά και να επεξεργαστείτε λάθη χωρίς να σπάσετε την ολοκλήρωση, ορίζει το τελετουργικό της αλλαγής και κάνει την εξέλιξη προβλέψιμη. Κλειδί: προεπιλεγμένες πρόσθετες αλλαγές, μεγάλες - μόνο για θραύση, αυτόματοι έλεγχοι συμβατότητας και στοχαστική πολιτική λήξης ισχύος.

Βασικές αρχές

1. Πρώτη προσθήκη: νέα προαιρετικά πεδία/μέθοδοι/συμβάντα - εντάξει; διαγραφές και αλλαγές νοήματος - σημαντικές.
2. MGC (σύμβαση ελάχιστης εγγύησης) είναι σταθερή· εμπλουτισμός - μέσω δυνατοτήτων/'? συμπεριλαμβάνονται = '.
3. Ανεκτικός αναγνώστης: οι πελάτες αγνοούν άγνωστα πεδία και επιβιώνουν σωστά επεκτάσεις enum.
4. Σημασιολογική έκδοση: 'MAJOR. MINOR. PATCH 'για τεχνουργήματα, SDK και εκδηλώσεις.
5. Αυτοματοποιημένο σύστημα: αλλαγές θραύσης μπλοκ με σχήμα-diff, linters και CDC.

Πού να αποθηκεύσετε την έκδοση (μηχανική διευθυνσιοδότησης)

REST/HTTP

Έκδοση URI: '/v1/orders '→ εύκολο στη διαδρομή, βολικό στις πύλες. Μείον - «επισκιάζει» την εξέλιξη των ιδεών.
Μέσα/Κεφαλίδα: 'Αποδοχή: εφαρμογή/vnd. παράδειγμα. εντολές. v1 + json '- ακριβής έλεγχος μορφής· δυσκολότερο να απομυθοποιηθεί.
Έκδοση ερωτήματος: '? api-version = 1 '- βολικό για A/B, αλλά εύκολο να χαθεί σε κρύπτες/κορμούς.
Σύσταση: URI για κύριες γραμμές + σημαίες χαρακτηριστικών/ικανοτήτων και άρνηση περιεχομένου για μικρές επεκτάσεις.

gRPC/Protobuf

Πακέτα/υπηρεσίες: "πληρωμές πακέτων. v1· PaymentsV1 εξυπηρέτησης· "- σαφείς γραμμές.
Η αρίθμηση ετικετών παραμένει αμετάβλητη. οι διαγραμμένες ετικέτες δεν μπορούν να επαναχρησιμοποιηθούν.
Νέα πεδία - «προαιρετικά», να σπάσει → νέο '.v2'.

GraphQL

Σχήμα χωρίς ρητές μεγάλες επιχειρήσεις στο URL. Εξέλιξη μέσω παραθύρων @ deprected και μετανάστευσης. Το «πραγματικό» μείζον είναι ένα νέο σύστημα τελικού σημείου.
Η πολυπλοκότητα/το βάθος του ελέγχου αποτελεί μέρος της σύμβασης.

Καθοδηγούμενη από γεγονότα (Kafka/NATS/Pulsar)

Όνομα γεγονότος: 'πληρωμή. έχει εγκριθεί. v1 'είναι η έκδοση του τύπου.
Μητρώο Schema (Avro/JSON Schema/Protobuf) με τρόπους συμβατότητας (BACKWARD/FORWARD/FULL).
Μείζων → διπλής εκπομπής «v1» και «v2» για τη μεταβατική περίοδο.

Έκδοση μοντέλου και πολιτική αλλαγής

Σημασιολογική έκδοση

MAJOR - αλλαγές διακοπής: διαγραφή/μετονομασία πεδίων, αλλαγή κλειδιών μέλους, διαφορετική έννοια της κατάστασης, αυστηρότερη επικύρωση.
MINOR - πρόσθετο: νέα προαιρετικά πεδία/τελικά σημεία/συμβάντα, νέες τιμές enum με ανεκτικό αναγνώστη.
PATCH - διορθώνει χωρίς να αλλάζει τη σύμβαση και τη σημασιολογία.

Απερήμωση & Ηλιοβασίλεμα

Ο Mark είναι απαρχαιωμένος ('Decretated: true', '@ deprected'), δημοσιεύει ημερομηνία λήξης, εναλλακτικό οδηγό και οδηγό μετανάστευσης.
Στο HTTP - κεφαλίδες 'Sunset', 'Deprecation'. σε γεγονότα - ξεχωριστή ".deprecation. ειδοποίηση ".
Χρήση τηλεμετρίας για να αποφασιστεί αν θα αφαιρεθεί.

Στρατηγικές έκδοσης κατά στυλ

ΑΝΆΠΑΥΣΗ

Κύριες γραμμές στο/v1 ,/v2.
MINOR: επέκταση σχήματος, '? πεδία = ','? συμπεριλαμβάνονται = "· ασφαλείς επεκτάσεις enum.
ETag/If-Match και idempotent POST για συνέπεια μη θραύσης.
Σφάλματα - σταθερή μορφή ('type', 'code', 'trace _ id').

gRPC

Εισαγωγή νέων υπηρεσιών/μεθόδων θραύσης: 'IndependentV2. Σύλληψη '.
Οι καταστάσεις σφάλματος και η σημασιολογία προθεσμίας αποτελούν μέρος της σύμβασης. αλλαγή → νέας μεθόδου/υπηρεσίας.
Streaming: Συμφωνήστε για την εντολή μηνυμάτων και μην την αλλάξετε σε ελάσσονα.

GraphQL

Προσθήκη πεδίων και τύπων ελεύθερα. διαγραφές - μέσω του παραθύρου «@ detrecated» + μετάβασης· μεγάλος επανασχεδιασμός → νέου συστήματος ('/graphql-v2 ').
Ενδοσκόπηση και περιγραφές - πρέπει να υπάρχουν για τη μετάβαση των πελατών.

Εκδηλώσεις

Πυρήνας εναντίον εμπλουτισμένου: ο πυρήνας είναι σταθερός, οι εμπλουτισμοί ζουν κοντά και εκδίδονται ξεχωριστά.
Η κλείδα κατάτμησης είναι αμετάβλητη εντός της κύριας γραμμής.
Μείζονες μεταναστεύσεις - «διπλή εκπομπή» + προβολή/μετανάστευση καταναλωτών.

Διαπραγμάτευση και σημαίες ικανοτήτων

Ικανότητες: ο πελάτης στέλνει τις δυνατότητες X: risk_score,price_v2'; ο εξυπηρετητής απαντά με εκτεταμένη προβολή.
Προτιμήστε (HTTP) και υποδείξεις για μερικές απαντήσεις.
Σε υποδοχές/ρεύματα - ένα μήνυμα χειραψίας με μια λίστα υποστηριζόμενων επεκτάσεων.

Απελευθέρωση σημαντικών εκδόσεων χωρίς πόνο

1. RFC/ADR: γιατί απαιτείται μείζονος σημασίας, τι σπάει, ο πίνακας κινδύνου.
2. Διπλή διαδρομή: παράλληλη εκτόξευση των «v1» και «v2» (διπλή έκδοση εκδηλώσεων, δύο διαδρομές πύλης, αντικατοπτρισμός κυκλοφορίας).
3. Προσαρμογείς μετάβασης: πληρεξούσιοι/μεταφραστές για μεγάλους πελάτες.
4. Κανάριος: ανά ομάδα πελατών/θέμα/ετικέτα στην πύλη.
5. Σχέδιο ηλιοβασίλεμα: ημερομηνίες, επικοινωνία, περίπτερα, δεδομένα δοκιμών, παρακολούθηση χρήσης.

Πλατφόρμα και ρόλοι υποδομής

API Gateway/Service Mesh: δρομολόγηση ανά έκδοση, κεφαλίδες, διαδρομές· όριο ταχύτητας и αυτόματη ανά έκδοση.
Schema Registry & Catalog: Πηγή αλήθειας για Specs/σχήματα με διάχυτη ιστορία.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Παρατήρηση: η έκδοση πρέπει να περιλαμβάνεται στα αρχεία καταγραφής/μονοπάτια/μετρήσεις.

Δοκιμή έκδοσης

Σχήμα-diff σε PR: διακοπή μπλοκ.
Συμβάσεις με γνώμονα τους καταναλωτές: Ο πάροχος δοκιμάζεται έναντι πραγματικών καταναλωτικών συμβάσεων.
Χρυσά δείγματα: Απαντήσεις αναφοράς σε εκδόσεις.
καναρίνι: σύγκριση του p95/p99, λάθη και timeouts μεταξύ των εκδόσεων.
Επανάληψη γεγονότων: οι προβλέψεις επανασυναρμολογούνται στο v2 χωρίς αποκλίσεις.

Μετανάστευση δεδομένων και βάσεων δεδομένων

Για REST/gRPC: Οι μεταναστεύσεις βάσεων δεδομένων συντονίζονται μέσω επέκτασης και σύμβασης (προσθέστε μια στήλη → αρχίστε να γράφετε → να αλλάζετε ανάγνωση → να διαγράφετε παλιά).
Για εκδηλώσεις: διπλή εκπομπή και μετανάστευση των καταναλωτών· Μερικές φορές - αναπαραγωγή του ημερολογίου σε νέες προβλέψεις.
Μην κάνετε «μεγάλες εκρήξεις» - χωρίστε σε βήματα με ανατροπές.

Σχέση ασφάλειας

Πεδία ανά έκδοση: μεμονωμένα πεδία/ρόλοι OIDC για v1/v2.
Τα μυστικά/απαιτήσεις της μάρκας αποτελούν μέρος της σύμβασης. την αλλαγή τους = μείζονα.
PII/PCI - μην επεκτείνετε το ωφέλιμο φορτίο χωρίς λόγο· νέα πεδία - με ελάχιστα προνόμια.

Αντι-μοτίβα

Swagger-wash: επικαιροποιημένη προδιαγραφή, εξυπηρετητής όχι (ή αντίστροφα).
Η επαναχρησιμοποίηση ετικετών protobuf αποτελεί αθόρυβη διαφθορά δεδομένων.
Αλλαγή νοημάτων enum χωρίς μείζονα.
Global '/v2 '«για χάρη των καλλυντικών»: μια εκδοχή χωρίς το γεγονός της διακοπής.
Ξεχασμένο ηλιοβασίλεμα/μετρήσεις χρήσης: είναι αδύνατο να αφαιρεθεί η παλιά έκδοση με ασφάλεια.
Ένα κοινό θέμα για διαφορετικούς μεγάλους: ένα μείγμα παραγγελιών και κλειδιών.

Κατάλογος ελέγχου πριν την απελευθέρωση

• Οι αλλαγές είναι πρόσθετες ύλες ή παρασκευάζεται ξεχωριστή κύρια σειρά.
• Linters και schema-diff είναι πράσινο (σπάσιμο δεν σύρθηκε).
• Επικαιροποιημένες υποσημειώσεις SDK/παραδείγματα/τεκμηρίωση, συμβατότητα.
• Ενεργοποιημένος ανεκτικός αναγνώστης σε πελάτες. δοκιμή εφεδρικής εφεδρείας.
• Για μείζονα - διπλή-τρέξιμο σχέδιο, προσαρμογείς, καναρίνι, ηλιοβασίλεμα ημερομηνίες και αλληλογραφία.
• Μετρικά/κούτσουρα/μονοπάτια περιέχουν μια έκδοση και κατάτμηση από αυτήν.
• Υπάρχει ένα περίπτερο και χρυσά σύνολα για τη σύγκριση v1↔v2.
• Για γεγονότα, το μητρώο σχήματος είναι σε λειτουργία BACKWARD/FULL, τα κλειδιά κατάτμησης είναι αμετάβλητα.

Υποδείγματα δειγμάτων

REST (URI + διαπραγμάτευση)

Οδός: '/api/v2/orders/{ id} '

• Απερήμωση: 'Ηλιοβασίλεμα: 2026-06-30', 'Σύνδεσμος: ; rel = «εναλλακτικό» '

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Εκδηλώσεις

"πληρωμή. αιχμαλωτίστηκε. v2 '(βασική) και' πληρωμή. εμπλουτισμένος. v2 '(λεπτομέρειες).
Για τη μεταβατική περίοδο, ο παραγωγός είναι «v1» και «v2».

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

Πότε ακριβώς χρειάζεται το '/v2 '

Όταν αλλάζουν αναλλοίωτα/σημασιολογία, τα πεδία/μέθοδοι αφαιρούνται, η μορφή των αναγνωριστικών, το κλειδί κατάτμησης, SLA/συγχρονισμοί αλλάζουν έτσι ώστε οι πελάτες να σπάσουν.

Μπορείτε να ζήσετε χωρίς ρητή έκδοση στο REST

Μόνο για μικρά συστήματα. Για τις εξωτερικές ενοποιήσεις, οι σαφείς κύριες γραμμές είναι καλύτερες.

Πόσο καιρό να διατηρηθεί η ξεπερασμένη εκδοχή

Εξαρτάται από το οικοσύστημα. Για τους εξωτερικούς εταίρους, συνήθως 6-12 μήνες με έγκαιρη κοινοποίηση και καναρίνι.

Πώς είναι διαφορετική η έκδοση του γεγονότος από την API

Εκδηλώσεις - μόνο στο παράρτημα· νέα σημασιολογία = νέος τύπος '.v2' και διπλή εκπομπή. Η κλείδα κατανομής αποτελεί μέρος της σύμβασης.

Αποτέλεσμα

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