API'ler için sözleşme testleri: hızlı ekiplerde kırıcı değişiklikleri önleyin

Neden kırıcı API değişiklikleri sürümlere karışmaya devam ediyor

Çoğu ekip birden fazla istemciye hizmet eden tek bir API ile çalışır: bir web uygulaması, bir iOS uygulaması, bir Android uygulaması ve bazen iç araçlar da. Herkes aynı uç noktalarda anlaştığını düşünse bile, her istemci API'ye biraz farklı şekilde güvenir. Bir ekran bir alanın her zaman var olmasını beklerken, başka bir ekran o alanı yalnızca bir filtre uygulandığında kullanabilir.

Gerçek sorun bu parçalar farklı zamanlarda yayınlandığında ortaya çıkar. Backend değişiklikleri günde birkaç kez canlıya geçebilir, web hızlıca deploy ederken, mobil sürümler inceleme döngüleri ve kademeli dağıtımlar nedeniyle daha yavaş ilerler. Bu zaman farkı sürpriz kırılmalara yol açar: API en yeni istemci için güncellenir, ama dünün mobil derlemesi hâlâ kullanımdadır ve artık işleyemeyeceği yanıtlar alır.

Bunlar olduğunda belirtiler genellikle saklı olmaz:

• Bir alan yeniden adlandırıldığı veya taşındığı için aniden boşalan bir ekran
• Beklenmeyen null'lar veya eksik nesneler nedeniyle çökme
• Yeniden üretmesi zor “Bir şey bozuldu” destek talepleri
• Bir backend deployundan hemen sonra hata kayıtlarında ani artış
• Kök nedeni düzeltmek yerine savunmacı kod ekleyen hata düzeltme sürümleri

Manuel test ve QA genellikle bu sorunları kaçırır çünkü riskli durumlar mutlu yol (happy path) değildir. Bir testçi “Sipariş oluştur”un çalıştığını doğrulayabilir ama eski bir uygulama sürümünü, kısmen doldurulmuş bir profili, nadir bir kullanıcı rolünü veya bir listenin boş olduğu yanıtı denemeyebilir. Önbellekleme, özellik bayrakları ve kademeli dağıtımlar ekleyince, bir test planının kapsayabileceğinden çok daha fazla kombinasyon ortaya çıkar.

Tipik bir örnek: backend status: "approved" değerini yerelleştirmeyi desteklemek için status: { code: "approved" } olarak değiştirir. Web uygulaması aynı gün güncellenir ve sorun görünmez. Ancak mevcut iOS sürümü hâlâ bir string beklemekte, yanıtı ayrıştırmada başarısız olmakta ve kullanıcılar girişten sonra boş bir sayfa görmektedir.

İşte bu yüzden API'ler için sözleşme testi vardır: QA'nın yerini almak için değil, bu “en yeni istemcimde çalışıyor” değişikliklerini üretime ulaşmadan önce yakalamak için.

Sözleşme testi nedir (ve ne değildir)

Sözleşme testi, bir API tüketicisi (web uygulaması, mobil uygulama veya başka bir servis) ile bir API sağlayıcısının (backend) birbirleriyle nasıl konuşacakları konusunda anlaştığı bir yoldur. Bu anlaşma sözleşmedir. Bir sözleşme testi tek bir basit şeyi kontrol eder: sağlayıcı, tüketicinin güvendiği şekilde davranmaya devam ediyor mu, değişikliklerden sonra?

Pratikte, API'ler için sözleşme testi birim testleri ile uçtan uca testler arasına girer. Birim testleri hızlı ve yereldir, ama paylaşılan sınırı değil iç kodu test ettikleri için ekipler arasındaki uyumsuzlukları kaçırabilirler. Uçtan uca testler birçok sistemi kapsayan gerçek akışları çalıştırır ama daha yavaştır, bakımı zordur ve çoğunlukla bir API değişikliğiyle alakasız nedenlerle başarısız olur (test verisi, UI zamanlaması, kararsız ortamlar).

Bir sözleşme büyük bir doküman değildir. Tüketicinin göndereceği istekleri ve alması gereken yanıtları odaklanmış şekilde açıklar. İyi bir sözleşme genellikle şunları kapsar:

• Uç noktalar ve metodlar (örneğin POST /orders)
• Gerekli ve isteğe bağlı alanlar, tipleri ve temel kurallar
• Durum kodları ve hata yanıtı biçimi (örneğin 400 ile 404 arasındaki fark)
• Başlıklar ve kimlik doğrulama beklentileri (token mevcut, content-type)
• Önemli varsayılanlar ve uyumluluk kuralları (bir alan eksikse ne olur)

Aşağıda sözleşme testinin erken yakalayacağı kırılma tipine basit bir örnek var: backend total_price alanını totalPrice olarak yeniden adlandırır. Birim testleri yine de geçebilir. Uçtan uca testler o ekranı kapsamayabilir veya daha sonra kafa karıştırıcı bir şekilde başarısız olabilir. Sözleşme testi hemen başarısız olur ve tam olarak hangi uyuşmazlık olduğunu gösterir.

Sözleşme testinin ne olmadığını netleştirmek faydalıdır. Performans testi, güvenlik testi veya tam kullanıcı yolculuğu testlerinin yerini almaz. Ayrıca her mantık hatasını yakalayamaz. Yaptığı iş, hızlı ekiplerde en yaygın sürüm riskini azaltmaktır: istemciyi sessizce kıran “küçük” API değişiklikleri.

Eğer backend'iniz sık sık üretiliyorsa veya değişiyorsa (örneğin AppMaster gibi bir platformda API'leri yeniden ürettiğinizde), sözleşme testleri pratik bir emniyet ağıdır çünkü her değişiklikten sonra istemci beklentilerinin hala geçerli olduğunu doğrular.

Web ve mobil ekipler için bir sözleşme yaklaşımı seçin

Web ve mobil sık sık yayınlarken zor olan kısım “API'yi test etmek” değil, her istemci için neyin değişmemesi gerektiği konusunda anlaşmaktır. İşte sözleşme testi yardımcı olur, ancak sözleşmenin kimin sahipliğinde olacağını seçmeniz gerekir.

Seçenek 1: Tüketici odaklı sözleşmeler (CDC)

Tüketici odaklı sözleşmelerde, her istemci (web uygulaması, iOS, Android, partner entegrasyonu) ihtiyaç duyduğu şeyleri tanımlar. Sağlayıcı daha sonra bu beklentileri karşılayabileceğini kanıtlar.

Bu yöntem, istemciler bağımsız hareket ettiğinde iyi çalışır çünkü sözleşme backend ekibinin neyin kullanıldığını düşündüğünden ziyade gerçek kullanımı yansıtır. Ayrıca çoklu istemci gerçeğine uyar: iOS bir alanı kullanıyor olabilir, web kullanmayabilir; web sıralama veya sayfalama kurallarına dikkat ediyor olabilir, mobil önemsemeyebilir.

Basit bir örnek: mobil uygulama price_cents alanının bir tamsayı olmasına dayanıyor. Web sadece biçimlendirilmiş fiyatı gösterdiği için backend'in bunu stringe çevirmesini fark etmeyebilir. Mobilden gelen bir CDC bu değişikliği yayına almadan önce yakalar.

Seçenek 2: Sağlayıcı-odaklı şemalar

Sağlayıcı-odaklı şemalarda backend ekibi tek bir sözleşme (çoğunlukla bir şema veya spesifikasyon) yayınlar ve bunu uygular. Tüketiciler o tek doğru kaynağa karşı test eder.

Bu, API kamuya açık veya kontrolünüzde olmayan birçok tüketici tarafından paylaşılıyorsa ya da ekipler arasında sıkı tutarlılık gerekiyorsa iyi bir uyum sağlar. Başlangıç için de daha basittir: tek bir sözleşme, değişiklikleri gözden geçirmek için tek yer, tek onay yolu.

Seçimde hızlı bir yol:

• İstemciler sıkça yayınlıyor ve API'nin farklı dilimlerini kullanıyorsa CDC'leri seçin.
• Herkes için tek bir sabit “resmi” sözleşmeye ihtiyaç duyuyorsanız sağlayıcı-odaklı şemaları seçin.
• Birkaç yüksek riskli uç nokta için sağlayıcı şeması ve bunların dışında CDC'ler şeklinde hibrit kullanın.

AppMaster gibi bir platformla geliştiriyorsanız, aynı fikir geçerlidir: web ve yerel mobil uygulamaları ayrı tüketiciler gibi ele alın. Aynı backend'i paylaşsalar bile genellikle tam olarak aynı alanlara ve kurallara güvenmezler.

Bir API sözleşmesine ne koymalısınız (gerçek kırılmaları yakalasın diye)

Bir API sözleşmesi, web ve mobil istemcilerinizin gerçekten neye bağlı olduğunu yansıtıyorsa yardımcı olur. Kimsenin kullanmadığı şık bir spesifikasyon, üretimi kıran değişikliği yakalamaz.

Tahminlerle değil gerçek kullanım ile başlayın. En sık kullanılan istemci çağrılarını (uygulama kodundan, API gateway kayıtlarından veya ekiplerden alınan kısa bir listeden) alın ve bunları sözleşme vakalarına çevirin: tam yol, metod, başlıklar, sorgu parametreleri ve tipik istek gövdesi şekli. Bu sözleşmeyi küçük, alakalı ve tartışılması zor kılar.

Başarılı ve başarısız yanıtları dahil edin. Ekipler genellikle mutlu yolu test eder ve hataların da istemcilerin güvendiği şeyler olduğunu unuturlar: durum kodu, hata gövdesi şekli ve hatta sabit hata kodları/mesajlar. Bir mobil uygulama belirli bir “e-posta zaten kullanılmış” mesajı gösteriyorsa, bir sözleşme 409 yanıtı şeklini kilitlemelidir ki aniden 400 ile farklı bir gövde olmasın.

En sık kırılan alanlara ekstra dikkat gösterin:

• İsteğe bağlı alanlar vs gerekli alanlar: bir alanı kaldırmak genellikle isteğe bağlı bir alanı zorunlu hale getirmekten daha güvenlidir.
• Null'lar: bazı istemciler null ile “eksik” arasında farklı davranır. Neye izin vereceğinize karar verin ve tutarlı olun.
• Enum'lar: yeni bir değer eklemek, kapalı liste varsayan eski istemcileri bozabilir.
• Sayfalama: parametrelerde ve yanıt alanlarında (örneğin cursor veya nextPageToken) anlaşın ve bunları sabit tutun.
• Tarih ve sayı formatları: açık şekilde belirtin (ISO stringleri, integer kuruş/cents vb.).

Sözleşmeyi nasıl temsil edersiniz

Ekiplerin okuyabileceği ve araçların doğrulayabileceği bir format seçin. Yaygın seçenekler JSON Schema, örnek tabanlı sözleşmeler veya OpenAPI spesifikasyonundan türetilen tipli modellerdir. Pratikte, örnekler artı bir şema kontrolü iyi çalışır: örnekler gerçek payloadları gösterir, şema kuralları ise "alan yeniden adlandırıldı" veya "tip değişti" hatalarını yakalar.

Basit bir kural: eğer bir değişiklik istemci güncellemesi gerektiriyorsa, sözleşme testi başarısız olmalıdır. Bu zihniyet sözleşmeleri gerçek kırılmalara odaklar, teorik mükemmelliğe değil.

Adım adım: CI hattınıza sözleşme testleri ekleyin

API sözleşme testlerinin amacı basittir: biri API'yi değiştirdiğinde CI size herhangi bir web veya mobil istemcinin bu değişiklikten sonra bozulacağını değişiklik canlıya alınmadan önce söylemeli.

1) Önce istemcilerin gerçekten neye güvendiğini yakalayın

Tek bir uç nokta seçin ve gerçek kullanımda önemli olan beklentileri yazın: gerekli alanlar, alan tipleri, izin verilen değerler, durum kodları ve yaygın hata yanıtları. Hepsi bir anda API'yi tanımlamaya çalışmayın. Mobil uygulamalar için eski uygulama sürümü beklentilerini de dahil edin; çünkü kullanıcılar anında güncelleme yapmazlar.

Bunu pratikçe yapmak için bugünün istemcilerinin yaptığı birkaç gerçek isteği (kayıtlardan veya test fixtürlerinden) alın ve tekrarlanabilir örneklere dönüştürün.

2) Sözleşmeleri ekiplerin bakım yapacağı yere koyun

Sözleşmeler unutulmuş bir klasörde yaşadığında başarısız olurlar. Değişikliğe yakın tutun:

• Aynı ekip her iki tarafın da sahibi ise sözleşmeleri API deposuyla saklayın.
• Web, mobil ve API farklı ekiplerin sorumluluğundaysa, ekiplerin sahip olduğu paylaşılan bir repo kullanın, tek bir kişinin değil.
• Sözleşme güncellemelerini kod gibi ele alın: incelenmiş, versiyonlanmış ve tartışılmış olsun.

3) CI'de her iki tarafta da kontroller ekleyin

İki sinyal istiyorsunuz:

• Sağlayıcı doğrulaması her API build'inde: "API bilinen tüm sözleşmeleri hâlâ karşılıyor mu?"
• Tüketici kontrolleri her istemci build'inde: "Bu istemci yayımlanmış son sözleşmeye hâlâ uyuyor mu?"

Bu iki yönden gelen kontroller sorunları her iki taraftan da yakalar. Eğer API bir yanıt alanını değiştirirse API pipeline'ı başarısız olur. Eğer bir istemci yeni bir alan beklemeye başlarsa istemci pipeline'ı başarısız olur ve API bunu destekleyene kadar merge engellenir.

4) Başarısızlık kuralını belirleyin ve uygulayın

Merge veya yayını engelleyen şeyin ne olduğunu açıkça belirtin. Yaygın bir kural: herhangi bir sözleşme kıran değişiklik CI'de başarısız olur ve main dalına merge'i engeller. İstisnalara ihtiyaç varsa, yazılı bir karar gerektirin (örneğin koordine edilmiş bir yayın tarihi).

Somut örnek: backend totalPrice'ı total_amount olarak yeniden adlandırır. Sağlayıcı doğrulaması hemen başarısız olur, bu yüzden backend ekibi geçiş süresi boyunca eski alanı da tutar ve her iki istemci güvenle yayımlamaya devam eder.

Hızlı ekipleri yavaşlatmadan versiyonlama ve geriye dönük uyumluluk

Hızlı ekipler çoğunlukla mevcut istemcilerin zaten güvendiği şeyleri değiştirerek API'leri bozar. "Kırıcı değişiklik" terimi, daha önce çalışan bir isteği başarısız yapan veya yanıtı istemcinin işleyemeyeceği şekilde anlamlı biçimde değiştiren her şeyi kapsar.

Yaygın kırıcı değişiklikler şunlardır (uç nokta hâlâ var olsa bile):

• İstemcilerin okuduğu bir yanıt alanını kaldırmak
• Bir alan tipini değiştirmek (örneğin "total": "12"'den "total": 12'ye)
• İsteğe bağlı bir alanı zorunlu yapmak (veya yeni bir zorunlu istek alanı eklemek)
• Kimlik doğrulama kurallarını değiştirmek (açık uç nokta şimdi token mı istiyor)
• İstemcilerin ayrıştırdığı durum kodlarını veya hata şeklini değiştirmek (200'den 204'e veya yeni bir hata formatı)

Çoğu ekip daha güvenli alternatifler seçerek versiyon artışlarından kaçınabilir. Daha fazla veriye ihtiyacınız varsa yeni bir alan ekleyin, var olanı yeniden adlandırmayın. Daha iyi bir uç nokta gerekiyorsa yeni bir rota ekleyip eski rotayı çalışır durumda bırakın. Doğrulamayı sıkılaştırmanız gerekiyorsa bir süre hem eski hem yeni girişi kabul edin, sonra kademeli olarak yeni kuralları uygulayın. Sözleşme testleri burada yardımcı olur çünkü mevcut tüketicilerin beklentilerinin hâlâ karşılandığını kanıtlamanızı zorunlu kılar.

Kademelendirme (deprecation) hızın yüksek kalmasını sağlarken kullanıcıları etkilememeyi sağlar. Web istemcileri günlük güncellense de mobil uygulamalar inceleme kuyrukları ve yavaş benimseme nedeniyle haftalarca geride kalabilir. Kademelendirmeyi gerçek istemci davranışına göre planlayın, umuda göre değil.

Pratik bir kademelendirme politikası şöyle görünebilir:

• Değişikliği erkenden duyurun (sürüm notları, dahili kanal, ticket)
• Kullanım belirlenen eşik altına düşene kadar eski davranışı koruyun
• Kullanılan eski yol için başlıklarda/kayıtlarda uyarılar döndürün
• Çoğu istemci yükseltildikten sonra bir kaldırma tarihi belirleyin
• Sözleşme testleri, aktif hiçbir tüketicinin artık ona ihtiyaç duymadığını gösterene dek eski davranışı silmeyin

Açık versiyonlamayı yalnızca değişikliği geriye dönük uyumlu hâle getiremeyeceğiniz durumlarda kullanın (örneğin kaynak yapısında veya güvenlik modelinde köklü bir değişim). Versiyonlama uzun vadeli maliyet ekler: artık iki davranışı, iki dokümantasyon setini ve daha fazla uç durumu yönetirsiniz. Versiyonları nadir ve kasıtlı tutun ve sözleşmelerle her iki versiyonun da eski sürüm güvenliğe kaldırılana dek dürüst kaldığını doğrulayın.

Yaygın sözleşme testi hataları (ve nasıl kaçınılır)

Sözleşme testi, gerçek beklentileri kontrol ettiğinde en iyi şekilde çalışır; sisteminizin oyuncak bir versiyonunu kontrol ettiğinde değil. Çoğu başarısızlık, ekiplerin kendilerini güvende hissetmelerine rağmen hataların üretime sızmasına izin veren birkaç tahmin edilebilir kalıptan gelir.

Hata 1: Sözleşmeleri "şık taklitler" gibi ele almak

Aşırı taklit (over-mocking) klasik tuzaktır: sözleşme testi geçer çünkü sağlayıcı davranışı sözleşmeye uyması için taklit edilmiştir, gerçek servis bunu yapabildiği için değil. Deploy ettiğinizde ilk gerçek çağrı başarısız olur.

Daha güvenli bir kural basittir: sözleşmeler çalıştırılan sağlayıcıya (veya aynı şekilde davranan bir build artefaktına) karşı doğrulanmalıdır; gerçek serileştirme, gerçek doğrulama ve gerçek kimlik doğrulama kurallarıyla.

En sık görülen hatalar ve genellikle işe yarayan düzeltmeler:

• Sağlayıcı davranışını aşırı taklit etmek: sözleşmeleri stublanmış bir servis yerine gerçek bir sağlayıcı build'ine karşı doğrulayın.
• Sözleşmeleri çok katı yapmak: ID'ler, zaman damgaları ve diziler gibi değişkenlerde esnek eşleştirme kullanın; istemcilerin güvenmediği her alanı doğrulamaktan kaçının.
• Hata yanıtlarını görmezden gelmek: en azından başlıca hata vakalarını (401, 403, 404, 409, 422, 500) ve istemcinin ayrıştırdığı hata gövdesi şeklini test edin.
• Sahipliği netleştirmemek: gereksinimler değiştiğinde kimin sözleşmeyi güncelleyeceğini atayın; API değişikliklerinin "definition of done"'unun bir parçası olsun.
• Mobil gerçeklerini unutmak: sadece en yeni derleme ve hızlı Wi‑Fi ile değil, daha yavaş ağlar ve eski uygulama sürümleriyle test yapın.

Hata 2: Zararsız değişiklikleri engelleyen kırılgan sözleşmeler

Eğer bir sözleşme yeni isteğe bağlı bir alan eklendiğinde veya JSON anahtarları yeniden sıralandığında başarısız oluyorsa, geliştiriciler kırmızı build'i görmezden gelmeyi öğrenir. Bu amaca zarar verir.

"Önemli olan yerde katı" olmaya çalışın. Gerekli alanlar, tipler, enum değerleri ve doğrulama kuralları konusunda katı olun. Fazladan alanlar, sıralama ve doğal olarak değişen değerler konusunda esnek olun.

Küçük bir örnek: backend status değerini "active" | "paused"'dan "active" | "paused" | "trial"'a değiştiriyor. Eğer bir mobil uygulama bilinmeyen değerleri bir çökme olarak işliyorsa, bu bir kırıcı değişikliktir. Sözleşme bunun nasıl ele alınacağını kontrol etmeli ya da sağlayıcı yeni değeri yalnızca tüm istemciler bunu işleyene kadar göndermemelidir.

Mobil istemciler biraz daha fazla dikkati hak eder çünkü sahada daha uzun süre kalırlar. Bir API değişikliğini "güvenli" ilan etmeden önce sorun:

• Eski uygulama sürümleri hâlâ yanıtı ayrıştırabiliyor mu?
• İstek bir zaman aşımı sonrası yeniden denendiğinde ne olur?
• Önbelleğe alınmış veriler yeni formatla çakışır mı?
• Bir alan eksikse bir geri dönüş mekanizması var mı?

Eğer API'leriniz üretiliyorsa veya hızla güncelleniyorsa (AppMaster dahil), sözleşmeler pratik bir koruma sağlar: hızlı hareket ederken web ve mobil istemcilerin her değişiklikten sonra çalışmaya devam ettiğini kanıtlamanızı sağlar.

Yayın öncesi hızlı kontrol listesi

Bunu bir API değişikliğini merge veya yayınlamadan hemen önce kullanın. Hızlı ekiplerde en büyük yangınlara sebep olan küçük düzenlemeleri yakalamak için tasarlanmıştır. Eğer zaten sözleşme testi yapıyorsanız, bu liste sözleşmelerin engellemesi gereken kırılmalara odaklanmanıza yardımcı olur.

Her seferinde sorulacak 5 soru

• İstemcilerin okuduğu herhangi bir yanıt alanını ekledik, kaldırdık veya yeniden adlandırdık mı (iç içe alanlar dahil)?
• Herhangi bir durum kodu değişti mi (200 vs 201, 400 vs 422, 404 vs 410) veya hata gövdesi formatı değişti mi?
• Hangi alanlar zorunlu/isteğe bağlı arasında değişti ("null olabilir" ile "zorunlu mevcut" farkı dahil)?
• Sıralama, sayfalama veya varsayılan filtreler değişti mi (sayfa boyutu, sıralama, cursor tokenları, varsayılanlar)?
• Sağlayıcı ve tüm aktif tüketiciler (web, iOS, Android ve iç araçlar) için sözleşme testleri çalıştı mı?

Basit bir örnek: API eskiden totalCount döndürüyordu ve bir istemci bunu “24 sonuç” göstermek için kullanıyor. Siz bunu endpoint'ten çıkardınız çünkü "liste zaten öğelere sahip". Backend tarafı çökmez ama UI bazı kullanıcılar için boş veya "0 sonuç" göstermeye başlar. Bu gerçek bir kırıcı değişikliktir, endpoint hâlâ 200 döndürse bile.

Eğer herhangi bir soruya "evet" dediyseniz

Gönderimden önce şu hızlı takibi yapın:

• Eski istemcilerin güncelleme olmadan çalışıp çalışmayacağını doğrulayın. Eğer hayırsa, geriye dönük uyumlu bir yol ekleyin (eski alanı tutun veya her iki formatı bir süre destekleyin).
• İstemcilerde hata işleme mantığını kontrol edin. Birçok uygulama bilinmeyen hata formatlarını "Bir şey yanlış" olarak ele alır ve kullanışlı mesajları gizler.
• Sözleşme testlerini desteklenen her yayınlanmış istemci sürümü için çalıştırın, sadece en son dal değil.

Eğer dahili araçları hızlıca inşa ediyorsanız (örneğin bir admin paneli veya destek panosu), bu tüketicilerin de dahil olduğundan emin olun. AppMaster'da ekipler genellikle aynı backend modellerinden web ve mobil uygulamalar ürettiği için küçük bir şema değişikliğinin bile yayımlanmış bir istemciyi sözleşme CI'de kontrol edilmezse kırabileceğini unutmak kolaydır.

Örnek: web ve mobil yayına ulaşmadan önce bir kırılmayı yakalamak

Yaygın bir kurulum hayal edin: API ekibi günde birkaç kez deploy ediyor, web uygulaması günlük olarak ship ediyor ve mobil uygulamalar haftalık yayınlıyor (app store incelemesi ve kademeli dağıtımlar yüzünden). Herkes hızlı hareket ediyor, bu yüzden gerçek risk kötü niyet değil, zararsız görünen küçük değişikliklerdir.

Bir destek talebi kullanıcı profili yanıtında daha net isimlendirme istiyor. API ekibi GET /users/{id} içinde bir alanı phone'dan mobileNumber'a yeniden adlandırıyor.

Bu yeniden adlandırma düzenli hissetse de kırıcı bir değişikliktir. Web istemcisi profil sayfasında telefon numarasını boş gösterebilir. Daha da kötüsü, mobil istemci phone'u zorunlu kabul ediyorsa çökebilir veya profili kaydederken doğrulamada başarısız olabilir.

Sözleşme testleri ile bu kullanıcıya ulaşmadan önce yakalanır. Kontrollerin nasıl başarısız olduğunu örnekleyelim:

• Sağlayıcı build başarısız olur (API tarafı): API CI işi web ve mobilden kaydedilmiş tüketici sözleşmelerine karşı sağlayıcıyı doğrular. Sağlayıcı artık phone döndürmediğini ve tüketicilerin bunu beklediğini gördüğünde doğrulama başarısız olur ve deploy engellenir.
• Tüketici build başarısız olur (istemci tarafı): Web ekibi API yayınlanmadan önce sözleşmelerini mobileNumber'ı gerektirecek şekilde günceller. Sözleşme testi, sağlayıcının henüz o alanı sağlamadığını gösterip başarısız olur.

Her iki durumda da hata erken, yüksek sesli ve spesifiktir: hangi uç nokta ve hangi alanın uyuşmadığını gösterir; bunun yerine yayın sonrası "profil sayfası bozuk" şeklinde bir hata görürsünüz.

Çözüm genellikle basittir: değişikliği yıkıcı değil ekleyici yapın. API bir süre her iki alanı da döndürür:

• mobileNumber ekleyin.
• phone'u alias olarak bırakın (aynı değer).
• Sözleşme notlarında phone'u kullanımdan kaldırılmış (deprecated) olarak işaretleyin.
• Web ve mobil mobileNumber okumaya geçsin.
• Desteklenen istemci sürümlerinin çoğu geçtiğinde phone'u kaldırın.

Zorunlu teslim tarihleri altında gerçekçi bir zaman çizelgesi şöyle olabilir:

• Pzt 10:00: API ekibi mobileNumber ekler ve phoneu tutar. Sağlayıcı sözleşme testleri geçer.
• Pzt 16:00: Web mobileNumbera geçer ve yayımlar.
• Perş: Mobil mobileNumbera geçer ve bir sürüm gönderir.
• Gelecek Salı: Mobil sürüm kullanıcıların çoğuna ulaşır.
• Sonraki sprint: API phoneu kaldırır ve sözleşme testleri hiçbir desteklenen tüketicinin buna ihtiyaç duymadığını doğrular.

Bu, temel değerin özeti: sözleşme testleri "kırıcı değişiklik ruleti"ni kontrol edilen, zamana yayılmış geçişlere dönüştürür.

Hızlı hareket eden ekipler için sonraki adımlar (no-code seçeneği dahil)

Eğer sözleşme testlerinin gerçekten kırılmaları önlemesini istiyorsanız (sadece daha fazla kontrol eklemek değil), dağıtımı küçük tutun ve sahipliği netleştirin. Amaç basit: kırıcı değişiklikleri web ve mobil sürümlere ulaşmadan yakalamak.

Küçük bir rollout planıyla başlayın. En çok acıya neden olan top 3 uç noktayı seçin (genellikle auth, kullanıcı profili ve temel bir "liste veya arama" uç noktası). Önce bunları sözleşmeye alın, ekip iş akışına güvendikçe genişletin.

Yönetmesi kolay bir rollout:

• 1. Hafta: en iyi 3 uç nokta için sözleşme testleri, her pull request'te çalışsın
• 2. Hafta: mobil kullanımın en yüksek olduğu sonraki 5 uç nokta ekleyin
• 3. Hafta: hata yanıtları ve uç durumlar (boş durumlar, doğrulama hataları) kapsansın
• 4. Hafta: backend değişiklikleri için "sözleşme yeşil" bir yayın kapısı olsun

Sonra kimin ne yaptığını belirleyin. Sorumluluklar belli olduğunda ekipler daha hızlı hareket eder.

Roller basit tutun:

• Sözleşme sahibi: genellikle backend ekibi, davranış değiştiğinde sözleşmeleri güncellemekten sorumlu
• Tüketici gözden geçirenler: web ve mobil liderleri, değişikliklerin kendi istemcileri için güvenli olduğunu onaylar
• Build sorumlusu (build sheriff): günlük veya haftalık döner, CI'deki sözleşme test başarısızlıklarını triage eder
• Yayın sahibi: bir sözleşme kırılırsa yayını engelleme kararını verir

Herkesin önem verdiği tek bir başarı metriğini takip edin. Birçok ekip için en iyi sinyal, yayınlardan sonra daha az hotfix ve API değişikliklerine bağlı istemci regresyonlarının (uygulama çökmeleri, boş ekranlar, kırık ödeme akışları) azalmasıdır.

Daha hızlı geri bildirim döngüsü arıyorsanız, no-code platformlar değişimi azaltarak sürüklenmeyi (drift) düşürebilir; değişikliklerden sonra temiz kod yeniden oluşturmak, yamaların birikip davranışı kazara değiştirmesini önler.

AppMaster ile API'ler ve istemciler oluşturuyorsanız, pratik bir sonraki adım şudur: bir uygulama oluşturun, Data Designer (PostgreSQL) içinde verilerinizi modelleyin, Business Process Editor'de iş akışlarını güncelleyin, sonra yeniden üretip bulutunuza deploy edin veya kaynak kodu dışa aktarın. Bunu CI'de sözleşme kontrolleriyle eşleştirin ki her yeniden üretilen build web ve mobilin beklentileriyle eşleştiğini ispatlasın.