Çift tıklama ve zaman aşımı, sipariş ucuna aynı işi ikinci kez yazdırabilir. Bu rehber, idempotent API nedir sorusunu kuyruk katmanı değil istemci-sunucu sözleşmesi üzerinden yanıtlar. Anahtar, kilit ve aynı yanıtı geri verme adımlarını uygulamaya dökersiniz.
Ödeme veya sipariş onayında müşteri düğmeye iki kez basabilir. Ağ yavaşsa tarayıcı isteği zaman aşımına düşürür; kullanıcı veya istemci aynı gövdeyi yeniden gönderir. Sunucu her gelen POST’u yeni iş sanırsa stok düşer, tahsilat çiftleşir, kargo kaydı çoğalır.
Idempotent API nedir sorusu bu sahneyi çözmek içindir. Aynı istemci isteğinin bir, iki veya beş kez ulaşması sunucudaki iş etkisini bir kez üretir. Bu rehber kuyruk tüketimini veya bildirim tekrarını değil; HTTP sözleşmesiyle çift yazmayı kesmeyi anlatır. Buton kilidi tek başına yetmez, çünkü ikinci istek çoğu zaman kilit kalkmadan veya başka bir sekmeden gelir.
Idempotent API nedir ve siparişte ne işe yarar
Idempotent bir uç, aynı isteğin tekrarlanmasının kaynak üzerindeki etkiyi değiştirmemesini vaat eder. Okuma için bu doğaldır. Asıl mesele yazma ucudur: sipariş oluştur, ödeme başlat, kupon düş, stok rezerv et.
Sözleşme şunu söyler: istemci aynı işi aynı kimlikle tekrar gönderirse sunucu ikinci bir sipariş açmaz. İlk iş hâlâ işleniyorsa bekletir veya çakışma döner. İlk iş bittiyse ilk yanıtın özünü yeniden verir. Kullanıcı “oldu mu?” diye yenilediğinde ikinci fatura doğmaz.
Bu, “istek hiç kaybolmaz” vaadi değildir. Ağ kopabilir; istemci yeniden dener. Idempotent sözleşme, yeniden denemeyi güvenli kılar. En az bir kez ulaşan isteğin en fazla bir kez yazmasını hedeflersiniz.
Idempotent API, tekrarlayan HTTP isteğini ikinci bir iş kaydına çevirmez; aynı işin kimliğini tanır ve aynı sonucu korur.
Bu ayrım e-ticaret sitesi akışında görünür hale gelir. Sepet onayı stok, tahsilat ve sipariş belgesini birlikte değiştirir. Bir kez fazla yazılan kayıt, destek yükünden önce muhasebe ve kargo kaydını bozar.
Çift tıklama ile ağ tekrarı aynı kaydı nasıl üretir
Çift yazma çoğu ekipte “kullanıcı hatası” diye kapanır. Kaynak ise iki ayrı kanalın aynı POST’u çoğaltmasıdır.
Arayüzdeki ikinci tıklama
Onay düğmesi yanıt gelene kadar açık kalır. İkinci tıklama ikinci isteği üretir. İki istek de sunucuya “yeni sipariş” olarak düşer. Oturum aynıdır, sepet aynıdır; kayıtlardaki birincil anahtar ise farklıdır. Veritabanı iki satır görür.
Düğmeyi devre dışı bırakmak ilk tıklamayı yumuşatır. Yeterli değildir. Sayfa yenilenir, ikinci sekme açık kalır, mobil tarayıcı geri gelir. Arayüz kilidi sunucu sözleşmesinin yerini tutmaz.
Zaman aşımı ve kör tekrar
İstek sunucuya ulaşır, sipariş yazılır, yanıt tarayıcıya dönmeden bağlantı düşer. İstemci hata görür ve aynı gövdeyi tekrar atar. Sunucu ilk yazımdan habersiz ikinci kaydı açar. Kullanıcı tek sipariş sandığı halde iki tahsilat veya iki rezervasyon oluşur.
Bu sahne kuyruk işçisinden bağımsızdır. Tarayıcı, mobil uygulama veya sunucudan sunucuya HTTP istemcisi aynı davranışı üretir: “cevap gelmedi, tekrar gönder.” Sözleşme yoksa tekrar yeni iş demektir.
- Aynı kullanıcı, aynı sepet, iki ayrı istek kimliği.
- İlk istek başarılı olmuş ama yanıt kaybolmuş olabilir.
- İkinci istek iş kuralına göre de geçerlidir; sunucu niyeti ayırt edemez.
- Ayırt etmek için istemcinin işe verdiği kalıcı bir kimlik gerekir.
HTTP fiiline göre yan etki: hangisi zaten tekrarlanabilir
Bazı fiiller kaynak modelinde tekrarlanmaya yatkındır. Sipariş açan POST ise varsayılan olarak yatkın değildir. Fiili değiştirmek sorunu tek başına kapatmaz; kaynağın kimliğini kimin verdiği belirler.
| Fiil ve uç | Tipik etki | Aynı isteği tekrarlamak |
|---|---|---|
| GET /orders/123 | Okur | Yan etki yok; aynı belge döner |
| PUT /orders/abc-istemci-id | Verilen kimlikle yazar | Aynı gövde aynı kaydı günceller |
| DELETE /orders/123 | Kaynağı kaldırır | İkinci deneme zaten yok durumunu korur |
| POST /orders | Sunucu yeni kimlik üretir | Her kabul ikinci sipariş riski taşır |
PUT ile istemcinin ürettiği kimliğe yazmak güçlü bir sözleşmedir. PUT /orders/9f3a… ikinci kez gelirse sunucu aynı kaynağı görür. POST /orders ise kimliği sunucuda üretir; tekrar yeni satırdır. POST’u bırakmak zorunda değilsiniz. POST’a istemci anahtarı eklemek, fiili PUT yapmadan aynı korumayı kurar.
KepezWeb işlerinde bu tercih uç kataloğunda yazılır: hangi yazma yeni kaynak üretir, hangisi verilen iş kimliğini kabul eder. Katalogda bu cümle yoksa istemci her zaman yeni iş denemiş sayılır.
İstemci anahtarıyla sözleşme kurmak
Çift yazmayı kesen pratik sözleşme, her denemenin değil her işin bir kimliği olmasıdır. Bu kimlik sipariş numarası olmak zorunda değildir. İstemcinin işi başlatırken ürettiği, tekrarlarda değişmeyen bir anahtardır.
Yaygın biçim bir başlıktır: istemci Idempotency-Key veya eşdeğer bir iş anahtarı gönderir. Gövdedeki client_order_id de aynı işi görür. Önemli olan kanal değil, kapsam ve sürekliliktir.
- Kullanıcı onay anında istemci bir anahtar üretir; yeniden denemede aynı kalır.
- Anahtar o kullanıcı, o uç ve o iş için tektir. Başka sepet başka anahtar alır.
- İstek zaman aşımına düşerse istemci gövdeyi ve anahtarı birlikte tekrarlar.
- Sunucu anahtarı daha önce gördüyse yeni sipariş açmaz; kayıtlı sonucu döner.
- Anahtar yoksa yazma ucu reddedilir. Sessizce yeni kayıt açılmaz.
Anahtarı sunucunun üretmesi bu sorunu çözmez. Yanıt gelmeden kopan istemci yeni anahtar ister ve ikinci iş açar. Anahtar, onay tıklamasının yanında doğmalıdır. Sayfa yenilense bile aynı iş aynı anahtarı taşıyacaksa tarayıcı deposunda, mobil yerelde veya formun gizli alanında tutulur.
Gövde ile anahtarı bağlayın. Aynı anahtar, farklı tutar veya farklı ürün listesiyle gelirse bu “tekrar” değildir. Sunucu ikinci sipariş yazmak yerine çakışmayı belirtir. Aksi halde anahtar, kötü niyetli veya hatalı istemcinin ilk siparişi sessizce değiştirmesine yol açar.
Sunucuda ikinci yazmayı durduran kayıt düzeni
Sözleşme sunucuda bir tablo ve bir kilit olmadan tutulmaz. Akış sadedir: anahtarı oku, varsa sonucu ver, yoksa işi bir kez yaz, sonucu anahtara bağla.
Kayıt, kilit ve aynı yanıt
Anahtar için benzersiz kısıt koyun. Kapsam en azından kullanıcı ve uç adını içersin. Böylece A kullanıcısının anahtarı B’nin siparişini kilitlemez; ödeme başlatma anahtarı sipariş ucunu da ezmez.
İki istek aynı anda boş görüp ikisi de yazmaya kalkabilir. Benzersiz kısıt ikinci yazmayı keser. Ek olarak “işleniyor” durumu koyun. İlk istek sürerken gelen ikincisi yeni kayıt denemesin; beklesin veya “henüz hazır değil” desin. İkinci istemci rastgele bir hata görüp farklı anahtarla tekrar denemesin.
İş bitince durum kodunu ve yanıt gövdesinin özünü anahtarla saklayın. Tekrar geldiğinde aynı iş etkisini korursunuz. Yanıtı saklamaz, yalnızca “bu anahtar var” derseniz istemci ikinci seferde farklı bir gövde görür ve yeni iş açmaya çalışır.
- Anahtar + uç + kullanıcı için benzersiz dizin.
- İstek gövdesinin özeti; aynı anahtarda farklı özet çakışmadır.
- İşleniyor / tamamlandı / reddedildi durumları.
- Tamamlanan işte ilk durum kodu ve yanıt özü.
- Süresi biten anahtarın sessizce yeni sipariş açmaması; politika açıkça yazılır.
Hangi işler bu sözleşmeyi ister
Her GET’e anahtar takmayın. Her güncelleme de sipariş kadar kırılgan değildir. Öncelik, tekrarı ikinci mali etkiye çeviren uçlardadır: sipariş oluşturma, ödeme niyeti, stok rezervasyonu, kupon tüketimi, kontör düşümü.
Kısmi güncelleme ayrı düşünülür. “Adresi düzelt” tekrarında aynı adresin iki kez yazılması çoğu zaman zararsızdır. “Kuponu bir kez düş” tekrarında ikinci düşüm zarardır. Zarar yan etkiye göre anahtar zorunlu kılınır.
KepezWeb tarafında yazılım geliştirme işi bu noktada uç listesini tarar: hangi POST yeni belge doğurur, hangisi belgenin alanını düzeltir. Yeni belge doğuran her uca istemci anahtarı konur; düzeltme ucu kaynak kimliğiyle konuşur.
Uygulamada sık görülen boşluklar
Sözleşme cümlesi yazılıp anahtar alanı eklenince iş bitmiş sayılmaz. Çift sipariş çoğu zaman aşağıdaki boşluklardan sızar.
- Yalnızca arayüz kilidi. Sunucu hâlâ her POST’u yeni iş kabul eder.
- Anahtarın her denemede yenilenmesi. Zaman aşımı sonrası üretilen yeni UUID, yeni sipariştir.
- Anahtarı isteğe bağlı bırakmak. Eski istemci veya hatalı entegrasyon anahtarsız yazar.
- Gövde özetini kontrol etmemek. Aynı anahtar başka tutarla kaydı sessiz değiştirir veya ikinci iş açar.
- İşleniyor halini yok saymak. Paralel iki istek ikisi de “yok” görür; yarışı yalnızca dizin kurtarır, istemci ise karışık hata alır.
- Yanıtı saklamamak. İkinci çağrı “zaten var” der ama sipariş numarasını vermez; istemci yeni iş açar.
- Bildirim tekrarıyla karıştırmak. Ödeme sağlayıcısının aynı olayı tekrar göndermesi ayrı bir doğrulama işidir; sipariş POST’unun anahtarı onun yerini tutmaz.
Son maddeyi ayırın. Sağlayıcı aynı ödemeyi birkaç kez haber verebilir. O kanalın imza ve tekrar kuralı ödeme ve kargo bildirimi tarafındadır. Bu yazıdaki sözleşme, sizin sipariş ve tahsilat ucunuza gelen istemci tekrarını keser. İkisini tek “tekrar” başlığında birleştirmek boşluk bırakır: biri içeri giren yazmayı, diğeri dışarıdan gelen olayı ilgilendirir.
Testi de sözleşmeye bağlayın. Aynı anahtar ve aynı gövdeyle ardışık iki çağrı tek kayıt üretmeli, ikinci yanıt birincisiyle aynı iş kimliğini vermelidir. Aynı anahtar farklı gövdeyle çakışma üretmelidir. Farklı anahtar iki kayıt üretmelidir; bu bilinçli ikinci sipariştir. Zaman aşımı senaryosunu da oynayın: ilk isteği yazıp yanıtı düşürün, tekrarın yeni satır açmadığını görün.
Sıkça Sorulan Sorular
POST ucu hiç idempotent olur mu?
Olur. Fiil POST kalsa bile istemci iş anahtarı gönderir, sunucu anahtarı benzersiz kaydeder ve tekrarında yeni belge açmaz. PUT ile istemci kimliği vermek alternatif bir biçimdir; asıl olan kimliğin tekrarda değişmemesidir.
Onay düğmesini kilitlemek yeterli midir?
Değildir. Kilidi kaldırmadan gelen ikinci tıklamayı azaltır. Zaman aşımı, sayfa yenileme, ikinci sekme ve otomatik istemci tekrarı sunucuya ikinci yazma olarak gelir. Koruma anahtar ve sunucu kaydındadır.
Anahtarı kim üretmeli, ne kadar yaşamalıdır?
Anahtarı işi başlatan istemci üretir. Sunucunun yanıtta verdiği numara, yanıt gelmeden kopan tekrarı kurtarmaz. Yaşam süresi, kullanıcının “olmadı” deyip aynı onayı yeniden deneyeceği makul pencere kadardır. Süre dolunca aynı anahtarın sessizce ikinci siparişe dönüşmemesi gerekir; kural açık yazılır.
Aynı anahtar farklı sepetle gelirse ne yapılır?
Bu bir tekrar değildir. Sunucu yeni sipariş yazmaz, gövde özetini karşılaştırır ve çakışmayı belirtir. İstemci ya ilk işlemin sonucunu alır ya da yeni iş için yeni anahtar üretir.
Bu sözleşme webhook tekrarından farklı mıdır?
Farklıdır. Webhook, dış sistemin aynı olayı yeniden bildirmesidir. Idempotent sipariş ucu, sizin yazma API’nize düşen çift tıklama ve ağ tekrarını keser. İkisi de “tekrar” der; kayıt yeri, imza ve anahtar sahibi ayrıdır.
Sipariş ve tahsilat uçlarında çift yazmayı anahtarla kesmek istiyorsanız KepezWeb ile uç sözleşmesini birlikte netleştirebilirsiniz. İhtiyacınızı teklif al sayfasından iletin; yazma uçlarını iş kimliği, kilit ve aynı yanıt üzerinden sadeleştiririz.
