Klient priradí jednej obchodnej operácii stabilný idempotentný kľúč, server ho viaže na identitu a obsah požiadavky, atómovo uloží stav a pri opakovaní vráti pôvodný výsledok alebo bezpečný konflikt. Návrh otestujte pri súbehu, timeoute a čiastočnom zlyhaní.
Idempotencia API znamená, že opakované vykonanie tej istej zamýšľanej operácie nevytvorí ďalší neželaný účinok. Je dôležitá pri objednávke, platbe, faktúre, rezervácii alebo importe kontaktu. Klient môže požiadavku zopakovať po timeoute, používateľ dvakrát kliknúť a sprostredkovateľ doručiť udalosť viackrát, hoci prvý pokus už uspel.
Jednoduchá kontrola, či záznam existuje, nemusí stačiť pri súbehu alebo čiastočnom zlyhaní. Návrh potrebuje identitu operácie, atómové uloženie stavu, pravidlá opakovanej odpovede a bezpečnú opravu. Idempotencia neznamená ignorovať každú podobnú požiadavku; dve skutočne odlišné objednávky musia zostať odlišné.
Pochopte, odkiaľ opakovanie prichádza
HTTP klient často nevie, či timeout nastal pred spracovaním alebo po ňom. Opakovanie je preto prirodzená stratégia, nie chyba. Niektoré fronty a webhookové mechanizmy sú navrhnuté na doručenie aspoň raz, čo vedome pripúšťa duplicitu. Používateľský dvojklik, návrat prehliadača alebo opätovný import vytvárajú ďalšie cesty k rovnakému účinku.
Zmapujte operácie, pri ktorých duplicita spôsobí obchodný problém. Čítanie zvyčajne nemá rovnaké riziko ako vytvorenie platby. Aktualizácia na presnú hodnotu sa správa inak než príkaz zvýšiť množstvo. Ku každej operácii určte identitu zámeru a obdobie, počas ktorého sa opakovanie považuje za rovnaké.
Navrhnite stabilný idempotentný kľúč
Kľúč má vzniknúť raz pre konkrétny obchodný zámer a zostať rovnaký pri technickom opakovaní. Nemá sa generovať nanovo pri každom pokuse, inak server duplicitu nerozozná. Rozsah kľúča spojte s klientom, účtom alebo endpointom, aby sa náhodná zhoda medzi rôznymi používateľmi nestala konfliktom.
Server môže uložiť odtlačok významného obsahu a odmietnuť rovnaký kľúč s inými parametrami. Chráni tým klienta pred omylom, keď kľúč znovu použije na inú sumu alebo produkt. Nezahŕňajte do porovnania hodnoty, ktoré sa pri každom pokuse prirodzene menia, napríklad technickú časovú značku.
- jeden kľúč pre jeden obchodný zámer
- väzba na klienta a typ operácie
- kontrola zmeneného obsahu
- jasná doba uchovania stavu
Uložte stav a výsledok atómovo
Pri prvom prijatí vytvorte záznam operácie spôsobom, ktorý zabráni dvom súbežným pracovníkom získať vlastníctvo. Jedinečný databázový kľúč alebo transakčný mechanizmus je spoľahlivejší než oddelené najprv skontroluj a potom vlož. Stav môže rozlišovať prijaté, spracovávané, úspešné a zlyhané operácie.
Po úspechu uchovajte bezpečný výsledok alebo odkaz na vytvorený objekt. Opakovaná požiadavka má dostať konzistentnú odpoveď bez ďalšieho účinku. Pri dlhej práci môže server oznámiť, že operácia pokračuje, a ponúknuť stavový endpoint. Neuchovávajte nepotrebný citlivý obsah iba kvôli idempotencii.
Riešte čiastočný úspech a poradie krokov
Operácia môže uložiť objednávku a zlyhať pri odoslaní e-mailu alebo externom API. Rozlíšte hlavný obchodný záväzok od následných úloh. Vedľajšie kroky spracujte cez odolný front a tiež im priraďte vlastnú identitu. Zrušenie celého výsledku nemusí byť možné ani správne po prijatej platbe.
Ak rovnaký objekt mení viac udalostí, idempotencia sama nevyrieši ich poradie. Použite verziu, očakávaný stav alebo sekvenčné spracovanie podľa objektu. Staršia udalosť nemá prepísať novší finálny stav. Konflikt urobte viditeľný na manuálne rozhodnutie, ak ho nemožno bezpečne vyriešiť pravidlom.
Testujte súbeh, vypršanie a opravu
Spustite rovnakú požiadavku súbežne, prerušte spojenie po odoslaní a zopakujte ju počas spracovania aj po úspechu. Overte rovnaký kľúč s odlišným obsahom, neplatného klienta a opakovanie po uplynutí retenčného okna. Kontrolujte obchodný výsledok, sklad, doklad a udalosti, nie iba stavový kód.
Prevádzka potrebuje vidieť operácie uviaznuté v spracovaní a bezpečne rozhodnúť o pokračovaní. Manuálne vymazanie idempotentného záznamu môže spustiť duplicitu, preto vytvorte riadený opravný postup. Sledujte mieru opakovaní; náhly rast môže signalizovať timeout, chybu klienta alebo problém siete.
- dva súbežné pokusy s rovnakým kľúčom
- timeout po úspešnom uložení obchodného objektu
- rovnaký kľúč s odlišným obsahom
- čiastočný úspech nadväzujúcej externej operácie
- kontrolované opakovanie po manuálnej oprave
- vypršanie uloženého kľúča počas obnovy služby
- bezpečný konflikt pri neplatnej identite klienta
- jediný výsledný doklad vo všetkých systémoch
Časté otázky
Je idempotencia rovnaká ako deduplikácia?
Súvisia, ale nie sú totožné. Idempotencia viaže opakované technické pokusy na jeden zámer a výsledok. Deduplikácia môže neskôr spájať samostatné záznamy podľa podobnosti alebo obchodných pravidiel.
Kto má vytvoriť idempotentný kľúč?
Zvyčajne klient, ktorý pozná hranicu jedného zámeru a vie kľúč opakovane použiť. Server určuje formát, rozsah, validáciu a dobu uchovania podľa kontraktu API.
Ako dlho uchovávať výsledok operácie?
Podľa najdlhšieho realistického opakovania, obchodného rizika a nákladov na uloženie. Retenčné pravidlo musí byť zdokumentované; po jeho uplynutí môže rovnaký kľúč znamenať nový výsledok.
Zdroje a ďalšie čítanie
Web developer zo Spišskej Novej Vsi. Venuje sa WordPressu, WooCommerce, vlastným pluginom, API integráciám, webovým aplikáciám a praktickým AI automatizáciám.
