Üçüncü Parti API Entegrasyonunda Dayanıklılık: Zaman Aşımı, Tekrar Deneme, Devre Kesici

Bir api entegrasyonu yazmak kolaydır: adrese istek atarsınız, yanıtı işlersiniz, iş biter. Zor olan, o adres yanıt vermediğinde, çok yavaş yanıt verdiğinde veya beklenmedik bir gövde döndürdüğünde sisteminizin ayakta kalmasıdır. Üretimde yaşanan kesintilerin önemli bir bölümü kendi kodunuzda değil, güvendiğiniz bir dış servisin yavaşlamasında başlar ve sizin uygulamanız üzerinden yayılır.

1. Zaman aşımı: en ucuz ve en çok atlanan önlem

Çoğu HTTP istemcisi varsayılan olarak çok uzun süre — bazen sonsuza kadar — bekler. Dış servis çökmeden yavaşladığında bu durum şu zinciri üretir: her istek bir işçi süreci meşgul eder, işçiler tükenir, kendi uygulamanız da yanıt veremez hâle gelir. Yani dış servisin yavaşlığı sizin kesintiniz olur.

Bağlantı ve okuma için ayrı ayrı zaman aşımı belirleyin. Kullanıcının beklediği bir istekte üst sınır genellikle birkaç saniyedir; arka plan işlerinde daha uzun tutulabilir. Kritik nokta şudur: varsayılanı bilmeden bırakmak, bir karar vermemek değil, en kötü kararı vermektir.

2. Tekrar deneme — ama her hatayı değil

Tekrar deneme, geçici hataları görünmez kılar; yanlış uygulandığında ise çöken servisi tamamen yere serer. İki kural belirleyicidir.

Neyi tekrar denemeli? Ağ hataları, zaman aşımları ve sunucu tarafı geçici hatalar (5xx, 429) tekrar denenebilir. İstemci hataları (400, 401, 404, 422) tekrar denenmemelidir — aynı istek yine aynı hatayı verecektir, tek sonucu boşa yük olur.

Nasıl beklemeli? Sabit aralıklı tekrar deneme, yük altındaki bir servise eşzamanlı dalgalar hâlinde vurur. Doğru desen üstel geri çekilmedir: 1 sn, 2 sn, 4 sn... üzerine küçük bir rastgelelik eklenir. Bu rastgelelik, aynı anda hata alan yüzlerce istemcinin aynı saniyede yeniden denemesini engeller.

3. Devre kesici: ısrar etmeyi bırakmak

Bir servis gerçekten çökmüşse, her isteği üç kez denemek durumu iyileştirmez; hem kendi kaynaklarınızı hem karşı tarafı tüketir. Devre kesici deseni bu noktada devreye girer: belirli bir süre içinde belirli sayıda hata olursa devre açılır ve bir süre boyunca istekler hiç gönderilmez, doğrudan hata döndürülür. Süre sonunda tek bir deneme isteği gönderilir; başarılıysa devre kapanır.

Bu desenin asıl faydası, çöken servisin toparlanmasına alan bırakmasıdır. Yan faydası ise kullanıcıya hızlı ve dürüst bir hata dönebilmenizdir — otuz saniye bekleyip hata almak, bir saniyede "şu an bu özellik kullanılamıyor" demekten çok daha kötü bir deneyimdir.

4. Idempotency: aynı işi iki kez yapmamak

Tekrar deneme mekanizması, tehlikeli bir soru getirir: istek aslında ulaştıysa ve yalnızca yanıt kaybolduysa? Ödeme veya sipariş gibi işlemlerde bu, çift kayıt anlamına gelir.

Çözüm, her mantıksal işleme benzersiz bir idempotency anahtarı vermek ve karşı tarafın aynı anahtarla gelen ikinci isteği yeni bir işlem saymamasıdır. Kendi API'nizi tasarlarken de aynı sözleşmeyi sunmalısınız; bu konu REST API tasarımı ve webhook uçları yazılarımızda karşı taraftan bakılarak ele alınıyor.

5. Eşzamanlı yapmayın: kuyruğa alın

Kullanıcının bir düğmeye basmasıyla dış servise gitmek arasında doğrudan bağ kurmak, dayanıklılığı baştan sınırlar. Fatura oluşturma, e-posta gönderme, bildirim iletme gibi işler kuyruğa alındığında dış servis çöktüğünde kullanıcı akışı etkilenmez; iş kuyrukta bekler ve servis döndüğünde tamamlanır.

Dış servis yanıtlarını kısa süreli önbelleğe almak da yükü belirgin azaltır; süre ve geçersiz kılma kararları için önbellek stratejileri yazımıza bakabilirsiniz. Kuyruk kullanımının kritik detayı ölü mektup kuyruğudur: kalıcı olarak başarısız olan işler sonsuza kadar denenmemeli, ayrı bir yere alınıp görünür kılınmalıdır. Aksi halde tek bir bozuk kayıt tüm kuyruğu tıkar.

6. Görünürlük: sessiz başarısızlık en kötüsüdür

Dayanıklılık desenleri hataları gizler — bu iyidir, ama tamamen görünmez kılarsa tehlikelidir. Her entegrasyon için üç şey ölçülmelidir: başarı oranı, gecikme dağılımı (ortalama değil, yüksek yüzdelikler) ve devre kesicinin kaç kez açıldığı. Neyin loglanacağına dair pratik kurallar için üretimde log yazımız yol gösterir; özellikle dış servis yanıtlarında hassas veri loglamamak kritik bir ayrıntıdır.

Sözleşme değişiklikleri de sessiz kırılma kaynağıdır: karşı taraf bir alanı kaldırdığında kodunuz genellikle üretimde patlar. Yanıtları şemaya karşı doğrulamak ve beklenmeyen yapıyı hata olarak raporlamak bu riski erken yakalar. HTTP semantiği ve durum kodlarının doğru yorumu için MDN HTTP dokümantasyonu iyi bir referanstır.

Sonuç

Dayanıklı bir API entegrasyonu, mutlu senaryoyu değil kötü senaryoyu tasarlamakla kurulur. Her dış çağrıya zaman aşımı koymak, yalnızca geçici hataları üstel geri çekilmeyle tekrar denemek, ısrar etmeyi bırakan bir devre kesici eklemek, idempotency anahtarıyla çift işlemi engellemek ve kritik işleri kuyruğa almak — bu beş adım, entegrasyon kaynaklı kesintilerin büyük kısmını ortadan kaldırır. Bugün kod tabanınızda hızlı bir arama yapın: zaman aşımı belirtilmemiş kaç tane dış çağrı var? O sayı, gelecekteki kesintilerinizin listesidir.