Duplicati degli ordini con le API: cause e protezione

Perché i duplicati compaiono dopo una sola azione

Il titolare del pannello può premere un pulsante una sola volta e vedere più ordini identici: per follower, visualizzazioni, reazioni o un altro servizio. Di solito il problema non è nel clic in sé, ma nella catena tra client, API, database e fornitore.

Dal punto di vista del server, "una richiesta" non è sempre una sola. Il client potrebbe non aver ricevuto la risposta e aver ripetuto l'invio, mentre la prima operazione era già stata salvata. A volte l'ordine viene creato una sola volta nel database del pannello, ma viene inviato due volte al fornitore. Sono scenari diversi e si correggono in modi diversi.

Un timeout non significa che l'ordine non sia stato creato

La causa più frequente è che il client attende una risposta per un tempo limitato. Il server riceve la richiesta, crea l'ordine, ma risponde dopo il timeout impostato. Il client considera l'operazione non riuscita e la invia di nuovo.

Di conseguenza il primo ordine è già nel database e la seconda richiesta ne crea un altro. Questo accade particolarmente spesso con una risposta lenta dell'API esterna, una coda sovraccarica o una connessione instabile tra i servizi.

Il timeout indica solo l'assenza di risposta, non l'assenza di elaborazione della richiesta.

Ripetizioni automatiche lato client

Le librerie per le richieste HTTP, le attività in background e i servizi di integrazione spesso ripetono automaticamente la richiesta. Il motivo può essere un errore di connessione, un codice di risposta del server, un'interruzione di rete o una risposta troppo lenta.

La ripetizione in sé è utile: riduce il numero di ordini persi in caso di guasti temporanei. Il difetto di questo approccio è che, senza protezione dalla rielaborazione, trasforma qualsiasi instabilità di rete in duplicati.

• la ripetizione può essere avviata nel codice del sito o del bot;
• l'attività può essere riavviata dalla coda;
• la richiesta può essere ripetuta da un proxy o da un modulo di integrazione;
• l'operatore può inviare manualmente di nuovo l'ordine dopo un errore.

La richiesta ripetuta arriva prima della prima risposta

A volte due richieste identiche raggiungono davvero l'API quasi contemporaneamente. Per esempio, l'utente ha inviato il modulo due volte, il frontend non ha bloccato il pulsante o l'attività in background è partita di nuovo prima del completamento della prima.

Se il gestore prima verifica l'esistenza dell'ordine e poi lo crea, due operazioni parallele possono superare il controllo contemporaneamente. Ognuna vedrà che l'ordine non esiste ancora e ognuna aggiungerà un nuovo record.

Questa situazione è chiamata race condition. Un semplice controllo preliminare nel codice non protegge completamente da essa. Il difetto del controllo senza un vincolo a livello di database è che si rompe sotto carico parallelo.

L'ordine è stato salvato, ma la risposta dell'API è andata persa

La richiesta attraversa diverse fasi: il server riceve i dati, crea il record, mette l'attività in coda, invia la risposta. Un guasto è possibile tra una fase e l'altra. Per esempio, il database ha già confermato la creazione dell'ordine, ma la connessione si è interrotta prima di trasmettere la risposta al client.

Il client non sa se l'ordine è stato accettato e ripete l'operazione. Un'API senza un meccanismo di verifica specifico interpreta la richiesta come nuova. Nel log spesso sembra che il servizio abbia creato due ordini "da solo", anche se ha ricevuto due richieste in ingresso.

Chiave di idempotenza per la creazione dell'ordine

Per le operazioni di creazione serve una chiave di idempotenza univoca. Il client la genera prima del primo invio e la trasmette insieme ai parametri dell'ordine. In caso di ripetizione per timeout o errore si usa la stessa chiave.

L'API salva la chiave insieme al risultato dell'elaborazione. Se arriva una richiesta con una chiave già nota, il server non crea un nuovo ordine, ma restituisce il risultato della prima chiamata: l'identificativo dell'ordine, il suo stato o l'errore già generato.

Una chiave deve corrispondere a una singola operazione di business, non a una singola connessione HTTP.

Il difetto del metodo è che le chiavi vanno archiviate, ripulite secondo regole precise e verificate lato API. Se si genera una nuova chiave a ogni ripetizione, la protezione non funziona. Se si usa una stessa chiave per ordini diversi, alcune nuove operazioni verranno rifiutate per errore.

L'unicità deve essere controllata dal database

È meglio integrare l'idempotenza con un vincolo di unicità nel database. A questo scopo si sceglie una combinazione che descriva in modo univoco l'ordine: l'identificativo interno del client, la chiave di idempotenza, il tipo di servizio e altri campi necessari.

Il database deve rifiutare il secondo record, anche se due gestori sono arrivati alla creazione contemporaneamente. Dopo il conflitto l'API restituisce l'ordine esistente, non un errore senza spiegazione.

Il difetto di un vincolo di unicità rigido è che non può essere basato solo sul link o sullo username. Il client può ordinare consapevolmente lo stesso servizio sullo stesso canale più volte. Un vincolo troppo ampio bloccherebbe i normali acquisti ripetuti.

La coda può consegnare l'attività più di una volta

Le code di attività funzionano spesso secondo il principio della "consegna almeno una volta". Se un worker ha elaborato l'attività ma non ha fatto in tempo a confermarne l'esecuzione, la coda può assegnare la stessa attività di nuovo a un altro worker.

Per la coda questo è un modo normale di non perdere l'attività. Per la creazione di un ordine senza idempotenza è una fonte di duplicati. L'identificativo dell'attività o una chiave separata dell'operazione deve essere trasmesso fino al gestore finale, incluso il modulo di invio dell'ordine al fornitore.

Il difetto della disattivazione della riconsegna è che, in caso di caduta del worker, alcuni ordini possono andare persi. È più sicuro accettare le possibili ripetizioni e rendere il gestore resistente ad esse.

I duplicati nascono tra il pannello e il fornitore

L'ordine interno può essere creato una sola volta, ma la richiesta all'API esterna viene inviata due volte. La causa è la stessa: il pannello non ha ricevuto la risposta dal fornitore e ha deciso di ripetere l'invio. Se il fornitore ha già accettato la prima richiesta, dalla sua parte compariranno due richieste identiche.

Serve un collegamento separato tra l'ordine interno e quello esterno: un identificativo di invio, una chiave di idempotenza o la risposta salvata del fornitore. Non si può dare per scontato che la protezione all'ingresso del proprio pannello protegga automaticamente le chiamate in uscita.

Il difetto del confronto con un'API di terze parti è che non tutti i fornitori supportano la ricerca tramite chiave esterna. In tal caso bisogna registrare i tentativi di invio e analizzare separatamente gli stati indeterminati.

Il webhook non deve creare un nuovo ordine

I webhook comunicano i cambiamenti: ordine accettato, avviato, completato, annullato o da verificare. L'errore si verifica quando il gestore del webhook interpreta la notifica come un comando per creare di nuovo l'ordine.

Lo stesso webhook può arrivare più volte. Il mittente ripete la consegna se non ha ricevuto una conferma, e le notifiche a volte arrivano fuori ordine. Il gestore deve trovare l'ordine esistente tramite l'identificativo esterno e aggiornarne lo stato.

Il difetto dell'elaborazione dei webhook solo in base all'ora di ricezione è che una notifica in ritardo può sovrascrivere lo stato attuale con uno obsoleto. Servono un identificativo dell'evento, una versione dello stato o regole chiare di transizione.

Quali registrazioni aiutano a trovare l'origine dei duplicati

Per l'indagine non basta vedere solo due numeri d'ordine. Servono dati su ogni fase dell'elaborazione: ora della richiesta, chiave di idempotenza, identificativo del client, parametri dell'ordine, numero dell'attività in background, risposta dell'API esterna e tentativi di reinvio.

• confrontate i duplicati tramite la chiave dell'operazione, non solo tramite il link;
• verificate se nel log dell'API in ingresso ci sono state richieste identiche;
• controllate se l'attività è stata ripetuta nella coda;
• separate la creazione dell'ordine interno dall'invio al fornitore;
• salvate l'identificativo esterno della richiesta subito dopo aver ricevuto la risposta.

Il difetto dei log troppo brevi è che l'origine del problema scompare prima che si riesca ad analizzarla. Il difetto del logging eccessivo è che nelle registrazioni possono finire token, dati personali e altri campi sensibili, che vanno quindi mascherati.

Come gestire un risultato indeterminato della richiesta

Dopo un timeout non si può creare subito di nuovo l'ordine con nuovi dati. Prima l'API deve verificare l'operazione tramite la chiave di idempotenza o l'identificativo del client. Se l'ordine viene trovato, si restituisce il suo stato attuale. Se l'elaborazione è ancora in corso, il client riceve uno stato di attesa.

1. Creare la chiave dell'operazione prima della prima richiesta.
2. Inviare la stessa chiave a ogni ripetizione.
3. Salvare la chiave e l'ordine in un'unica operazione protetta del database.
4. Trasmettere l'identificativo dell'operazione alla coda e all'API esterna.
5. Restituire l'ordine creato in precedenza in caso di richiesta ripetuta.

Questo scenario richiede modifiche all'API e all'integrazione del client. Il suo difetto è un debug più complesso e più stati dell'ordine, ma la riconsegna della richiesta smette di significare automaticamente un nuovo acquisto.