API uyumluluğu ve güncellemeleri
1) Uyumluluk temelleri
Additive-first: eskiyi bozmadan yenilerini ekleyin (yeni isteğe bağlı alanlar/uç noktalar, yeni enum değerleri).
Kararlı sözleşmeler: "şartname çalışmalarında vaat edilenler"; davranışları belgelenmiştir.
Geri> İleri: geriye uyumluluk önceliği; İleri hoşgörülü-okuyucular aracılığıyla izin verilir.
Belgeler birincil: Gerçeğin tek kaynağı, planın kayıt defteri sürümüdür (OpenAPI/AsyncAPI/Proto).
Açık evrim: kırılma - sadece yeni bir ana sürüm ve bir göç rehberi aracılığıyla.
2) Değişikliklerin taksonomisi
2. 1 Uyumlu (MINOR/PATCH)
İsteğe bağlı alanlar/başlıklar, yeni uç noktalar, varsayılanlarla sorgu parametreleri ekleyin.
Sınırları artırma ('page _ size', TTL), kodları/semantikleri değiştirmeden hataları netleştirme.
İstemciler "bilinmeyen'i (toleranslı-okuyucu) yoksayarsa enum değerleri ekleyin.
2. 2 Belirsiz (Davranışsal)
Varsayılanları değiştirme, sıralama düzeni, ince zaman aşımları, kotalar - iş mantığını "kırabilir". RFC + anonsu ve kanarya gerektirir.
2. 3 Kırma (MAJOR)
Alanları yeniden adlandırma/silme, türü/biçimi değiştirme, hata kodlarını değiştirme, sözleşmelerin/kimlik doğrulama şemalarının ters uyumsuzluğu.
3) Sürüm politikası
Strateji: 'Yol sürümleme' ('/v1 ','/v2').
Minör/yama: "ekle, kırma".
Tarihli başlıklar (isteğe bağlı): Yumuşak artımlı değişiklikler için 'X-API-Version-Date'.
Ortam Türleri (Op.): 'Accept: application/vnd. Acme. İnce granülasyon için v1 + json '.
4) Değer düşüklüğü ve gün batımı
4. 1 İletişim başlıkları
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Çekilme emri
1. Portalda duyuru/posta listesi/SDK yayın notları.
2. Uyarı süresi 90-180 gün ≥.
3. Evlat edinme panosundaki durumlar.
4. Gün batımından sonra - 410 Kabul edilirse, ödemesiz süre için Gone veya "salt okunur" modu.
5) Geçişler ve sürümlerin bir arada bulunması
Raporlarla geçiş ve mutabakatta çift yazma/çift okuma.
Adaptörler (geçici): Eski yükün ağ geçidi dönüşümleri - yeni şemalar; Adaptör ömrü sınırlıdır.
SDK yardımı: Her iki sürümü de destekleyen sürümler, azaltma uyarılarıyla (işlem başına 1 kez).
Özellik bayrakları: Anahtarlar/kiracılar listesine göre yeni semantiklerin dahil edilmesi.
6) Geriye ve ileriye dönük uyumluluk
6. 1 Geriye doğru (eski istemciler ↔ yeni sunucu)
Tür biçimlerini/zorunlu biçimlerini değiştirmeyin.
Yeni alanlar sadece isteğe bağlıdır.
Hatalar - eski 'error _ code', yeni kodlar ekleyin, değiştirmeyin.
6. 2 İleri (yeni istemciler ↔ eski sunucu)
'OPTIONS'/'/versions' üzerinden yetenekleri kontrol edin.
Grace davranışı: Müşteri eksik özelliklere toleranslı olmalıdır.
7) Sözleşmeler ve otomatik kontroller
Kayıt defteri: mağaza şema sürümleri; PR kazıları - kırılma/kırılmayan raporlar.
Linter: isimler/tipler, idempotency, sayfalama, kararlı kodlar.
CDC (Tüketici Odaklı Sözleşmeler): Tedarikçinin CI'sında entegratör testleri (Pakt ve analoglar).
Kapı: PR, 'büyük bir çarpma'/RFC olmadan kırılırken engellenir.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Kanarya uzatma ve ters
Kanarya: %10 - %25 - %50 - %100 trafik; SLO bozulması üzerinde otomatik geri alma (5xx/latency/429).
Beta tuşları: allowlist tarafından yeni sürümlere erişim.
Serbest bırakma donması: yanma sırasında hata bütçesi.
Kabul analitiği: Yeni sürümde trafik/müşteri payı, geçiş süresi.
9) Ayrıntılı uyumluluk: hatalar, sayfalama, idempotence
9. 1 Hatalar
Mevcut komut dosyalarındaki HTTP durumlarını değiştirmeyin.
'error _ code' - kararlı; Yeni kodlar sadece ekle.
'uygulama/problem + json'tek bir formattır.
9. 2 Pagination
Eski 'ofset/limit' destekleniyorsa imleç/keyset = MINOR'a geçin.
'(updated_at,id)'ve imleç kararlılığını belgeleyin.
9. 3 Idempotency
Yazmak için - çatışma durumunda 'Idempotency-Key' + '409 IDEMP_REPLAY'.
Göçler idempotensin semantiğini değiştirmemelidir.
10) Ağ geçidi dönüşümleri (uygun olduğunda)
Harita v1 - v2 alanları, hataları normalleştirmek, tarih/para formatlarını dönüştürmek.
Korkuluklar: dönüşümler şeffaf ve oturum açabilir; kırılmayı gizlemeyin, ancak zaman sınırlı bir köprü olarak kullanın.
11) İletişim ve Portal
Changelog с датами ('eklendi/değiştirildi/kullanımdan kaldırıldı/kaldırıldı/düzeltildi').
Sürüm kartı: durum (beta/GA/kullanımdan kaldırılmış), gün batımı tarihi, kılavuzlara bağlantılar.
Bildirim webhooks: 'kullanımdan kaldırma. notice ',' versiyonu. Serbest bırakıldı ',' planı. Değişim.
SDK yayın notları + portal banner.
12) Başarı metrikleri
Benimseme oranı v2 (istek/müşteri başına).
Geriye dönük compat olayları.
Serbest bırakılmadan önce/sonra hata karışımı (4xx/5xx/429 paylaşımları).
Benimseme zamanı medyan.
Destek yükü (biletler/hafta).
Hizmet bedeli.
13) Şablonlar ve örnekler
13. 1 Sürüm başlıkları ve indirimler
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Sürüm politikası (YAML parçası)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 OpenAPI Alan Ekleme Uyumlu
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Serbest bırakma kontrol listesi (MINOR/MAJOR)
KÜÇÜK
- DIFF: kırılmayan, linter yeşili
- Dokümantasyon/SDK güncellendi (örnekler/kodekler)
- Kanarya + otomatik SLO geri dönüşü
- İletişim Planı, Portal Sayfası
- Benimseme ve hata panoları
MAJOR
- RFC/ADR, günbatımı tarihi ve ≥90 penceresi -180 gün
- v1↔v2 köprüsü ve geçiş kılavuzu
- Çift yazma/okuma ve mutabakatlar
- Her iki API + uyarısı ile SDK
- Anahtar entegratörlerle pilot uygulama
15) Uygulama planı (3 yineleme)
1. Vakıf (2 hafta):
CI'da şemaların, lintlerin ve auto-diff'in kaydı; Uyumluluk politikası; 'Amortisman/Günbatımı' başlıkları.
2. Yönetilen sürümler (3-4 hafta):
Kanaryalar, özellik bayrakları, SLO uyarıları; sürüm portalı; SDK 2 şube desteği ile serbest bırakır.
3. Otomasyon ve ölçek (sürekli):
CI'daki tüketicilerin CDC testleri, evlat edinme eğilimleri hakkında gün batımı tahmini, otomatik bildirimler ve hatırlatıcılar.
16) Mini-SSS
Alan türünü majör olmadan değiştirebilir miyim?
Hayır. "Stroka chislo" bile kırılıyor. Yeni bir alana girin, eski alan kullanımdan kaldırılır.
Enum: Değer ekleyebilir misiniz?
Evet, müşteriler hoşgörülü okuyucular ise. Aksi takdirde - önce bir uyarı ve beta.
Eski versiyonun fiyatı ne kadar?
Şimdiye kadar, yeni % ≥95'in benimsenmesi korunmuştur. Politikadaki son tarihi belirleyin.
Toplam
API uyumluluğu bir disiplindir: eklemeli yaklaşım, resmi şemalar ve difhler, kanarya sürümleri, net düşüşler ve yönetilen geçişler. Değişim politikalarını birleştirin, kontrolleri ve iletişimleri otomatikleştirin, benimsenmeyi ölçün - ve güncellemeleriniz istemcileri kırmayı bırakacak ve güvenilirliği kaybetmeden evrimin hızı artacaktır.