Açıklayıcı · Mühendislik

İdempotency anahtarı nedir: ve uygulamanızın neden birine ihtiyacı var

4 Kasım 2026 · Software by Design

Çevrimdışı çalışabilen her uygulama er geç aynı soruyu yanıtlar: kullanıcı “gönder”e iki kez basarsa ya da ağ isteğin ortasında ölür ve istemci yeniden denerse ne olur? yanıt, idempotency anahtarı denen küçük bir mekanizmadır, nasıl çalıştığı ve kendi kodumuzda nasıl göründüğü burada.

Sorun tek cümlede

Ağlar güvenilmezdir, o yüzden istemciler yeniden denemek zorundadır. Yeniden denemeler aynı mantıksal aksiyonun birden fazla kez gelmesi demektir. Koruma olmadan “birden fazla”, iki mesai kaydı, iki fatura, iki rezervasyon olur.

Sorunun ne olmadığına dikkat edin: “kullanıcı çift tıkladı” değil. Kullanıcılar çift tıklar elbette, ama asıl yaygın durum çok daha az görünürdür, şantiyedeki bir mobil uygulama sinyali kaybeder, giriş damgasını kuyruğa alır, sunucu onu uygular, yanıt yolda ölür ve uygulama (doğru olarak) onu tekrar gönderir. Kopya, sistemin tam da tasarlandığı gibi çalışmasıdır.

Mekanizma

İdempotency anahtarı, istemcinin mantıksal aksiyon başına ürettiği benzersiz bir kimliktir, HTTP isteği başına değil. İstemci aynı anahtarı ilk isteğe ve o aksiyonun her yeniden denemesine iliştirir. Sunucu gördüğü anahtarların kaydını tutar. Bir anahtar ikinci kez geldiğinde, mutasyonu ikinci kez çalıştırmak yerine ilk sonucu döndürür.

Onu çalışır kılan üç özellik:

  • Anahtarın sahibi istemcidir. Anahtarı sunucu üretseydi, onu almadan önce yapılan bir yeniden deneme tanınamazdı. Anahtar cihazda basılır, mobil uygulamalarımızda, kullanıcının damgaladığı anda üretilen bir UUID. Ağ çağrısı ateşlendiğinde değil.
  • Kayıt bir sonuç değil, bir claim’dir. Sunucu önce claim’i yazar (“bu anahtar artık benim, sonuç beklemede”), sonra mutasyonu yapar. Eşzamanlı bir yeniden deneme claim’i bulur ve ilk sonucu bekler ya da tekrarlar, altına ikinci bir mutasyon asla sızdıramaz.
  • Claim, payload’a bağlıdır. Aksiyonun ve normalize edilmiş girdilerinin hash’ini anahtarla birlikte saklarız. Aynı anahtar, farklı payload → sessiz bir üzerine yazma değil, 409 çakışması. Yeniden deneme yalnızca “aynı şeyi bir kez daha” anlamına gelmelidir.

Uygulamalarımızda nerede karşınıza çıkar

ArbeitszeitCheck’in mobil damga kuyruğu her replay’de bir clientRequestId taşır. TourCheck aynı sözleşmeyi checkpoint onaylarındaki client_event_id alanına bağlar; bir replay orada claim’in tamamını (not, fotoğraf, zaman damgası) saklı satırla karşılaştırır. Süre dolması dedupe kadar önemlidir: claim satırlarımız yedi gün yaşar. Uzun bir hafta sonu kapsama kaybını karşılayacak kadar uzun, tablonun log’a dönüşmeden kuyruk olarak kalacağı kadar kısa.

Kendi uygulamanız için kısa sürüm

API’niz durum değiştiriyorsa ve istemciniz yeniden deneyebiliyorsa ve her istemci yeniden deneyebilir, tam olarak üç şeye ihtiyacınız var: aksiyon başına istemci üretimi bir anahtar, ilk yazılan bir claim satırı ve “aynı anahtar”ın aynı zamanda “aynı niyet” demek olmasını sağlayan bir payload hash’i. Desenin tamamı budur. Geri kalan her şey, replay pencereleri, temizlik işleri, çakışma durum kodları, bu üç taahhüdün etrafındaki tesisattır.