API sürüm oluşturma stratejileri

Sürüm oluşturma neden gereklidir

API, istemcilerden daha hızlı değişir. Sürüm oluşturma, entegrasyonları bozmadan özellikleri serbest bırakmanıza ve hataları düzenlemenize olanak tanır, değişim ritüelini ayarlar ve evrimi öngörülebilir kılar. Anahtar: varsayılan katkı değişiklikleri, ana - sadece kırılma, otomatik uyumluluk kontrolleri ve düşünceli gün batımı politikası için.

Temel ilkeler

1. Additive-first: yeni isteğe bağlı alanlar/yöntemler/olaylar - tamam; Silme ve anlam değişiklikleri - büyük.
2. MGC (minimum garanti sözleşmesi) istikrarlıdır; zenginleştirme - yetenekleri aracılığıyla/'? include = '.
3. Toleranslı okuyucu: istemciler bilinmeyen alanları göz ardı eder ve enum uzantılarından sağ kurtulur.
4. Semantik Sürüm Oluşturma: 'MAJOR. MINÖR. Artifaktlar, SDK'lar ve olaylar için PATCH '.
5. Otomatikleştir: şema-diff, linters ve CDC testleri kırılma değişikliklerini engeller.

Sürümün nerede saklanacağı (adresleme mekaniği)

REST/HTTP

URI sürümü:'/v1/orders '- rotası kolay, ağ geçitlerinde uygun. Eksi - fikirlerin evrimini "gizler".
Medya/Başlık: 'Accept: application/vnd. örnek. emirler. v1 + json '- tam format kontrolü; Çürütmek daha zor.
Sorgu sürümü: '? api-version = 1 '- A/B için uygun, ancak önbellek/günlüklerde kaybetmek kolay.
Öneri: Ana hatlar için URI + özellik/yetenek bayrakları ve küçük uzantılar için içerik olumsuzlaması.

gRPC/Protobuf

Paketler/hizmetler: 'Paket ödemeleri. v1; hizmet PaymentsV1; '- açık çizgiler.
Etiket numaralandırma değişmez; Silinen etiketler yeniden kullanılamaz.
Yeni alanlar - 'isteğe bağlı'; breaking new '.v2'.

GraphQL

URL'de açık majörler olmayan şema. @ Kullanımdan kaldırılmış ve geçiş pencereleri aracılığıyla evrim; "Gerçek" majör yeni bir uç nokta şemasıdır.
Kontrol karmaşıklığı/derinliği sözleşmenin bir parçasıdır.

Olay odaklı (Kafka/NATS/Pulsar)

Etkinlik adı: 'ödeme. yetkilendirildi. v1 'türündeki versiyondur.
Schema registry (Avro/JSON Schema/Protobuf) uyumluluk modlarıyla (BACKWARD/FORWARD/FULL).
Major - geçiş dönemi için 'v1've' v2 'çift yayar.

Versiyon Modeli ve Değişim Politikası

Semantik Sürüm Oluşturma

MAJOR - kırılma değişiklikleri: alanları silme/yeniden adlandırma, üyelik anahtarlarını değiştirme, durumların farklı anlamları, geçerliliği sıkılaştırma.
MINOR - katkı maddesi: yeni isteğe bağlı alanlar/uç noktalar/olaylar, toleranslı okuyucuya sahip yeni enum değerleri.
PATCH - sözleşme ve semantiği değiştirmeden düzeltir.

Kullanımdan Kaldırma ve Gün Batımı

Geçersiz ('Deprecated: true', '@ deprecated'), günbatımı tarihi, alternatif ve geçiş kılavuzu yayınlayın.
HTTP'de - 'Sunset', 'Deprecation' başlıkları; olaylarda - ayrı bir '.deprecation. Dikkat edin.
Kaldırılıp kaldırılmayacağına karar vermek için telemetri kullanımı.

Stile Göre Sürüm Oluşturma Stratejileri

REST

/ v1 ,/v2 üzerindeki ana hatlar.
MINOR: şema uzantısı, '? fields = ','? include = '; güvenli enum uzantıları.
Kırılmayan tutarlılık için ETag/If-Match ve idempotent POST.
Hatalar - kararlı biçim ('type', 'code', 'trace _ id').

gRPC

Kırmak için yeni hizmetler/yöntemler tanıtın: 'PaymentsV2. Yakala '.
Hata durumları ve son tarih semantiği sözleşmenin bir parçasıdır; Değişim - yeni yöntem/hizmet.
Akış: Mesaj sırasını kabul edin ve minör olarak değiştirmeyin.

GraphQL

Alanları ve türleri serbestçe ekleyin; Silme işlemleri - '@ depressed' + geçiş penceresi aracılığıyla; Büyük yeniden tasarım - yeni şema ('/graphql-v2 ').
İç gözlem ve açıklamalar - müşteri göçleri için olması gereken.

Olaylar

Çekirdek vs zenginleştirilmiş: Çekirdek kararlıdır, yakındaki yaşamı zenginleştirir ve ayrı ayrı sürümlenir.
Bölüm anahtarı ana satır içinde değişmez.
Büyük göçler - 'çift yayma' + projeksiyon/tüketici göçü.

Müzakere ve yetenek bayrakları

Yetenekler: istemci 'X-Capabilities: risk_score,price_v2' gönderir; Sunucu genişletilmiş bir görünümle yanıt verir.
Tercih (HTTP) ve kısmi yanıtlar için ipuçları.
Soketlerde/akışlarda - desteklenen uzantıların bir listesini içeren bir el sıkışma mesajı.

Büyük versiyonların ağrısız serbest bırakılması

1. RFC/ADR: Neden majör gerekli, ne kırılır, risk matrisi.
2. Çift çalıştırma: 'v1've' v2'nin paralel başlatılması (çift olay yayınlama, iki ağ geçidi yönlendirmesi, trafik yansıtma).
3. Geçiş adaptörleri: Ağır istemciler için 'v1↔v2' proxy'ler/çeviriciler.
4. Kanarya: ağ geçidinde müşteri grubu/konu/etikete göre.
5. Günbatımı planı: tarihler, iletişim, standlar, test verileri, kullanım izleme.

Platform ve altyapı rolleri

API Ağ Geçidi/Servis Ağı: sürüme, başlıklara, yollara göre yönlendirme; Sürüm başına auth и hız sınırı.
Schema Registry & Catalog: Source of Truth for Specs/Schemes with Diffuse History [Şema Kayıt Defteri ve Kataloğu: Dağınık Geçmişe Sahip Özellikler/Şemalar İçin Doğruluk Kaynağı].
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Gözlem: Sürüm günlüklere/izlere/metriklere dahil edilmelidir.

Sürüm testi

PR'de şema-diff: blok kırma.
Tüketici Odaklı Sözleşmeler: Sağlayıcı, gerçek tüketici sözleşmelerine karşı test edilir.
Altın örnekler: Sürümlere referans yanıtları.
E2E kanarya: p95/p99 karşılaştırması, sürümler arasındaki hatalar ve zaman aşımları.
Olaylar için tekrar oynatma: Projeksiyonlar hiçbir tutarsızlık olmadan v2'ye yeniden birleştirilir.

Veri ve veritabanı taşıma

REST/gRPC için: veritabanı geçişleri, genişletme ve sözleşme yoluyla koordine edilir (bir sütun ekleyin - yazmaya başlayın - anahtar okuma - eski sil).
Olaylar için: çift yayım ve tüketici geçişi; Bazen - günlüğü yeni projeksiyonlarda tekrar oynatmak.
"Büyük patlamalar" yapmayın - geri dönüşlerle adımlara ayrılın.

Güvenlik ilişkisi

Sürüm başına kapsamlar: v1/v2 için bireysel OIDC kapsamları/rolleri.
Belirtecin sırları/iddiaları sözleşmenin bir parçasıdır; değişimleri = majör.
PII/PCI - gereksiz yere yükü genişletmeyin; Yeni alanlar - en az ayrıcalıkla.

Anti-desenler

Swagger-wash: spesifikasyon güncellendi, sunucu değil (veya tam tersi).
Protobuf etiketlerini yeniden kullanmak, verilerin sessiz bir şekilde bozulmasıdır.
Majör olmadan enum anlamlarını değiştirmek.
Global'/v2 '"kozmetik uğruna": kırılma gerçeği olmayan bir versiyon.
Gün batımı/kullanım metriklerini unuttum: eski sürümü güvenli bir şekilde kaldırmak mümkün değildir.
Farklı ana dallar için ortak bir konu: emir ve anahtarların bir karışımı.

Yayın öncesi kontrol listesi

• Değişiklikler katkı maddesidir veya ayrı bir ana hat hazırlanır.
• Linters ve şema-diff yeşildir (kırılma taranmadı).
• Güncellenmiş SDK/örnekler/belgeler, uyumluluk dipnotları.
• Müşteriler üzerinde etkin hoşgörülü okuyucu; Enum-fallback testi yapıldı.
• Büyük için - çift çalışma planı, adaptörler, kanarya, günbatımı tarihleri ve posta.
• Metrikler/günlükler/yollar bir sürüm ve onun tarafından segmentasyon içerir.
• v1↔v2 karşılaştırmak için bir stand ve altın setler var.
• Olaylar için, şema kayıt defteri GERİ/TAM modundadır, bölüm anahtarları değişmez.

Örnek şablonlar

REST (URI + müzakere)

Rota: '/api/v2/orders/{ id} '

Заголовок: 'Prefer: include = öğeler, müşteri', 'X-Capabilities: risk_score'

Kullanımdan kaldırma: 'Sunset: 2026-06-30', 'Bağlantı: ; rel = "alternatif" '

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Olaylar

'ödeme. yakalandı. V2 '(çekirdek) ve' ödeme. zenginleştirilmiş. v2 '(ayrıntılar).
Geçiş dönemi için, üretici 'v1've' v2'ye gider.

SSS

'/v2 'tam olarak ne zaman gerekli?
Değişmezler/semantikler değiştiğinde, alanlar/yöntemler kaldırılır, tanımlayıcıların biçimi, bölümleme anahtarı, SLA/zamanlamalar değişir, böylece istemciler kırılır.

REST'te açık bir versiyon olmadan yaşayabilir misiniz?
Sadece küçük sistemler için. Dış entegrasyonlar için, açık ana çizgiler daha iyidir.

Eski versiyonu ne kadar süre saklayabilirsiniz?
Ekosisteme bağlıdır. Dış ortaklar için, genellikle erken bildirim ve kanarya ile 6-12 ay.

Olay sürümlerinin API'den farkı nedir?
Olaylar - sadece ekle; yeni semantik = yeni tip '.v2've dual-emit. Bölümleme anahtarı sözleşmenin bir parçasıdır.

Sonuç

Sürüm stratejileri süreç ve araçlardır: varsayılan katkı evrimi, açık ana çizgiler, yetenek-müzakere, çift çalışma ve gün batımı. Otomatik uyumluluk kontrolleri, kullanım telemetrisi ve dokümantasyon disiplini ekleyin - API'leriniz "gece geçişleri've müşterilerinizde beklenmedik düşüşler olmadan hızla gelişecektir.