Tarihçe: Monolitik mimarilerde, API değişiklikleri entegrasyon test aşamaları aracılığıyla yönetilebiliyordu. Ancak, mikro hizmetler benimsenmesiyle birlikte, hizmet bağımlılıklarının yayılması, tek bir kırıcı değişikliğin onlardan yüzlercesinde arızalara yol açtığı bir "sürüm cehennemi" oluşturdu. Bu, manuel OpenAPI incelemelerinden, CI/CD hatlarında otomatik, sözleşme odaklı doğrulama kapılarına geçişi zorunlu kıldı.
Problem: Geleneksel testler, bir API'nin izole olarak çalıştığını doğrularken, istek/yanıt şemalarındaki değişikliklerin mevcut tüketicilerle örtük sözleşmeleri ihlal edip etmediğini tespit etme konusunda başarısızdır. Manuel spesifikasyon incelemeleri hata eğilimlidir ve yüzlerce iç içe geçmiş hizmet arasında ölçeklenemez, bu da kullanımda olan eski alanların kaldırılması durumunda üretim olaylarına yol açar.
Çözüm: OpenAPI fark analizini tüketici odaklı sözleşme testi ile entegre eden çok katmanlı bir doğrulama hattı uygulayın. Değişiklikleri kırıcı (alan kaldırma, tür değişiklikleri) veya kırıcı olmayan (isteğe bağlı eklemeler) olarak kategorize etmek için Optic veya Swagger Diff gibi araçları kullanın. Sağlayıcı değişikliklerinin kaydedilmiş tüketici beklentilerini karşıladığını doğrulamak için Pact'i entegre edin. Tespit edilen değişikliklerin şiddetine dayanarak gereken sürüm artışlarını hesaplayan ve artış yetersizse dağıtımları engelleyen anlamlı sürümleme otomasyonunu zorunlu kılın.
validate_api_compatibility: stage: test script: - optic diff openapi.yaml --base main --severity breaking - pact-verifier --provider-app-version $CI_COMMIT_SHA --publish-verification-results - python scripts/check_semver.py --schema-diff-report optic-report.json rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"
Ekibimiz on iki iç mikro hizmet ve üç dış bankacılık partnerine hizmet eden bir Ödeme Geçidi APIsini sürdürüyordu. 3D Secure 2.0 doğrulama alanlarını eklemek için yapılan rutin bir iyileştirme sırasında, bir geliştirici, eski transactionReference dize alanını kaldırarak yerine bir nesne yapısı getirdi.
Problem tanımı: Değişiklik, yeni yapı veriyi doğru bir şekilde işlediği için birim ve entegrasyon testlerini geçmiştir. Ancak, üç eski muhasebe mikro hizmeti hala düz dize alanını bekliyordu. Manuel OpenAPI incelemesi, bu yapısal değişikliğin kırıcı doğasını göz ardı etti. Dağıtım sırasında, uzlaşma görevleri serileştirme hataları ile başarısız oldu ve bu dört saatlik bir kesintiye neden oldu.
Farklı çözümler düşünülmüş:
Kontrol listesi ile manuel gözden geçirme: Tüm OpenAPI değişikliklerini incelenmesi için kıdemli mühendislerin gözden geçirmesini zorunlu kılınan bir kırıcı değişiklik kontrol listesi kullanma. Bu yaklaşım insan dikkati gerektirir ancak baskı altında temel olarak güvenilmez, hızlı dağıtım döngüleri ile ölçeklenemez ve gizli tüketici bağımlılıklarını hesaba katamaz.
Otomatik JSON Şeması karşılaştırması: Herhangi bir yapısal farkı hata olarak işaret eden basit bir diff aracı uygulayın. Bu hızlı geri bildirim sağlar ancak ekleme değişikliklerini (yeni isteğe bağlı alanlar) ihlaller olarak ele alarak aşırı yalancı pozitifler üretir, bu da ekiplerin karmaşık istisna listelerini sürdürmeye zorlar ve sonunda uyarılara karşı aşırı yüklenme nedeniyle uyarıları görmezden gelmelerine neden olur.
Tüketici sözleşme testi ile anlamlı sürümleme kapıları: Tüketici odaklı sözleşmeler için Pact'i dağıtın ve OpenAPI fark analizi için Optic CLI'yi birleştirin. Bu, değişiklikleri gerçek kaydedilmiş tüketici etkileşimlerine karşı doğrular, sadece gerçekten kırıcı değişikliklerin arızalara neden olmasını sağlar. Otonom şekilde anlamlı sürüm artışlarını otomatik olarak önerir ve eski alanların kaldırılması zaman çizelgelerini korur. Dezavantajı, tüketici ekipleri ile onboarding için gerekli başlangıç yatırım maliyetidir ve sözleşme belgeleri için depolama yüküdür.
Seçilen çözüm ve mantık: Tüketici sözleşme testini seçtik çünkü bu, bağımsız dağıtım ihtiyacına uygun düşüyordu ve zincirleme arızaları önlüyordu. Manuel incelemelerin aksine, yatay ölçeklenebilir. Temel diff araçlarının aksine, anlamlı etkileri anlıyor. Başlangıç maliyetini, ilk olarak yalnızca kritik hizmet yolları için sözleşme testlerine zorunlu kılarak kabul ettik.
Sonuç: Kırıcı değişiklikler, sonraki sekiz ay boyunca üretim sürümlerinden kaldırıldı. Dağıtım sıklığı, ekiplerin otomatik kapılara güvenmesi nedeniyle iki haftada birden günlük hale geldi. Aynı yeniden düzenleme daha sonra denendiğinde, Pact doğrulaması hemen pull request'te başarısız oldu ve eski hizmetle uyumsuzluğu vurguladı.
REST API doğrulamasında sözdizimsel kırıcı değişiklikler ile anlamsal kırıcı değişiklikler arasında nasıl ayrım yaparsınız?
Sözdizimsel değişiklikler, alan kaldırma veya tür değiştirme gibi OpenAPI şeması farkları ile tespit edilebilen yapısal değişiklikleri içerir. Anlamsal değişiklikler yapıların korunmasına rağmen davranışı değiştirir, isteğe bağlı bir parametre için varsayılan değerin değiştirilmesi veya dönen dizilerin sıralama düzeninin değiştirilmesi gibi. Saf şema doğrulama anlamsal kırılmaları gözden kaçırır, bu da sözleşme testleri veya gölge trafik karşılaştırması ile değiştirilen iş mantığı çıktılarının tespit edilmesini gerektirir.
Expand-contract oluşturma kalıbı nedir ve otomasyon bunu nasıl zorlamalıdır?
Expansiyon-kontrakt kalıbı, yeni işlevselliğin eski işlevselliğin yanında eklenmesini (genişletme), tüketicilerin taşınmasını, ardından eski kodun kaldırılmasını (sözleşme) gerektirir. Otomasyon, alanın depreceye girme sürelerini izlemeli ve deprece alanlar hattı gereğince kaldırıldığında yapılar başarısız olmalıdır. Ayrıca, sistem, bir geri alma zorlayıcısı ile birlikte, eski uç noktalarda sıfır trafik doğrulamak amacıyla telemetriyi izlemesi gerekir, böylece yalnızca kod düzeyinde uyumluluğun ötesinde gerçek tüketici hazır olduğundan emin olunmalıdır.
Tüketiciler dışındaki üçüncü taraflar olduğunda API uyumluluğunu nasıl doğrularsınız, bunlar sözleşme test hattınıza katılamaz?
Pact iki yönlü sözleşmelerin mümkün olmadığı dış tüketiciler için, trafik gölgeleme ve VCR testleri kullanarak sentetik tüketici simülasyonu uygulanır. Üretim kalıplarını kaydedin, temsili mock'lar oluşturmak için yeni API sürümlerine karşı yeniden oynatın. Bu, otomatik geri alma tetikleyicileri olan kanton dağıtımları ile birleştirilmeli ve çoklu çeyreklerde zorunlu deprece bildirimi politikaları belirlenmiş LTS politikaları sürdürülmelidir.