Idempotentlik we açarlar

Idempotentlik näme

Idempotentlik - şol bir kesgitleýji bilen gaýtalanmagyň jemleýji täsirini üýtgetmeýän amalyň häsiýeti. Paýlanan ulgamlarda bu netijäni retraýalara, habarlaryň dublikatlaryna we wagtlara garamazdan "birmeňzeş gaýtadan işlemäge" deň etmegiň esasy usulydyr.

Esasy pikir: her bir gaýtalanýan amal ulgam "muny eýýäm" tanap, netijäni bir gezekden köp ulanmaýan açar bilen bellenmeli.

Bu möhüm ýerde

Tölegler we balanslar: "operation _ id".
Bron etmek/kwotalar/çäkler: şol bir slot/çeşme.
Webhuklar/habarnamalar: gaýtadan eltip bermek täsirini köpeltmeli däldir.
Import/göçmek: faýllary/bukjalary gaýtalamak.
Akym prosessing: broker/CDC-den goşa.

Açarlaryň görnüşleri we olaryň hereket edýän meýdany

1. Operation key - iş amalynyň anyk synanyşygynyň kesgitleýjisi

Mysal üçin: 'idempotency _ key' (HTTP), 'operation _ id' (RPC).
Sebit: hyzmat/agregat; duplikasiýa tablisasynda saklanylýar.

2. Event key - wakanyň/habaryň özboluşly kesgitleýjisi

Mysallar: 'event _ id' (UUID), '(producer_id, sequence)'.
Sebit: sarp ediji/sarp edijiler topary; proýeksiýalary goraýar.

3. Business key - predmet meýdanynyň tebigy açary

Mysal üçin: 'payment _ id', 'invoice _ number', '(user_id, day)'.
Meýdany: agregat; özboluşlylygy/wersiýasy barlanylanda ulanylýar.

TTL we saklamak syýasaty

TTL açarlary ≥ mümkin bolan penjiräniň gaýtalanmagy: logyň retensiýasy + tor/proses gijikdirmeleri.
Möhüm domenler üçin (tölegler) TTL - günler/hepdeler; telemetriýa üçin - sagat.
Kesilen tablisalary joblar bilen arassalaň; audit üçin - arhiwläň.

Açarlar üçin ammar (duplikasiýa)

Geleşik DB (maslahat berilýär): ygtybarly upsert/unique-indeksler, effektli bilelikdäki amal.
KV/Redis: çalt, gysga TTL üçin amatly, ýöne ALTP bilen bilelikdäki geleşik bolmazdan - seresap boluň.
Akym prosessorynyň state store: lokal + brokerde çeýnjlog; gowy Flink/KStreams.

• idempotency_keys

`consumer_id` (или `service`), `op_id` (PK на пару), `applied_at`, `ttl_expires_at`, `result_hash`/`response_status` (опц.) .

Indeksler: '(consumer_id, op_id)' - özboluşly.

Amala aşyrmagyň esasy usullary

1) "effekt + ösüş" geleşigi

Netijäni ýazmak we okamagyň/pozisiýanyň ösüşini düzetmek - bir amalda.

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) Optimistic Concurrency (agregatyň görnüşi)

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 sinks (upsert/merge)

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

Teswirnamalardaky görelde

HTTP/REST

'Idempotency-Key' sözbaşy: <uid 'hash>'.
Serwer açaryň ýazgysyny saklaýar we şol jogaby yzyna gaýtarýar (ýa-da '409 '/' 422' kody üýtgewsiz gapma-garşylykda).
"Howpsuz" POST üçin - hökmany 'Idempotency-Key' durnukly wagt/retraj syýasaty.

gRPC/RPC

Metadata 'idempotency _ key', 'request _ id' + deadline.
Serwer satuwy - REST-daky ýaly: Geleşikdäki babyň tablisasy.

Brokerler/akym (Kafka/NATS/Pulsar)

Prodýuser: durnukly 'event _ id '/idempotent prodýuser (nirede saklanýar).
Konsumer: '(consumer_id, event_id)' we/ýa-da agregatyň işewürlik wersiýasy boýunça.
Indempotent däl/zaýalanan habarlar üçin aýratyn DLQ.

Webhuklar we daşarky hyzmatdaşlar

Şertnamada 'Idempotency-Key '/' event _ id' -ni talap ediň; gaýtadan eltip bermek howpsuz bolmaly.
'notification _ id' we iberiş statuslaryny saklaň; retrada - köpeltmäň.

Açar dizaýny

Kesgitleýiş: retralar şol bir açary ibermeli (müşderide/orkestratorda öňünden dörediň).
Görünýän ýeri: 'op _ id' -ni 'service: aggregate: id: purpose' hökmünde dörediň.
Gapma-garşylyklar: iş parametrlerinden UUIDv7/ULID ýa-da hashy ulanyň (zerur bolsa duz bilen).
Iýerarhiýa: frontda umumy 'operation _ id' → ähli kiçi amallara ýaýlyma berilýär (idempotent zynjyry).

UX we önüm taraplary

Açar boýunça gaýtalanýan haýyş şol bir netijäni (beden/statusy goşmak bilen) ýa-da aç-açan "eýýäm ýerine ýetirildi".
"Şowlulyk üçin" ikinji synanyşygyň ýerine ulanyja "amal işlenilýär/tamamlandy" statuslaryny görkeziň.
Uzak amallar üçin - açar boýunça polling ('GET/operations/{ op _ id}').

Synlamak

'op _ id', 'event _ id', 'trace _ id', netijesini ýazyň: 'APPLIED '/' ALREADY _ APPLIED'.
Metrikler: gaýtalamalaryň paýy, tablisalaryň ululygy, amallaryň wagty, wersiýalaryň gapma-garşylyklary, DLQ-stawka.
Trace: açar buýrukdan geçmeli → waka → proýeksiýa → daşarky kynçylyk.

Howpsuzlyk we laýyklyk

PII-ni açarda saklamaň; açar - identifikator, töleg däl.
Uzak wagtlap TTL-de dada ýazgylarynda duýgur ýerleri şifrläň.
Saklamak syýasaty: TTL we arhiwler; ýatdan çykarmak hukugy - jogaplary/meta-maglumatlary kripto-silmek arkaly (eger olarda PII bar bolsa).

Synag

1. Dublikatlar: bir habaryň/haýyşyň 2-5 gezek geçmegi - täsiri birmeňzeş.
2. Ädimleriň arasynda düşmek: effekti ýazmazdan öň/soň, ofseti düzetmekden öň/soň.
3. Gaýtadan başlamak/sarp edijileriň deňagramlylygy: goşa ulanmak ýok.
4. Bäsdeşlik: bir 'op _ id' bilen paralel soraglar → bir effekt, ikinjisi - 'ALREADY _ APPLIED/409'.
5. Uzak ömürli açarlar: dikeldilenden soň TTL we gaýtalamalaryň gutarandygyny barlamak.

Antipattern

Her retrada tötänleýin täze açar: ulgam gaýtalanmalary tanamaýar.
Iki aýratyn topar: ilki täsir, soň ofset - olaryň arasyndaky ýykylmak täsirini gaýtalaýar.
Diňe dellalyň ynamy: gök/agregatda atanyň ýoklugy.
Agregatyň wersiýasynyň ýoklugy: gaýtalanýan waka ýagdaýy ikinji gezek üýtgedýär.
Fat keys: açar iş meýdançalaryny/PII → syzmak we çylşyrymly indeksleri öz içine alýar.
Gaýtalanýan jogaplaryň ýoklugy: Müşderi howpsuz retra edip bilmez.

Mysallar

Töleg POST

Müşderi: 'POST/payments' + 'Idempotency-Key: k-789'.
Serwer: Amal - 'payment' we 'idempotency _ keys' -de ýazgy döredýär.
Gaýtalamak: şol bir '201 '/bedeni yzyna gaýtarýar; üýtgewsiz gapma-garşylykda - '409'.

Bonus hasaplamak (sink)

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

Wakalardan proýeksiýa

Konsumer 'seen (event_id)' we 'version' agregatyny saklaýar; gaýtalamak - ignor/idempotent upsert.
Okamagyň ösüşi proýeksiýanyň täzelenmegi bilen bir amalda ýazylýar.

Önümçiligiň çek-sanawy

• Ähli howply amallar üçin idempotent açary we onuň görünýän ýeri kesgitlenildi.
• TTL we üýtgeşik indeksleri bolan baba tablisalary bar.
• Okamagyň täsiri we ösüşi atomiki birleşýär.
• Write-modelde optimistik bäsdeşlik bar.
• API şertnamalary 'idempotency-Key '/' operation _ id' we gaýtalamalaryň özüni alyp barşyny ýazga alýar.
• Metrikler we loglarda 'op _ id '/' event _ id '/' trace _ id' bar.
• Dublikatlar, ýykylmalar we ýaryşlar üçin synaglar - CI.
• TTL/arhiw syýasaty we PII howpsuzlygy berjaý edilýär.

FAQ

"Idempotency-Key" "Request-Id" -den nähili tapawutlanýar?
'Request-Id' - yzarlamak; retralarda üýtgäp biler. 'Idempotency-Key' - amalyň semantik kesgitleýjisi, gaýtalananda hökmanydyr.

DB bolmazdan idempotentlik edip bolarmy?
Gysga penjire üçin - hawa (Redis/prosessor içindäki nagt pul), ýöne bilelikdäki geleşik bolmazdan, goşa töwekgelçilik artýar. Möhüm domenlerde - bir DB amalynda has gowudyr.

Daşarky hyzmatdaşlar bilen näme etmeli?
Açarlar we gaýtalanýan jogaplar barada ylalaşyň. Partnýor goldamaýan bolsa, çagyryşy idempotent gatlagyňyza öwüriň we "eýýäm ulanyldy" saklaň.

TTL nädip saýlamaly?
Iň ýokary gijikdirmeleri jemläň: giriş retensiýasy + worst-case network/revalance + bufer. Ätiýaçlyk goşuň (× 2).

Jemi

Idempotentlik açarlaryň, amallaryň we wersiýalaryň düzgünidir. Amallaryň durnukly kesgitleýjileri + okamagyň täsirini we ösüşini atom taýdan düzetmek + dempotent sinks/proýeksiýalar ulag derejesiniň jadysyz "takmynan bir effekt" berýär. Açarlary kesgitlenen, TTL - real we synaglar - zyýanly ediň. Şonda retralar we dublikatlar hadysalara däl-de, adaty ýagdaýa öwrüler.