Förklaring · Teknik
Vad är en idempotensnyckel: och varför er app behöver en
Förr eller senare svarar varje app som fungerar offline på samma fråga: vad händer när användaren trycker på "skicka" två gånger, eller när nätverket dör mitt i en request och klienten gör en retry? Det svaret är en liten mekanism som kallas idempotensnyckel, så här fungerar den, och så här ser den ut i vår egen kod.
Problemet i en mening
Nätverk är opålitliga, så klienter måste göra retries. Retries betyder att samma logiska åtgärd anländer fler än en gång. Utan skydd blir "fler än en gång" två tidposter, två fakturor, två bokningar.
Notera vad problemet inte är: det är inte "användaren dubbelklickade". Användare dubbelklickar visst, men det vanliga fallet är mycket mindre synligt, en mobilapp på en byggarbetsplats tappar täckningen, lägger instämplingen i kö, servern tillämpar den, svaret dör på vägen och appen (helt korrekt) skickar den igen. Dubletten är systemet som fungerar som avsett.
Mekanismen
En idempotensnyckel är en unik identifierare som klienten genererar per logisk åtgärd, inte per HTTP-request. Klienten sätter samma nyckel på den ursprungliga requesten och på varje retry av den åtgärden. Servern håller reda på nycklarna den har sett. När en nyckel anländer två gånger returnerar servern det första resultatet i stället för att exekvera mutationen två gånger.
Tre egenskaper gör att det fungerar:
- Klienten äger nyckeln. Om det var servern som delade ut den skulle en retry innan den tagits emot inte kunna identifieras. Nyckeln skapas på enheten, i våra mobilappar ett UUID som genereras i det ögonblick användaren stämplar, inte när nätverksanropet avfyras.
- Posten är en claim, inte ett resultat. Servern skriver claimet först ("den här nyckeln är nu min, resultat väntar") och muterar sedan. En konkurrerande retry hittar claimet och väntar på eller spelar upp det ursprungliga utfallet, den kan aldrig smyga in en andra mutation under.
- Claimet binder nyttolasten. Vi lagrar en hash av åtgärden och dess normaliserade indata tillsammans med nyckeln. Samma nyckel, annan nyttolast → en 409-konflikt, inte en tyst överskrivning. En retry ska bara någonsin betyda "samma sak igen".
Var den dyker upp i våra appar
ArbeitszeitChecks mobila stämpelkö bär ett clientRequestIdcodeclient_event_id genom varje uppspelning. TourCheck binder samma kontrakt till code på bekräftelser av kontrollpunkter, där en uppspelning jämför hela claimet, anteckning, foto, tidsstämpel, mot den lagrade raden. Livslängden spelar lika stor roll som dedupliceringen: våra claim-rader lever i sju dagar, långt nog för att täcka en långhelg utan täckning, kort nog för att tabellen ska förbli en kö och inte en logg.
Kortversionen för er egen app
Om ert API muterar tillstånd och er klient kan göra retries, och det kan varje klient, behöver ni exakt tre saker: en klientgenererad nyckel per åtgärd, en claim-rad vid första skrivningen och en payload-hash så att "samma nyckel" också betyder "samma avsikt". Det är hela mönstret. Allt annat, uppspelningsfönster, städjobb, statuskoder för konflikt, är rörläggning kring de tre åtagandena.