Proxy Üzerinden İdempotens ve Yeniden Denemeler: Bir İsteğin Tekrarı Neden Sipariş İkizine Yol Açmaz
Makale içeriği
- Giriş: tek buton, iki sipariş ve yanıtların kaybolduğu bir tünel
- Temeller: i̇dempotens nedir ve bir isteğin tekrarı neden tehlikelidir
- Derinlemesine bakış: sunucu sözleşmesi ve güvenli tekrarın anatomisi
- Yöntem 1: i̇stemci tarafında idempotent anahtar üretmek ve iletmek
- Yöntem 2: anahtar deposunun sunucu tarafı uygulaması
- Yöntem 3: i̇dempotensi bozmayan proxy üzerinden yeniden deneme protokolü
- Yöntem 4: sunucu idempotent anahtarları desteklemiyorsa
- Sık yapılan hatalar: ekipler kendi elleriyle nasıl ikiz yaratır
- Uygulama için araçlar ve kaynaklar
- Vakalar ve sonuçlar
- Sss: i̇dempotens ve tekrarlar hakkında zor sorular
- Sonuç: umut yerine sözleşme
Giriş: Tek buton, iki sipariş ve yanıtların kaybolduğu bir tünel
Yıllardır sorunsuz çalışan bir entegrasyon düşünün. Servisiniz dış bir sisteme sipariş gönderiyor, akış mobil proxy havuzundan geçiyor; amaç istekleri bölgelere dağıtmak ve tek bir adresin limitine takılmamak. Her şey istikrarlı. Derken muhasebe bir rapor getiriyor: ay boyunca iş ortağında kırk yedi ikiz sipariş belirmiş. Aynı ürünler, aynı tutarlar, oluşturulma saatleri arasında üç-dört saniye fark. Kimse hiçbir şeyi değiştirmemiş. Ne oldu?
En olağan şey oldu: proxy üzerinden bağlantı dönüş yolunda koptu. Sunucu isteği aldı, siparişi oluşturdu, yanıtı gönderdi; ama yanıt istemciye ulaşmadı. İstemci dürüstçe isteğin başarısız olduğunu düşündü ve tekrarladı. İkinci istek de çalıştı. İkiz böyle doğar ve hiçbir yeniden deneme politikası tek başına buna karşı korumaz.
Burada hemen bir sınır çizmek önemli. 429 hatasından sonra isteklerin nasıl doğru şekilde tekrarlanacağını, denemeler arasında ne kadar bekleneceğini ve üstel gecikmenin nasıl kurulacağını ayrı bir yazıda ele aldık: bu, yeniden deneme politikasının konusu. Bugünün konusu başka. Bugün, istemci ile sunucu arasındaki sözleşmeden söz ediyoruz; bu sözleşme, tekrarı nasıl gerçekleştirdiğinizden bağımsız olarak onu güvenli ya da tehlikeli kılar. Bu sözleşmenin adı idempotenstir ve başlıca aracı idempotent anahtardır.
Konu neden özellikle proxy üzerinden çalışırken bu kadar kritik? Çünkü proxy, zincire yanıtın kaybolabileceği bir bölüm daha ekler. Üstelik mobil proxy'ler rotasyonda dış IP'yi değiştirir ve sunucu pekâlâ ikinci isteği başka bir adresten görebilir. İkiz korumanız oturuma, IP'ye veya zaman penceresine dayanıyorsa çöker. İdempotent anahtara dayanıyorsa tekrarın nereden geldiği hiç önemli değildir.
Bu rehberde idempotensin protokol ve iş mantığı düzeyinde nasıl işlediğini, anahtarların nasıl üretilip saklanacağını, eşzamanlı tekrarlara dayanan bir sunucu deposunun nasıl tasarlanacağını, dış API anahtarları desteklemiyorsa ne yapılacağını ve deneyimli ekiplerin bile takıldığı hataları ele alacağız. Rakamlarla vakaları inceleyecek, kontrol listeleri oluşturacak ve zor soruları yanıtlayacağız. Materyal, sipariş, ödeme ve "iki kez"in "kötü" anlamına geldiği her türlü işlemle çalışan entegrasyon geliştiricileri, mimarlar ve teknik liderler için hazırlandı.
Temeller: İdempotens nedir ve bir isteğin tekrarı neden tehlikelidir
Basit kelimelerle tanım
Bir işlem, birden çok kez yürütüldüğünde tek yürütmeyle aynı sonucu veriyorsa idempotenttir. Asansör çağırma butonuna on kez basmak idempotenttir: asansör bir kez gelir. Sepete bir birim daha ürün eklemek idempotent değildir: her basış durumu değiştirir. Para transferi kesinlikle idempotent değildir; tabii sistem özellikle aynı kimlikle yapılan transfer tekrarının hiçbir şey yapmaması için tasarlanmadıysa.
HTTP'de spesifikasyona göre idempotent sayılan metotlar vardır: GET, PUT, DELETE, HEAD. Bir de varsayılan olarak idempotent sayılmayan POST vardır. Sipariş oluşturmak, ödeme yapmak, mesaj göndermek için en sık kullanılan metot tam da POST'tur. Yani en riskli işlem, en idempotent olmayan metotta yaşar. Tesadüf mü? Daha çok, birlikte yaşamak zorunda olduğumuz tarihsel bir düzenlilik.
Her isteğin üç olası sonucu
İstemci bir istek gönderip yanıt alamadığında belirsizlik durumuna düşer. Tam olarak üç senaryo mümkündür:
- İstek sunucuya ulaşmadı. Tekrarlamak güvenlidir: hiçbir şey olmadı.
- İstek ulaştı, sunucu işlemi yürüttü, yanıt kayboldu. Tekrarlamak tehlikelidir: işlem ikinci kez yürütülür.
- İstek ulaştı, sunucu yürütmeye başladı ve henüz bitirmedi. Tekrarlamak iki kat tehlikelidir: iki işlem paralel yürütülür.
Asıl bela, istemcinin bu senaryoları ayırt edememesidir. Zaman aşımı üç durumda da aynı görünür. Kopan bağlantı da öyle. Buradan dağıtık sistemlerin temel ilkesi çıkar: güvenilir teslim ancak "en az bir kez" (at-least-once) olarak mümkündür. "Tam bir kez" (exactly-once) garantisi taşıma katmanında elde edilemez; yalnızca uygulama katmanında, tekrarları zararsız kılarak taklit edilebilir. İdempotens de tam olarak bu taklit yöntemidir.
Proxy belirsizlik zincirini nasıl uzatır
Proxy olmadan istemci ile sunucu arasında tek bir ağ bölümü vardır. Proxy ile iki tane: istemci — proxy ve proxy — sunucu. Yanıt her ikisinde de kaybolabilir. Üstelik ilk bölümde kaybolduysa, proxy yanıtı çoktan almıştır, sunucu işlemi çoktan tamamlamıştır ve istemci bunu asla öğrenemeyecektir.
Mobil proxy'ler kendine özgü bir durum daha ekler. Planlı ya da talep üzerine IP rotasyonu, baz istasyonları arasında geçiş, radyo kanalında doğal kalite dalgalanmaları. Bu olayların her biri TCP bağlantısını rastgele bir anda koparabilir. Üstelik kopma genellikle istek gövdesi aktarılırken değil (gövde küçüktür ve hızla gider), yanıt beklenirken gerçekleşir; o anda bağlantı sadece açık tutulur. Tam o anda sunucu siparişinizi işler. Tam o anda kopma ikiz şansını maksimuma çıkarır.
İdempotent anahtar nedir
İdempotent anahtar (Idempotency-Key), istemcinin bir kez üretip bu işlemi yürütmek için yaptığı her denemeyle birlikte gönderdiği benzersiz bir iş işlemi tanımlayıcısıdır. Sunucu anahtarı ve sonucu hatırlar. Aynı anahtarla gelen tekrar istekte sunucu işlemi yeniden yürütmez, saklanan sonucu döndürür. İstemci istediği kadar tekrarlayabilir: sipariş bir kez oluşturulur.
İfadeye dikkat edin: anahtar işlemi tanımlar, HTTP isteğini değil. Bu ayrım, ileride uygulama hatalarını incelerken merkezi hâle gelecek.
Derinlemesine bakış: Sunucu sözleşmesi ve güvenli tekrarın anatomisi
Sözleşme bir davranış anlaşmasıdır
İdempotens bir başlık ya da kütüphane değildir. Sunucunun tekrarlarda istemciye belirli bir davranış vaat ettiği, istemcinin de anahtar oluşturma kurallarına uyacağını taahhüt ettiği bir sözleşmedir. İyi bir sözleşme şu soruları yanıtlar:
- İdempotens birimi hangi varlıktır: sipariş, ödeme, sipariş satırı, parti mi?
- İstemci anahtarı nasıl iletir: başlık, gövde alanı, URL parçası?
- Anahtar çakıştığında ama gövde farklıysa ne olur?
- İlk istek hâlâ çalışırken aynı anahtarla ikincisi gelirse ne olur?
- Sunucu anahtarı ne kadar hatırlar?
- Tekrarda ne döner: aynı yanıtın byte byte kopyası mı, yoksa varlığın güncel hâli mi?
- Tekrar, loglar ve metriklerde yeni istekten nasıl ayrılır?
Bu sorulardan en az birinin yanıtı API dokümantasyonunda yoksa sözleşme eksiktir ve belirsiz durumlarda davranış uygulamaya, sürüme ve ayın evresine bağlı kalır.
Anahtarın üç durumu
Sunucuda her anahtarın üç aşamalı bir yaşam döngüsü vardır. Bu döngüyü anlamak, ikizlerle ilgili sorunların yüzde doksanını açıklar.
- Yok. Anahtar ilk kez görülür. Sunucu onu atomik olarak rezerve etmeli ve işlemeye başlamalıdır.
- İşlemde (in-progress). İlk istek işleniyor. Aynı anahtarla gelen ikinci istek ikinci bir işleme başlatmamalıdır. Seçenekler: bekleme isteyen 409 Conflict döndürmek, ilk bitene kadar bloklayıp sonucunu döndürmek, duruma bağlantı veren 202 Accepted döndürmek.
- Tamamlandı. Sonuç saklandı. Tekrar, yan etki olmadan saklanan sonucu döndürür.
En sık görülen mimari hata, ortadaki durumun atlanmasıdır. Geliştirici "anahtar veritabanında var mı" diye bakar, yok bulur, işlemeye başlar; tam o anda paralel bir tekrar da aynısını yapar. İki akış, iki kontrol, iki sipariş. Kontrol ve rezervasyon tek bir atomik işlem olmalıdır: benzersiz indeksli bir ekleme, Redis'te koşullu yazma, kilitleme içeren işlem.
İstek parmak izi
Anahtar işlemi tanımlar, ama hangi içerikli işlemi? İstemci bir hata nedeniyle K anahtarını 1000 liralık tutarla gönderdiyse ve sonra aynı anahtarla 10000 liralık tutarla tekrarlarsa sunucu ne yapmalı? Sessizce ilk işlemin sonucunu döndürmek tehlikelidir: istemci 10000 ödediğini sanır. İkinciyi yürütmek idempotensi bozar.
Doğru cevap: sunucu istek parmak izini (fingerprint) saklar — normalleştirilmiş gövdenin ve anlamlı başlıkların bir karması. Aynı anahtarla ama farklı parmak iziyle gelen tekrarda 422 Unprocessable Content ya da idempotency_key_reused_with_different_payload gibi açık kodlu bir 400 hatası döner. Bu, istemcinin mantık hatalarına ve sahte tekrarlara karşı korur.
Yanıtı saklama: Anlık görüntü mü, güncel durum mu
Tekrarda ne döndürüleceğine dair iki yaklaşım vardır. Anlık görüntü: sunucu orijinal yanıtın durumunu, başlıklarını ve gövdesini saklar ve değişmeden döndürür. Bu, kesin idempotent ve öngörülebilirdir. Güncel durum: sunucu anahtarla oluşturulan varlığı bulur ve güncel temsilini döndürür. Denemeler arasında sipariş başka bir duruma geçtiyse daha kullanışlıdır ama daha az öngörülebilirdir.
Ödeme sistemlerinde anlık görüntü baskındır: istemci ilk denemede aldığı yanıtın tam aynısını almalıdır. Sipariş yönetim sistemlerinde sıklıkla melez kullanılır: hata kodları için anlık görüntü, başarı için güncel durum. Önemli olan seçimin sözleşmede sabitlenmiş olmasıdır.
Proxy sözleşme düzeyinde neyi değiştirir
Teknik olarak proxy idempotens sözleşmesine katılmaz: başlıklar ve gövde için şeffaftır. Ama olasılıkları değiştirir. Doğrudan bağlantıda başarılı yürütmeden sonra yanıtın kaybolması nadirdir, yüzdenin yüzdesi kadar bir oran. Mobil proxy ve rotasyonlu bir zincirde bu olay düzenli hâle gelir. Beş dakikalık IP rotasyonu ile bazı entegrasyonlarda isteklerin yaklaşık %0,3–0,8'inin yanıt bekleme aşamasında bağlantı koptuğunu gözlemledik. Günde on bin sipariş için bu, her gün otuz-seksen potansiyel ikiz demektir. İdempotent anahtar olmadan her biri gerçek bir ikize dönüşür.
Bir ikinci incelik daha var. Birçok sunucu anti-fraud mantığına "başka IP'den gelen tekrar istek" kontrolü ekler. Mobil proxy rotasyonunda tekrar neredeyse her zaman yeni bir adresten gelir. Sunucu bunu şüpheli aktivite olarak yorumlar ve anahtar deposuna başvurmadan tekrarı reddederse, istemci saklanan sonucu alamaz ve belirsiz kalır. İyi bir sözleşme, anahtarı ağa bağlı sezgilerden önce kontrol eder.
Yöntem 1: İstemci tarafında idempotent anahtar üretmek ve iletmek
Anahtar nerede doğar
Ana kural: anahtar iş işlemi başına bir kez, ilk gönderme denemesinden önce üretilir ve işlemi gerçekleştirme niyetiyle birlikte saklanır. Anahtar her HTTP çağrısında HTTP istemcisinin içinde oluşturulursa tekrar yeni bir anahtar alır ve tüm koruma sıfırlanır. Bu o kadar sık yapılan bir hata ki ayrı bir yanlış kalıplar bölümüne taşıyacağız; ama burada da tekrarlayalım: anahtar taşıma düzeyinde değil, sipariş servisi düzeyinde yaşar.
Pratik sıralama şöyle görünür:
- Kullanıcı ya da iç süreç sipariş oluşturmayı başlatır.
- Servis, durumu pending olan yerel bir "sipariş niyeti" kaydı oluşturur ve bir anahtar üretir.
- Anahtar ve veri yükü tek bir işlemde yerel veritabanına kaydedilir.
- Ancak işlem kesinleştikten sonra dış API'ye proxy üzerinden gönderim başlatılır.
- Tüm tekrarlar anahtarı yerel kayıttan okur, yenisini üretmez.
- Yanıt alındıktan sonra yerel kayıt sonuç ve dış sipariş kimliğiyle güncellenir.
Bu sıralama, servisiniz tekrarlar ortasında yeniden başlasa bile anahtarın değişmemesini garanti eder: anahtar veritabanında durur.
Anahtar biçimi
Anahtar küresel olarak benzersiz ve üçüncü kişiler için tahmin edilemez olmalıdır. Çalışan seçenekler:
- UUID sürüm 4 — klasik, 122 bit rastgelelik, her yerde uygun.
- UUID sürüm 7 veya ULID — üst bitlerde zaman damgası taşır, bu da sunucu veritabanında sıralama ve indeksleme için kullanışlıdır. 2026'da yeni sistemler için artık standart tercih.
- Doğal tanımlayıcıdan türetilen deterministik anahtar — örneğin sepet kimliği, kullanıcı kimliği ve sepet sürümünün karması. İstemci durumu kaybedip aynı veriden anahtarı yeniden üretebildiğinde kullanışlıdır.
Kaçınılması gerekenler: sıralı sayılar (başkasının anahtarını kolayca tahmin edip başkasının yanıtını alırsınız), kısa dizeler, yalnızca düşük hassasiyetli zamana bağlı anahtarlar.
İletim yöntemi
Fiilî standart Idempotency-Key başlığıdır. IETF spesifikasyon taslağı tam da bu adı sabitler ve modern API'lerin çoğu buna uyar. Proxy üzerinden örnek çağrı:
curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders
Bazı API'ler anahtarı istek gövdesinde kabul eder (client_reference_id, external_id, request_id alanı). Bu da çalışan bir seçenektir; ama bir incelikle: sunucu gövde alanını anahtar olarak kullanıyorsa, bu alan mutlaka benzersiz indekste yer almalıdır; aksi hâlde koruma değil, sadece etiket olur.
Anahtarın kapsamı
Anahtar tek bir istemci hesabı ve tek bir uç nokta içinde benzersiz olmalıdır. İyi bir sunucu, dahili depolama anahtarını hesap kimliği, metot, yol ve iletilen anahtarın birleşimi olarak oluşturur. Bu, farklı istemciler arasındaki çakışmalara ve anahtarın başka bir işlem için kazara yeniden kullanılmasına karşı korur.
İstemci tarafı kontrol listesi
- Anahtar ilk denemeden önce üretilir ve niyetle birlikte veritabanında saklanır.
- Tüm tekrarlar aynı anahtarı kullanır.
- Tekrarda istek gövdesi ilk denemeyle byte byte aynıdır.
- İstemci 409'u (işlem sürüyor) hata değil, bekleyip tekrarlama sinyali olarak işler.
- İstemci parmak izi uyuşmazlığı kodlu 422'yi müdahale gerektiren bir mantık hatası olarak işler.
- İstemci anahtarı işlemle ilgili her log satırına yazar; böylece ikizler soruşturulabilir.
- İstemci proxy değişiminde, IP rotasyonunda veya yedek havuza geçişte anahtarı sıfırlamaz.
Yöntem 2: Anahtar deposunun sunucu tarafı uygulaması
İstemcilerinizin veya iş ortaklarınızın proxy üzerinden eriştiği bir sunucunun sahibiyseniz bu bölüm size hitap eder. Yalnızca istemciyseniz, bu bölüm başkasının uygulamasının kalitesini dokümantasyon ve davranıştan değerlendirmenize yardımcı olur.
Depolama şeması
Anahtarlar için asgari tablo veya yapı şu alanları içerir:
- scope_key — bileşik anahtar: hesap, metot, yol, iletilen Idempotency-Key. Benzersiz indeks.
- fingerprint — normalleştirilmiş istek gövdesinin karması.
- state — şu değerlerden biri: in_progress, completed, failed.
- response_status, response_headers, response_body — yanıt anlık görüntüsü, tamamlanınca doldurulur.
- resource_id — varsa oluşturulan varlığın kimliği.
- locked_at, completed_at, expires_at — askıda kalan işlemlerin yönetimi ve temizlik için zaman damgaları.
Atomik rezervasyon
Uygulamanın kalbi, tek bir eylemle ya in_progress durumunda bir kayıt oluşturan ya da kaydın zaten var olduğunu bildiren işlemdir. İlişkisel veritabanında bu, benzersiz indeks çakışmasını işleyen bir eklemedir. Redis'te, anahtar yoksa değeri yazan ve hemen yaşam süresini belirleyen NX ve EX bayraklı SET komutudur. "Önce SELECT, sonra INSERT" yok: arada paralel bir tekrar sızar.
Mantık düzeyinde sözde kod:
- scope_key ve fingerprint'i hesapla.
- state = in_progress olan bir kayıt eklemeyi dene. Ekleme başarılıysa işlemi yürütmeye geç.
- Çakışma varsa var olan kaydı oku.
- Fingerprint uyuşmuyorsa uyuşmazlık kodlu 422 döndür.
- state = in_progress ise Retry-After başlıklı 409 döndür ya da (makul zaman aşımı sınırında) tamamlanmayı bekle.
- state = completed ise saklanan yanıt anlık görüntüsünü, tekrarı işaretleyen bir başlıkla döndür; örneğin
Idempotent-Replayed: true.
Yürütme ve sonucun kesinleştirilmesi
İkinci tuzak burada gizlidir. İşlem çalıştı, sipariş oluştu, ama süreç sonucu anahtar deposuna yazmadan çöktü. Kayıt sonsuza dek in_progress durumunda kalır. Tekrar 409 alır, sonra bir 409 daha ve böylece sonsuza kadar.
Üç çözüm yaklaşımı vardır:
- Tek işlem. Sipariş oluşturma ve anahtar kaydını güncelleme aynı veritabanı işleminde yürütülür. Sipariş ve anahtarlar aynı veritabanında yaşıyorsa en güvenilir seçenek.
- Anahtarı varlığın parçası yapmak. İdempotent anahtar doğrudan sipariş tablosunda benzersiz indeksle saklanır. O zaman siparişin kendisi anahtar kaydıdır; ayrı tablo gerekmez. İşlem başına tek varlık olan durumlar için basit ve güvenilir.
- Askıda kalanları kurtarma. Arka plan süreci eşikten (örneğin 60 saniye) eski in_progress kayıtlarını bulur, işlemin gerçekten yürütülüp yürütülmediğini kontrol eder (resource_id ya da varlık araması ile) ve ya kesinleştirmeyi tamamlar ya da kaydı failed'a çevirip tekrara izin verir.
İlk denemenin hatalarını işleme
İlk deneme hatayla biterse ne saklanmalı? Hata tipine bağlı. Doğrulama hataları (400, 422) deterministiktir: aynı gövdeyle tekrar aynı sonucu verir, önbelleğe alınabilir. Altyapı hataları (500, 503, veritabanı zaman aşımı) deterministik değildir: bunlar önbelleğe alınırsa istemci işlemi asla başarıyla tamamlayamaz. Doğru davranış: altyapı hatasında anahtarı serbest bırakmak (kaydı silmek ya da failed'a çevirip yeniden sahiplenmeye izin vermek), böylece sonraki tekrar yeniden denesin.
Anahtarın yaşam süresi
Anahtarlar sonsuza kadar saklanamaz: tablo şişer. Ama çok kısa süre de tehlikelidir: istemci ağ arızasından yarım saat sonra tekrarlarsa anahtar hâlâ yaşıyor olmalıdır. Büyük ödeme sağlayıcılarının pratiği asgari 24 saatte birleşiyor. E-ticarette siparişler için 24–72 saat makuldür. İstemcinin uzun süreli arızalardan sonra tekrarlayabileceği işlemler için (örneğin günde bir kez katalog senkronizasyonu) süre, senkronizasyon aralığının en az iki katı olmalıdır.
Gözlemlenebilirlik
Her tekrar iz bırakmalıdır. Toplanmaya değer metrikler: completed'a denk gelen tekrar sayısı (zararsız tekrarlar), 409 sayısı (eşzamanlı tekrarlar), 422 sayısı (parmak izi uyuşmazlığı — neredeyse her zaman istemci hatası), en eski in_progress kaydının yaşı (askıda işlemlerin göstergesi). Tekrarların benzersiz işlemlere oranı, istemciyle sunucu arasındaki ağ kalitesinin doğrudan ölçüsüdür. Ani artış, proxy kanalının kalitesinin bozulduğunu ya da rotasyonun değiştiğini gösterir.
Sunucu tarafı kontrol listesi
- Anahtar rezervasyonu atomiktir.
- Ayrı bir in_progress durumu ve eşzamanlı tekrara anlaşılır bir yanıt vardır.
- Gövde parmak izi saklanır; uyuşmazlık açık bir hatayla reddedilir.
- Sonuç kesinleştirme işlemseldir veya askıda kayıtları kurtarma mekanizması vardır.
- Altyapı hataları önbelleğe alınmaz, deterministik olanlar alınır.
- TTL 24 saatten az değildir ve belgelenmiştir.
- Tekrar bir başlıkla işaretlenir ve metriklerde görünür.
- Anahtar kontrolü anti-fraud ağ sezgilerinden önce gelir.
Yöntem 3: İdempotensi bozmayan proxy üzerinden yeniden deneme protokolü
Yeniden deneme politikası komşu makalenin konusudur; ama yeniden deneme politikasının idempotensle kesiştiği dar bir alan vardır: proxy zincirinden hangi sinyaller tekrarın gerektiğini gösterir ve tekrar sözleşmeyi nasıl bozmamalıdır. Bunu ele alalım.
Proxy arızasını upstream arızasından ayırın
Proxy üzerinden çalışırken istemci üç kaynaklı hata alır ve bunlara farklı tepki vermelidir:
- Proxy'ye bağlantı hataları. Proxy'ye bağlanılamadı, proxy 407 döndü (kimlik doğrulama gerekli), proxy istek gönderilmeden bağlantıyı kapattı. İstek sunucuya kesinlikle ulaşmadı. Tekrar anahtar olmadan bile güvenlidir; ama anahtarla daha iyidir.
- Proxy'nin upstream'e erişirken verdiği hatalar. Proxy 502 Bad Gateway veya 504 Gateway Timeout döndürdü. Burada belirsizlik en yüksektir: 502 genellikle upstream'in düzgün yanıt vermediğini, ama işlemi yürütmüş olabileceğini gösterir; 504, proxy'nin beklemekten yorulduğunu, sunucunun hâlâ işliyor olabileceğini gösterir. Tekrar yalnızca anahtarla.
- Proxy'den geçen upstream yanıtları. Hedef sunucudan gelen 500, 503, 429. Semantiği hedef API'nin sözleşmesi belirler. Yeniden deneme politikası kurallarına göre anahtarla tekrar.
Ayrı bir dikkat yanıt okunurken bağlantının kopmasına değer. Başlıklar geldi, gövde koptu. En sinsi durum bu: 201 Created durumunu belki gördünüz, ama gövdeden sipariş kimliğini alamadınız. Anahtarla tekrar eksiksiz yanıt anlık görüntüsünü döndürür. Anahtar olmadan ikinci bir sipariş alırsınız ve birincinin kimliğini de asla öğrenemezsiniz.
IP rotasyonunu arka plan değil, olay olarak ele alın
Mobil proxy havuzunuz adresleri planlı olarak döndürüyorsa, kritik işlemlerin gönderimini istikrar pencereleriyle senkronize edin. Basit bir teknik: proxy servisi API'sinden bir sonraki rotasyona kalan süreyi öğrenmek ve eğer kalan süre yanıt bekleme zaman aşımınızdan kısaysa sipariş oluşturmaya başlamamak. Bu idempotensin yerini tutmaz ama tekrar sayısını, dolayısıyla anahtar deposu ve iş ortağı anti-fraud yükünü azaltır.
Rotasyon talep üzerineyse, bir işlemin denemeleri arasında gereksiz yere IP değiştirmeyin. Bazı ekipler "yapışmayı aşmak için" bunu yapar; ama aynı anahtarı yeni bir adresten gören sunucu ek kontrol başlatabilir. Anahtar ikizi önler, ama tekrar yavaşlayabilir.
Zaman aşımları: Bir değil iki sınır
Doğrudan bağlantıda genellikle yanıt için tek bir zaman aşımı tanımlanır. Proxy üzerinden en az iki tane gerekir: proxy ile bağlantı kurma zaman aşımı (kısa, birkaç saniye) ve upstream'den yanıt bekleme zaman aşımı (daha uzun, sipariş işleme süresini hesaba katarak). İkisi birleştirilirse kısa zaman aşımı yavaş işlemede sürekli devreye girip gereksiz tekrarlar doğurur, uzun olan ise erişilemeyen proxy için fazladan saniyeler bekletir.
Önemli: yanıt bekleme zaman aşımı, sunucudaki gerçek sipariş oluşturma süresinden kısa olmamalıdır. Aksi hâlde sistematik olarak tam işleme anında bağlantıyı kesersiniz ve her işlem "kopan deneme artı tekrar" çiftine dönüşür. Anahtar ikizleri önler ama sunucu boşuna işlem kaynağı harcar.
Başka bir proxy üzerinden tekrar
Makul strateji: ilk tekrar denemesi aynı proxy üzerinden (belki bağlantı sadece göz kırptı), ikincisi havuzdan başka bir proxy üzerinden (belki sorun belirli kanalda). Anahtar değişmez. Gövde değişmez. Yalnızca rota değişir. Böylece ağ sorunlarını isteğin kendi sorunlarından ayırır ve tanı bilgisi elde edersiniz: ikinci proxy'den hemen geçtiyse sorun kanaldaydı.
Adım adım güvenli tekrar protokolü
- Anahtarı ve gövdeyi yerel niyet kaydından oku.
- İsteği mevcut proxy üzerinden iki zaman aşımıyla gönder.
- Başarı durumunda: sonucu kaydet, bitir.
- Sunucudan 409: belirtilen süre ya da makul aralık kadar bekle, aynı anahtarla tekrarla.
- Parmak izi uyuşmazlığı kodlu 422: dur, olay çıkar, otomatik tekrarlama.
- Proxy bağlantı hatası: proxy değiştir, hemen tekrarla.
- 502, 504, kopma ya da zaman aşımı: gecikme politikasını uygula, aynı anahtarla tekrarla; ikinci tekrardan itibaren başka proxy üzerinden.
- Denemeler tükendikten sonra: kaydı unknown durumunda bırak, mutabakat kuyruğuna aktar (bkz. Yöntem 4).
Sekizinci madde kritiktir. "Sipariş oluşturuldu mu bilmiyorum" durumu meşru bir durumdur ve sessizce ne "oluşturuldu"ya ne de "oluşturulmadı"ya indirgenemez.
Yöntem 4: Sunucu idempotent anahtarları desteklemiyorsa
İdeal dünya, dokümantasyonunda "idempotens" kelimesinin geçmediği iş ortağı API'sinde son bulur. İstemciyseniz ve sunucu her POST'ta yeni sipariş oluşturuyorsa ne yapmalı? Basitten mimariye uzanan birkaç teknik vardır.
İstek gövdesindeki doğal anahtar
Birçok API, biçimsel Idempotency-Key olmadan external_order_id, client_reference, merchant_order_number gibi bir alan kabul eder ve hesap içinde bu alana göre benzersizlik vaat eder. Bu, başka bir adla idempotenstir. Dokümantasyonu kontrol edin ve en önemlisi davranışı doğrulayın: test ortamında aynı dış kimlikle iki istek gönderin ve yinelenen hatası mı dönüyor yoksa ikinci varlık mı oluşuyor bakın. Dokümantasyondaki vaatlerle gerçek davranış, istenenden daha sık ayrışır.
Tekrardan önce okuma
Sunucu, varlıkları dış kimliğinize ya da parametrelerinize göre (örneğin zamana ve tutara göre filtrelenen sipariş listesi) arama imkânı veriyorsa, her tekrardan önce bir kontrol isteği yapın: benim işaretlerimle bir sipariş zaten oluştu mu? Bu kesin bir garanti vermez (kontrol ve tekrar arasında bir aralık sızabilir), ama ikiz olasılığını büyük ölçüde azaltır. Şema:
- İlk deneme belirsiz bir şekilde sonuçlandı.
- Sunucudaki işlemin tamamlanmasına yetecek kadar bir aralık bekle.
- Dış kimlik ya da benzersiz alan kombinasyonuna göre filtrelenmiş bir GET çalıştır.
- Sipariş bulunursa kimliğini kaydet, tekrara gerek yok.
- Bulunamazsa POST'u tekrarla.
Aramanın işlemesi için siparişe bulunabileceği bir işaret koyun: yorum, özel alan, benzersiz pozisyon numarası. Sunucu onu anahtar olarak yok saysa bile yanıtta döndürür ve karşılaştırabilirsiniz.
İşlemi rezervasyon ve onaya bölmek
Bazı API'ler iki fazlı bir model destekler: önce taslak ya da hold (güvenle tekrarlanabilen veya iptal edilebilen işlem), sonra taslak kimliğiyle onay. Onay, kimliğiyle doğası gereği idempotenttir: bir taslağı iki kez onaylayamazsınız. Böyle bir model varsa, anahtar olsa bile tek adımlı oluşturmaya tercih edilir; çünkü en riskli adımın belirsizlik penceresini küçültür.
Sizin tarafınızda Outbox deseni
Sunucu hiçbir garanti vermese bile, sizin tarafınızda her işlemin tek bir niyetle çıkmasını garanti edebilirsiniz. İşlemsel Outbox, giden işlemlerin tablosudur; kayıt, iş değişikliğiyle (örneğin sepeti "oluşturuluyor" durumuna geçirmek) aynı işlemde bu tabloya düşer. Ayrı bir gönderici süreç Outbox'tan kayıtları alır ve proxy üzerinden istekleri yürütür. Her kaydın, anahtar ya da external_id olarak kullandığınız benzersiz bir kimliği vardır. Gönderici iş ortasında çökse bile kayıt Outbox'ta kalır ve tekrar aynı kimlikle gider.
Son savunma hattı olarak mutabakat
Reconciliation, yani mutabakat, işlemlerinizin listesini iş ortağındaki varlıkların listesiyle karşılaştıran ve tutarsızlıkları bulan düzenli bir süreçtir: iş ortağında olup size bağlanmamış siparişler, unknown durumundaki işlemler, eşleşen işaretlere sahip ikizler. Mutabakat ikizi önlemez, ama onu bir ay sonra muhasebe raporundan değil, dakikalar içinde bulur. İstikrarsız kanallar üzerinden yapılan işlemler için bu zorunlu bir bileşendir, opsiyonel değil.
Pratik: mutabakatı, maksimum tekrar zaman aşımınızdan büyük işlemler için her 10–15 dakikada çalıştırın, bulunan varlıkları otomatik olarak unknown kayıtlara bağlayın ve tespit edilen ikizleri tutar eşiğin üzerindeyse manuel onayla iptal kuyruğuna aktarın.
Saga ve telafi işlemleri
Sipariş bir eylemler zincirinin parçasıysa (depo rezervasyonu, ödeme, teslimat), bir halkadaki ikiz tüm zinciri bozar. Saga deseni her adım için telafi edici bir eylem olduğunu varsayar: sipariş iptali, ödeme iadesi, rezervasyon kaldırma. Telafi de idempotent olmalıdır; yoksa iptal ikizleriyle mücadele edersiniz. Entegrasyonu tasarlarken "eylem — telafi" çiftlerini hemen yazın ve her ikisi için de tekrarın güvenli olduğunu doğrulayın.
Sık yapılan hatalar: Ekipler kendi elleriyle nasıl ikiz yaratır
Hata 1. Anahtar HTTP istemcisinin içinde üretilir
En yaygın olanı. HTTP kütüphanesinin üzerindeki sarmalayıcı her çağrıda yeni bir UUID ile Idempotency-Key başlığı ekler. Aynı kütüphanedeki yeniden deneme mekanizması gönderimi yeniden tetikler — ve yeni bir anahtar alır. Dışarıdan her şey doğru görünür: başlık var. Aslında koruma yoktur. Sunucu ya da proxy loglarından tekrarlarda anahtarın aynı kaldığını doğrulayın.
Hata 2. İstek "düzeltilirken" anahtar gövdeyle birlikte değişir
İstemci geçersiz alan nedeniyle 400 aldı, alanı düzeltti ve aynı anahtarla tekrarladı. Parmak izi kontrolü olan sunucu 422 döner. Kontrolü olmayan sunucu önbellekteki 400 hatasını döner ve istemci duvara toslar. Düzeltilmiş istek yeni bir işlemdir, yeni anahtar gerektirir.
Hata 3. Anahtar kontrolü SELECT, sonra INSERT
Yukarıda ele alındı, ama tekrarlayalım: okuma ile yazma arasında paralel bir tekrar sızar. Bu özellikle proxy üzerinden çalışırken sık görülür; çünkü istemci zaman aşımları birkaç saniye aralıklı tekrarlar doğurur ve sipariş işleme de o kadar sürer. Yalnızca atomik rezervasyon.
Hata 4. IP ya da oturuma göre idempotens
Sunucu "bu IP'den az önce aynı istek geldi" diye hatırlar ve tekrarı reddeder. Mobil proxy rotasyonunda tekrar başka bir adresten gelir ve koruma devreye girmez. Tersi de kötüdür: aynı proxy adresinden gelen meşru farklı siparişler (aynı IP arkasında çok müşteriniz var) ikiz olarak reddedilir. Anahtar açık olmalı ve istemci tarafından iletilmelidir.
Hata 5. Çok kısa TTL
Anahtarlar "Redis'i kirletmemek için" beş dakika yaşar. Ağ arızası yirmi dakika sürer. Tekrar kuyruğu işleme yarım saat sonra ulaşır. Anahtar unutulmuştur, sipariş ikinci kez oluşur. TTL, gerçekçi en uzun ertelenmiş tekrar senaryosunu kapsamalıdır.
Hata 6. Altyapı hatalarını önbelleğe almak
İlk deneme, veritabanının geçici erişilemezliği yüzünden 500 ile düştü. Sunucu 500'ü anahtar için sonuç olarak sakladı. Sonraki tüm tekrarlar 500'ü önbellekten alır, oysa veritabanı çoktan ayağa kalktı. İstemci, orijinal işlemle bağlantıyı kaybederek anahtarı değiştirmek zorunda kalır. Yalnızca deterministik sonuçlar önbelleğe alınabilir.
Hata 7. Unknown durumunu indirgemek
Denemeler tükendikten sonra istemci işlemi failed olarak işaretler ve kullanıcının siparişi yeniden vermesine izin verir. Ama sunucu ilk işlemi yürüttü. Kullanıcı iki sipariş ve iki kez çekim alır. Unknown durumu açıkça var olmalı ve iyimser bir varsayımla değil, mutabakatla çözülmelidir.
Hata 8. "Daha kolay" diye idempotent olmayan işlemleri tekrarlamak
Genel bir yeniden deneme katmanı, anahtarsız POST'lar dahil tüm istekleri aynı şekilde tekrarlar. Bu, ilk ağ fırtınasına kadar çalışır; sonrasında bir saatte yüzlerce ikiz belirir. Yeniden deneme katmanı hangi isteklerin tekrarlanabileceğini bilmeli ve açık anahtar olmadan idempotent olmayanları tekrarlamayı reddetmelidir.
Hata 9. Parti başına tek anahtar
İstemci yüz siparişten oluşan diziyi tek anahtarla gönderir. Sunucu altmış tanesini işleyip çöker. Aynı anahtarla tekrar 409 ya da kısmi bir anlık görüntü alır. Hangi kırk tanesinin oluşturulması gerektiği nasıl anlaşılır? Partiler için ya her pozisyon için anahtar, ya tüm partinin atomikliği için sunucu garantisi, ya da öğe başına durum içeren bir yanıt gerekir. Bunlar olmadan istikrarsız kanal üzerinden partiler kaos kaynağıdır.
Hata 10. Loglarda anahtarın olmaması
İkiz gerçekleşti ve bunun aynı anahtarla mı (sunucu hatası) yoksa iki farklı işlem mi (istemci hatası) olduğunu anlamaya çalışıyorsunuz. Loglarda anahtar yok. Soruşturma tahmine dönüşür. Anahtar, her iki tarafta ve proxy servisi başlık loglamayı destekliyorsa proxy günlüğünde de her satırda bulunmalıdır.
Uygulama için araçlar ve kaynaklar
İstemci tarafında
- Tanımlayıcı kütüphaneleri. UUIDv7 ve ULID üreticileri tüm büyük diller için mevcuttur. Anahtarlar sunucu veritabanı indekslerine girecekse, milisaniye içinde monotonluk garantileyenleri seçin.
- Ayrı zaman aşımlı HTTP istemcileri. İstemcinizin proxy'ye bağlanma zaman aşımını ve yanıt okuma zaman aşımını ayrı ayrı tanımlamanıza izin verdiğinden emin olun. Modern istemcilerin çoğu bunu yapabilir, ama varsayılan olarak genellikle tek bir zaman aşımı vardır.
- Teslim garantili kuyruklar. Outbox'ı uygulamak için işleme onayı olan herhangi bir broker sistemi uygundur. Önemli olan mesaj kimliğinin yeniden teslimler arasında sabit kalmasıdır — anahtarın temeli olarak kullanmak için idealdir.
- Proxy yönetim API'si. Kaliteli mobil proxy servislerinde kanal durumunu, rotasyona kalan süreyi öğrenmenize, talep üzerine IP değiştirmenize izin veren programatik bir arayüz bulunur. Bu API ile entegrasyon, kritik işlemleri rotasyondan önce başlatmamayı ve denemeler arasında rotayı bilinçli değiştirmeyi mümkün kılar.
Sunucu tarafında
- Benzersiz indeksli ilişkisel veritabanı. Hacimler elveriyorsa anahtar deposu için en güvenilir seçenek. Çakışma işleyen ekleme, kutudan çıkan atomik bir işlemdir.
- Redis veya eşdeğeri. Yüksek yüklü sistemler için: rezervasyon amacıyla NX ve EX bayraklı SET, yanıt anlık görüntüsü için ayrı anahtar. Düğüm arızasında veri kaybı riskini unutmayın ve kalıcılığı yapılandırın.
- İdempotens middleware'i. Popüler web çerçeveleri için temel sözleşmeyi (rezervasyon, parmak izi, anlık görüntü) uygulayan hazır ara katmanlar vardır. Eşzamanlı tekrarlarda ve yürütme ile kesinleştirme arasında çökmede nasıl davrandıklarını kontrol edin — iyi uygulamalarla biçimsel olanlar tam da orada ayrışır.
- API ağ geçitleri. Bazı ağ geçitleri girişte başlığa göre tekilleştirme yapabilir. Bu uygulamadan yükü alır, ama ağ geçidi genellikle iş sonucunu bilmez ve altyapı hatalarını önbelleğe alabilir. İlk filtre olarak kullanın, tek koruma olarak değil.
Test etme
- Ağ arızası enjeksiyonu. İsteği gönderdikten sonra ama yanıttan önce bağlantıyı koparabilen, yanıtı zaman aşımından uzun geciktirebilen, 502 ve 504 döndürebilen proxy test araçları. Bu tür testler olmadan sistemin tek önemli senaryodaki davranışını göremezsiniz.
- Eşzamanlı testler. Aynı anahtarla N isteğin eşzamanlı gönderimi. Beklenen sonuç: tam olarak bir oluşturulmuş varlık, N-1 adet 409 ya da anlık görüntü yanıtı. Başka herhangi bir sonuç kusurdur.
- İşlem ortasında yeniden başlatma testi. Sipariş oluşturulduktan sonra ama anahtar kesinleşmeden süreci öldürün. Askıda kayıtları kurtarma mekanizmasının çalıştığını doğrulayın.
- Rotasyon testi. İlk deneme bir IP üzerinden, tekrar başka bir IP üzerinden. Sunucunun tekrarı sezgiyle reddetmek yerine anlık görüntüyü döndürdüğünü kontrol edin.
Standartlar ve belgeler
Idempotency-Key başlığına ilişkin IETF spesifikasyon taslağı, sözleşmeyi formüle etmek için başlangıç noktasıdır: orada başlık adı, çakışma semantiği ve önerilen yanıt kodları tanımlanmıştır. Büyük ödeme sağlayıcılarının herkese açık dokümantasyonu, dış entegratörler için sözleşmenin nasıl yazılacağına dair iyi bir örnektir: TTL, gövde uyuşmazlığında davranış, eşzamanlı isteklerin işlenmesi. HTTP semantiği spesifikasyonundaki idempotent metotlar bölümü, PUT ve DELETE'nin neden tekrarlanabildiğini, POST'un neden tekrarlanamadığını açıklar; uç noktaları tasarlamadan önce bunu yeniden okumaya değer.
Vakalar ve sonuçlar
Vaka 1. Sipariş toplayıcı ve ayda 47 ikiz
Bir toplayıcı şirket, siparişleri lojistik ortağının sistemine her beş dakikada rotasyon yapan mobil proxy havuzu üzerinden iletiyordu. Hacim günde yaklaşık 12 bin siparişti. İdempotent anahtar yoktu: iş ortağı API'si bunları belgelemiyordu. İkizler ayda bir finansal mutabakatla keşfediliyordu; her biri iptal, iade ve manuel işçilikle ortalama 900 liraya mal oluyordu.
Proxy loglarındaki tanı şunu gösterdi: isteklerin %0,4'ü gövde gönderildikten sonra ve yanıt alınmadan önce bağlantı kopmasıyla sonlanıyordu; ağırlıklı olarak rotasyon dakikalarında. Tekrar üç saniye sonra gidiyordu ve vakaların %30'unda ilk deneme o ana kadar çoktan yürütülmüştü. Hesaplama gözlemlenen ikizlerle uyuşuyordu.
Çözüm üç adımda. Birincisi, iş ortağının API'sinin external_id alanını kabul ettiği ve bu alana göre yinelenenleri reddettiği ortaya çıktı; dokümantasyonda tek satırla anılıyordu. Alan, yerel Outbox'tan gelen sabit bir tanımlayıcıyla doldurulmaya başlandı. İkincisi, rotasyon pencereleri gönderimle senkronize edildi: rotasyondan 15 saniye önce yeni sipariş gönderilmiyordu. Üçüncüsü, her 10 dakikada bir mutabakat eklendi. Çeyrek dönem sonucu: sıfır ikiz, tekrar sayısında rotasyon senkronizasyonu sayesinde %70 azalma, bekleme pencereleri nedeniyle ortalama sipariş verme süresinde 1,2 saniye artış — kabul edilebilir bir bedel.
Vaka 2. Ödeme servisi ve eşzamanlı tekrarlar
Bir fintech servisi kendi tarafında idempotensi uygulamıştı: başlık kabul ediliyor, anahtar veritabanına kaydediliyor, tekrarda anlık görüntü dönüyordu. İkizler yine de oluşuyordu, seyrek ama düzenli: yaklaşık her 40 bin işlemde bir. Soruşturma, anahtar kontrolünün önce okuma, sonra yazma şeklinde yapıldığını ve agresif zaman aşımlı istemcilerin (farklı proxy'ler üzerinden bir saniye içinde iki tekrar) aradaki pencereye denk geldiğini gösterdi.
Benzersiz indeksli eklemeyle değiştirildi ve in_progress durumu, 409 yanıtı ve bir saniyelik Retry-After başlığı eklendi. Eşzamanlı tekrar metriği eklendi. Beklenmedik bir şey gösterdi: tüm işlemlerin %2'si en az bir 409 alıyordu; yani istemciler sanılandan çok daha agresif tekrarlıyordu. Servis, zaman aşımı önerileriyle dokümantasyonu güncelledi ve iki ay içinde 409 oranı %0,3'e düştü. Altı ayda ikiz: sıfır.
Vaka 3. Pazaryeri entegrasyonu ve partiler
Bir satıcı, stok ve fiyatları pazaryerine proxy üzerinden 500'lük partiler hâlinde yüklüyordu. Partinin idempotensi tüm istek düzeyindeydi. Bağlantı koptuğunda tekrar ya reddediliyordu (parti işlemde) ya da hangi pozisyonların güncellendiği anlaşılmayan kısmi bir sonuç anlık görüntüsü dönüyordu. Satıcı "güncellenmedi" sonucuna varıp yeniden yüklüyor, bu da eski ve yeni parti arasında yarış koşulları yaratıyordu.
Çözüm: öğe başına işlem kimlikli partilere geçmek ve belirsiz tamamlanmadan sonra öğe başına durum istemek. Parti boyutu işleme süresi zaman aşımını aşmasın diye 100 pozisyona indirildi. "Askıda" kalan güncelleme sayısı günde onlardan sıfıra düştü ve daha önce düzenli olarak alıcı siparişlerinin iptaline yol açan stok tutarsızlıkları ortadan kalktı.
Vaka 4. Otomatik ajan ve zincirleme tekrarlar
2026 trendi: giderek daha fazla entegrasyon, talimatlara göre API çağıran büyük dil modelleri tabanlı otonom ajanlar tarafından yürütülüyor. Bir ekip, tedarikçilerden satın alma yapmak için böyle bir ajan devreye aldı. Ajan belirsiz bir yanıt aldığında "akıl yürütüyor" ve her seferinde yeni bir istek üreterek işlemi tekrarlamaya karar veriyordu. Anahtar yoktu, çünkü ajan çağrıyı her seferinde sıfırdan kuruyordu. İlk haftada 11 ikiz satın alma.
Düzeltme: ajanın doğrudan oluşturma isteği üretmesi yasaklandı. Ajan, iç bir araç üzerinden Outbox'a niyet kaydı oluşturuyor; gönderimi anahtarlı ve mutabakatlı deterministik servis yapıyor. Ajan yalnızca nihai durumu alıyor. İkizler kayboldu ve her satın almayı kimin neden başlattığına dair tam izleme de beraberinde geldi. Genel çıkarım: tekrar yeteneğine sahip otonom sistemler, yeni ve güçlü bir ikiz kaynağıdır; onlar için idempotens bariyeri zorunludur.
SSS: İdempotens ve tekrarlar hakkında zor sorular
Spesifikasyona göre idempotent olan PUT ve DELETE için idempotent anahtar gerekli mi?
Biçimsel olarak hayır: aynı gövdeyle PUT tekrarı aynı durumu verir. Ama nüanslar var. PUT oluşturmada 201, güncellemede 200 döndürüyorsa, tekrar başka bir durum döndürür ve istemci bunu farklı yorumlayabilir. DELETE tekrarda 204 yerine 404 döner; bu da sıklıkla hata olarak işlenir. Anahtar ve yanıt anlık görüntüsü davranışı öngörülebilir kılar. Ayrıca PUT yan etkiler doğuruyorsa (bildirim gönderme, denetime kayıt), bunlar tekrar yürütülür. Metodun idempotensi, tüm yan etkilerin idempotensi anlamına gelmez.
Sunucu 409 in_progress döndürdü ama ilk deneme aslında ölmüşse ne yapmalı?
Bu sunucunun sorumluluğudur: zamana göre eşiği olan askıda kayıtları kurtarma mekanizması olmalıdır. İstemci 409'u sonsuza kadar değil, sınırlı sayıda beklemelidir (örneğin iki dakikaya kadar), sonra işlemi unknown'a çevirip mutabakata aktarmalıdır. Sunucu sistematik olarak in_progress'i makul süreden uzun tutuyorsa bu bir uygulama kusurudur ve API sahibine bildirilmelidir.
İstek zincirde birden çok proxy'den geçiyorsa anahtar ne olacak?
Özel bir şey yapılmaz: anahtar başlıkta iletilir ve her zincirden şeffaf geçer. Kontrol edilmesi gereken tek şey, aradaki bir düğümün standart dışı başlıkları silip silmediğidir. Bazı kurumsal ağ geçitleri başlıkları beyaz listeye göre filtreler. Basit test: isteği tüm zincirden kendi hata ayıklama uç noktanıza gönderin ve başlığın ulaştığını doğrulayın.
İstek gövdesinin karmasını anahtar olarak kullanıp istemcide hiçbir şey saklamamak mümkün mü?
Mümkün, ama çekincelerle. Aynı içerikli iki farklı sipariş (aynı ürün, aynı tutar, aynı alıcı) aynı anahtarı alır ve ikincisi tekrar olarak reddedilir. Bunu önlemek için gövdeye benzersiz bir bileşen eklenir — sepet kimliği ya da yerel sıra numarası. O zaman gövde karması işlemin deterministik anahtarı olur. Bu yaklaşım güvenilir yerel depolaması olmayan istemciler için kullanışlıdır, ama gövdenin katı normalleştirilmesini gerektirir: JSON'daki alan sırası değişirse karma değişir.
Sunucunun ilk denemeyi tamamlaması için tekrardan önce ne kadar beklemeli?
Bu yeniden deneme politikası sorusudur; ama sözleşme açısından önemli olan tek şey şudur: sunucu 409'lu in_progress destekliyorsa "göz kararı" beklemeye gerek yoktur — sunucu işlemin hâlâ yürütüldüğünü kendisi bildirir. Sunucu böyle bir duruma sahip değilse tekrardan önceki aralık, sunucudaki işleme süresinin 99. yüzdelik dilimini aşmalıdır. Bunu dokümantasyondan, başarılı istek metriklerinden ya da test ortamında ampirik olarak öğrenebilirsiniz.
Okuma işlemlerini idempotent yapmak gerekir mi?
GET tanımı gereği idempotenttir, anahtara ihtiyaç duymaz. Ama bir istisna vardır: "yan etkili okuma", örneğin bir bildirimi okundu olarak işaretleyen ya da limit düşen GET. Bu bir mimari kokudur; bu tür işlemleri GET'e idempotens eklemek yerine anahtarlı POST'a dönüştürmek daha iyidir.
Geçiş ya da API sürüm değişikliğinde anahtarlara ne olur?
Uç nokta sürümünü sunucudaki anahtarın kapsamına dahil edin. O zaman v1'de kullanılan anahtar v2'de aynı anahtarla çakışmaz. İstemci için kural basittir: geçiş yeni işlemler ve yeni anahtarlar demektir, eski anahtarlar taşınmaz. Geçiş anında unknown durumunda bir işlem varsa, önce mutabakatla çözün, sonra geçin.
İş dünyasına, "ikiz neredeyse hiç olmuyor"ken idempotens için neden bir sprint harcanması gerektiği nasıl anlatılır?
Bir ikizin maliyetini hesaplayın: iptal, iade, destek, itibar, bazen iş ortağı cezaları. Gözlemlenen sıklıkla çarpın. Sonra sıklığın ağ olaylarında doğrusal olmayan biçimde arttığını gösterin: sakin bir günde sıfır ikiz, operatörün arıza gününde bir saatte yüzlerce. İdempotens, primi bilinen, kazancı bilinmeyen ama potansiyel olarak devasa bir sigortadır. Üstelik bir yan etki de sağlar: süreçleri, ikiz korkusu olmadan agresif biçimde tekrarlama yeteneği, arızalardan sonra toparlanmayı hızlandırır.
İdempotens sunucudaki yükü artırır mı?
Çok az: işlem başına bir ek yazma ve bir okuma. Buna karşılık acil senaryolarda yükü azaltır; çünkü tekrar, siparişi baştan işlemek yerine milisaniyeler içinde anlık görüntüyü döndürür. Tekrar fırtınasında idempotensli sunucu, idempotenssiz sunucudan daha iyi dayanır — bu sezgiye aykırı ama pratikte doğrulanmıştır.
Sonuç: Umut yerine sözleşme
Ana noktaları toplayalım. Her ağ, istekleri "en az bir kez" ilkesiyle teslim eder. Proxy — özellikle rotasyonlu ve radyo kanallı mobil olanlar — tekrarları nadirlik değil norm hâline getirir. Yeniden deneme politikası "ne zaman ve nasıl tekrarlanmalı" sorusunu yanıtlar. İdempotens "tekrar neden hiçbir şeyi bozmaz" sorusunu yanıtlar. İkinci yanıt olmadan birincisi tehlikelidir.
Güvenli tekrar üç sütuna dayanır. İlk denemeden önce doğan ve HTTP istemcisinde değil veritabanınızda yaşayan işlem anahtarı. Atomik rezervasyon, in_progress durumu, gövde parmak izi, yanıt anlık görüntüsü ve makul TTL içeren sunucu sözleşmesi. Belirsizlikte takılı kalan işlemler için son savunma hattı olan mutabakat. Sunucu sözleşme sağlamıyorsa anahtar rolünü doğal tanımlayıcı, depo rolünü de Outbox'ınız üstlenir.
Bugün hemen yapılacaklar:
- Entegrasyonlarınızda otomatik olarak tekrarlanan tüm POST işlemlerini bulun. Her biri için yanıtlayın: anahtar var mı, nerede üretiliyor, tekrarlarda aynı kalıyor mu.
- İş ortağı API'lerinin dokümantasyonunu external_id alanları ve Idempotency-Key başlığı açısından okuyun. İki aynı istekle test ortamında davranışı doğrulayın.
- İşlem modelinize unknown durumunu ve bunun için bir mutabakat sürecini ekleyin.
- Sunucunun sahibiyseniz üç testi çalıştırın: eşzamanlı tekrarlar, yürütme ve kesinleştirme arasında çökme, başka IP'den tekrar.
- Panonuza tekrarların benzersiz işlemlere oranını koyun. Bu, proxy üzerinden kanalınızın sağlık göstergesidir.
İdempotens, mühendislik disiplininin doğrudan iş huzuruna dönüştüğü nadir bir durumdur. Bir kez tasarlanan sözleşme yıllarca ikizlerden, tekrar fırtınalarından ve muhasebeden gelen gece aramalarından korur. Ve dürüst olmak gerekirse, istikrarsız bir kanal üzerinden binlerce tekrarın grafiğine bakıp ikiz sütununda kararlı bir sıfır görmenin ayrı bir keyfi vardır.