Idempotência e Deduplicação

Uma operação é idempotente quando repetir a mesma operação pretendida produz o mesmo efeito pretendido que executá-la uma vez. Deduplicação é uma técnica de implementação: identificar uma entrega repetida e reutilizar ou rejeitar o resultado anterior. Nenhuma delas significa que haverá uma única requisição ou tentativa.

Defina a identidade lógica

Para um comando de API, uma chave gerada pelo cliente deve identificar uma operação lógica. O servidor normalmente armazena:

• chave e escopo do chamador ou tenant;
• fingerprint dos campos semanticamente relevantes;
• estado do processamento e resultado estável;
• criação e expiração.

Uma restrição de unicidade no banco deve arbitrar primeiras requisições concorrentes. Reutilizar a chave com outra requisição deve ser rejeitado.

CREATE TABLE idempotency_record (
    tenant_id       bigint       NOT NULL,
    operation_key   varchar(128) NOT NULL,
    request_hash    varchar(128) NOT NULL,
    status          varchar(24)  NOT NULL,
    response_body   text,
    created_at      timestamp    NOT NULL,
    PRIMARY KEY (tenant_id, operation_key)
);

A tabela é apenas um esboço. Defina a responsabilidade por registros deixados em andamento após falha, limites da resposta, retenção, privacidade e como uma duplicata em espera descobre o resultado final.

Mensagens e efeitos colaterais

Brokers frequentemente entregam pelo menos uma vez. O consumidor pode registrar o ID da mensagem na mesma transação local da alteração; a unicidade transforma a reentrega em no-op. Se chamar outro sistema, ele precisa de seu próprio limite de idempotência. Verificar e depois escrever sem proteção sofre corrida.

Idempotência é definida em um limite. Definir uma coluna para um valor solicitado costuma ser idempotente; incrementar saldo não é, salvo se o comando tiver identidade durável. E-mail, cobrança e publicação exigem análises separadas.

Relação com novas tentativas e outbox

Novas tentativas são mais seguras quando compartilham uma chave lógica. A outbox transacional torna atômicos o estado local e o registro do evento, mas o relay pode publicar duplicatas; os consumidores ainda precisam de idempotência ou deduplicação.

Teste duplicatas simultâneas, mesma chave com entrada diferente, falhas antes e depois do commit, expiração, reentrega e reconstrução. Não afirme efeitos exatamente uma vez sem definir todos os limites envolvidos.