Ters gabat gelmek

Ters gabat gelmek näme?

Ters laýyklyk (backward compatibility) - ulgam täzelenende köne müşderileri/sarp edijileri kabul etmek we dogry işlemek ukyby. Has aňsat: hyzmatyň/wakalaryň täze wersiýasyny çykarýarsyňyz we bar bolan integrasiýalar üýtgemän işlemegini dowam etdirýär.

Açar: şertnamalary bozmaň. Islendik ewolýusiýa - eýýäm goýberilenleri täzeden düzmek däl-de, goşmak arkaly.

Esasy ýörelgeler

1. Additive-first

Täze meýdanlar/usullar/wakalar goşmaça goşulýar. Bar bolan hiç zat aýrylmaýar we manysyny üýtgetmeýär.

2. Iň az kepillik şertnamasy (MGC)

Özeniňizi kesgitläň - meýdanlar/amallar toplumy, onsuz ssenariýa manysyny ýitirýär. Ýadro durnukly. Galan zatlaryň hemmesi giňeltmek.

3. Tolerant reader

Müşderiler näbelli ýerleri äsgermezlik edýärler we täze enum (fallback) bahalaryny dogry dolandyrýarlar.

4. Wersiýa syýasaty

Bozýan üýtgeşmeler - diňe major-line arkaly ('/v2 ',' payments. v2`, `event. v2`). Minor - additives.

5. Gözegçilik etmek - şertnamanyň bir bölegi

Loglarda/treýslerde we metriklerde müşderiniň wersiýasy, formaty, capability-baýdaklary görünýär. Bu bolsa migrasiýa dolandyrmaga mümkinçilik berýär.

Howpsuz vs howply üýtgeşmeler

Adatça howpsuz (BC-OK)

Goşmaça meýdanlary goşmak (JSON/Euro/Protobuf 'optional '/' nullable').
Täze endpointleri/usullary/wakalary goşmak.
Goşmaça manylar bilen enum giňeltmek (tolerant reader bilen).
Walidasiýanyň gowşamagy (maksimumlaryň ýokarlanmagy, alternatiw formatlaryň goşulmagy).
Manyňa täsir etmeýän sözbaşylary/meta maglumatlary goşmak.

Howply (Breaking)

Meýdanlary aýyrmak/adyny üýtgetmek, bar bolan meýdanlaryň görnüşini ýa-da borçlylygyny üýtgetmek.
Status semantikasyny/ýalňyşlyk kodlaryny üýtgetmek.
Protobuf-taglary başga meýdanlar üçin gaýtadan ulanmak.
Wakanyň partiýalaşdyryş açaryny üýtgetmek (agregat üçin tertibi bozýar).
SLA/wagtlary berkitmek, köne müşderileriň ýykylmagyna sebäp bolýar.

Özara gatnaşyk stillerine görä

REST/HTTP + JSON

Goşmaça: Täze meýdanlar - 'optional', serwer olary köne müşderilerden talap etmeýär.
Wersiýalary: major - ýolda ('/v2 ') ýa-da mediatip; minor - i '? include = '/'? fields =' arkaly.
Ýalňyşlyklar: ýekeje format; major bolmasa kodlary/semantikany üýtgetmäň.
ETag/If-Match: ýaryşsyz howpsuz täzelenmeler üçin.
Idempotentlik: POST üçin 'Idempotency-Key' - köne müşderiler retrada täsirini "iki esse" etmeýärler.

gRPC / Protobuf

Bellikler üýtgewsiz. Öçürilen bellikleri gaýtadan ulanmaň.
Täze meýdanlar - 'optional '/' repeated'; adaty bahalar köne kod bilen dogry işlenilýär.
Akym: minor içindäki habarlaryň tertibini/borçlylygyny üýtgetmäň.
Ýalňyşlyklar - statuslaryň durnukly toplumy; täze semantika → täze usul/hyzmat ('.v2').

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

Adynyň ady: 'domain. action. v{major}`.
Core vs Enriched: ýadro durnukly; baýlaşdyrmak - aýry-aýry görnüşler/mowzuklar ('.enriched').
Shemalaryň gabat geliş tertibi: köplenç BACKWARD; CI gabat gelmeýän üýtgeşmeleri bloklaýar.
Partiýa ýerleşdirmek: açar (mysal üçin 'payment _ id') - şertnamanyň bir bölegi; ony üýtgetmek - breaking.

GraphQL

Meýdanlary/görnüşleri goşmak - OK; aýyrmak/adyny üýtgetmek - '@deprecated' we göçmek penjiresi arkaly.
Major bolmasa "nullable → non-nullable" -y ýokarlandyrmaň.
complexity/depth - çäklendirmeleri üýtgetmek = şertnamany üýtgetmek.

BC-ni saklamaga kömek edýän patternler

Ters piramida modeli: ýadrosyny durnuklaşdyryň, goşmaça giňeldiň.
Capability negotiation: Müşderi goldanýan mümkinçilikleri ('X-Capabilities '/handshake) habar berýär, serwer sazlanýar.
Dual-run/dual-emit: göçmek wagtynda bir wagtyň özünde 'v1' we 'v2' -ni saklaň.
Adapterler: proksi/geýtweý "agyr" müşderiler üçin 'v1 v2' soraglaryny terjime edýär.
Expand-and-contract (BD üçin): Ilki bilen täzesini goşuň, ýazmaga/okamaga başlaň, diňe köne birini aýyryň.

Governance we amal

1. Şertnamalaryň katalogy (shemalaryň sanawy): laýyklyk syýasatlary bilen hakykatyň ýeke-täk çeşmesi.
2. CI/CD-de linterler we diff-çekler: OpenAPI-diff, Buf-breaking, Euro/JSON Schema laýyklygyny barlamak.
3. CDC/Consumer-Driven Contracts: üpjün ediji hakyky sarp ediji şertnamalary üçin barlanýar.
4. Golden samples: regress üçin salgylanma soraglary/jogaplar/wakalar.
5. Change management: RFC/ADR breaking, sunset meýilnamalary, aragatnaşyk.

Köne wersiýalary aýyrmak

Köne ('@deprecated', düşündirişler, 'Deprecation', 'Sunset' sözbaşylary) belläň.
Migrasiýa penjiresi: öňünden yglan edilen senesi, synag stendi, kod mysallary.
Ulanyş telemetriýasy: 'v1' -de başga kim? wersiýa boýunça metrikleri/logleri bölüň.
Traffigiň nola çenli dual-run, soň - aýyrmak.

Gözegçilik we operasiýa metrikleri

Wersiýa boýunça haýyşlaryň/habarlaryň göterimi.
Goýberilenden soň köne müşderilerde ýalňyşlyklaryň/wagtlaryň paýy.
Gabat gelmeýän payload paýy (şlýuzda/akym süzgüçlerinde shema bilen tassyklama).
Sarp edijileriň migrasiýasy (näçe wagt diňleýärler 'v1').

Ters laýyklygy barlamak

Schema-diff: fail при remove/rename/type-change.
Şertnama-synaglar: köne SDK/müşderiler täze satuwa garşy kowalap gelýärler.
E2E-kanareýa: köne traffigiň bir bölegi täze wersiýa, p95/p99, kodlary, retraýlary deňeşdirmek.
Wakalaryň sözleri: proýeksiýalar köne logdan gapma-garşylyksyz täze logika bilen ýygnalýar.
Fault-injection: gijikdirmeler/bölekleýin jogaplar - köne müşderiler ýykylmaýar.

Mysallar

REST (goşmaça)

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

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

Köne müşderiler 'risk _ score' -a üns bermän işlemegini dowam etdirýärler.

Protobuf (bellikler)

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

Wakalar (ýadro + baýlaşdyrmak)

`payment. authorized. v1 '- özeni (iň az faktlar).
`payment. enriched. v1 '- jikme-jiklikler; ýadro sarp edijiler baýlaşdyrmaga bagly däl.

Anti-patternler

Swagger-wash: shema täzelendi, ýöne hyzmat köne görnüşde hereket edýär (ýa-da tersine).
Gizlin döwükler: wersiýasyz meýdanyň/statusyň manysyny üýtgetdiler.
Protobuf-tegleri gaýtadan ulanmak: maglumatlaryň "asuda" korrupsiýasy.
Gaty müşderiler: nätanyş meýdanlara düşýärler/enum; tolerant reader ýok.
Mega-endpoint: birmeňzeş - islendik üýtgeşiklik potensial döwülýär.

Goýberilmezinden öň çek sanawy

• Üýtgeşmeler goşmaça; ýadro (MGC) degilmedi.
• Linterler/diff-barlaglar geçdi; breaking-baýdaklar ýok.
• Müşderi SDK täzelendi (ýa-da goşmaça giňeltmek üçin talap edilmeýär).
• Müşderilerde tolerant reader işjeňleşdirildi; enum-fallback barlandy.
• Metrikler/loglarda wersiýa we capability-baýdaklar bar.
• Potensial döwmek üçin '/v2 ', dual-run we sunset meýilnamasy bar.
• Resminamalar/mysallar täzelendi, altyn toplumlar bar.

FAQ

Backward vs forward - tapawudy näme?
Backward - täze serwerler köne müşderiler bilen işleýär. Forward - täze müşderiler köne serwerler bilen dogry işleýärler (tolerant reader we arassa defoltlar sebäpli). Doly tegelek - full compatibility.

Uly üýtgeşmeler üçin hemişe '/v2 'etmeli?
Invariantlar/görnüşler/açarlar/semantika bozulsa, hawa. Otherwiseogsam, çyzygy saklaň we goşmaça ösüň.

Enum hakda näme?
Köne manyny üýtgetmän täze bahalary goşuň. Müşderiler näbelli manyda fallback bolmaly.

Eýýäm "döwülen" bolsa näme etmeli?
Yza çekilmegi, hot-fix adapteri, 'v2' -s dual-run, aragatnaşyk we migrasiýa gollanmasy.

Jemi

Ters gabat gelmek ewolýusiýanyň düzgünidir: ýadrosyny durnuklaşdyryň, goşmaça giňeldiň, çydamly reader giriziň, barlaglary awtomatlaşdyryň we aňly deprekeýt ediň. Şeýlelik bilen, müşderileriňizi "göze görünmeýän" üýtgeşmeleriň galyndylarynyň aşagynda goýman, platformany çalt ösdürip bilersiňiz.