Idempotency (Eş Etkililik) Nedir?
Kısa tanım
Idempotency (eş etkililik), bir işlemin bir kez ya da aynı biçimde art arda birçok kez uygulanmasının sistemde aynı sonucu bırakması özelliğidir. Ağ hataları ve zaman aşımları nedeniyle isteklerin tekrarlandığı dağıtık sistemlerde, bir tekrarın çift ödeme ya da mükerrer kayıt yaratmamasını sağlar. HTTP'de GET, PUT ve DELETE tanımı gereği idempotent'tir; POST gibi işlemler ise idempotency anahtarı gibi tekniklerle güvenle tekrarlanabilir hâle getirilir.
Diğer adları: Idempotency, İdempotans, Idempotent, Idempotency key, Eş etkililik
“Ata” ile “ekle” arasındaki fark
Terim matematikten gelir: bir işlemi sonucuna yeniden uygulamak sonucu değiştirmiyorsa o işlem idempotent'tir. Yazılımdaki karşılığı sezgiseldir. “Sipariş durumunu gönderildi yap” komutunu üç kez çalıştırmak, bir kez çalıştırmakla aynı sonucu verir. “Bakiyeye 100 TL ekle” komutunu üç kez çalıştırmak ise 300 TL ekler. İlki bir değeri atar, ikincisi mevcut değerin üzerine ekler. Çoğu idempotency sorunu, ikinci türden bir işlemin farkında olmadan tekrarlanmasından doğar.
Ölçüt, sistemde bırakılan etkidir; dönen yanıt değil. Bir kaydı silen istek ilk seferde “silindi”, ikinci seferde “bulunamadı” dönebilir, yine de idempotent'tir. HTTP metotlarının bu açıdan nasıl sınıflandığı HTTP metodu maddesindeki tabloda yer alıyor.
Tekrarlanan istekler kaçınılmazdır
Dağıtık bir sistemde “aynı istek iki kez gelmez” varsayımı er geç çöker. Tipik kaynaklar şunlardır:
- İstemci zaman aşımına uğrar ve yeniden dener; oysa sunucu ilk isteği çoktan işlemiştir, yalnızca yanıt yolda kaybolmuştur.
- Kullanıcı yavaş yanıt veren “Öde” düğmesine iki kez basar.
- Mobil cihaz Wi-Fi'dan hücresel ağa geçerken bağlantı kopar.
- Bir yük dengeleyici ya da SDK, hatayı görünce isteği otomatik olarak tekrarlar.
- Mesaj kuyrukları ve webhook sağlayıcıları çoğunlukla “en az bir kez” (at-least-once) teslimat garantisi verir; aynı mesaj ikinci kez gelebilir.
Ağ üzerinde “tam olarak bir kez” teslimatı garanti etmek pratikte mümkün değildir. Sistemlerin gerçekte yaptığı, en az bir kez teslimatı idempotent işleme ile birleştirerek “etkisi bir kez” sonucuna ulaşmaktır.
Idempotency anahtarı nasıl çalışır?
POST doğası gereği idempotent olmadığından, ödeme gibi kritik işlemlerde istemci her işlem için benzersiz bir anahtar üretir ve bu anahtarı istek başlığında gönderir:
POST /v1/odemeler HTTP/1.1
Host: api.example.com
Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"
Content-Type: application/json
{"siparis": "S-20931", "tutar": "749.90", "para_birimi": "TRY"}- Sunucu anahtarı daha önce görmediyse, anahtarı ve isteğin parmak izini (gövde özeti) kaydeder, işlemi yürütür, ardından yanıtın durum kodunu ve gövdesini anahtarla birlikte saklar.
- Aynı anahtar aynı gövdeyle tekrar gelirse işlem yeniden yürütülmez; saklanan yanıt aynen döndürülür.
- Aynı anahtar farklı bir gövdeyle gelirse bu bir istemci hatasıdır ve reddedilir.
- İlk istek hâlâ işlenirken ikinci kopya gelirse, ikincisi beklemek yerine çakışma hatası alır.
Bu desen yaygın biçimde ödeme altyapılarında kullanılır. Örneğin Stripe ilk isteğin sonucunu, başarısız olsa bile, durum kodu ve gövdesiyle saklar; anahtarlar en az 24 saat geçtikten sonra temizlenebilir ve en fazla 255 karakter olabilir. IETF'te Idempotency-Key başlığını standartlaştırmaya yönelik bir taslak bulunuyor; taslak, eksik anahtar için 400, farklı gövdeyle yeniden kullanım için 422, devam eden bir isteğin kopyası için 409 önerir. Ekim 2026 itibarıyla bu belge bir RFC değil, süresi dolmuş bir taslaktır; davranış sağlayıcıdan sağlayıcıya değişebilir.
Uygulamada sık yapılan hatalar
- Her denemede yeni anahtar: Anahtar işlem başlarken bir kez üretilmeli ve bütün tekrarlarda aynen gönderilmelidir. Her yeniden denemede yeni UUID üreten bir istemci korumayı tamamen boşa çıkarır.
- Kontrol ve kayıt arasındaki yarış: “Anahtar var mı?” kontrolü ile kaydın yazılması ayrı adımlarsa, aynı anda gelen iki kopya ikisini de geçebilir. Anahtar sütununa benzersizlik kısıtı koymak ve iş kaydıyla anahtar kaydını aynı veritabanı işlemi içinde yazmak gerekir.
- Kapsamsız anahtarlar: Anahtarlar hesap bazında tutulmalı; iki farklı müşterinin aynı anahtarı göndermesi birbirinin yanıtını görmesine yol açmamalıdır.
- Belirsiz saklama süresi: Anahtarların ne kadar tutulacağı belgelenmeli; süre dolduktan sonra gelen bir tekrar yeni istek olarak işlenecektir.
- Kişisel veriyle anahtar: E-posta adresi gibi kişisel veriler anahtar olarak kullanılmamalı; rastgele bir UUID yeterlidir.
Webhook tüketen tarafta da mantık aynıdır: gelen olayın kimliği işlenmiş olaylar tablosuna benzersiz olarak yazılır, kimlik zaten varsa olay sessizce onaylanır ama yan etkileri (e-posta, stok düşümü) ikinci kez çalıştırılmaz.