Simple Message Queue (formerly MNS):Idempotência de consumo

O que é idempotência de consumo?

Uma operação é considerada idempotente quando sua execução múltiplas vezes produz o mesmo resultado de uma única execução. Em filas de mensagens, exceções de rede ou falhas no sistema podem causar a entrega duplicada da mesma mensagem. O consumo idempotente assegura que a lógica de negócios execute apenas uma vez, mesmo diante de entregas repetidas, evitando operações duplicadas como cobrar um cliente duas vezes.

Exemplo: Um consumidor recebe uma mensagem de débito de pagamento referente a um pedido no valor de USD 100. Devido a exceções de rede ou falhas sistêmicas, o SMQ reentrega a mensagem e o consumidor a recebe repetidamente. Com o consumo idempotente implementado, o pagamento é debitado somente uma vez e apenas um registro de débito é gravado, não importa quantas vezes a mensagem seja entregue.

Quando ocorre a entrega duplicada

O SMQ adota semântica de entrega at-least-once. Em sistemas distribuídos, qualquer um dos cenários abaixo pode resultar na entrega da mesma mensagem mais de uma vez:

• Tempo de processamento excede a duração de invisibilidade: Se o consumidor A levar mais tempo para processar uma mensagem do que o valor definido em InvisibleDuration, o SMQ considera que a mensagem não foi processada e a reentrega ao consumidor B. Assim, ambos os consumidores processam a mesma mensagem.

• Falha de rede após processamento bem-sucedido: Após o consumidor concluir o processamento de uma mensagem, uma falha de rede impede que a chamada DeleteMessage chegue ao SMQ. Quando a conexão é restaurada, o SMQ reentrega a mensagem porque ela nunca foi excluída.

• Reinicialização do broker ou do consumidor: Caso um broker ou consumidor seja reiniciado depois de processar uma mensagem, mas antes da conclusão de DeleteMessage, o SMQ pode reentregar a mensagem assim que a duração de invisibilidade expirar.

Implemente o consumo idempotente

Escolha uma chave de idempotência

Não utilize o ID da mensagem como chave de idempotência. Mensagens com IDs diferentes podem conter o mesmo conteúdo e, quando um cliente retransmite uma mensagem, essa retransmissão pode receber um novo ID. Depender dos IDs das mensagens faria com que sua lógica de deduplicação não detectasse as entregas duplicadas que deveria evitar.

Em vez disso, derive a chave de idempotência de um atributo de negócio estável que identifique a operação de forma única. Por exemplo:

• Pagamento de pedido: {orderId}/{operationType}, como order-9527/payment

• Atualize o estoque: {itemSku}/{warehouseId}/{batchId}

A chave deve permanecer igual em todas as entregas da mesma mensagem lógica e ser diferente para operações realmente distintas.

Padrões de deduplicação

Escolha um ou mais dos padrões a seguir conforme a arquitetura do seu sistema:

• Rastreamento por identificador único: Atribua um identificador exclusivo a cada mensagem. Ao entregar uma mensagem ao consumidor, registre esse identificador. Essa prática ajuda a garantir que o mesmo consumidor não processe a mensagem novamente.

• Restrição de unicidade no banco de dados: Adicione uma restrição de unicidade na coluna da chave de idempotência no banco de dados. Quando uma mensagem duplicada chegar e o código tentar inserir a mesma chave, o banco rejeitará a inserção com uma violação de restrição. Capture esse erro e trate-o como uma operação nula bem-sucedida. Para evitar condições de corrida entre a verificação e a inserção, envolva ambas em uma única transação ou utilize uma operação de upsert.

• Verificação de estado do negócio: Antes de executar qualquer lógica, consulte o estado atual da mensagem. Verifique se ela já existe ou se já foi processada. Nesse caso, ignore o processamento e retorne imediatamente. Esse padrão funciona bem quando as operações de negócio são naturalmente orientadas por estado.

• Mesclagem de operações: Para operações comutativas ou acumulativas, projete a operação de modo que aplicá-la várias vezes produza o mesmo resultado de aplicá-la uma única vez — por exemplo, usando SET balance = X em vez de SET balance = balance - Y.