Geriye dönük uyumluluk

Geriye dönük uyumluluk nedir

Geriye dönük uyumluluk - sistem güncellendiğinde eski müşterileri/tüketicileri kabul etmek ve doğru şekilde işlemek için sistemin özelliği. Daha basit: Hizmetin/etkinliklerin yeni bir sürümünü yayınlarsınız ve mevcut entegrasyonlar değişmeden çalışmaya devam eder.

Anahtar: Anlaşmaları bozmayın. Herhangi bir evrim, zaten serbest bırakılmış olanı eklemekten, yeniden yapmaktan değil.

Temel ilkeler

1. Önce katkı maddesi

Yeni alanlar/yöntemler/olaylar isteğe bağlı olarak eklenir. Var olan hiçbir şey kaldırılmaz ve anlamı değiştirmez.

2. Minimum Garanti Sözleşmesi (MGC)

Bir çekirdek tanımlayın - komut dosyasının anlamını yitirdiği bir dizi alan/işlem. Çekirdek stabil. Diğer her şey uzatmadır.

3. Hoşgörülü okuyucu

İstemciler bilinmeyen alanları yoksayar ve yeni enum (geri dönüş) değerlerini doğru şekilde işler.

4. Sürümler Politikası

Değişiklikleri kırmak - sadece ana hat ('/v2 ',' ödemeler. V2 ', olay. v2 '). Minör - katkı maddesi.

5. Gözlemlenebilirlik - sözleşmenin bir parçası

İstemci sürümü, formatı, yetenek bayrakları günlüklerde/izlerde ve metriklerde görülebilir. Bu, geçişinizi yönetmenizi sağlar.

Güvenli vs tehlikeli değişiklikler

Genel olarak güvenli (BC-OK)

İsteğe bağlı alanlar ekleyin (JSON/Avro/Protobuf 'isteğe bağlı'/' geçersiz').
Yeni uç noktalar/yöntemler/olaylar ekleyin.
Ek değerlere sahip enum uzantısı (toleranslı okuyucu ile).
Geçerliliğin zayıflaması (maksimizasyon, alternatif formatların eklenmesi).
Anlamlı olmayan üstbilgiler/meta veriler ekleyin.

Tehlikeli (Kırılma)

Alanları silin/yeniden adlandırın, varolan alanların türünü veya zorunlu olanını değiştirin.
Durum/hata kodu semantiği değişir.
Diğer alanlar için protobuf etiketlerini yeniden kullanın.
Olay bölümleme anahtarını değiştirme (toplama sırasını bozar).
SLA'ların/zaman aşımlarının sıkılaştırılması, eski müşterilerin düşmeye başlamasına neden olur.

Etkileşim Stilleri ile

REST/HTTP + JSON

Ekleme: yeni alanlar - 'isteğe bağlı', sunucu eski istemcilerden bunları gerektirmez.
Sürümler: major - transit ('/v2 ') veya medya türü; minör - uzantıları ve 'aracılığıyla? include ='/'? alanlar = '.
Hatalar: tek tip format; Majör olmadan kodları/semantiği değiştirmeyin.
ETag/If-Match: yarışmadan güvenli güncellemeler için.
Idempotency: POST için 'Idempotency-Key' - eski müşteriler geri çekilmeler üzerindeki etkiyi 'ikiye katlamaz'.

gRPC/Protobuf

Etiketler değişmedi. Silinen etiketler yeniden kullanılamaz.
Yeni alanlar - 'isteğe bağlı'/' tekrarlanan'; Varsayılan değerler eski kod tarafından doğru şekilde işlenir.
Akış: minör içindeki mesajların sırasını/yükümlülüğünü değiştirmeyin.
Hatalar - kararlı bir durum kümesi; Yeni semantik - yeni yöntem/hizmet ('.v2').

Olay odaklı (Kafka/NATS/Pulsar) + Avro/JSON/Proto

Adlandırma: 'domain. eylem. v {major} '.
Çekirdek vs Zenginleştirilmiş: çekirdek kararlı; zenginleştirme - bireysel türler/temalar ('.enriched').
Şema uyumluluk modu: daha sık geriye doğru; CI, uyumsuz değişiklikleri engeller.
Bölümleme: anahtar (örneğin, 'payment _ id') - sözleşmenin bir parçası; değiştir - kırma.

GraphQL

Alan/tür ekleme - Tamam; sil/yeniden adlandır - '@ kullanımdan kaldırıldı've geçiş penceresi aracılığıyla.
Majör olmadan "nullable - non-nullable" yükseltmeyin.
Karmaşıklığı/derinliği izleyin - limit değişikliği = sözleşme değişikliği.

BC'nin korunmasına yardımcı olacak desenler

Ters piramit modeli: çekirdeği stabilize edin, isteğe bağlı olarak genişletin.
Yetenek anlaşması: Istemci desteklenen yetenekleri bildirir ('X-Capabilities'/el sıkışma), sunucu ayarlar.
Dual-run/dual-emit: Geçiş sırasında 'v1've' v2'yi aynı anda tutun.
Adaptörler: Proxy'ler/ağ geçitleri'ağır "istemciler için 'v1↔v2' isteklerini çevirir.
Genişlet ve sözleşme (DB için): Önce yeni bir tane ekleyin, yazmaya/okumaya başlayın, ancak daha sonra eskisini silin.

Yönetişim ve Süreç

1. Sözleşme Kataloğu (Şema Kayıt Defteri): Uyumluluk ilkelerine sahip tek bir doğruluk kaynağı.
2. CI/CD'de Linters ve diff kontrolleri: OpenAPI-diff, Buf-breaking, Avro/JSON Schema uyumluluk kontrolü.
3. CDC/Tüketici Odaklı Sözleşmeler: Sağlayıcı gerçek tüketici sözleşmeleri için test edilmiştir.
4. Altın örnekler: regresyon için referans sorguları/yanıtları/olayları.
5. Değişim yönetimi: Kırılma, gün batımı planları, iletişim üzerine RFC/ADR.

Deprekate ve eski sürümlerin kaldırılması

Geçersiz olarak işaretleyin ('@ kullanımdan kaldırıldı', açıklamalar, başlıklar 'Kullanımdan kaldırıldı', 'Günbatımı').
Geçiş penceresi: önceden duyurulmuş tarih, test tezgahı, kod örnekleri.
Kullanım telemetrisi: 'V1'de başka kim var? Metrikleri/günlükleri sürüme göre segmentlere ayırın.
Sıfır trafiğe çift çalıştırın, sonra silin.

Gözlemlenebilirlik ve operasyonel metrikler

Sürümlere göre istek/mesaj yüzdesi.
Yayınlandıktan sonra eski istemciler için hata/zaman aşımı paylaşımı.
Uyumsuz yük oranı (ağ geçidi/akış filtrelerinde şema tarafından doğrulama).
Tüketici göçü gecikmesi (kaç kişi daha 'v1' dinliyor).

Geriye dönük uyumluluk testi

Schema-diff: fail при remove/rename/type-change.
Sözleşme testleri: Eski SDK'lar/müşteriler yeni uygulamaya karşı yarışıyor.
E2E kanarya: eski trafiğin bir kısmı yeni versiyona, p95/p99'un karşılaştırılması, kodlar, retrays.
Olay tekrarı: Projeksiyonlar, eski kütükten yeni mantıkla tutarsızlıklar olmadan toplanır.
Hata enjeksiyonu: gecikmeler/kısmi yanıtlar - eski müşteriler düşmez.

Örnekler

REST (katkı maddesi)

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

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

'Risk _ score'u göz ardı eden eski müşteriler çalışmaya devam ediyor.

Protobuf (etiketler)

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

Olaylar (çekirdek + zenginleştirme)

'ödeme. yetkilendirildi. v1 '- çekirdek (minimum gerçekler).
'ödeme. zenginleştirilmiş. v1 '- parçaları; Çekirdek tüketiciler zenginleşmeye bağımlı değildir.

Antipatterns

Swagger-wash: şema güncellendi, ancak hizmet eski şekilde (veya tam tersi) davranıyor.
Gizli kesmeler: bir sürüm olmadan alanın/durumun anlamını değiştirdi.
Protobuf etiketlerinin yeniden kullanımı: "sessiz" veri bozulması.
Zor istemciler: bilinmeyen alanlarda/enumda düşmek; Hoşgörülü okuyucu yok.
Mega-uç nokta: Hepsi bir arada - herhangi bir değişiklik potansiyel bir hurda haline gelir.

Yayın öncesi kontrol listesi

• Değişiklikler katkı maddesidir; Çekirdek (MGC) el değmemiş.
• Linters/diff kontrolleri geçti; Bayrak kırma diye bir şey yok.
• İstemci SDK'ları güncellendi (veya katkı maddesi uzantısı için gerekli değildir).
• Müşteriler için etkin toleranslı okuyucu; Enum-fallback kontrol edildi.
• Metrikler/günlükler sürüm ve yetenek bayrakları içerir.
• Potansiyel kırılma için'/v2 ', çift çalışma ve gün batımı planı var.
• Belgeler/örnekler güncellendi, altın setler var.

SSS

Geriye ve ileriye doğru - fark nedir?
Geriye dönük - yeni sunucular eski müşterilerle çalışır. İleri - yeni istemciler eski sunucularla doğru çalışır (hoşgörülü okuyucu ve düzgün varsayılanlar nedeniyle). Tam daire - tam uyumluluk.

Büyük değişiklikler için her zaman'/v2 'yapmam gerekiyor mu?
Evet, eğer değişmezler/tipler/anahtarlar/anlamlar kesilirse. Aksi takdirde, çizgiyi koruyun ve ek olarak gelişin.

Peki ya enum?
Eskilerin anlamını değiştirmeden yeni değerler ekleyin. Müşterilerin bilinmeyen bir değerde geri dönüşü olmalıdır.

Ya zaten "kırıldıysanız"?
Geri alma, hot-fix adaptörü, çift çalıştırma, iletişim ve geçiş kılavuzu ile 'v2' sürümü.

Toplam

Geriye dönük uyumluluk, evrimin disiplinidir: çekirdeği stabilize eder, ek olarak genişletir, hoşgörülü bir okuyucu uygular, kontrolleri otomatikleştirir ve bilinçli bir amortismanı sürdürür. Bu şekilde, müşterileri "görünmez" değişikliklerin enkazı altında bırakmadan platformu hızlı bir şekilde geliştirebilirsiniz.