REL04-BP04 Rendere idempotenti le operazioni di mutazione - Pilastro dell'affidabilità
Guida all'implementazioneRisorse

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

REL04-BP04 Rendere idempotenti le operazioni di mutazione

Un servizio idempotente promette che ogni richiesta venga elaborata esattamente una volta, in modo che effettuare più richieste identiche abbia lo stesso effetto di una singola richiesta. Questo rende più facile per un client implementare i tentativi senza temere che una richiesta venga erroneamente elaborata più volte. A tal fine, i client possono inviare richieste API con un token di idempotenza, che viene utilizzato ogni volta che la richiesta viene ripetuta. Un'API del servizio idempotente utilizza il token per restituire una risposta identica a quella restituita la prima volta che la richiesta è stata completata, anche se lo stato sottostante del sistema è cambiato.

In un sistema distribuito, è relativamente semplice eseguire un'azione al massimo una volta (il client effettua una sola richiesta) o almeno una volta (continuando a richiedere fino a quando il client non riceve una conferma di successo). È più difficile garantire che un'azione venga eseguita esattamente una volta, in modo che più richieste identiche abbiano lo stesso effetto di una singola richiesta. Utilizzando i token di idempotenza nelle API, i servizi possono ricevere una richiesta di mutazione una o più volte senza la necessità di creare record duplicati o effetti collaterali.

Risultato desiderato: hai un approccio coerente, ben documentato e ampiamente adottato per garantire l'idempotenza in tutti i componenti e servizi.

Anti-pattern comuni:

  • Applichi l'idempotenza indiscriminatamente, anche quando non è necessaria.

  • Introduci una logica troppo complessa per implementare l'idempotenza.

  • Utilizzi i timestamp come chiavi per l'idempotenza. Questo può causare imprecisioni a causa del disallineamento dell'orologio o a causa di più client che utilizzano gli stessi timestamp per applicare le modifiche.

  • Archivi interi payload per l'idempotenza. In questo approccio, salvi i payload completi dei dati per ogni richiesta e li sovrascrivi a ogni nuova richiesta. Questo può ridurre le prestazioni e influenzare la scalabilità.

  • Generi le chiavi in modo incoerente tra i vari servizi. Senza chiavi coerenti, i servizi potrebbero non riconoscere le richieste duplicate, con conseguenti risultati indesiderati.

Vantaggi dell'adozione di questa best practice:

  • Maggiore scalabilità: il sistema può gestire tentativi e richieste duplicate senza dover eseguire una logica aggiuntiva o una complessa gestione dello stato.

  • Maggiore affidabilità: l'idempotenza aiuta i servizi a gestire più richieste identiche in modo coerente, riducendo il rischio di effetti collaterali indesiderati o di record duplicati. Questo aspetto è particolarmente importante nei sistemi distribuiti, dove gli errori di rete e i tentativi sono frequenti.

  • Miglioramento della coerenza dei dati: poiché la stessa richiesta produce la stessa risposta, l'idempotenza aiuta a mantenere la coerenza dei dati nei sistemi distribuiti. Questo è essenziale per mantenere l'integrità delle transazioni e delle operazioni.

  • Gestione degli errori: i token di idempotenza rendono più semplice la gestione degli errori. Se un client non riceve una risposta a causa di un problema, può tranquillamente inviare nuovamente la richiesta con lo stesso token di idempotenza.

  • Trasparenza operativa: l'idempotenza consente di migliorare il monitoraggio e la registrazione. I servizi possono registrare le richieste con i propri token di idempotenza, il che facilita il monitoraggio e il debug dei problemi.

  • Contratto API semplificato: può semplificare il contratto tra i sistemi lato client e lato server e ridurre il timore di un'elaborazione errata dei dati.

Livello di rischio associato se questa best practice non fosse adottata: medio

Guida all'implementazione

In un sistema distribuito, eseguire un'azione al massimo una volta (il client effettua una sola richiesta) o almeno una volta (il client continua a richiedere finché non viene confermato l'esito positivo) è relativamente semplice. Tuttavia, è difficile implementare esattamente una volta il comportamento. A tal fine, i client devono generare e fornire un token di idempotenza per ogni richiesta.

Utilizzando i token di idempotenza, un servizio può distinguere tra nuove richieste e richieste ripetute. Quando un servizio riceve una richiesta con un token di idempotenza, controlla se il token è già stato utilizzato. Se il token è stato utilizzato, il servizio recupera e restituisce la risposta memorizzata. Se il token è nuovo, il servizio elabora la richiesta, memorizza la risposta insieme al token e restituisce la risposta. Questo meccanismo rende tutte le risposte idempotenti, migliorando l'affidabilità e la coerenza del sistema distribuito.

Anche l'idempotenza è un comportamento importante delle architetture basate su eventi. Queste architetture sono in genere supportate da una coda di messaggi come Amazon SQS, Amazon MQ, Amazon Kinesis Streams o Amazon Managed Streaming per Apache Kafka (MSK). In alcune circostanze, un messaggio pubblicato una sola volta può essere accidentalmente recapitato più di una volta. Quando un publisher genera e include i token di idempotenza nei messaggi, richiede che l'elaborazione di qualsiasi messaggio duplicato ricevuto non comporti un'azione ripetuta per lo stesso messaggio. I consumatori devono tenere traccia di ogni token ricevuto e ignorare i messaggi che contengono token duplicati.

I servizi e i consumatori devono anche passare il token di idempotenza ricevuto a tutti i servizi a valle che vengono chiamati. Ogni servizio a valle della catena di elaborazione ha la stessa responsabilità di assicurarsi che l'idempotenza sia implementata per evitare l'effetto collaterale di elaborare un messaggio più di una volta.

Passaggi dell'implementazione

  1. Identifica le operazioni idempotenti

    Determina quali operazioni richiedono idempotenza. Questi includono in genere i metodi HTTP POST, PUT e DELETE e le operazioni di inserimento, aggiornamento o eliminazione del database. Le operazioni che non mutano lo stato, come le query di sola lettura, di solito non richiedono idempotenza, a meno che non abbiano effetti collaterali.

  2. Utilizza identificatori univoci

    Includi un token univoco in ogni richiesta di operazione idempotente inviata dal mittente, direttamente nella richiesta o come parte dei relativi metadati (ad esempio, un'intestazione HTTP). Ciò consente al destinatario di riconoscere e gestire richieste o operazioni duplicate. Gli identificatori comunemente usati per i token includono Universally Unique Identifier (UUID) e K-Sortable Unique Identifier (KSUID).

  3. Monitora e gestisci lo stato

    Mantieni lo stato di ogni operazione o richiesta nel carico di lavoro. Ciò può essere ottenuto memorizzando il token di idempotenza e lo stato corrispondente (come in attesa, completato o non riuscito) in un database, una cache o un altro archivio persistente. Queste informazioni sullo stato consentono al carico di lavoro di identificare e gestire richieste o operazioni duplicate.

    Mantieni la coerenza e l'atomicità utilizzando, se necessario, meccanismi di controllo della simultaneità appropriati, come blocchi, transazioni o controlli ottimistici della simultaneità. Questo include il processo di registrazione del token idempotente e l'esecuzione di tutte le operazioni di mutazione associate al servizio della richiesta. Questo aiuta a prevenire le condizioni di gara e verifica che le operazioni idempotenti vengano eseguite correttamente.

    Rimuovi periodicamente i vecchi token di idempotenza dal datastore per gestire l'archiviazione e le prestazioni. Se il sistema di archiviazione lo supporta, prendi in considerazione l'utilizzo di timestamp di scadenza per i dati (spesso noti come valori di time-to-live, o TTL). La probabilità di riutilizzo dei token di idempotenza diminuisce nel tempo.

    Le comuni opzioni di archiviazione AWS genericamente utilizzate per memorizzare i token di idempotenza e il relativo stato includono:

    • Amazon DynamoDB: DynamoDB è un servizio di database NoSQL che offre prestazioni a bassa latenza ed elevata disponibilità, il che lo rende adatto all'archiviazione di dati correlati all'idempotenza. Il modello di dati chiave-valore e documento di DynamoDB consente di memorizzare e recuperare in modo efficiente i token di idempotenza e le informazioni di stato associate. DynamoDB può anche far scadere automaticamente i token di idempotenza se l'applicazione imposta un valore TTL al momento dell'inserimento.

    • Amazon ElastiCache: ElastiCache è in grado di archiviare token di idempotenza con un elevato throughput, bassa latenza e a costo ridotto. ElastiCache (Redis) e ElastiCache (Memcached) possono entrambi far scadere automaticamente i token di idempotenza se l'applicazione imposta un valore TTL al momento dell'inserimento.

    • Amazon Relational Database Service (RDS): puoi utilizzare Amazon RDS per archiviare i token di idempotenza e le informazioni di stato correlate, soprattutto se l'applicazione utilizza già un database relazionale per altri scopi.

    • Amazon Simple Storage Service (S3): Amazon S3 è un servizio di archiviazione di oggetti altamente scalabile e durevole che può essere utilizzato per archiviare i token di idempotenza e i metadati correlati. Le funzionalità di controllo delle versioni di S3 possono essere particolarmente utili per il mantenimento dello stato di operazioni idempotenti. La scelta del servizio di archiviazione dipende in genere da fattori quali il volume dei dati correlati all'idempotenza, le caratteristiche di prestazione richieste, l'esigenza di durabilità e disponibilità e il modo in cui il meccanismo di idempotenza si integra con l'architettura complessiva del carico di lavoro.

  4. Implementa operazioni idempotenti

    Progetta l'API e i componenti del carico di lavoro in modo che siano idempotenti. Incorpora i controlli di idempotenza nei componenti del carico di lavoro. Prima di elaborare una richiesta o eseguire un'operazione, controlla se l'identificatore univoco è già stato elaborato. In caso affermativo, restituisci il risultato precedente invece di eseguire nuovamente l'operazione. Ad esempio, se un client invia una richiesta per creare un utente, verifica se esiste già un utente con lo stesso identificatore univoco. Se l'utente esiste, deve restituire le informazioni utente esistenti anziché crearne una nuovo. Allo stesso modo, se un consumatore di code riceve un messaggio con un token di idempotenza duplicato, deve ignorare il messaggio.

    Crea suite di test complete che convalidino l'idempotenza delle richieste. Devono coprire un'ampia gamma di scenari, come richieste andate a buon fine, richieste non riuscite e richieste duplicate.

    Se il carico di lavoro sfrutta le funzioni AWS Lambda, prendi in considerazione Powertools per AWS Lambda. Powertools per AWS Lambda è un kit di strumenti per sviluppatori che aiuta a implementare le best practice serverless e ad aumentare la velocità di sviluppo quando si lavora con le funzioni AWS Lambda Lambda. In particolare, fornisce un'utilità per convertire le funzioni Lambda in operazioni idempotenti, sicure per riprovare.

  5. Comunica chiaramente l'idempotenza

    Documenta l'API e i componenti del carico di lavoro per comunicare chiaramente la natura idempotente delle operazioni. Questo aiuta i clienti a comprendere il comportamento previsto e a capire come interagire con il carico di lavoro in modo affidabile.

  6. Monitora ed esegui audit

    Implementa meccanismi di monitoraggio e audit per rilevare eventuali problemi correlati all'idempotenza delle risposte, come variazioni impreviste delle risposte o gestione eccessiva di richieste duplicate. Questo può aiutare a rilevare e indagare su eventuali problemi o comportamenti imprevisti nel carico di lavoro.

Risorse

Best practice correlate:

Documenti correlati:

Video correlati:

Strumenti correlati: