İdempotans (Idempotency)
İdempotans, bir işlemin bir kez de çalışsa birçok kez de çalışsa aynı etkiye sahip olması özelliğidir; böylece bir istek, zaman aşımından sonra örneğin bir müşteriden iki kez ücret alınmadan güvenle yeniden denenebilir.
İdempotans nedir?
İdempotent bir işlem, ilk çalıştırmadan sonra sonucu değiştirmeden tekrarlanabilir. "Sipariş durumunu kargolandı olarak ayarla" idempotenttir: iki kez çalıştırmak durumu yine kargolandı olarak bırakır. "Bakiyeye 10 $ ekle" ise idempotent değildir: iki kez çalıştırmak 20 $ ekler.
Bu önemlidir, çünkü ağlar hata verir. Bir istemci çoğu zaman isteğin mi başarısız olduğunu yoksa yalnızca yanıtın mı kaybolduğunu ayırt edemez. İşlem idempotentse istemci basitçe yeniden deneyebilir.
HTTP'de RFC 9110, PUT, DELETE ve güvenli yöntemleri (GET, HEAD, OPTIONS ve TRACE) idempotent olarak tanımlar. POST idempotent değildir; ödeme ve sipariş API'lerinin idempotans anahtarları eklemesinin nedeni budur.
İdempotans anahtarları nasıl çalışır?
İstemci bir istekle birlikte benzersiz bir anahtar gönderir; sunucu o anahtar için ilk sonucu saklar ve her yeniden denemede aynı sonucu döndürür. Stripe API yaygın bir referanstır:
İstemci bir Idempotency-Key başlığı gönderir. Stripe V4 UUID'leri önerir ve anahtarlar en fazla 255 karakter olabilir.
API v1 için Stripe, uç nokta çalışmaya başladığında ilk isteğin durum kodunu ve gövdesini kaydeder ve yeniden denemelerde, 500 hataları dahil, bu kaydedilmiş yanıtı döndürür.
Aynı anahtar farklı parametrelerle gelirse Stripe hata döndürür.
Anahtarlar en az 24 saatlik olduktan sonra temizlenebilir; bundan sonra yeniden kullanılan bir anahtar yeni bir istek başlatır.
Tüm POST istekleri anahtar kabul eder. GET ve DELETE için gerekmez, çünkü bunlar tanım gereği idempotenttir.
Diğer kalıplar şunlardır: veritabanında benzersizlik kısıtları, insert yerine upsert kullanımı ve webhook'ları veya kuyruk mesajlarını işlerken işlenmiş olay kimliklerini saklamak.
İdempotans pratikte nasıl görünür?
Para taşıyan veya kayıt oluşturan her adımı iki kez çalıştırılmaya karşı güvenli hale getirin. Müşteri Öde'ye tıkladıktan sonra ödeme adımının bazen zaman aşımına uğradığı bir çevrimiçi mağaza düşünün.
Ödeme süreci başladığında sunucu o sepet için bir anahtar oluşturur; örneğin taslak siparişle birlikte saklanan bir UUID.
Ödeme sağlayıcısına giden istek bu anahtarı taşır. Zaman aşımından sonra sunucu aynı anahtarla yeniden dener.
Siparişler tablosunda ödeme kimliği üzerinde benzersizlik kısıtı vardır; böylece ikinci bir "ödeme başarılı" olayı ikinci bir sipariş oluşturamaz.
Webhook işleyicisi işlediği her olay kimliğini kaydeder ve tekrarları atlar.
Diyelim ki müşteri iki kez tıklıyor ve ağ bir yanıtı düşürüyor. Müşteriden bir kez ücret alınır ve tek bir sipariş e-postası gelir.
Yaygın idempotans hataları nelerdir?
İdempotans hatalarının çoğu, yanlış anda oluşturulan veya yanlış yerde kontrol edilen anahtarlardan kaynaklanır.
Her denemede yeni anahtar: her denemede yeni bir anahtar oluşturmak amacı boşa çıkarır.
Farklı işlemler için tek anahtar: aynı anahtarı paylaşan iki farklı ödeme reddedilir veya birleştirilir.
Yarış koşulları: aynı anda gelen iki özdeş istek, kontrol ve yazma işlemi atomik değilse (örneğin bir benzersizlik kısıtıyla) "bunu daha önce gördüm mü?" kontrolünü ikisi de geçebilir.
Önce yan etkiler: tekrar kontrolünden önce gönderilen bir e-posta yine iki kez gider.
Hassas anahtarlar: Stripe, e-posta adreslerinin veya diğer kişisel tanımlayıcıların anahtar olarak kullanılmamasını tavsiye eder.
Süre dolması: anahtar temizlendikten sonra gelen yeniden denemeler yeni istek olarak çalışır.
İdempotans, tekilleştirmeden ve tam olarak bir kez teslimattan nasıl farklıdır?
Tekilleştirme tekrarlanan mesajları eler; idempotans ise işlemin kendisini tekrarlanmaya karşı güvenli kılar. Yeniden denemeler aynı mesajın iki kez gelebileceği anlamına gelir; bu yüzden tüketiciler tekrarları beklemelidir. Tekilleştirme bunları genellikle kimliğe göre, belirli bir zaman penceresi içinde filtreler.
Bir ağ üzerinden tam olarak bir kez teslimatı garanti etmek zordur. Sistemler genellikle aynı pratik sonuca yeniden denemeleri idempotent işleyicilerle birleştirerek ulaşır.
Fikir veri için de geçerlidir. Yeniden çalıştırılan bir ETL işi bir günün verisini iki kez eklememeli, üzerine yazmalıdır. Bir agentic iş akışında yapay zekâ agent'ı bir araç çağrısını yeniden deneyebilir; bu yüzden veri yazan araçların da aynı korumaya ihtiyacı vardır. Güvenilir API entegrasyonunun temel bir gereğidir.
İdempotent ve idempotent olmayan işlemler karşılaştırması
İdempotent | İdempotent olmayan | |
|---|---|---|
Örnek | Durumu kargolandı olarak ayarla | Bakiyeye 10 $ ekle |
HTTP yöntemleri | GET, HEAD, OPTIONS, TRACE, PUT, DELETE | POST, bir anahtarla korunmadıkça |
Yeniden denemek güvenli mi | Evet | Yalnızca anahtar veya tekilleştirme ile |
Tipik önlem | Doğru tasarım yeterlidir | İdempotans anahtarları, benzersizlik kısıtları |
Tekrarlanırsa risk | Yok | Mükerrer kayıtlar veya çift ücretlendirme |
Vizio AI idempotansa nasıl yaklaşır?
Vizio AI'ın yayımlanmış vaka çalışmaları idempotans çalışmalarını ayrıntılı olarak anlatmaz. Bu, her entegrasyon, ödeme akışı veya veri hattı için geçerli bir tasarım kuralıdır.
Nereden başlamalı: kayıt oluşturan veya para taşıyan her uç noktayı ve zamanlanmış işi listeleyin ve her biri iki kez çalışırsa ne olacağını kontrol edin.