X'inhu l-Idempotenza? Għaliex l-API tal-Kontabilità u tal-Ħlasijiet jeħtiġuh

Operazzjoni tkun idempotenti (idempotent) jekk it-twettiq tagħha darbtejn ikollu l-istess effett bħat-twettiq tagħha darba biss. Il-qari ta' rekord huwa naturalment idempotenti. Il-ħolqien ta' fattura le - sejjaħlu darbtejn u jkollok żewġ fatturi, żewġ riċevibbli, u klijent li jistaqsi għaliex ġie fatturat darbtejn.

Dik id-differenza tgħodd minħabba li in-netwerks jonqsu b'mod speċifiku u diżgustanti: it-talba tirnexxi, u r-rispons jintilef. Il-klijent jara timeout u ma jkunx jista' jiddistingwi bejn "qatt ma waslet" u "waslet, ħadmet, ir-rispons intilef". L-unika għażla li tidher sigura hi li terġa' tipprova, u t-tentattiv ripetut huwa proprju dak li joħloq id-duplikazzjoni.

Għaliex il-kontabilità tagħmilha agħar

F'biċċa l-kbira tas-sistemi, id-duplikazzjoni hija biss inkonvenjent. F'ledger hija problema li tmur għall-agħar:

• Fattura doppja tikkonsma numru minn sekwenza mingħajr spazji (gapless sequence), għalhekk it-tħassir tagħha mhix għażla - l-immutabilità tfisser li l-korrezzjoni tagħha teħtieġ nota ta' kreditu, li hija dokument li l-klijent tiegħek jara.
• Id-duplikazzjoni tpoġġi d-dħul fil-ġurnal (journal entries), għalhekk id-dħul, il-VAT u r-riċevibbli jkunu kollha stmati żżejjed sakemm xi ħadd induna.
• Din tidħol fir-ritorn tal-VAT u, fil-Litwanja, fir-reġistri i.SAF.
• Jekk ikun tat-timbru lil ħlas, il-flus ikunu fil-fatt iċċaqalqu.

"Iċċekkja biss għal duplikati" lanqas ma taħdem, minħabba li żewġ fatturi tassew separati lill-istess klijent għall-istess ammont fl-istess jum huma kompletament normali. Is-sistema ma tistax tnaqqas l-intenzjoni mill-kontenut - il-klijent irid jiddikjaraha.

Kif jaħdmu ċ-ċwievet tal-idempotenza

Il-klijent jiġġenera ċavetta unika għal kull operazzjoni loġika u jibgħatha mat-talba:

POST /v1/sales/invoices/create
Idempotency-Key: 8f14e45f-ea1b-4c2b-9f3a-2d7c1e0b5a91

Is-server imbagħad iggarantixxi:

1. L-ewwel talba b'din iċ-ċavetta - ipproċessa b'mod normali, aħżen ir-riżultat marbut ma' dik iċ-ċavetta.
2. Tentattiv ieħor bl-istess ċavetta u l-istess payload - terġax teżegwixxi; irrifondi r-rispons maħżun.
3. L-istess ċavetta, payload differenti - irrifjuta. Iċ-ċavetta hija dikjarazzjoni li din hija l-istess operazzjoni; korp (body) differenti jfisser li ma hijiex, u r-ritorn tas-silenzju tar-riżultat il-qadim ikun agħar minn żball.
4. Tentattiv ieħor waqt li l-oriġinali għadu qed jaħdem - irrifjuta bi żball li jista' jerġa' jipprova (retryable error) minflok ma teżegwixxi fl-istess ħin.

Il-Punt 4 huwa dak li l-implimentazzjonijiet naivi jitilfu. Klijent li jiskadilu t-timeout f'5 sekondi u jerġa' jipprova f'6 se jaħbat mat-talba tiegħu stess li tkun għadha għaddejja; mingħajr protezzjoni għall-konkorrenza, it-tnejn jipproċedu u jkollok id-duplikazzjoni li l-mekkaniżmu kien jeżisti biex jipprevjeni.

Kif tiġġenera ċ-ċwievet b'mod korrett

Iċ-ċavetta trid tidentifika l-operazzjoni, mhux it-tentattiv:

• Korrett: UUID iġġenerat darba meta l-utent ikklikkja "oħroġ fattura", użat mill-ġdid għal kull tentattiv ripetut ta' dak il-klikk.
• Korrett: ċavetta deterministika derivata mid-dominju tiegħek stess - order-1041-invoice.
• Żbaljat: UUID frisk għal kull tentattiv HTTP. Kull tentattiv jirċievi ċavetta ġdida, u għalhekk kull tentattiv huwa operazzjoni ġdida, u ma tkun implimentat xejn.
• Żbaljat: hash tal-payload. Żewġ operazzjonijiet legalment identiċi mbagħad jaħbtu, u t-tieni tinbela' fis-silenzju.

Iċ-ċwievet jeħtieġu perjodu ta' żamma (retention period) - twil biżżejjed biex ikopri twieqi realistiki ta' tentattivi ripetuti u interruzzjonijiet tal-klijent, mhux għal dejjem.

X'ma solvix l-idempotenza

L-idempotenza tipproteġi kontra l-eżekuzzjoni doppja tal-istess talba. Ma tipproteġix kontra:

• Żewġ utenti differenti li joħolqu l-istess fattura minn sessjonijiet differenti - din hija problema ta' regola tan-negozju, solvuta b'restrizzjonijiet ta' unika (uniqueness constraints) bħal fattura waħda għal kull ordni.
• Duplikati loġiċi b'ċwievet differenti.
• Nuqqas ta' determinismu ġewwa l-operazzjoni - jekk l-handler jiġġenera timestamp jew numru, ir-rispons maħżun jaqbad l-ewwel wieħed, li huwa l-imġiba mixtieqa iżda li ta' min jifhimha.

Tikkumplimenta, minflok ma tissostitwixxi, ir-restrizzjonijiet tad-database. Il-ledger ta' Nordlet juża t-tnejn: iċ-ċwievet tal-idempotenza jwaqqfu t-talbiet li jerġgħu jippruvaw, filwaqt li l-indici uniċi jwaqqfu l-lottijiet ta' saldu doppji għal kull ID ta' pagament, fatturi ta' xiri doppji għal kull fornitur u numru tad-dokument, u ġirjiet ta' deprezzament doppji għal kull assi u perjodu.

Kif Nordlet jimplimentaha

Ibgħat header Idempotency-Key fuq kwalunkwe talba li tbiddel l-istat - string mhux vojta ta' l-iktar 255 karattru.

L-ewwel talba b'ċavetta mogħtija tiġi eżegwita u r-riżultat tagħha jinħażen. Tentattiv ripetut bl-istess ċavetta u l-istess payload jirrifondi r-rispons maħżun mingħajr ma jerġa' eżegwixxi, sabiex il-fattura tinħoloq eżattament darba irrispettivament minn kemm-il darba tissejjaħ it-talba.

Żewġ modi ta' falliment huma espliċiti minflok ma jkunu siekta:

• L-istess ċavetta, payload differenti → miċħuda: "Idempotency-Key was already used with a different request payload." Dan jaqbad il-każ perikoluż verament fejn klijent jerġa' juża ċavetta filwaqt li jibdel l-ammont.
• L-istess ċavetta, l-oriġinali għadu qed jaħdem → miċħuda bħala li tista' terġa' tinpprova: "A request with this Idempotency-Key is still being processed, retry shortly." L-ebda eżekuzzjoni doppja konkorrenti.

Iċ-ċwievet huma limitati skont il-kumpanija (scoped per company), sabiex żewġ klijenti (tenants) li jiġġeneraw l-istess UUID qatt ma jaħbtu magħhom infushom.

Il-garanzija komplementari taħdem fid-direzzjoni l-oħra. Il-kunsinna tal-webhooks hija tal-inqas darba (at-least-once), li jfisser li l-endpoint tiegħek kultant jirċievi l-istess avveniment darbtejn - wara timeout fejn il-kunsinna fil-fatt irnexxiet, jew fuq konsenja mill-ġdid. Kull avveniment iġorr ID, u l-handler tiegħek għandu jirreġistra l-IDs ipproċessati u jinjora dawk ripetuti. L-idempotenza hija proprjetà li ż-żewġ naħat ta' integrazzjoni jeħtieġu; il-gwida dwar il-konvenzjonijiet tal-API tkopri n-naħa tat-talbiet fid-dettall.

FAQ

X'inhi ċavetta tal-idempotenza?

Identifikatur iġġenerat mill-klijent mibgħut ma' talba li jippermetti lis-server jirrikonoxxi tentattiv ripetut tal-istess operazzjoni loġika. L-ewwel talba tiġi eżegwita; tentattivi ripetuti bl-istess ċavetta jirrifondu r-riżultat maħżun minflok ma jerġgħu jeżegwixxu.

Għaliex l-APIs tal-kontabilità jeħtieġu l-idempotenza?

Minħabba li kitba doppja toħloq dokument reali b'konsekvenzi reali - it-tieni fattura li tikkonsma numru sekwenzjali, li titpoġġa fil-ledger, u li tidħol f'ritorn tal-VAT. B'differenza minn qari doppju, ma tistax sempliċement titħassar; trid tiġi kkoreġuta b'nota ta' kreditu.

Għandi niġġenera ċavetta ġdida għal kull tentattiv ripetut?

Le - dan iħassar il-mekkaniżmu għal kollox. Iġġenera ċavetta waħda għal kull operazzjoni loġika u użaha mill-ġdid għal kull tentattiv ripetut ta' dik l-operazzjoni. Çavetta ġdida għal kull tentattiv tfisser li kull tentattiv jiġi ttrattat bħala operazzjoni ġdida.

X'jiġri jekk nuża mill-ġdid ċavetta b'payload differenti?

It-talba tiġi miċħuda. Iċ-ċavetta tiddikjara li din hija l-istess operazzjoni, għalhekk korp mibdul jfisser li xi ħaġa mhix tajba - l-aktar probabbli żball ta' użu mill-ġdid taċ-ċavetta fuq il-klijent. Ir-ritorn tar-riżultat ta' qabel fis-silenzju jkun agħar.

L-idempotenza tipprevjeni d-duplikati kollha?

Le. Tipprevjeni l-eżekuzzjoni doppja tal-istess talba. Żewġ utenti differenti li joħolqu b'mod indipendenti l-istess fattura jkunu għamlu żewġ talbiet differenti, li hija problema ta' regola tan-negozju għal restrizzjonijiet ta' unika, mhux xi ħaġa li ċavetta tal-idempotenza tista' tara.