Compatibilitate și actualizări API
1) Fundamentele de compatibilitate
Aditiv-primul: adăugați noi fără a rupe vechi (noi câmpuri opționale/puncte finale, noi valori ale enumului).
Contracte stabile: „ceea ce se promite în caietul de sarcini lucrări;” comportament documentat.
Înapoi> Înainte: prioritate de compatibilitate înapoi; înainte este permis prin intermediul cititorilor toleranți.
Documentele sunt primare: singura sursă de adevăr este versiunea de registru a schemei (OpenAPI/AsyncAPI/Proto).
Evoluție explicită: rupere - doar printr-o nouă versiune majoră și un ghid de migrare.
2) Taxonomia modificărilor
2. 1 Compatibil (MINOR/PLASTURE)
Adăugați câmpuri/antete opționale, puncte finale noi, parametri de interogare cu valori implicite.
Creșterea limitelor ('page _ size', TTL), clarificarea erorilor fără modificarea codurilor/semanticii.
Adăugați valori enum dacă clienții ignoră „necunoscut” (tolerant-reader).
2. 2 Ambiguă (comportamentală)
Schimbarea defaults, ordinea de sortare, timeout-uri subțiri, cote - poate „rupe” logica de afaceri. Necesită anunțul RFC + și canari.
2. 3 Rupere (MAJOR)
Redenumiți/ștergeți câmpurile, schimbați tipul/formatul, înlocuiți codurile de eroare, inversați incompatibilitatea contractelor/schemelor de autentificare.
3) Politica de versioning
Strategie: „versioning path” („/v1 ”, „/v2”).
Minor/patch: „adăugați, nu rupeți”.
Antete datate (opțional): „X-API-Version-Date” pentru modificări incrementale moi.
Tipuri media (Op.): 'Acceptă: cerere/vnd. acme. v1 + json "pentru granulare fină.
4) Deprecieri și apus de soare
4. 1 Anteturi de comunicare
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Comanda de retragere
1. Anunț în portalul/lista de corespondență/note de lansare SDK.
2. Fereastra de avertizare ≥ de 90-180 de zile.
3. Statusuri în tabloul de bord al adopţiei.
4. După apus - 410 Gone sau „read-only” mod pentru perioada de grație, dacă a fost de acord.
5) Migrații și coexistența versiunilor
Dual-write/dual-read în tranziție și reconciliere cu rapoartele.
Adaptoare (temporare): conversii gateway ale sarcinii utile vechi → noi scheme; durata de viață a adaptorului este limitată.
Ajutor SDK: versiuni care acceptă ambele versiuni, cu avertismente de decrementare (1 timp pe proces).
Steaguri caracteristice: includerea de noi semantici în conformitate cu lista de chei/chiriași.
6) Compatibilitate înapoi și înainte
6. 1 Înapoi (clienți vechi ↔ server nou)
Nu modificați formatele de tip/obligatoriu.
Câmpurile noi sunt doar opționale.
Erori - old' error _ code ', adăugați coduri noi, nu înlocuiți.
6. 2 Forward (clienți noi ↔ server vechi)
Verificați capacitățile prin „OPȚIUNI ”/„/versiuni”.
Comportament de grație: Clientul trebuie să fie tolerant la caracteristicile lipsă.
7) Contracte și controale automate
Registry: stochează versiunile schemei; PR sapă → rapoarte de rupere/non-rupere.
Linter: nume/tipuri, idempotență, paginare, coduri stabile.
CDC (Contracte bazate pe consumatori): teste integrator în CI furnizorului (Pact și analogi).
Poarta: PR-ul este blocat atunci când se sparge fără un 'major bump '/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Extensie canară și inversă
Canare: 10% → 25% → 50% → 100% din trafic; auto-rollback pe SLO degradare (5xx/latență/429).
Tastele beta: acces la versiuni noi prin lista de permisiuni.
Eliberați înghețarea: bugetul de eroare în timpul arderii.
Analiza acceptării: cota de trafic/clienți pe noua versiune, timpul de migrare.
9) Compatibilitate în detaliu: erori, paginație, idempotență
9. 1 Erori
Nu modificați stările HTTP în scripturile existente.
„error _ code” - stabil; coduri noi numai adăuga.
'aplicare/problemă + json' este un singur format.
9. 2 Paginare
Comută la cursor/keyset = MINOR dacă vechiul 'offset/limit' este acceptat.
Documentaţi sortarea „(updated_at,id)” şi stabilitatea cursorului.
9. 3 Idempotenţa
Pentru scriere - 'Idempotency-Key' + '409 IDEMP_REPLAY' în caz de conflict.
Migrațiile nu ar trebui să schimbe semantica idempotenței.
10) Gateway transformări (atunci când este cazul)
Hărți v1→v2 câmpuri, normalizați erorile, convertiți formatele de date/bani.
Guardrails: transformările sunt transparente și logabile; nu ascundeți ruperea, ci utilizați ca o punte limitată în timp.
11) Comunicații și Portal
Changelog с датами ('adăugat/schimbat/depreciat/eliminat/fix').
Versiune card: stare (beta/GA/depreciate), data apus de soare, link-uri către ghiduri.
Carnete de notificare: 'amortizare. notificare „,” versiune. eliberat „,” plan. schimbare ".
Note de lansare SDK + banner portal.
12) Măsurători de succes
Rata de adoptare v2 (per cerere/client).
Incidente înapoiate.
Eroare mix (4xx/5xx/429 shares) înainte/după eliberare.
Timp de adoptare mediană.
Încărcare suport (tichete/săptămână).
Cost-to-Serve.
13) Șabloane și exemple
13. 1 Titluri și decretări ale versiunii
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Politica versiunii (fragment 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. 3 Câmp OpenAPI Adăugați compatibil
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) Lista de verificare de lansare (MINOR/MAJOR)
MINOR
- DIFF: non-rupere, verde linter
- Documentație/SDK actualizat (exemple/codec-uri)
- Canare + auto-SLO rollback
- Planul de comunicații, Pagina portalului
- Tablouri de bord de adopție și eroare
MAJOR
- RFC/ADR, data apusului și fereastra ≥90 -180 zile
- v1↔v2 pod și ghid de migrare
- Dual-write/read și reconcilieri
- SDK cu ambele API-uri + alerte
- Pilot cu integratori cheie
15) Planul de implementare (3 iterații)
1. Fundația (2 săptămâni):
Registrul schemelor, scame și auto-diff în CI; politica de compatibilitate; Titluri de „depreciere/apus de soare”.
2. Versiuni gestionate (3-4 săptămâni):
Canare, steaguri caracteristice, alerte SLO; portalul versiunii; SDK lansează cu suport pentru 2 ramuri.
3. Automatizare și scară (continuă):
Testele CDC ale consumatorilor în CI, prognoza de apus de soare privind tendințele de adopție, notificări automate și memento-uri.
16) Mini-Întrebări frecvente
Pot schimba tipul de câmp fără un major?
Nu, nu este. Chiar şi „stroka→chislo” se strică. Introduceți un câmp nou, cel vechi este depreciat.
Enum: poți adăuga valori?
Da, dacă clienții sunt toleranți-cititori. În caz contrar - mai întâi o alertă și beta.
Cât de mult să dețină versiunea veche?
Până în prezent, adoptarea noului ≥95% a fost menținută. Fixați termenul limită în politică.
Total
Compatibilitatea API este o disciplină: abordare aditivă, scheme formale și dife-uri, eliberări canare, decretări clare și migrații gestionate. Consolidați politicile de schimbare, automatizați verificările și comunicațiile, măsurați adoptarea - iar actualizările dvs. vor înceta să rupă clienții, iar viteza de evoluție va crește fără a pierde fiabilitatea.