API Sözleşme Uyumluluğu

Neden Sözleşme Uyumluluğu

Sözleşme uyumluluğu, bir API'nin mevcut entegrasyonları bozmadan gelişebilmesidir. Büyüyen sistemlerde, API'ler istemci kodundan daha sık değişir; Uyumluluk, özellikleri "büyük hareketler" düzenlemeden yinelemeli olarak serbest bırakmanıza izin verir.

Anahtar fikir: sözleşme önceliklidir, değişiklikler uyumluluk kurallarına göre gerçekleştirilir ve otomatik olarak kontrol edilir.

Temel kavramlar

Sözleşme - resmi arayüz belirtimi: kaynaklar/yöntemler/olaylar, veri şemaları, hata kodları, limitler, SLA'lar, güvenlik gereksinimleri.
Sağlayıcı - API'nin sahibi. Tüketici - Müşteri/Entegrasyon.

• Geri: Yeni tedarikçi eski tüketicilerle çalışır.
• İleri: Eski tedarikçi yeni tüketicilerle çalışır (genellikle "hoşgörülü okuyucular'tarafından elde edilir).
• Tam: Hem geri hem de ileri (en güçlü seçenek) gözlenir.
• Ekleme özelliği - mevcut öğeleri bozmadan isteğe bağlı öğeler ekleyin.

Sürüm Oluşturma Politikası

• MAJOR - kırılma değişiklikleri (yalnızca yeni bir API satırı yayınlandığında:'/v2 ',' hizmeti. v2 ').
• MINOR - ilave değişiklikler (yeni isteğe bağlı alanlar/yöntemler).
• PATCH - sözleşmeyi değiştirmeden düzeltir.
• Reddetme Politikası: eski öğelerin beyanı, destek penceresi (gün batımı), başlıklarda/meta verilerde uyarılar, para çekme planı.

Güvenli vs tehlikeli değişiklikler

Güvenli (genellikle geriye dönük uyumlu)

JSON/Protobuf/Avro'ya isteğe bağlı bir alan ekleyin.
Yeni bir uç nokta/yöntem/olay ekleyin.
Tüketiciler bilinmeyen değerlere toleranslıysa enumu yeni değerlerle genişletmek.
Minimum sıkmadan limitleri (örneğin, 'maxItems') yükseltmek.
Doğru varsayılanlarla nullable ekleme.
Açıklama/örnek metni düzenleyin.

Tehlikeli (uyumluluğu bozar)

Alanları yeniden adlandırın/silin, türlerini değiştirin veya zorunlu kılın.
Durum kodu/hata semantiği değişikliği (örneğin, '200'idi,' 204 'veya' 404'oldu).
Tanımlayıcıların biçimini değiştirme (UUID - int).
Sürüm olmadan validasyonun sıkılaştırılması (daha sıkı minimumlar/desenler).
GRPC akışlarında/olaylarında düzeni ve yapıyı değiştirme.
Yeni alanlar için Protobuf'ta etiket numaralarını yeniden kullanın.

Interaction Style tarafından birlikte çalışabilirlik

REST/HTTP + JSON Şeması

Ekleme: Yeni alanları 'isteğe bağlı'/' geçersiz'olarak işaretliyoruz.
İstemcide Hoşgörülü Okuyucu: bilinmeyen alanları görmezden gelin; düzene güvenmemek.
Sürüm oluşturma: major - yolda ('/v2 ') veya ortam türünde (' application/vnd. örnek. V2 + json ').
ETag/If-Match: yarışmadan güvenli güncellemeler için.
Hatalar: Tek biçim ('type', 'code', 'title', 'detail', 'trace _ id'), 'code' değerini major olmadan değiştirmez.
Pagination: imleçler ofset tercih edilir; 'next _ cursor' alanları ekleyin, var olanların anlamını değiştirmeyin.

gRPC/Protobuf

Etiket numaralandırma değişmez. Silinen etiketler yeniden kullanılamaz.
Yeni alanlar sunucuda makul varsayılanlar ile 'isteğe bağlı'/' tekrarlanır'.
Streaming-RPC'de sipariş ve zorunlu iletileri değiştirmeyin.
Hata durumları sabittir ('INVALID _ ARGUMENT', 'FAILED _ PRECONDITION', vb.); Yeni semantik - yöntem/hizmetin yeni bir versiyonu.

Olay Odaklı (Kafka/NATS/Pulsar) + Avro/JSON Şeması

Olayları adlandırma: 'domain. eylem. v {major} '.
Yeni alanlar isteğe bağlıdır; Çekirdek ve zenginleştirme izole ('.enriched').
Şema kayıtları: tema/olay üzerinde uyumluluk kuralları (GERİ/İLERI/TAM).
Enum uzantısı tüketici tarafı toleranslı okuyucu için geçerlidir.
Aggregate = breaking changes için partition/order anahtar değişimi.

GraphQL

Alan/tür eklemek güvenlidir; Sil/yeniden adlandır - yalnızca @ kullanımdan kaldırıldı ve geçiş penceresi aracılığıyla.
Majör olmadan türleri/non-nullable değiştirmeyin.
Kontrol karmaşıklığı/derinliği - limitler sözleşmenin bir parçasıdır.

Sürdürülebilir evrim modelleri

Additive-first: Kırılmadan genişletin.
Yetenek anlaşması: istemciler desteklediklerini bildirir (başlıklar/parametreler/anlaşmalar), sunucu ayarlar.
Sözleşme sınırları: MGC (minimum garanti sözleşmesi) ve ayrı uzantıları (ters piramit modeli) düzeltin.
Varsayılan olarak tolerans: istemciler gereksiz yoksayar ve bilinmeyen enum (geri dönüş) değerlerini doğru şekilde işler.
Dual-write/Dual-emit: büyük değişiklikler için, bir süre paralel olarak 'v1've' v2 'bırakın.
Günbatımı başlıkları/Olaylar: Sürümler kaldırıldığında önceden bildir.

Yönetişim ve Otomasyon

• OpenAPI/Spektral: adlandırma, sayfalama, hata kodları, alan formatları.
• Buf/Protobuf: etiketlerin yeniden kullanılmasına izin vermeme, paket gösterimi.
• AsyncAPI/Schema Registry: CI düzeyinde şema uyumluluğu.
• Sözleşme Kataloğu (SSOT): Dağınık geçmişe sahip merkezi şema/sürüm kaydı.
• API Guild: Kuralları, şablonları ve inceleme değişikliklerini benimseyen lonca/komite.
• Değişiklik Yönetimi: RFC/ADR, sürüm notları, geçiş kılavuzları.

Uyumluluk testi

CI'de Schema-diff: blok kırma kekleri (OpenAPI-diff, Buf kırma, SR uyumluluğu).
Tüketici Odaklı Sözleşmeler (CDC): Pakt/Benzer - Tedarikçi ve Tüketiciye Özel Sözleşmeler.
Altın örnekler: regresyon için referans sorguları/yanıtları ve olaylar.
E2E Kanarya: trafik/bireysel tüketim gruplarının payına yayılıyor.
Kaos/gecikme: Zaman aşımı/Retray kontrolü - Bir gecikme-SLO değişikliği sözleşme değişikliği olarak kabul edilir.

Geçişler ve kullanımdan kaldırılma

1. Kullanımdan kaldırıldığını bildirme: Öğeyi işaretleyin, gün batımı terimini ve alternatifini belirtin.
2. Uyumluluk süresini koruyun: çift yazma/çift yayma, köprüler, adaptörler.
3. Telemetri toplayın: Başka kim eskiyi kullanır?
4. İletişim: postalar, sürüm notları, test standları.
5. Kaldırma: pencere sona erdikten sonra - sabit bir sürümle kaldırma.

Değişiklik örnekleri

REST

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

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

Bilinmeyen alanları görmezden gelen istemciler kesilmez.

Protobuf

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

Olay

'ödeme. yetkilendirildi. v1 '(çekirdek) +' ödeme. zenginleştirilmiş. v1 '(zenginleştirme). Kritik yol tüketicileri çekirdeği okur ve zenginleştirmeye bağımlı değildir.

Antipatterns

Swagger-wash: Resmi olarak bir şartname var, ancak hizmetin davranışı onunla çelişiyor.
Gizliliğe göre kırma: yeni bir sürüm ve geçiş penceresi olmadan tür/durum/format değiştirildi.
Halka açık bir sözleşme olarak ham CDC olayları: sızdırılmış DB planları, evrimin imkansızlığı.
Sabit istemci: bilinmeyen alanlarda/değerlerde düşer; Hoşgörülü bir okuyucunun yokluğu.
Protobuf etiketlerini yeniden kullanma: sessiz veri bozulması.
"Sözleşme dışı'olarak gecikme: p95 beklenmedik bir şekilde uzatıldı - tüketiciler zaman aşımına uğradı.

Uyumluluk kontrol listesi (birleştirmeden önce)

• Değişiklikler katkı maddesidir (veya büyük versiyon hazırlanmıştır).
• Linters/diff kontrolleri geçti, uyumluluk kuralları yeşil.
• Hatalar/kodlar/durumlar semantiği değiştirmedi.
• Enum eski değerleri yasaklamadan genişletilmiş; Müşteriler - hoşgörülü.

MGC'nin sınırları değişmedi.

• Güncellenmiş örnekler/dokümantasyon/SDK.
• Büyük için - çift yazma/çift yayma planı, gün batımı tarihi, iletişim planı.
• Testler CDC/Golden/E2E geçti.

SSS

Geriye dönük uyumluluğun ileriye dönük uyumluluktan farkı nedir?
Geriye dönük - yeni sunucular eski müşterileri kırmaz. İleri - yeni istemciler eski sunucularda bozulmaz (hoşgörülü okuyucu ve düzgün varsayılanlar aracılığıyla).

Ne zaman'/v2 'yapıyorsun?
Değişmezler/anlambilim değiştiğinde, alanlar/yöntemler silinir, yeni bir güvenlik modeli gerekir - yeni bir satır başlatmak daha kolay ve daha dürüsttür.

Schema Registry/linters olmadan yaşayabilir misiniz?
Teorik olarak - evet, pratik olarak - bunlar sık sık regresyonlar ve "gizli" arızalardır. Otomasyon işe yarıyor.

Enum uzatılabilir mi?
Evet, istemciler bilinmeyen değerleri doğru bir şekilde ele alıyorsa (geri dönüş/yoksayma). Aksi takdirde - binbaşı.

Toplam

Sözleşme uyumluluğu kurallar + disiplin + otomasyondur. Ek olarak tasarım, sürüm kırma değişiklikleri, hoşgörülü bir okuyucu uygulayın, differs ve CDC'yi otomatik olarak kontrol edin, plan kullanımdan kaldırılır. Bu şekilde API'ler hızlı bir şekilde gelişebilir ve entegrasyonlar sabit kalabilir.