Gerekli alan, tür, enum, API yolu, parametre ve yanıt değişikliklerini güvenli bir sözleşme yayın akışında inceleyen uygulamalı rehber.
Uyumluluğu sürüm numarasından değil tüketiciden tanımlayın
Bir değişikliğin kırıcı olup olmadığı, yalnızca şemanın geçerli olmasına değil mevcut tüketicilerin hangi alanları gönderip okuduğuna bağlıdır. Önce desteklenen istemcileri, saklanan eski kayıtları ve geri alma süresini yazılı hale getirin.
Yeni zorunlu alan, tür daraltma veya enum değerinin kaldırılması genellikle eski üreticiyi ya da okuyucuyu etkiler. Yeni isteğe bağlı alan çoğunlukla daha güvenlidir; yine de additionalProperties: false kullanan tüketiciler için sorun yaratabilir.
- Tüketici ve üretici listesini çıkarın.
- Geri uyumluluk penceresini tarih ile belirtin.
- Kararı yalnızca sürüm etiketine bırakmayın.
İki belgeyi aynı kapsamda karşılaştırın
Eski ve yeni JSON Schema dosyalarının aynı kök nesneyi temsil ettiğini doğrulayın. OpenAPI karşılaştırmasında ise sunucudan yayınlanan gerçek belgeyi kullanın; farklı ortamların veya yarım oluşturulmuş dosyaların diff'i yanlış alarm üretir.
ByteQuant doğrudan properties, required, type, enum ve additionalProperties değişikliklerini; OpenAPI tarafında yol, yöntem, parametre zorunluluğu ve yanıt kaldırılmasını tarar. Dış $ref ve koşullu şemalar için uzman araç ve gerçek çözümleme gerekir.
Anonim fixture ile değişikliği yeniden üretin
Her bulgu için kişisel veri içermeyen en küçük eski istek, yeni istek, eski yanıt ve yeni yanıt örneğini saklayın. Yalnızca ideal örnek değil, eksik alan, bilinmeyen enum, boş dizi ve büyük payload gibi sınır vakalarını da çalıştırın.
Bir şema diff'i davranışı kanıtlamaz. Sunucunun varsayılan değer, hata kodu, sıralama ve sayfalama davranışı sözleşme testinde ayrıca gözlenmelidir.
Kırılmayı geçiş planına dönüştürün
Kırıcı değişiklik gerekiyorsa önce yeni alanı isteğe bağlı kabul eden sürümü yayınlayın, üreticileri taşıyın ve ölçümden sonra zorunluluğu etkinleştirin. Yol veya yanıt kaldırırken paralel sürüm, kullanımdan kaldırma tarihi ve makinece okunabilir uyarı sağlayın.
Değişiklik notu yalnızca 'schema updated' dememelidir; etkilenen işlem, eski davranış, yeni davranış, geçiş örneği, son tarih ve geri dönüş yolu görünür olmalıdır.
Yayın kapısını kanıtla kapatın
Yerel ön kontrol, anonim fixture testleri, tüketici testleri ve staging gözlemi aynı kayıt altında birleşmelidir. Onay sahibini ve kabul edilen riskleri yazın; otomatik araç karar sahibi değildir.
Üretim sonrası hata oranı, 4xx dağılımı ve eski istemci kullanımı izlenmelidir. Hassas payload veya erişim anahtarı rapora, CI çıktısına ya da paylaşılabilir URL'ye konulmamalıdır.
- Yayın öncesi ve sonrası ölçümü eşleştirin.
- Geri alma ölçütünü önceden belirleyin.
- Raporları sentetik veride tutun.
Bu rehberle birlikte kullanabileceğiniz araçlar
Aşağıdaki araçlar aynı kararın farklı kanıtlarını üretir. Her çıktıyı gerçek ortam, sözleşme veya yetkili kaynakla ayrıca doğrulayın.
- JSON Schema Geriye Uyumluluk Denetleyici
- OpenAPI Kırılma Değişikliği Denetleyici
- JSON Diff / Yapısal Karşılaştırma
- OpenAPI Endpoint Envanteri
Okuduklarınızı güvenli bir denemeye dönüştürün
“JSON Schema ve OpenAPI Sözleşmelerini Tüketiciyi Bozmadan Geliştirme” adımlarını gerçek veriye geçmeden önce sentetik bir örnekle JSON Schema Geriye Uyumluluk Denetleyici üzerinde deneyin. İşaretler yalnızca bu sekmede tutulur.
Rehberi tekrarlanabilir bir kontrole dönüştürün
“JSON Schema ve OpenAPI Sözleşmelerini Tüketiciyi Bozmadan Geliştirme” için aşağıdaki 4 araçlık kontrol planını kullanın. Hedef: Gerekli alan, tür, enum, API yolu, parametre ve yanıt değişikliklerini güvenli bir sözleşme yayın akışında inceleyen uygulamalı rehber. Gerçek veri yerine güvenli bir örnekle başlayın; her adımın beklenen sonucunu ve kabul kararını kaydedin.
JSON Schema Geriye Uyumluluk Denetleyici
- Hazırlık
- Eski şemayı ilk alana, yeni şemayı ikinci alana yapıştırın.
- Uygulama
- Yapısal karşılaştırmayı çalıştırın.
- Kabul kontrolü
- Her bulguyu gerçek örnekler ve tüketici testleriyle doğrulayın.
- Beklenen çıktı
- ayrıştırılmış yapı, alan ölçümleri ve açık sözdizimi bulguları. İki JSON Schema sürümünde tüketicileri bozabilecek değişiklikleri yapısal olarak bulun.
OpenAPI Kırılma Değişikliği Denetleyici
- Hazırlık
- Eski ve yeni OpenAPI JSON belgelerini ekleyin.
- Uygulama
- Kırılma adaylarını üretin.
- Kabul kontrolü
- Sunucu davranışı, örnek istek ve SDK testleriyle kararı doğrulayın.
- Beklenen çıktı
- normalize edilmiş web yapılandırması, bileşen envanteri ve uygulanabilir inceleme notları. İki OpenAPI JSON belgesinde kaldırılan yol, yöntem, parametre ve yanıtları raporlayın.
JSON Diff / Yapısal Karşılaştırma
- Hazırlık
- Eski ve yeni geçerli JSON değerlerini iki alana yapıştırın.
- Uygulama
- Yapısal karşılaştırmayı çalıştırıp yol ve değişiklik türü filtrelerini inceleyin.
- Kabul kontrolü
- Raporu kopyalayın veya JSON olarak indirin; anlamlı değişiklikleri şemayla ayrıca doğrulayın.
- Beklenen çıktı
- ayrıştırılmış yapı, alan ölçümleri ve açık sözdizimi bulguları. İki JSON değerinde eklenen, silinen, değişen ve türü değişen yolları bulun.
OpenAPI Endpoint Envanteri
- Hazırlık
- OpenAPI JSON belgesini yükleyin.
- Uygulama
- Endpoint envanterini oluşturun.
- Kabul kontrolü
- Eksik güvenlik ve operationId alanlarını kaynak kodda doğrulayın.
- Beklenen çıktı
- normalize edilmiş web yapılandırması, bileşen envanteri ve uygulanabilir inceleme notları. OpenAPI JSON belgelerinden yöntem, yol, etiket ve güvenlik özetini çıkarın.
JSON Schema Geriye Uyumluluk Denetleyici için şu sınır geçerlidir: Şema, kodlama ve veri kaybı varsayımlarını hedef sistemde doğrulayın. Bu koşul karşılanmıyorsa çıktıyı zincirin sonraki adımına aktarmayın.
“JSON Schema ve OpenAPI Sözleşmelerini Tüketiciyi Bozmadan Geliştirme” kaydında hassas içeriği değil; araç adını, seçilen ayarı, tarayıcı sürümünü ve “API sürüm incelemesi — İki JSON Schema sürümünde tüketicileri bozabilecek değişiklikleri yapısal olarak bulun.” için kabul/red gerekçesini tutun. Böylece kontrol gerçek veriyi çoğaltmadan tekrarlanabilir.
“JSON Schema ve OpenAPI Sözleşmelerini Tüketiciyi Bozmadan Geliştirme”, apı ve veri sözleşmeleri kapsamındaki görünür ByteQuant davranışı ile yeniden üretilebilir ürün kontrolleri karşılaştırılarak hazırlandı. Sınırlar ve kabul ölçütleri karar desteği sunar; hukuki ya da güvenlik danışmanlığı yerine geçmez.