API sürüm oluşturma ve sözleşme uyumluluğu

TL; DR

Uyumluluk disiplindir, şans değil. Açık bir sürüm politikası (SemVer) tutun, matematiği değiştirin (ne "kırılır", ne yapmaz), sözleşme testleri, şema kayıtları ve Sunset prosedürleri. Para ve uyumluluk için - vN ile sıkı REST/gRPC, UI toplamaları için - '@ kullanımdan kaldırıldı'ile evrimsel GraphQL. Her zaman: kanarya trafiği, geriye dönük uyumluluk ≥ bir sürüm döngüsü, geçiş kılavuzları, alan telemetri.

1) Temel kavramlar ve hedefler

Geriye dönük uyumlu (BC): Eski istemciler yeni sunucu için uygundur.
İleri uyumlu (FC): Yeni istemciler eski sunucu için uygundur (sınırlı).
Tel uyumluluğu: "Tel" üzerindeki format bozulmaz (özellikle gRPC/Protobuf için önemlidir).
SemVer: 'Binbaşı. MINÖR. PATCH '- sözleşmeyi kır - MAJOR'u yükselt.

Amaç, yıkıcı değişiklikleri en aza indirmek ve öngörülebilir geçiş pencereleri sağlamaktır.

2) Değişim Matrisi: Yapabilecekleriniz ve yapamadıklarınız

3) Farklı API stilleri için politikalar

3. 1 REST

URI'deki sürüm ('/v1/... ') veya domain (' api-v1. '). Başlık sürümü - yalnızca dahili durumlar için.
Ekle, silme: yeni alanlar - tamam, eski - diyagramda 'kullanımdan kaldırıldı'olarak işaretleyin ve en az bir döngü için bırakın.
Durumlar/hatalar: kodları ve yapı 'hatasını değiştirmeyin. kod/hata. mesaj/hata. Ayrıntılar '.
Idempotency değişmez: "Idempotency-Key'ile güvenli bir" POST'u "davranışsal olarak farklı'bir meydan okumaya dönüştürmeyin.

3. 2 gRPC/Protobuf

Alan numaraları kutsaldır: silinen numaraları tekrar kullanmayın, 'ayrılmış'olarak işaretleyin.
Sadece yeni isteğe bağlı/repit alanları ekleme; "zor zorunlu" - doğrulama yoluyla, "yeniden kazanılmış'değil.
Sürüm paketleri: 'ödemeler. v1 ',' ödemeler. v2 '.
Servis uyumluluğu: yeni RPC'ler - yeni bir yöntem; Eskilerin davranışlarını değiştirmeyiz.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 GraphQL

V2 olmadan Evrim: alanları/türleri ekleyin; silme - pencerenin duyurusu ile '@ depressed (reason)' aracılığıyla.
Kalıcı Sorgular: Genel istemciler için, sorguların beyaz listesini kullanın - uyumluluğu kontrol etmek daha kolaydır.
Alan düzeyinde authZ ve telemetri: silmeden önce hangi alanların gerçekten kullanıldığını bilir.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 Webhooks

Yoldaki sürüm ('/webhooks/v1/payments ') ve sabit olay zarfı (' event _ id ',' type ',' ts ',' data ').
İmzaları/NMAS'ı değiştirmeyin; Yeni algoritmalar - bir bayrak ile bir seçenek olarak.
Uzantılar - sadece yeni alanların verileri aracılığıyla. 've 'başlıklar' - eskileri silmeden.

4) Gateway API ve sürüm yönlendirme

Kural tabanlı yönlendirme:'/v1 'önekine göre,' X-Api-Version 'başlığına göre, etki alanına göre.
Gölge/Kanarya: Yeni sürümdeki üretim trafiğinin bir kısmını "gölgelere" yansıtın, cevapları karşılaştırın.
Sürüm başına oran/Kotalar: Geçiş sırasında eski istemcileri korur.

• 'Sunset: ' - sürüm kapatma tarihi
• 'Amortisman: doğru' - sürüm eskimiş olur
• 'Bağlantı: ; rel = "amortisman" '- on changelog/migration guide

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) Şema kayıtları ve sözleşmeleri

OpenAPI/JSON Şeması для REST; Protobuf tanımlayıcıları для gRPC; SDL kayıt defteri для GraphQL.
CI kontrolleri: linters + PR'de "breaking-changes check".
Tüketici Odaklı Sözleşmeler (CDC): Tüketici testleri (Pact/analog) - göze çarpmayan kırılmalara karşı koruma.
Changelog: makine tarafından okunabilir (örneğin, 'CHANGELOG. md '+ kayıt defterindeki serbest bırakma notları).

6) Alanların evrimi: başparmak kuralları

ID/anahtarlar: yeni bir alan '_ v2've bir geçiş dönemi olmadan biçimi (UUID↔int) değiştirmeyin.
Zaman/para birimi: UTC ISO-8601/epoch ve amount_minor + para birimini tutun; ölçeklendirmeyin (pennies/cents).
Enum: değer ekle - tamam; Eskilerin anlamını değiştirme. REST için, ints değil dize değerleri verin.
Pagination: imleç tabanlı daha kararlı; İmlecin semantiğini değiştirmeyin.

7) Tükenme ve "Günbatımı" prosedürü

1. Duyuru (T-90/60): changelog, ortaklara posta, 'Amortisman/Günbatımı' başlıkları.
2. Yinelenen dönem: V1 ve V2 paralel olarak çalışır; V1, yanıtlarda/günlüklerde uyarılarla donatılmıştır.
3. Kullanım telemetrisi: Başka kim V1'i arar? Nokta bağlantıları.
4. Dondurucu V1: sadece hata düzeltmeleri/özellik yok.
5. Sunset-410 gitti veya geçiş talimatı blok sayfası.

8) Ağrısız sürümler: döşeme stratejileri

Mavi/Yeşil veya Ağırlıklı yönlendirme: 1-5-25-50-100 % trafik.
Uyumluluk penceresi: Harici API'ler için en az 1-2 küçük sürüm, daha sık 6-12 ay.
Yükseltme yapmadan yeni mantık alanları/dalları eklemek için Özellik Bayrakları.
Okuma/Yazma-bölme: önce yeni bir alanı okumak için destek ekleyin, ardından yazmaya başlayın.

9) Birlikte çalışabilirlik testi (uygulama paketi)

Eski sürümlerden gelen yanıtlar için altın testler.
Devrelerin diff testleri: CI'da kırılma yok.
Yeniden oynatma üretimi V2 (gölge) için sahneleme üzerinde çalışır.
Geri/İleri komut dosyaları: Eski sunucudaki yeni istemci ve tersi (FC'nin geçerli olduğu durumlarda).
Webhook'ların sözleşme testleri: imza, format, zaman doğrulaması.

10) Sürüm oluşturma sürecinin metrikleri ve SLO'ları

Son MINOR'daki müşterilerin %'si (hedef ≥ Sunset'ten önce %80).
Sürüm başına uyumluluk/kullanılamama hataları (hedef 0).
Eski çağrıların paylaşımı (Sunset'e azalan).
İstemci geçiş süresi (medyan/p95).
Sürümler arasında gecikme/regresyon deltası (temelden daha kötü değil).

11) Eser örnekleri

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12) Bitişik kanalların sürümleri

SDK/CLI: SemVer + API sürüm bağımlılığı, README'de öngörülen uyumluluk.
Olaylar/akışlar (WS/Kafka): sürüm in 'envelope. 'versiyonu; Yeni özellikler - isteğe bağlı; Dedup ve özgeçmişler sürümler arasında aynı şekilde çalışır.
Raporlama/CSV: dosya adı/başlığında sürüm; Sağ tarafa sütun ekleyin, sıra/türleri değiştirmeyin.

13) Yönetişim ve roller

Sözleşme sahibi (domain owner), Steward API (rules and linters), Release Manager (Sunset/communications).
Değişiklikleri kırmak için RFC süreci: iş gerekçesi, geçiş planı, eserler, tarihler.
Birleştirilmiş API dizini: Diyagramların, sürümlerin, Günbatımı takviminin, kişinin görünür olduğu yerler.

14) Anti-desenler

"Sessiz" molalar: bir sürüm olmadan durum/hata/alan türünü değiştirin.
Protobuf numaralarının yeniden kullanımı - tekrar ve eski müşterileri yok eder.
Alan telemetrisi olmadan GraphQL - dokunmatik kaldırma.
Küresel v2 toplamı - nokta evrimi yerine megamigrasyon.
Genel API için sorgu parametresindeki sürüm açık olmayan ve savunmasız bir şemadır.
Göç rehberleri ve örnekleri yoktur - ortaklar durur, son tarihler bozulur.

15) Yeni sürümün check-list sürümü

• Güncellenmiş şema (OpenAPI/Protobuf/SDL), linters ve breaking-checks geçti.
• Entegrasyon ve sözleşme testleri (CDC) eklendi.
• SDK/örnek kod/geçiş kılavuzu ve Changelog hazır.
• Kullanımdan kaldırma/Günbatımı etkin (eski sürüm) + Sayfa nasıl taşınır.
• Kanarya/Gölge planı, metrikleri karşılaştıran uyarılar ve panolar.
• Geriye dönük uyumluluk kararlaştırılan bir süre boyunca korunur.
• Geri alma planı ve risk matrisi kabul edildi.

Özet

Kararlı bir API,'bir kez ve herkes için'değil, bir süreçtir. "Kurallara göre yaşa: SemVer + add-only evolution + devre kaydı + sözleşme testleri + Sunset prosedürleri. Ayrı stiller (REST/gRPC/GraphQL) ve politikaları, Gateway API'sine yönlendirme sürümleri, kanaryaları açın, efekti ölçün. Bu şekilde "sürprizleri kırmaktan" kaçınacak, ortak entegrasyonunu hızlandıracak ve parasal ve uyumluluk açısından kritik alanlar için öngörülebilirliği koruyacaksınız.