Idempotence ve anahtarlar

Idempotency nedir

Idempotency, aynı tanımlayıcıyla tekrarlamanın nihai etkiyi değiştirmediği bir işlemin özelliğidir. Dağıtılmış sistemlerde, bu, retray'lere, yinelenen mesajlara ve zaman aşımlarına rağmen, sonucu "tam olarak bir işleme" eşdeğer hale getirmenin ana yoludur.

Anahtar fikir: Potansiyel olarak tekrarlanabilir her işlem, sistemin'bu zaten yapıldı'yı tanıdığı ve sonucu bir kereden fazla uygulamadığı bir anahtarla işaretlenmelidir.

Önemli olduğu yerde

Ödemeler ve bakiyeler: 'operation _ id'ile silmeler/krediler.
Rezervasyonlar/kotalar/limitler: aynı yuva/kaynak.
Webhooks/bildirimler: tekrarlanan teslimat efekti çoğaltmamalıdır.
İçe Aktarma/Taşıma - Dosyaları/paketleri yeniden çalıştırın.
Akış işleme: broker/CDC'den kopyalar.

Anahtar türleri ve kapsamları

1. Operasyon anahtarı - ticari işlemin belirli girişiminin kimliği

Örnekler: 'Idempotency _ key' (HTTP), 'operation _ id' (RPC).
Kapsam: hizmet/toplu; veri tekilleştirme tablosunda saklanır.

2. Olay anahtarı - olayın/mesajın benzersiz tanımlayıcısı

Örnekler: 'Event _ id' (UUID), '(producer_id, sequence)'.
Alan: tüketici/tüketici grubu; Projeksiyonları korur.

3. İş anahtarı - doğal etki alanı anahtarı

Örnekler: 'payment _ id', 'invoice _ number', '(user_id, day)'.
Alan: agrega; benzersizlik/sürüm kontrollerinde kullanılır.

TTL ve Saklama Politikası

TTL anahtarları olası bir yineleme penceresi ≥: günlük tutma + ağ/işlem gecikmeleri.
Kritik alanlar için (ödemeler) TTL - gün/hafta; telemetri için - saat.
Arka plan işleri ile dedup tabloları temizleyin; denetim için - arşiv.

Anahtar depoları (veri tekilleştirme)

İşlemsel veritabanı (önerilen): güvenilir uppert/benzersiz indeksler, etkili ortak işlem.
KV/Redis: hızlı, kısa bir TTL için uygun, ancak OLTP ile ortak bir işlem olmadan - dikkatli.
State store stream işlemcisi: yerel olarak + komisyoncuda değişim; Flink/KStreams'de iyi.

• idempotency_keys

'consumer _ id' (или 'service'), 'op _ id' (PK на пару), 'applied _ at','tl _ expires _ at ',' result _ hash'/' response _ status '(опц.) .

Dizinler: '(consumer_id, op_id)' - benzersiz.

Temel uygulama teknikleri

1) Etki + İlerleme İşlemi

Sonucu kaydedin ve bir işlemde okuma/konumlandırma ilerlemesini yakalayın.

pseudo begin tx if not exists(select 1 from idempotency_keys where consumer=:c and op_id=:id) then
-- apply effect atomically (upsert/merge/increment)
apply_effect(...)
insert into idempotency_keys(consumer, op_id, applied_at)
values(:c,:id, now)
end if
-- record reading progress (offset/position)
upsert offsets set pos=:pos where consumer=:c commit

2) İyimser Eşzamanlılık (birim sürüm)

sql update account set balance = balance +:delta,
version = version + 1 where id=:account_id and version=:expected_version;
-- if 0 rows are updated → retry/conflict

3) Idempotent lavabolar (uppert/birleştirme)

sql insert into bonuses(user_id, op_id, amount)
values(:u,:op,:amt)
on conflict (user_id, op_id) do nothing;

Protokollerde idempotency

HTTP/REST

'Idempotency-Key: <uuuid' hash> 'başlığı.
Sunucu anahtar kaydını saklar ve aynı yanıtı tekrar döndürür (veya değişmez çakışma durumunda '409'/' 422' kodu).
"Güvensiz" POST için, 'Idempotency-Key' + kararlı zaman aşımı/yeniden ödeme politikası gereklidir.

gRPC/RPC

Meta veriler 'idempotency _ key', 'request _ id' + deadline.
Sunucu uygulaması - REST'te olduğu gibi: bir işlemde veri tekilleştirme tablosu.

Brokerler/Akış (Kafka/NATS/Pulsar)

Producer: stabil 'event _ id'/idempotent producer (destekleniyorsa).
Tüketici: '(consumer_id, event_id)'ve/veya toplamın iş versiyonuna göre tekilleştirme.
Idempotent olmayan/bozuk mesajlar için ayrı DLQ.

Webhooks ve dış ortaklar

Sözleşmede 'Idempotency-Key'/' event _ id' talebi; Yeniden teslimat güvenli olmalı.
'Notification _ id've gönderme durumlarını saklayın; Retray'de - çoğaltmayın.

Anahtar tasarımı

Determinizm: Retrays aynı anahtarı göndermelidir (müşteri/orkestratör üzerinde önceden üretilmelidir).
Kapsam: 'op _ id' formu 'service: aggregate: id: purpose'olarak.
Çarpışmalar: iş parametrelerinden UUIDv7/ULID veya karma kullanın (gerekirse tuzla).
Hiyerarşi: Öndeki genel 'operation _ id'tüm alt operasyonlara (idempotent zincir) çevrilir.

UX ve Ürün Özellikleri

Tekrarlanan bir anahtar isteği aynı sonucu (gövde/durum dahil) veya açık bir "zaten yürütülmüş" döndürmelidir.
Kullanıcıya,'iyi şanslar için "tekrar denemek yerine" işlemin işlendiğini/tamamlandığını "durumlarını gösterin.
Uzun işlemler için - anahtarla yoklama ('GET/operations/{ op _ id}').

Gözlemlenebilirlik

'Op _ id', 'event _ id', 'trace _ id', sonuç: 'APPLIED'/' ALREADY _ APPLIED'.
Metrikler: tekrarlama oranı, dedup tablo boyutu, işlem süresi, sürüm çakışmaları, DLQ oranı.
Trace: Anahtar komuttan geçmelidir - olay - projeksiyon - harici çağrı.

Güvenlik ve uyumluluk

PII'yi anahtarlarda saklamayın; Anahtar - tanımlayıcı, yük değil.
Veri tekilleştirme kayıtlarındaki hassas alanları uzun TTL ile şifreleyin.
Saklama politikası: TTL ve arşivler; Unutulma hakkı - yanıtların/meta verilerin kripto silinmesi yoluyla (PII içeriyorsa).

Test etme

1. Duplicates: bir mesaj/istek 2-5 kez çalıştırın - etkisi tam olarak bir.
2. Adımlar arasında bırakın: efekti kaydetmeden önce/sonra, ofseti sabitlemeden önce/sonra.
3. Tüketici yeniden başlatma/yeniden dengeleme: çift kullanım yok.
4. Rekabet: bir 'op _ id'ile paralel sorgular - bir etki, ikincisi -' ALREADY _ APPLIED/409 '.
5. Uzun ömürlü anahtarlar: TTL son kullanma tarihini kontrol eder ve kurtarma işleminden sonra tekrar dener.

Anti-desenler

Her yeniden oynatma için rastgele yeni anahtar: sistem tekrarları tanımıyor.
İki ayrı taahhüt: önce etki, sonra ofset - aralarındaki düşüş etkiyi çoğaltır.
Sadece brokere güvenmek: Çürükte/agregada veri tekilleştirme yok.
Eksik toplam sürüm: tekrarlanan olay değişiklikleri ikinci kez durumu.
Yağ tuşları: anahtar iş alanları/PII ™ sızıntıları ve karmaşık endeksleri içerir.
Tekrarlanabilir yanıt yok: Müşteri güvenli bir şekilde geri çekilemez.

Örnekler

Ödeme POST

Müşteri: 'POST/payments' + 'Idempotency-Key: k-789'.
Server: transaction - 'ödeme've' idempotency _ keys'de bir giriş oluşturur.
Yinele: aynı '201'/gövdesini döndürür; Değişmez çatışma durumunda - '409'.

Bonus tahakkuk (lavabo)

sql insert into credits(user_id, op_id, amount, created_at)
values(:u,:op,:amt, now)
on conflict (user_id, op_id) do nothing;

Olaylardan projeksiyon

Ünitenin 'görülen (event_id)'ve' sürümü 'tüketici mağazaları; Tekrar - görmezden/idempotent uppert.
Okuma ilerlemesi, projeksiyon güncellemesiyle aynı işlemde yakalanır.

Üretim kontrol listesi

• Tüm güvenli olmayan işlemler bir idempotent anahtara sahiptir ve kapsamı tanımlanmıştır.
• TTL ve benzersiz indekslere sahip veri tekilleştirme tabloları vardır.
• Okumanın etkisi ve ilerlemesi atomik olarak işlenir.
• İyimser rekabet (sürüm/sıra) yazma modeline dahil edilmiştir.
• API sözleşmeleri 'Idempotency-Key'/' operation _ id've tekrarlama davranışını yakalar.
• Metrikler ve günlükler 'op _ id'/' event _ id'/' trace _ id' içerir.
• Kopyalar, düşüşler ve yarışlar için testler - CI'da.
• TTL/Arşiv politikası ve PII güvenliği takip edilmektedir.

SSS

'Idempotency-Key', 'Request-Id'den nasıl farklıdır?
'İstek-Kimlik' - iz; Retray'lerde değiştirilebilir. 'Idempotency-Key', tekrarlamalar sırasında aynı olması gereken işlemin semantik tanımlayıcısıdır.

Bir veritabanı olmadan idempotans yapmak mümkün mü?
Kısa bir pencere için - evet (Redis/in-process cache), ancak ortak bir işlem olmadan, çoğaltma riski artar. Kritik alanlarda, bir veritabanı işleminde daha iyidir.

Dış ortaklarla ne yapmalı?
Anahtarları ve tekrarlanabilir yanıtları müzakere edin. İş ortağı desteklemiyorsa - çağrıyı idempotent katmanınıza sarın ve "zaten uygulanmış'olarak saklayın.

TTL nasıl seçilir?
Maksimum gecikmeleri toplayın: günlük tutma + net/yeniden dengeleme en kötü durum + arabellek. Stok ekleyin (× 2).

Toplam

Idempotency, anahtarların, işlemlerin ve sürümlerin bir disiplinidir. Kararlı çalışma tanımlayıcıları + etkinin atomik fiksasyonu ve okuma ilerlemesi + idempotent lavabolar/projeksiyonlar, taşıma seviyesi büyüsü olmadan "tam olarak bir etki" verir. Tuşları deterministik, TTL gerçekçi yapın ve kötü amaçlı test edin. O zaman geri çekilmeler ve kopyalar rutin hale gelecek, olaylar değil.