Compatibilitate inversă

Ce este compatibilitatea înapoi

Compatibilitate inversă - proprietatea sistemului de a accepta și procesa corect clienții/consumatorii vechi atunci când sistemul este actualizat. Mai simplu: lansați o nouă versiune a serviciului/evenimentelor, iar integrările existente continuă să funcționeze neschimbat.

Cheia: nu rupe acordurile. Orice evoluție este prin adăugarea, nu refacerea, unul deja eliberat.

Principii de bază

1. Aditiv-primul

Câmpurile/metodele/evenimentele noi sunt adăugate opțional. Nimic existent nu este eliminat și nu schimbă sensul.

2. Contract minim de garanție (MGC)

Definiți un kernel - un set de câmpuri/operațiuni fără de care scriptul își pierde sensul. Miezul este stabil. Restul sunt extensii.

3. Cititor tolerant

Clienții ignoră câmpurile necunoscute și gestionează corect noile valori enum (rezervă).

4. Politica versiunilor

Modificări de rupere - numai prin linia majoră ("/v2 "," plăți. v2 ',' eveniment. v2 '). Minor - aditiv.

5. Observabilitate - parte a contractului

Versiunea clientului, formatul, steagurile de capacitate sunt vizibile în jurnale/piste și valori. Acest lucru vă permite să gestionați migrația.

Safe vs schimbari periculoase

În general sigur (BC-OK)

Adăugați câmpuri opționale (JSON/Avro/Protobuf „opțional ”/„ nullable”).
Adăugați noi puncte finale/metode/evenimente.
Extindere enum cu valori suplimentare (cu cititor tolerant).
Slăbirea validării (maximizarea, adăugarea de formate alternative).
Adăugați antete/metadate nesemnificative.

Periculoase (de rupere)

Ștergeți/redenumiți câmpurile, modificați tipul sau obligativitatea câmpurilor existente.
Status/error code semantics change.
Reutilizați etichetele protobuf pentru alte câmpuri.
Schimbarea tastei de partiționare a evenimentului (rupe ordinea pentru agregat).
Strângerea SLA/timeout-urilor, determinând clienții vechi să înceapă să scadă.

Prin stiluri de interacțiune

REST/HTTP + JSON

Additivity: noi domenii - 'optional', serverul nu le solicita de la clientii vechi.
Versiuni: majore - în tranzit ('/v2 ') sau tip media; minor - prin extensii și "? include = '/'? fields = '.
Erori: format uniform; nu modificați codurile/semantica fără majore.
ETag/If-Match: pentru actualizări sigure fără curse.
Idempotency: „Idempotency-Key” pentru clienții POST - vechi nu „dubla” efectul asupra retragerilor.

gRPC/Protobuf

Etichetele sunt neschimbate. Etichetele șterse nu pot fi reutilizate.
Câmpuri noi - „opțional ”/„ repetat”; valorile implicite sunt manipulate corect de vechiul cod.
Streaming: nu modificați ordinea/obligația mesajelor în cadrul minorului.
Erori - un set stabil de stări; semantică nouă → metodă/serviciu nou ('.v2').

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON/Proto

Denumire: 'domeniu. acțiune. v {major} '.
Core vs Îmbogățit: miez stabil; îmbogățire - tipuri/teme individuale („.bogățit”).
Modul de compatibilitate Schema: mai des ÎNAPOI; CI blochează schimbările incompatibile.
Partiționare: cheie (de exemplu, "payment _ id') - parte a contractului; schimba - rupere.

GraphQL

Adăugarea de câmpuri/tipuri - OK; ștergere/redenumire - prin „@ depreciat” și fereastra de migrare.
Nu ridica „nullable → non-nullable” fără major.
Monitorizați complexitatea/adâncimea - modificarea limitei = modificarea contractului.

Modele pentru a ajuta la conservarea BC

Modelul piramidei inverse: stabilizați miezul, extindeți opțional.
Negocierea capacității: clientul raportează capacitățile acceptate („X-Capabilities ”/strângere de mână), serverul se ajustează.
Dual-run/dual-emit: Păstrați „v1” și „v2” în același timp în timpul migrării.
Adaptoare: proxy-urile/gateway-urile traduc cererile „v1↔v2” pentru clienții „grei”.
Extindeți-și-contract (pentru DB): mai întâi adăugați unul nou, începeți să scrieți/citiți, numai apoi ștergeți-l pe cel vechi.

Guvernare și proces

1. Catalog de contracte (Schema Registry): O singură sursă de adevăr cu politici de compatibilitate.
2. Lintere și controale diff în CI/CD: OpenAPI-diff, Buf-breaking, Avro/JSON Schema de verificare a compatibilității.
3. CDC/Contracte bazate pe consumatori: Furnizorul este testat pentru contracte reale de consum.
4. Eșantioane de aur: interogări/răspunsuri/evenimente de referință pentru regresie.
5. Managementul schimbării: RFC/ADR privind ruperea, planurile de apus, comunicarea.

Deprekate și eliminarea versiunilor vechi

Marcați învechit („@ depreciat”, descrieri, antete „depreciere”, „apus de soare”).
Fereastra de migrare: data pre-anunțată, banc de testare, exemple de cod.
Telemetrie de utilizare: Cine altcineva este pe „v1”? segment metrics/logs by version.
Dual-run la zero trafic, apoi ștergeți.

Observabilitate și valori operaționale

Procentul de cereri/mesaje după versiune.
Partajarea erorilor/timeouts pentru clienții mai în vârstă după eliberare.
Proporția sarcinii utile incompatibile (validarea de către schema de pe filtrele gateway/stream).
Lag-ul migrației consumatorilor (câți mai ascultă „v1”).

Testarea compatibilității înapoi

Schema-diff: nu reușesc при elimine/redenumi/schimbare de tip.
Teste de contract: vechi SDKs/clienții cursa împotriva implementării noi.
E2E canar: o parte a traficului vechi la noua versiune, compararea p95/p99, coduri, retraverse.
Reluarea evenimentului: Proiecțiile sunt colectate prin logică nouă din jurnalul vechi, fără discrepanțe.
Injecție de eroare: întârzieri/răspunsuri parțiale - clienții vechi nu cad.

Exemple

REST (aditiv)

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

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

Clienții vechi, ignorând 'risk _ score', continuă să lucreze.

Protobuf (etichete)

proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2

Evenimente (core + îmbogățire)

"plata. autorizat. v1 '- kernel (fapte minime).
"plata. îmbogățit. v1 "- părți; consumatorii principali nu depind de îmbogățire.

Antipatterns

Swagger-wash: schema a fost actualizată, dar serviciul se comportă în mod vechi (sau invers).
Pauze ascunse: a schimbat sensul câmpului/starea fără o versiune.
Reutilizarea etichetelor protobuf: corupere „silențioasă” a datelor.
Clienti duri: se incadreaza in domenii necunoscute/enum; nici un cititor tolerant.
Mega-endpoint: Unul all-in-one - orice schimbare devine o potențială resturi.

Lista de verificare înainte de lansare

• Modificările sunt aditive; nucleul (MGC) este neatins.
• Controalele linter/diff au trecut; nu există steaguri de rupere.
• SDK-urile client au fost actualizate (sau nu sunt necesare pentru extensia aditivă).
• Activat cititor tolerant pentru clienți; inum-rezervă verificată.
• Metrics/busteni conțin versiunea și steaguri de capacitate.
• Pentru ruperea potențială există „/v2 ”, plan dual-run și apus de soare.
• Documentație/exemple au fost actualizate, există seturi de aur.

ÎNTREBĂRI FRECVENTE

Înapoi vs înainte - care este diferența?
Înapoi - serverele noi funcționează cu clienții vechi. Forward - clienții noi lucrează corect cu servere vechi (datorită cititorului tolerant și implicit îngrijit). Cerc complet - compatibilitate completă.

Trebuie să fac mereu „/v2 ”pentru schimbări mari?
Da, dacă invarianții/tipurile/cheile/semantica se sparg. În caz contrar, păstrați linia și evoluați aditiv.

Ce zici de enum?
Adăugați valori noi fără a schimba sensul celor vechi. Clienţii trebuie să se fi retras la o valoare necunoscută.

Ce se întâmplă dacă ați deja "rupt'?
Rollback, adaptor hot-fix, eliberare 'v2' cu ghid dual-run, comunicare și migrare.

Total

Compatibilitatea înapoi este disciplina evoluției: stabilizarea nucleului, extinderea aditivă, implementarea unui cititor tolerant, automatizarea verificărilor și menținerea unei deprecieri conștiente. În acest fel puteți dezvolta rapid platforma fără a lăsa clienții sub dărâmăturile schimbărilor „invizibile”.