Explicación · Ingeniería
Qué es una clave de idempotencia: y por qué su app necesita una
Toda app capaz de funcionar sin conexión acaba respondiendo a la misma pregunta: ¿qué pasa cuando el usuario toca «enviar» dos veces, o cuando la red muere a mitad de la petición y el cliente reintenta? La respuesta es un pequeño mecanismo llamado clave de idempotencia, así funciona, y así se ve en nuestro propio código.
El problema en una frase
Las redes no son fiables, así que los clientes deben reintentar. Los reintentos hacen que la misma acción lógica llegue más de una vez. Sin protección, «más de una vez» se convierte en dos registros de horas, dos facturas, dos reservas.
Fíjate en lo que el problema no es: no es «el usuario hizo doble clic». Los usuarios hacen doble clic, pero el caso común es mucho menos visible, una app móvil en una obra pierde señal, encola el fichaje, el servidor lo aplica, la respuesta muere en tránsito y la app (correctamente) lo envía otra vez. El duplicado es el sistema funcionando exactamente como se diseñó.
El mecanismo
Una clave de idempotencia es un identificador único que el cliente genera por acción lógica, no por petición HTTP. El cliente adjunta la misma clave a la petición original y a cada reintento de esa acción. El servidor guarda un registro de las claves que ha visto. Cuando una clave llega dos veces, devuelve el primer resultado en lugar de ejecutar la mutación dos veces.
Tres propiedades lo hacen posible:
- La clave pertenece al cliente. Si la emitiera el servidor, un reintento lanzado antes de recibirla no podría identificarse. La clave se acuña en el dispositivo, en nuestras apps móviles, un UUID creado en el instante en que el trabajador ficha, no cuando sale la llamada de red.
- El registro es una reclamación, no un resultado. El servidor escribe primero la reclamación («esta clave ahora es mía, resultado pendiente») y solo después muta. Un reintento concurrente encuentra la reclamación y espera el resultado original, o lo repite, sin que jamás pueda colar una segunda mutación por debajo.
- La reclamación liga la carga. Guardamos con la clave un hash de la acción y sus entradas normalizadas. Misma clave, carga distinta → un conflicto 409, no una sobrescritura silenciosa. Un reintento solo debería significar «lo mismo otra vez».
Dónde aparece en nuestras apps
La cola de fichajes móvil de ArbeitszeitCheck lleva un clientRequestIdcodeclient_event_id a través de cada reenvío. TourCheck ata el mismo contrato a code en las confirmaciones de puntos de control, donde un reenvío compara la reclamación entera, nota, foto, marca temporal, contra la fila almacenada. La caducidad importa tanto como la deduplicación: nuestras filas de reclamación viven siete días, lo bastante para cubrir un fin de semana largo sin cobertura, lo bastante poco para que la tabla siga siendo una cola y no un registro.
La versión corta para su propia app
Si su API muta estado y su cliente puede reintentar, y todo cliente puede reintentar, necesita exactamente tres cosas: una clave generada en el cliente por acción, una fila de reclamación en la primera escritura y un hash de carga para que «misma clave» también signifique «misma intención». Ese es todo el patrón. Todo lo demás, ventanas de reenvío, tareas de limpieza, códigos de estado de conflicto, es fontanería alrededor de esos tres compromisos.