Συμβατότητα και επικαιροποιήσεις API
1) Θεμελιώδεις αρχές συμβατότητας
Πρώτη προσθήκη: προσθήκη νέων χωρίς διακοπή (νέα προαιρετικά πεδία/τελικά σημεία, νέες τιμές enum).
Συμβάσεις σταθερότητας: «ό, τι υπόσχεται η συγγραφή υποχρεώσεων·» τεκμηριωμένη συμπεριφορά.
Οπίσθια> Εμπρός: προτεραιότητα στη συμβατότητα προς τα πίσω. προς τα εμπρός επιτρέπεται μέσω ανεκτικών αναγνωστών.
Τα έγγραφα είναι πρωταρχικά: η μόνη πηγή αλήθειας είναι η έκδοση μητρώου του συστήματος (OpenAPI/AsyncAPI/Proto).
Ρητή εξέλιξη: ρήξη - μόνο μέσω μιας νέας σημαντικής έκδοσης και ενός οδηγού μετανάστευσης.
2) Ταξινόμηση μεταβολών
2. 1 Συμβατό (MINOR/PATCH)
Προσθήκη προαιρετικών πεδίων/κεφαλίδων, νέων τελικών σημείων, παραμέτρων ερωτήσεων με προεπιλογές.
Αύξηση ορίων ('page _ size', TTL), αποσαφήνιση σφαλμάτων χωρίς αλλαγή κωδικών/σημασιολογίας.
Προσθήκη τιμών enum αν οι πελάτες αγνοούν το «άγνωστο» (ανεκτικό αναγνώστη).
2. 2 Διφορούμενη (Συμπεριφορική)
Αλλάζοντας τις αθετήσεις, τη σειρά διαλογής, τα λεπτά χρονοδιαγράμματα, τις ποσοστώσεις - μπορούν να «σπάσουν» την επιχειρηματική λογική. Απαιτεί ανακοίνωση RFC + και καναρίνια.
2. 3 Θραύση (MAJOR)
Μετονομασία/διαγραφή πεδίων, αλλαγή τύπου/μορφότυπου, αντικατάσταση κωδικών σφάλματος, αντίστροφη ασυμβατότητα των συμβάσεων/συστημάτων επαλήθευσης ταυτότητας.
3) Πολιτική έκδοσης
Στρατηγική: 'έκδοση διαδρομής' ('/v1 ', '/v2').
Ελάσσονος σημασίας/έμπλαστρο: «προσθέστε, μην σπάσετε».
Χρονολογημένες κεφαλίδες (προαιρετικά): «X-API-Version-Date» για ήπιες στοιχειώδεις αλλαγές.
Τύποι μέσων (Op.): 'Αποδοχή: εφαρμογή/vnd. acme. v1 + json 'για λεπτή κοκκοποίηση.
4) Υποβαθμίσεις και ηλιοβασίλεμα
4. 1 Κεφαλίδες επικοινωνίας
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Εντολή ανάκλησης
1. Ανακοίνωση στη λίστα πύλης/αλληλογραφίας/σημειώσεις έκδοσης SDK.
2. Το προειδοποιητικό παράθυρο ≥ 90-180 ημέρες.
3. Κατάσταση στο ταμπλό υιοθεσίας.
4. Μετά το ηλιοβασίλεμα - 410 Gone ή «read-only» mode για την περίοδο χάριτος, εάν συμφωνηθεί.
5) Μετανάστευση και συνύπαρξη εκδόσεων
Διπλή γραφή/διπλή ανάγνωση σε μεταβατικό στάδιο και συμφιλίωση με αναφορές.
Προσαρμογείς (προσωρινοί): μετατροπές πύλης παλαιού ωφέλιμου φορτίου → νέα συστήματα. η διάρκεια ζωής του προσαρμογέα είναι περιορισμένη.
SDK βοήθεια: κυκλοφορίες που υποστηρίζουν και τις δύο εκδόσεις, με προειδοποιήσεις μείωσης (1 φορά ανά διαδικασία).
Σημαίες χαρακτηριστικών: συμπερίληψη νέας σημασιολογίας σύμφωνα με τον κατάλογο κλειδιών/ενοικιαστών.
6) Οπισθοδρόμηση και συμβατότητα προς τα εμπρός
6. 1 Οπισθοδρόμηση (παλαιοί πελάτες ↔ νέος διακομιστής)
Μη αλλάξετε μορφότυπο τύπου/υποχρεωτικό.
Τα νέα πεδία είναι μόνο προαιρετικά.
Σφάλματα - παλαιός 'error _ code', προσθήκη νέων κωδικών, μη αντικατασταθούν.
6. 2 Προς τα εμπρός (νέοι πελάτες ↔ παλαιός εξυπηρετητής)
Έλεγχος ικανοτήτων μέσω 'ΕΠΙΛΟΓΩΝ '/'/εκδόσεων'.
Συμπεριφορά χάριτος: Ο πελάτης πρέπει να είναι ανεκτικός στα ελλείποντα χαρακτηριστικά.
7) Συμβάσεις και αυτόματοι έλεγχοι
Μητρώο: αποθήκευση εκδόσεων σχημάτων· Ανασκαφές δημοσίων σχέσεων - αποσπασματικές/μη σπασμωδικές αναφορές.
Linter: ονόματα/τύποι, idempotency, pagination, stable codes.
CDC (Συμβάσεις με γνώμονα τον καταναλωτή): Δοκιμές Integrator στο CI του προμηθευτή (Σύμφωνο και αναλογικά).
Πύλη: Οι δημόσιες σχέσεις μπλοκάρονται όταν σπάνε χωρίς ένα 'major bump '/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Επέκταση των καναρινιών και αντίστροφη
Κανάριος: 10% → 25% → 50% → 100% της κυκλοφορίας. auto-rollback στην αποικοδόμηση SLO (5xx/latency/429).
Κλειδιά βήτα: πρόσβαση σε νέες εκδόσεις μέσω του καταλόγου επιλογών.
Πάγωμα απελευθέρωσης: προϋπολογισμός σφάλματος κατά την καύση.
Ανάλυση αποδοχής: μερίδιο κίνησης/πελατών στη νέα έκδοση, χρόνος μετάβασης.
9) Λεπτομερής συμβατότητα: σφάλματα, επισήμανση, ταυτότητα
9. 1 Σφάλματα
Μη αλλάξετε τις καταστάσεις HTTP στα υπάρχοντα σενάρια.
'error _ code' - σταθερή, προστίθενται μόνο νέοι κωδικοί.
'application/problem + json' is a single format.
9. 2 Pagination
Μετάβαση σε δρομέα/πληκτρολόγιο = MINOR αν υποστηρίζεται το παλιό 'offset/όριο'.
Τεκμηρίωση του είδους «(updated_at,id)» και σταθερότητα δρομέα.
9. 3 Ιδιαιτερότητα
Για γραφή - 'Idempotency-Key' + '409 IDEMP_REPLAY' σε περίπτωση σύγκρουσης.
Οι μεταναστεύσεις δεν πρέπει να αλλάζουν τη σημασιολογία της ιδεότητας.
10) Μετασχηματισμοί πύλης (κατά περίπτωση)
Χαρτογράφηση πεδίων, ομαλοποίηση σφαλμάτων, μετατροπή μορφών ημερομηνίας/χρήματος.
Φρουρά: οι μετασχηματισμοί είναι διαφανείς και αξιοσημείωτες. να μην αποκρύπτεται το σπάσιμο, αλλά να χρησιμοποιείται ως χρονικά περιορισμένη γέφυρα.
11) Επικοινωνίες και δικτυακή πύλη
Changelog с датами ('προστέθηκε/άλλαξε/απενεργοποιήθηκε/αφαιρέθηκε/σταθεροποιήθηκε').
Κάρτα έκδοσης: κατάσταση (beta/GA/υποτιμημένη), ημερομηνία λήξης, σύνδεσμοι με οδηγούς.
Κοινοποίηση webhooks: 'υποτίμηση. ανακοίνωση ',' έκδοση. απελευθερώθηκε ',' σχέδιο. αλλαγή ".
Σημειώσεις κυκλοφορίας SDK + πανό πύλης.
12) Μετρήσεις επιτυχίας
Ποσοστό υιοθέτησης v2 (ανά αίτηση/πελάτη).
Περιστατικά οπισθοπορείας.
Σφάλμα ανάμειξης (4xx/5xx/429 μετοχές) πριν/μετά την έκδοση.
Χρόνος για την υιοθέτηση της διάμεσης τιμής.
Φορτίο υποστήριξης (εισιτήρια/εβδομάδα).
Κόστος προς εξυπηρέτηση.
13) Υποδείγματα και παραδείγματα
13. 1 Τίτλοι και αποσβέσεις έκδοσης
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Πολιτική έκδοσης (τμήμα YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. OpenAPI Field Append Συμβατό
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Κατάλογος αποδέσμευσης (MINOR/MAJOR)
ΕΛΑΧΙΣΤΕΣ
- DIFF: μη θραύση, πράσινη επένδυση
- Επικαιροποιημένη τεκμηρίωση/SDK (παραδείγματα/κώδικες)
- Canary + auto-SLO rollback
- Σχέδιο Comm, Σελίδα πύλης
- Υιοθέτηση πινάκων διαχείρισης και σφαλμάτων
MAJOR
- RFC/ADR, ημερομηνία λήξης και παράθυρο ≥90 -180 ημέρες
- v1↔v2 γέφυρα και οδηγός μετανάστευσης
- Διπλή γραφή/ανάγνωση και συμφιλίωση
- SDK με αμφότερες τις καταχωρίσεις API +
- Χειριστής με βασικούς ενσωματωτές
15) Σχέδιο εφαρμογής (3 επαναλήψεις)
1. Ίδρυμα (2 εβδομάδες):
Μητρώο συστημάτων, χιτωνίων και αυτόματου κατακερματισμού στον ΚΚΠ. Πολιτική συμβατότητας Τίτλοι 'Deprecation/Sunset'.
2. Ελεγχόμενες κυκλοφορίες (3-4 εβδομάδες):
Κανάριοι Νήσοι, σημαίες, καταχωρίσεις SLO· πύλη έκδοσης· Το SDK απελευθερώνεται με υποστήριξη για 2 υποκαταστήματα.
3. Αυτοματοποίηση και κλίμακα (συνεχής):
Δοκιμές CDC των καταναλωτών στο CI, πρόβλεψη λήξης ισχύος σχετικά με τις τάσεις υιοθεσίας, αυτόματες κοινοποιήσεις και υπενθυμίσεις.
16) Mini-FAQ
Μπορώ να αλλάξω τον τύπο πεδίου χωρίς τυφλό
Όχι, δεν είναι. Ακόμα και το «stroka→chislo» σπάει. Εισάγετε ένα νέο πεδίο, το παλιό είναι υποτιμημένο.
Enum: μπορείτε να προσθέσετε τιμές
Ναι, αν οι πελάτες είναι ανεκτικοί αναγνώστες. Διαφορετικά - πρώτα συναγερμός και βήτα.
Πόσο να κρατήσει την παλιά έκδοση
Μέχρι στιγμής, η υιοθέτηση του νέου ≥95% έχει διατηρηθεί. Ορίστε την προθεσμία στην πολιτική.
Σύνολο
Η συμβατότητα των API είναι μια πειθαρχία: προσθετική προσέγγιση, επίσημα συστήματα και δίφια, απελευθέρωση καναρινιών, σαφείς μειώσεις και διαχείριση των μεταναστεύσεων. Εδραίωση πολιτικών αλλαγής, αυτοματοποιημένοι έλεγχοι και επικοινωνίες, υιοθέτηση μέτρων - και επικαιροποιήσεις σας θα σταματήσουν να σπάνε πελάτες, και η ταχύτητα της εξέλιξης θα αυξηθεί χωρίς απώλεια αξιοπιστίας.