DEV Community

Wesley Martins Brito
Wesley Martins Brito

Posted on

Idempotência: Como evitar que a instabilidade da rede duplique suas transações

Quando desenvolvemos sistemas, precisamos considerar que nem sempre as operações serão executadas apenas uma vez. Falhas de conexão, novas tentativas de requisições e mensagens duplicadas são situações comuns.

Mas como garantir que essas repetições não causem problemas?

Uma das respostas para isso é a idempotência. Na prática, ela é um dos conceitos mais importantes na construção de sistemas distribuídos, APIs resilientes e processamento de pagamentos.

Essa propriedade garante que, independentemente da quantidade de vezes que uma mesma operação seja executada, o resultado final seja o mesmo de quando ela foi executada pela primeira vez com sucesso.

Em HTTP, métodos como GET, PUT e DELETE são considerados idempotentes. Isso significa que, independentemente da quantidade de vezes que forem executados, o efeito produzido será o mesmo. Já o POST, por padrão, não possui essa característica e pode criar novos recursos a cada execução, gerando duplicidades indesejadas.

O cenário real do "Duplo Clique"

Imagine um usuário que está finalizando uma transferência pelo internet banking. Ele clica em confirmar, mas, devido a uma oscilação na conexão com a internet, não recebe uma resposta do servidor. Sem saber se a operação foi concluída, ele tenta novamente.

Se o sistema não estiver preparado para lidar com esse cenário, poderá realizar a mesma transferência mais de uma vez. Essa é uma situação muito grave, principalmente quando estamos falando de operações financeiras.

Um sistema precisa garantir que, independentemente da quantidade de tentativas, uma mesma operação não produza efeitos duplicados.

Outros exemplos comuns:

  • Scripts de deploy: executar um script várias vezes não deve criar novos servidores caso eles já existam.
  • Processamento de pagamentos: evitar cobranças duplicadas quando o cliente ou o próprio sistema realiza uma nova tentativa após um timeout de rede.

Como implementar a Idempotência na prática?

Existem algumas estratégias arquiteturais que ajudam a garantir a idempotência em um sistema:

  1. Constraints de Banco de Dados: utilização de chaves primárias ou índices UNIQUE para impedir a inserção de registros duplicados. Essa estratégia funciona como uma proteção adicional na camada de persistência.
  2. Idempotency Keys (Chaves de Idempotência): o cliente envia uma chave única na requisição (ex: no cabeçalho Idempotency-Key: 12345). O servidor armazena essa chave vinculada à operação e à resposta gerada. Se receber uma nova requisição com a mesma chave, identifica que aquela operação já foi processada e retorna a resposta anterior, sem executar a regra de negócio novamente.

Exemplo de implementação com Java e Spring Boot

No ecossistema Spring, uma das formas mais eficientes de implementar a validação de Idempotency Keys é utilizando um HandlerInterceptor em conjunto com o Redis para garantir atomicidade através de locks.

Veja um exemplo prático:

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import java.time.Duration;

@Component
public class IdempotencyInterceptor implements HandlerInterceptor {

    private final StringRedisTemplate redisTemplate;

    public IdempotencyInterceptor(StringRedisTemplate redisTemplate) {
        this.redisTemplate = redisTemplate;
    }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // Ignora métodos que já são naturalmente idempotentes
        if (request.getMethod().equals("GET") || request.getMethod().equals("OPTIONS")) {
            return true;
        }

        String idempotencyKey = request.getHeader("Idempotency-Key");

        if (idempotencyKey == null || idempotencyKey.isBlank()) {
            response.sendError(HttpServletResponse.SC_BAD_REQUEST, "O header Idempotency-Key é obrigatório.");
            return false;
        }

        String redisKey = "idempotency:" + idempotencyKey;

        // setIfAbsent garante atomicidade (SETNX no Redis). 
        // Se a chave já existir, retorna false e impede a concorrência.
        Boolean isNewRequest = redisTemplate.opsForValue()
                .setIfAbsent(redisKey, "PROCESSANDO", Duration.ofHours(24));

        if (Boolean.FALSE.equals(isNewRequest)) {
            response.sendError(HttpServletResponse.SC_CONFLICT, "Requisição duplicada detectada. Operação já processada ou em andamento.");
            return false;
        }

        return true;
    }
}
Enter fullscreen mode Exit fullscreen mode

Conclusão

Problemas sempre vão acontecer. Falhas na rede, mensagens duplicadas e usuários clicando várias vezes no mesmo botão são situações perfeitamente comuns no ambiente de produção.

A idempotência não impede que essas situações aconteçam, mas permite que o sistema lide com elas de forma segura, mantendo a consistência dos dados e evitando que uma mesma operação gere efeitos indesejados.

Construir sistemas considerando que a rede vai falhar é o que separa aplicações amadoras de aplicações verdadeiramente resilientes.


Sobre o autor:
Wesley Martins Brito é Desenvolvedor Full Stack atuando no desenvolvimento de sistemas corporativos e governamentais de alto impacto. Especialista no ecossistema Java (Spring Boot), com forte atuação no front-end utilizando Angular e Vue.js.

Top comments (0)