En el desenvolupament d' aplicacions modernes, especialment aquelles que manegen transaccions financeres o processos crítics, un dels problemes més esquius és la duplicació d' operacions a causa de reintents. Imagina que un usuari fa clic a "Pagar 49€", la xarxa es cau just quan el servidor ja va processar el cobrament però abans que la resposta arribi al client. El client reintenta i es produeix un doble càrrec. Aquest escenari no és una fallada de codi, sinó una propietat inherent a les comunicacions en xarxes no fiables. La solució és implementar claus d'idempotència, un patró que garanteix que una operació s'executi una sola vegada encara que es rebi múltiples vegades. En aquest article explorarem en profunditat com funciona aquest mecanisme, les seves implicacions tècniques i quan aplicar-lo.
\nEl problema dels reintents no és opcional. Qualsevol sistema distribuït enfronta timeouts, talls de xarxa o balancejadors de càrrega que interrompen la comunicació. Un timeout no significa que l'operació hagi fallat: pot que el servidor va completar la feina i la resposta es va perdre en el camí. Com que no podem distingir entre "no va arribar" i "sí que va arribar però no ho sé", hem de reintentar. Això implica que el nostre servidor rebrà la mateixa petició més d'una vegada. No podem evitar-ho, només podem decidir què passa quan això succeeix. La idempotència és el mecanisme que converteix aquest "almenys una vegada" en un efecte "exactament una vegada".
\nQuè significa exactament una operació idempotent? En termes pràctics, produir el mateix resultat després d' una o múltiples execucions. Quan un client envia una sol·licitud amb una clau única (per exemple, un UUID v4), el servidor registra aquesta clau i l'associa al resultat. Si arriba una segona sol·licitud amb la mateixa clau, el servidor retorna el mateix resultat sense tornar a executar la lògica de negoci. Aquest contracte entre client i servidor és la base de la idempotència. El client es compromet a generar una clau per cada operació lògica (no per cada intent HTTP), i el servidor es compromet a processar-la una sola vegada.
\nImplementar aquest patró requereix una infraestructura sòlida. La peça central és una taula a la base de dades que emmagatzema les claus, el seu estat (en progrés o completat), una empremta del cos de la petició (per detectar reutilitzacions incorrectes), el codi de resposta i el cos de la resposta, i una data d'expiració. La clau primària és el propi valor de la clau, cosa que garanteix unicitat. El primer pas del manejador és intentar inserir aquesta clau amb un INSERT ... ON CONFLICT DO NOTHING; si la inserció té èxit, el fil actual és el propietari de l' operació. Si falla, significa que ja existeix un registre, i llavors es consulta el seu estat: si està completat, es replica la resposta emmagatzemada; si està en progrés, es respon amb un 409 indicant que el procés encara no ha acabat; si l' empremta del cos no coincideix, es respon amb un 422, assenyalant un error de programació del client.
\nL'atomicitat és un altre pilar fonamental. L'efecte de negoci (per exemple, carregar una targeta) i l'actualització del registre d'idempotència han d'ocórrer en la mateixa transacció de base de dades. Si el servidor es cau just després de cobrar però abans de marcar la clau com a completada, la transacció es reverteix i el reintent trobarà la clau en estat "en progrés" (o simplement no existirà) i podrà executar-se netament. Quan l'efecte de negoci involucra serveis externs (com una passarel·la de pagament), cal recórrer al patró d'outbox: dins de la transacció s'escriu una intenció, i un worker extern s'encarrega d'executar-la i registrar el resultat. La passarel·la externa també ha de suportar idempotència (habitualment mitjançant la seva pròpia clau), i el worker ha de ser resilient a fallades.
A més de la concurrència i l' atomicitat, cal considerar la neteja de claus antigues. Un TTL de 24 hores és un estàndard raonable (copiat d'APIs com Stripe). Passat aquest temps, la clau es considera expirada i s'elimina amb un procés periòdic. Això evita que la taula creixi indefinidament i que claus orfes bloquegin futures operacions. Un índex sobre la data d'expiració accelera l'eliminació.
\nNo tots els endpoints necessiten idempotència. Les operacions GET són inherentment idempotents, igual que els PUT que estableixen un valor absolut. El patró només és necessari en operacions amb efectes secundaris no idempotents: càrrecs, trameses, creació de recursos amb identificador únic, increments de comptadors, etc. El cost d'implementar-lo (taula, lògica addicional, transaccions) s'ha de justificar pel risc de duplicació. En sistemes de pagaments o aprovisionament, aquest risc és molt alt.
\nEn Q2BSTUDIO, com a empresa especialitzada en aplicacions a mida i programari a mida, hem implementat aquest patró en múltiples projectes crítics. Els nostres equips integren idempotència amb serveis cloud AWS i Azure per garantir escalabilitat i resiliència. A més, apliquem intel·ligència artificial per predir pics de reintents o automatitzar respostes, i oferim ciberseguretat per protegir les claus i les dades sensibles. Els nostres serveis d'intel·ligència de negoci amb Power BI permeten monitoritzar en temps real la taxa de reintents i l'efectivitat de la idempotència, facilitant la presa de decisions.
\nTambé hem explorat l'ús d'agents IA per gestionar automàticament el cicle de vida de les claus: des de la generació d'UUIDs fins a la detecció de patrons anòmals que podrien indicar un atac de repetició. La IA per a empreses ja no és només una promesa; en Q2BSTUDIO l'apliquem per optimitzar processos transaccionals i reduir la càrrega operativa.
\nEn resum, la idempotència és una eina imprescindible quan els reintents són inevitables i el cost d'una duplicació és alt. No és un luxe, és una exigència de disseny. Implementar-la correctament requereix entendre la capa de xarxa, la base de dades, la concurrència i l' atomicitat. Si estàs construint una API on un doble càrrec seria un incident greu, val la pena invertir des del primer dia en aquest patró. En Q2BSTUDIO t'ajudem a fer-ho bé, integrant idempotència amb arquitectures cloud, intel·ligència artificial i les millors pràctiques de ciberseguretat.
