Görsel iş akışlarında üçüncü taraf API'ler için devre kesici deseni

Üçüncü taraf API kesintileri neden birden fazla özelliği bozar

Tek bir üçüncü taraf API günlük işlemlerin ortasında yer alır: ödemeleri almak, adresleri doğrulamak, envanteri senkronize etmek, mesaj göndermek, kimlik doğrulamak. Sağlayıcı sorun yaşadığında genellikle tek bir buton bozulmaz; ilerlemek için gereken yanıtı bekleyen bütün akışlar durabilir.

İşte bu yüzden bir devre kesici önemlidir. Bu teori değil; entegrasyon sağlıksız olsa bile temel operasyonları çalışır tutmanın pratik bir yoludur.

Yavaş ve tamamen kapalı olmak farklı şekillerde zarar verir.

Bir API yavaş olduğunda, iş akışı yine de başarılı olmaya çalışır ama her adım bekler. Kullanıcılar dönen ekranlar görür, destek ekipleri “takıldı” biletleri alır ve arka plan işler birikir. Yavaşlık sinir bozucudur çünkü kendi sisteminizin bozulduğunu gösteriyor olabilir.

Bir API kapalıysa zaman aşımı veya sert hatalar gelir. Bu daha net ama genellikle daha tehlikelidir çünkü iş akışları genellikle yeniden dener. Çok sayıda istek aynı anda yeniden denediğinde, bu bir trafik fırtınası yaratır, kurtarmayı zorlaştırır ve kendi sisteminizi de yavaşlatabilir.

Yaygın belirtiler hızla görülür: zaman aşımı, büyüyen kuyruklar, kısmi güncellemeler ve çok sayıda manuel temizlik gereksinimi.

Gerçek hasar zincirleme etkilerdir. Örneğin bir gönderim ücreti sağlayıcısı yavaşsa, teklif olmadan sipariş onaylanmadığı için sipariş yerleştirme yavaşlar. Ödemeler bozuksa destek, her şey çalışıyor olsa bile iade işlemlerini yapamayabilir.

Kesintileri yok sayamazsınız. Hedef, iş akışlarını açık geri dönüş yolları, geçici engelleme kuralları ve uyarılarla tasarlamaktır; böylece entegrasyon iyileşirken iş sipariş almaya, müşterilere hizmet vermeye ve iş kaydetmeye devam edebilir.

Devre kesici basitçe nedir

Devre kesici, API çağrıları için bir güvenlik anahtarıdır. Üçüncü taraf servis başarısız olmaya başladığında, devre sizin iş akışınızın onu tekrar tekrar vurmasını engeller. Tek bir kesintiyi yavaş ekranlara, zaman aşımına ve takılı işlere dönüştürmek yerine etki alanını kontrol edersiniz.

Bir devre kesicinin üç basit sonucu vardır:

• Sağlayıcı sağlıklı görünüyorsa çağrıya izin verin.
• Hatalar yüksekse çağrıyı engelleyin ve hemen bir geri dönüş yoluna gidin.
• Kısa bir duraklamadan sonra sınırlı bir test çağrısı yapın; sağlayıcı geri dönmüş mü kontrol edin.

Terim tercih ederseniz bunlar “kapalı”, “açık” ve “yarı-açık”tır. İsimler önemli değil; öngörülebilirlik önemli. Sağlayıcı hasta olduğunda, iş akışınız her seferinde aynı şekilde davranmalı.

Bu hataları gizlemez. Hataları kaydetmeye, kullanıcılara veya operasyonlara net bir durum göstermeye ve doğru kişileri uyarmaya devam edersiniz. Hızlıca başarısız olmayı, işi daha güvenli bir alternatife yönlendirmeyi veya tekrar denemeden önce kısa bir süre beklemeyi seçmiş olursunuz.

Hangi API çağrılarının işi asla durdurmaması gerektiğini seçin

Devre kesiciler seçici olduğunuzda en iyi çalışır. Her sağlayıcı çağrısı özel korumayı hak etmez. Parayı, siparişleri veya müşteri erişimini engelleyecek adımlarla başlayın.

Pratik bir yöntem: bir kullanıcı isteğini uçtan uca takip edin. Hangi noktada bir zaman aşımı kullanıcının görevi bırakmasına veya ekibinizin daha sonra temizlemesi gereken bir karmaşa yaratmasına neden olur?

Tipik “çekirdek işi engellememesi gereken” çağrılar şunlardır: ödemeler, gönderim ve yerine getirme, login/SSO/MFA, OTP ve onay mesajları, onaya bağlı uyumluluk kontrolleri.

Ayrıca kullanıcıya görünen adımları arka plan işlerinden ayırın. Bir ödeme ekranında kullanıcı bekliyorsa hızlı bir karara ihtiyacınız var: başarılı, geri dönüş veya net bir hata. Takip numarası senkronizasyonu gibi arka plan işleri için daha yavaş yeniden denemeler uygundur, yeter ki ana akışı engellemesin.

Kapsam kaymasını önlemek için küçük başlayın. Önce 1–3 iş akışını koruyun, sonra genişletin.

Herhangi bir şey kurmadan önce “güvenli geri dönüş”ün ne demek olduğunu tanımlayın. İyi geri dönüşler spesifik ve test edilebilir olmalıdır:

• Ödemeler: sepetin kaybolmaması için siparişi “ödeme bekliyor” olarak kaydedin.
• Gönderim: önbelleğe alınmış bir ücret, sabit ücret veya etiketi sonra satın almak üzere siparişi onaylayın.
• Kimlik: SSO kapalıysa parola ile girişe izin verin veya e-posta doğrulamaya geçin.
• Mesajlaşma: SMS'i sıraya alın ve mümkünse alternatif bir yol sağlayın.

AppMaster’ın Business Process Editor’ünde bu genellikle temiz bir dal olur: çekirdek işlem devam ederken sağlayıcıya bağımlı adım kontrollü bir alternatif alır.

Durumlar, eşikler ve açıklanabilir zamanlayıcılar

Devre kesici bir güvenlik anahtarıdır. Çoğu zaman çağrılara izin verir. Sağlayıcı başarısız olmaya başladığında, iş akışınızı boşa geçen zaman ve hata birikiminden korumak için devreyi kapatır.

Üç durum

Kapalı normaldir. API'yi çağırırsınız ve devam edersiniz.

Hatalar bir sınırı aştığında devre Açık olur. Sağlayıcıya çağrı yapmayı kısa bir süre durdurursunuz ve hemen bir geri dönüşe yönlendirirsiniz (önbellek değeri, sıraya alma, alternatif akış).

Soğuma sonrası devre Yarı-açık olur. Az sayıda test çağrısına izin verirsiniz. Başarılı olursa tekrar Kapalı'ya dönersiniz; başarısız olursa tekrar Açık olursunuz.

Ne ölçmeli

Sağlayıcının nasıl hata verdiğine uyan sinyalleri kullanın:

• Zaman aşımı
• HTTP 5xx hataları
• Yükselen gecikme (kullanışsız derecede yavaş)
• Bağlantı/DNS hataları
• 429 hız sınırlamaları

Görsel iş akışı aracında bunlar genellikle basit kontrollerle eşleşir: durum kodu, geçen süre ve belirli hata çıktıları.

Başlangıç eşikleri ve iki ana zamanlayıcı

Açıklaması kolay sayılarla başlayın, sonra gerçek trafikle ayarlayın. Örnekler:

• 30–60 saniye içinde 5–10 çağrı başarısızsa devreyi açın.
• Veya kayan pencerede çağrıların %20–%40'ı başarısız olursa açın.
• Gecikmeyi, işleminizin tolere edebileceğinden (genellikle 2–5 saniye) fazla olduğunda başarısız sayın.

Ardından iki zamanlayıcı belirleyin:

• Soğuma süresi (Açık): genellikle 30 saniye ile 5 dakika arası.
• Yarı-açık test penceresi: 1–5 test çağrısı veya 10–30 saniye gibi kısa bir zaman penceresi.

Hedef basittir: sağlayıcı sağlıksız olduğunda hızlıca başarısız olun, sağlayıcı geri döndüğünde otomatik toparlanın.

Adım adım: görsel iş akışında devre kesici oluşturma

En önemli tasarım kararı, “şu anda sağlayıcıyı çağırmalı mıyız?” kararını bir yerde toplamak, her iş akışına yaymamak.

1) Sağlayıcı çağrısını tek bir yeniden kullanılabilir blok arkasına koyun

Her iş akışının sağlayıcıya ihtiyaç duyduğunda kullandığı bir alt süreç (reusable workflow block) oluşturun. AppMaster’da bu doğal olarak bir Business Process’e karşılık gelir. Dar tutun: girdiler, sağlayıcı isteği ve net bir başarılı/başarısız sonucu olsun.

2) Hataları sadece sayılara değil zamana göre takip edin

Her sonucu bir zaman damgasıyla kaydedin. Son başarı, son hata, pencere içindeki hatalar, mevcut durum ve soğuma sonlanma süresi gibi alanları saklayın.

Bu alanları bir tabloda tutun ki devre yeniden başlatmalardan sağ çıkabilsin ve birden çok örnek arasında tutarlı kalsın. Data Designer ile PostgreSQL bunun için uygundur.

3) Her zaman izleyeceğiniz durum değişikliklerini tanımlayın

Kuralları basit tutun. Örnek: 2 dakika içinde 5 hata olursa Açık'a geç. Açıkken sağlayıcı çağrısını atla ve geri dönüşü çalıştır. Soğuma sonrası Yarı-açık ol ve kontrollü bir denemeye izin ver. Başarırsa kapat; başarısız olursa tekrar aç.

4) İş akışını dallandırın: sağlayıcı yolu vs geri dönüş yolu

Sağlayıcı isteğinden önce saklanan durumu kontrol edin:

• Kapalı: sağlayıcıyı çağırın, sonra başarı veya hatayı güncelleyin.
• Açık: çağrıyı atlayın ve geri dönüşü çalıştırın.
• Yarı-açık: sınırlı bir denemeye izin verin, sonra kapatmak veya yeniden açmak için karar verin.

Örnek: bir gönderim etiketi API'si kapalıysa, geri dönüş olarak siparişi “Etiket bekleniyor” durumuyla oluşturup bir yeniden deneme işi sıraya alın; böylece kasa veya depo işi bloke olmaz.

5) Farklı iş akışları arasında paylaşılmasını sağlayın

Birden fazla iş akışı ve sunucunuz varsa hepsi aynı devre durumunu okumalı ve yazmalıdır. Aksi takdirde bir örnek sağlayıcıyı vurmaya devam ederken diğeri zaten durmaya karar vermiş olabilir.

İşin devam etmesini sağlayan geri dönüş yolları

Devre kesici işe yarar ancak çağrı engellendiğinde ne olacağını siz belirlemelisiniz. İyi bir geri dönüş kullanıcıyı ilerletir, veriyi korur ve daha sonra temizlemeyi öngörülebilir kılar.

Bir gönderim ücreti sağlayıcısı kapalıysa kesin bir fiyat gerekmeden siparişi kabul edebilirsiniz. Görsel iş akışında başarısız API adımını, yine de kullanılabilir bir sonuç üreten bir geri dönüş dalına yönlendirin.

Pratikte geri dönüşler genellikle şunlardır:

• Son bilinen önbelleğe alınmış değeri kullanmak (tazelik penceresiyle).
• Güvenli bir varsayılan tahmin kullanmak ve açıkça etiketlemek.
• Manuel incelemeye yönlendirmek.
• İşi daha sonra yeniden denemek üzere sıraya almak (asenkron iş).

Kullanıcı deneyimi mantık kadar önemlidir. Belirsiz bir hata göstermeyin. Ne olduğunu ve kullanıcıın ne yapabileceğini söyleyin: “Şu an ücreti doğrulayamıyoruz. Tahmini gönderim ücretiyle siparişi verebilir veya incelemeye kaydedebilirsiniz.”

Kısa ve uzun kesintiler için plan yapın. Kısa bir kesinti (dakikalar) genellikle “devam et, arka planda yeniden dene” anlamına gelir. Uzun bir kesinti (saatler) daha sıkı davranışlar gerektirebilir; örneğin daha fazla manuel inceleme veya onay.

Ayrıca her geri dönüşü takip edin ki mutabakat kolay olsun. En azından geri dönüş türü, orijinal istek detayları, kullanıcıya ne gösterildiği (tahmin miydi) ve takip için bir durum kaydedin.

Geçici engelleme kuralları ve akıllı yeniden denemeler

Kontrolsüz yeniden denemeler küçük sağlayıcı aksaklıklarını gerçek kesintilere dönüştürür. Çok sayıda iş akışı aynı anda yeniden denediğinde sağlayıcı yavaşlar, kuyruklar dolar ve kota aşımı yaşanır.

Yeniden denemeler öngörülebilir ve sınırlı olmalı, ayrıca devre durumuna saygı göstermeli. Pratik bir politika:

• Maksimum yeniden denemeyi düşük tutun (genellikle 2–3).
• Üstel geri çekilme kullanın (ör. 2s, 8s, 30s).
• Yeniden denemelerin senkronize olmaması için jitter ekleyin.
• Toplam yeniden deneme süresini sınırlayın (ör. 60–90 saniye).
• Eğer devre Açık ise yeniden deneme yapmayın; doğrudan geri dönüşe gidin.

Geçici engelleme ilgili ama farklıdır. Sunucunun “şu an çalışmaz” dediği durumlar için kullanılır. Yaygın kurallar:

• 429 hız limiti: Retry-After süresi kadar engelle veya güvenli bir sabit pencere uygula.
• 401/403 yetki hatası: kimlik bilgileri yenilenene kadar engelle, sonra bir kez test et.
• Sürekli 5xx: kısa süre engelle, sonra küçük bir deneme yap.

Bir blok sırasında zaten hareket eden işler için ne olacağına karar verin: sıraya alın, yeniden yönlendir, veya kademeli bozulma yapın (ör. siparişi kabul et ama “SMS gönder”i ertele).

Ne yapacağınızı söyleyen uyarılar

Devre kesici yalnızca insanlar bunu hızlıca duyduğunda yararlıdır. Amaç gürültü değil. Davranış değiştiğinde bir net mesaj: çağrılar engelleniyor, geri dönüşler aktif, veya devre beklenenden uzun açık kaldı.

İyi varsayılan tetikleyiciler:

• Devre açıldığında uyar.
• Açık kaldığı süre beklenenin üzerine çıkarsa uyar.
• Açılmadan önce hatalarda ani bir artış olursa uyar.

Uyarıları eyleme dönük yapın. Sağlayıcı ve endpoint, mevcut durum ve ne zaman değiştiği, kullanıcıların ne hissedeceği, akışın şu anda ne yaptığı (engelliyor, yeniden deniyor, geri dönüş) ve önerilen bir sonraki adımı ekleyin.

Şiddete göre uyarıları yönlendirin. Kritik olmayan zenginleştirme API'si e-postaya gidebilir. Ödeme, giriş veya sipariş gönderimi genellikle paging (sayfalama) gerektirir. AppMaster’da bu, şiddet bayrağına göre e-posta, Telegram veya SMS gönderen dallara kolayca eşlenir.

Kurtarılıp kurtarılamadığınızı görmek için küçük bir metrik seti tutun: engellenen çağrılar ve her sağlayıcı için geri dönüş kullanımı genellikle yeterlidir.

Örnek senaryo: sağlayıcı kesintisinde siparişleri durdurmadan devam etmek

Yaygın bir hata: gönderim ücreti sağlayıcınız müşteriler ödeme yaparken kapanır. Eğer iş akışınız sipariş oluştururken canlı ücretleri zorunlu kılıyorsa tek bir kesinti tüm siparişleri durdurabilir.

Normalde sipariş oluşturulur, ardından akış canlı ücret ister ve seçilen taşıyıcı ve fiyatla sipariş kaydedilir.

Sağlayıcı başarısız olmaya başlayınca çağrılar zaman aşımına uğrar veya 5xx döner. Eşik aşılınca (örneğin 2 dakikada 5 hata) devre açılır.

Açıkken iş akışı kısa bir pencere için (ör. 10 dakika) gönderici sağlayıcıyı çağırmayı bırakır. Bu, başarısız bir sağlayıcının herkes için checkout'u yavaşlatmasını engeller.

Checkout'u engellemek yerine geri dönüş şu adımları yapabilir:

• Sabit bir ücret uygula (veya güvenli bir tahmin).
• Siparişi yine de oluştur.
• Daha sonra yeniden hesaplama için shipping_rate_status ve shipping_rate_source gibi alanlarla “Shipping rate pending” olarak işaretle.
• Sağlayıcı hata detaylarını takip için kaydet.

AppMaster’da bu, Business Process Editor’de açık bir dal olup Data Designer alanlarıyla desteklenir.

Yayına almadan önce hızlı kontroller

Devre kesici demo altındaki haliyle gerçek stres altındaki haliyle aynı şekilde davranmalıdır. Yayın öncesi temel kontroller:

• Eşikler ve soğuma süreleri dokümante edilmiş ve değişmesi kolay olsun.
• Açık durum çağrıları hemen engellesin (sağlayıcı zaman aşımını beklemeden).
• Geri dönüş davranışı para ve müşteri taahhütleri için güvenli olsun.
• Yarı-açık denemeleri birkaç test çağrısıyla sınırlı olsun.
• Loglar zamanlamayı ve etkiyi kolay cevaplanabilir yapsın.

Geri dönüş güvenliğine ekstra zaman ayırın. “İşi devam ettiren” bir geri dönüş aynı zamanda finansal risk yaratabilir. Ödeme sağlayıcısı kapalıysa siparişleri ödenmiş olarak işaretlemek tehlikelidir. Daha güvenli bir yaklaşım “ödeme bekliyor” ile açık müşteri mesajıdır.

Kurtarmayı kasıtlı olarak test edin. Hataları zorlayın, devrenin açıldığını izleyin, soğumayı bekleyin ve Yarı-açık durumun yalnızca küçük bir deneme gönderdiğini doğrulayın. Başarırsa hızlıca kapanmalı; başarısız olursa sağlayıcıyı yeniden boğmadan tekrar açılmalıdır.

Loglarınız bir dakikadan kısa sürede şu sorulara cevap vermeli: kim etkilendi, ne zaman başladı, hangi iş akışı adımı devreyi tetikledi ve hangi geri dönüş kullanıldı.

Sonraki adımlar: deseni AppMaster'da uygulamak

Günlük operasyonları etkileyebilecek bir entegrasyon seçin (ödemeler, gönderim etiketleri, SMS, CRM senkronizasyonu). Önce o tek çağrı için devre kesiciyi uçtan uca kurun. Ekip davranışa güvenince, aynı şablonu diğer sağlayıcılar için tekrarlayın.

AppMaster’da devre durumunu Data Designer ile PostgreSQL'de modelleyin. Basit tutun: sağlayıcı (veya endpoint) başına bir kayıt; state, failure_count, last_failure_at, open_until ve kısa bir last_error alanları olsun.

Ardından iş mantığını Business Process Editor'da okunabilir dallarla uygulayın. Netlik zekâdan daha değerlidir.

Pratik bir kurulum sırası:

1. open_until gelecekteyse devreyi kontrol edip çağrıları engelleyin.
2. Sağlayıcı API çağrısını yapın ve hem başarı hem hata çıktısını yakalayın.
3. Başarı durumunda sayaçları sıfırlayın ve devreyi kapatın.
4. Hata durumunda sayaçları artırın ve eşikler karşılanınca devreyi açın.
5. Kullanıcıya görünen akışları bir geri dönüşe yönlendirin (sıraya al, önbellek kullan, manuel işleme izin ver).

Geri dönüş kararını destek ve operasyonların ne göreceğini bilmesi için sade bir dille dokümante edin.

Devre açıldığında AppMaster mesaj modüllerini (e-posta, SMS, Telegram) kullanarak bir sahibi bilgilendirin. Önemli olanları ekleyin: sağlayıcı, endpoint, durum ve önerilen ilk adım.

Eğer bu iş akışlarını AppMaster'da kuruyorsanız, appmaster.io başlangıç için pratik bir yerdir çünkü aynı görsel Business Process hem endpoint'leri, arka plan işlerini hem de uyarıları tek paylaşılan devre durumu ile besleyebilir.