Décryptage · Ingénierie
Qu'est-ce qu'une clé d'idempotence: et pourquoi votre appli en a besoin
Toute appli capable de fonctionner hors ligne finit par répondre à la même question: que se passe-t-il quand l'utilisateur tape « envoyer » deux fois, ou quand le réseau meurt en pleine requête et que le client réessaie ? La réponse est un petit mécanisme appelé clé d'idempotence, voici comment il fonctionne, et à quoi il ressemble dans notre propre code.
Le problème en une phrase
Les réseaux ne sont pas fiables, donc les clients doivent réessayer. Les réémissions font arriver la même action logique plus d'une fois. Sans protection, « plus d'une fois » devient deux entrées de temps, deux factures, deux réservations.
Notez ce que le problème n'est pas: ce n'est pas « l'utilisateur a double-cliqué ». Les utilisateurs double-cliquent, mais le cas courant est bien moins visible, une appli mobile sur un chantier perd le signal, met le pointage en file, le serveur l'applique, la réponse meurt en transit, et l'appli (à juste titre) le renvoie. Le doublon, c'est le système qui fonctionne exactement comme prévu.
Le mécanisme
Une clé d'idempotence est un identifiant unique que le client génère par action logique, pas par requête HTTP. Le client attache la même clé à la requête initiale et à chaque réémission de cette action. Le serveur conserve une trace des clés qu'il a vues. Quand une clé arrive deux fois, il renvoie le premier résultat au lieu d'exécuter la mutation deux fois.
Trois propriétés font que ça marche:
- La clé appartient au client. Si c'était le serveur qui l'émettait, une réémission partie avant sa réception serait impossible à identifier. La clé est frappée sur l'appareil, dans nos applis mobiles, un UUID créé à l'instant où l'ouvrier pointe, pas au moment où l'appel réseau part.
- L'entrée est une revendication, pas un résultat. Le serveur écrit d'abord la revendication (« cette clé m'appartient désormais, résultat en attente »), puis modifie. Une réémission concurrente trouve la revendication et attend le résultat original, ou le rejoue, sans jamais pouvoir glisser une seconde mutation dessous.
- La revendication lie la charge. Nous stockons avec la clé un hash de l'action et de ses entrées normalisées. Même clé, charge différente → un conflit 409, pas un écrasement silencieux. Une réémission ne devrait jamais vouloir dire autre chose que « la même chose, encore ».
Où elle apparaît dans nos applis
La file de pointage mobile d'ArbeitszeitCheck transporte un clientRequestId à travers chaque rejeu; TourCheck lie le même contrat à client_event_id sur les confirmations de points de contrôle, où un rejeu compare la revendication entière, note, photo, horodatage, à la ligne stockée. L'expiration compte autant que la déduplication: nos lignes de revendication vivent sept jours, assez longtemps pour couvrir un long week-end sans couverture, assez court pour que la table reste une file et non un journal.
La version courte pour votre propre appli
Si votre API modifie l'état et que votre client peut réessayer, et tout client peut réessayer, il vous faut exactement trois choses: une clé générée côté client par action, une ligne de revendication à la première écriture, et un hash de charge pour que « même clé » veuille aussi dire « même intention ». C'est tout le motif. Tout le reste, fenêtres de rejeu, tâches de nettoyage, codes de statut de conflit, n'est que la plomberie autour de ces trois engagements.