Əks uyğunluq

Əks uyğunluq nədir

Əks uyğunluq (backward compatibility) - sistem yeniləndikdə köhnə müştəriləri/istehlakçıları qəbul etmək və düzgün emal etmək üçün sistemin xüsusiyyətidir. Daha asan: Siz xidmətin/hadisələrin yeni versiyasını buraxırsınız və mövcud inteqrasiyalar dəyişmədən işləməyə davam edir.

Açar: razılaşmaları pozmayın. Hər hansı bir təkamül - əlavə etməklə, artıq buraxılmış deyil.

Əsas prinsiplər

1. Additive-first

Yeni sahələr/metodlar/hadisələr isteğe bağlıdır. Mövcud olan heç bir şey silinmir və mənasını dəyişdirmir.

2. Minimum zəmanət müqaviləsi (MGC)

Nüvəni təyin edin - sahələr/əməliyyatlar toplusu, onsuz ssenari mənasını itirir. Nüvə sabitdir. Qalan hər şey genişləndirmədir.

3. Tolerant reader

Müştərilər naməlum sahələrə məhəl qoymur və yeni enum (fallback) dəyərlərini düzgün idarə edirlər.

4. Versiya siyasəti

Sındırıcı dəyişikliklər - yalnız major xətti ('/v2 ',' payments. v2`, `event. v2`). Minor - additivdir.

5. Müşahidə - müqavilənin bir hissəsi

Loglarda/treyslərdə və metriklərdə müştərinin versiyası, formatı, capability bayraqları görünür. Bu, miqrasiyanı idarə etməyə imkan verir.

Təhlükəsiz vs təhlükəli dəyişikliklər

Adətən təhlükəsiz (BC-OK)

İsteğe bağlı sahələrin əlavə edilməsi (JSON/Avro/Protobuf 'optional '/' nullable').
Yeni nöqtələr/metodlar/hadisələr əlavə edin.
Əlavə qiymətlərlə enum genişləndirilməsi (tolerant reader ilə).
Validasiyanın zəifləməsi (maksimumların artırılması, alternativ formatların əlavə edilməsi).
Mənaya təsir etməyən başlıqlar/metadata əlavə edin.

Təhlükəli (Breaking)

Sahələrin silinməsi/adının dəyişdirilməsi, mövcud sahələrin növünün və ya məcburiyyətinin dəyişdirilməsi.
Status semantikasının/səhv kodlarının dəyişdirilməsi.
Protobuf etiketlərinin digər sahələr üçün yenidən istifadə edilməsi.
Hadisənin partizan açarının dəyişdirilməsi (aqreqat üçün qaydanı pozur).
Köhnə müştərilərin düşməyə başlamasına səbəb olan SLA/vaxtların sərtləşdirilməsi.

Qarşılıqlı əlaqə üslublarına görə

REST/HTTP + JSON

Additivlik: Yeni sahələr - 'optional', server köhnə müştərilərdən tələb etmir.
Versiyalar: major - yolda ('/v2 ') və ya mediatipdə; minor - '? include = '/'? fields =' uzantıları vasitəsilə.
Səhvlər: vahid format; major olmadan kodları/semantika dəyişmək deyil.
ETag/If-Match: qaçışsız təhlükəsiz yeniləmələr üçün.
İdempotentlik: POST üçün «Idempotency-Key» - köhnə müştərilər retrajlarda təsiri «ikiqat» etmirlər.

gRPC / Protobuf

Tags dəyişməz. Silinmiş etiketlər yenidən istifadə edilmir.
Yeni sahələr - 'optional '/' repeated'; default dəyərlər köhnə kod ilə düzgün işlənir.
Axın: minor daxilində mesajların qaydasını/öhdəliyini dəyişdirməyin.
Səhvlər - sabit status dəsti; yeni semantika → yeni üsul/xidmət ('.v2').

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

Adı: 'domain. action. v{major}`.
Core vs Enriched: nüvə stabil; zənginləşdirmə - ayrı-ayrı tiplər/mövzular ('.enriched').
Sxemlərin uyğunluq rejimi: daha tez-tez BACKWARD; CI uyğun olmayan dəyişiklikləri bloklayır.
Partiyalaşdırma: açar (məsələn, 'payment _ id') - müqavilənin bir hissəsi; onu dəyişdirmək - breaking.

GraphQL

Sahələrin/tiplərin əlavə edilməsi - OK; silmək/yenidən adlandırmaq - '@deprecated' və miqrasiya pəncərəsi vasitəsilə.
major olmadan «nullable → non-nullable» artırmayın.
complexity/depth nəzarət - limitlərin dəyişdirilməsi = müqavilə dəyişikliyi.

BC-nin saxlanmasına kömək edən nümunələr

Əks piramida modeli: nüvəni sabitləşdirin, isteğe bağlı olaraq genişləndirin.
Capability negotiation: Müştəri dəstəklənən imkanları ('X-Capabilities '/handshake) bildirir, server uyğunlaşır.
Dual-run/dual-emit: miqrasiya zamanı eyni zamanda 'v1' və 'v2' saxlayın.
Adapterlər: proxy/gateway «ağır» müştərilər üçün 'v1 v2' sorğularını tərcümə edir.
Expand-and-contract (DB üçün): əvvəlcə yenisini əlavə edin, yazmağa/oxumağa başlayın, yalnız sonra köhnəsini silin.

Governance və proses

1. Müqavilə kataloqu (sxemlərin reyestri): uyğunluq siyasətçiləri ilə vahid həqiqət mənbəyi.
2. CI/CD-də linterlər və diff çeklər: OpenAPI-diff, Buf-breaking, Avro/JSON Schema uyğunluq testi.
3. CDC/Consumer-Driven Contracts: provayder real istehlakçı müqavilələri üçün yoxlanılır.
4. Golden samples: referans sorğular/cavablar/reqress üçün hadisələr.
5. Change management: RFC/ADR breaking, sunset planları, rabitə.

Deprekeyt və köhnə versiyaların çıxarılması

Köhnəlmiş ('@deprecated', təsvirlər, başlıqlar 'Deprecation', 'Sunset').
Miqrasiya pəncərəsi: əvvəlcədən elan edilmiş tarix, test stendi, kod nümunələri.
Telemetriya istifadə: 'v1' başqa kim? versiyasına görə metrik/log seqmentləşdirin.
Dual-run sıfıra qədər trafik, sonra - silmək.

Müşahidə və əməliyyat metrikası

Versiyalara görə sorğu/mesaj faizi.
Buraxılışdan sonra köhnə müştərilərdə səhvlərin/vaxtların payı.
Uyğun olmayan payload payı (şlüz/axın filtrlərində sxem ilə validasiya).
İstehlakçı miqrasiyası (daha nə qədər 'v1' dinləyir).

Əks uyğunluq testi

Schema-diff: fail при remove/rename/type-change.
Müqavilə testləri: Köhnə SDK/müştərilər yeni həyata keçirməyə qarşı qaçırlar.
E2E-kanarya: p95/p99, kodlar, retrains müqayisə, yeni versiyası köhnə trafikin bir hissəsi.
Hadisələrin replikası: proyeksiyalar heç bir uyğunsuzluq olmadan köhnə logdan yeni bir məntiqlə toplanır.
Fault-injection: gecikmələr/qismən cavablar - köhnə müştərilər düşmür.

Nümunələr

REST (əlavə)

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

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

Köhnə müştərilər «risk _ score» görməməzlikdən gələrək işləməyə davam edirlər.

Protobuf

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

Hadisələr (nüvə + zənginləşdirmə)

`payment. authorized. v1 '- nüvə (minimum faktlar).
`payment. enriched. v1 '- detallar; nüvə istehlakçıları zənginləşdirmədən asılı deyil.

Antipatternlər

Swagger-wash: yenilənmiş sxem, lakin xidmət köhnə kimi davranır (və ya əksinə).
Gizli pozuntular: versiyası olmadan sahə/status mənasını dəyişdi.
Protobuf etiketlərinin yenidən istifadəsi: məlumatların «sakit» korrupsiyası.
Sərt müştərilər: tanımadığınız sahələrə/enum; tolerant reader yoxdur.
Mega-endpoint: bir-bir-bir - hər hansı bir dəyişiklik potensial bir qırılmaya çevrilir.

Buraxılışdan əvvəl çek siyahısı

• Dəyişikliklər əlavə; nüvə (MGC) toxunulmamış.
• Linters/diff çekləri keçdi; breaking bayraqlar yoxdur.
• Müştəri SDK yeniləndi (və ya əlavə genişləndirmə üçün tələb olunmur).
• Müştərilərdə tolerant reader aktiv; enum-fallback təsdiqləndi.
• Metrik/log versiyasını və capability bayraqlarını ehtiva edir.
• Potensial qırılma üçün '/v2 ', dual-run və sunset planı var.
• Sənədlər/nümunələr yeniləndi, qızıl dəstləri var.

FAQ

Backward vs forward - fərq nədir?
Backward - yeni serverlər köhnə müştərilərlə işləyir. Forward - yeni müştərilər köhnə serverlərlə düzgün işləyirlər (tolerant reader və səliqəli defoltlar hesabına). Tam dairə - tam compatibility.

Böyük dəyişikliklər üçün həmişə '/v2 'etməlisiniz?
Bəli, alternativlər/tiplər/açarlar/semantika pozulursa. Əks təqdirdə, xətti saxlayın və əlavə olaraq inkişaf edin.

enum ilə necə?
Köhnə mənasını dəyişmədən yeni dəyərlər əlavə edin. Müştərilər naməlum dəyərdə fallback olmalıdır.

Artıq «qırılıbsa» nə etməli?
Geri dönüş, hot-fix adapter, «v2» buraxılışı dual-run, rabitə və miqrasiya bələdçisi.

Yekun

Əks uyğunluq təkamül intizamıdır: nüvəni sabitləşdirin, əlavə genişləndirin, tolerant reader tətbiq edin, yoxlamaları avtomatlaşdırın və şüurlu deprekeyt edin. Beləliklə, müştəriləri «görünməz» dəyişikliklərin dağıntıları altında qoymadan platformanı sürətlə inkişaf etdirə bilərsiniz.