Neste artigo, vamos entender:

• Por que unicidade não é o único requisito de um ID
• As limitações de IDs sequenciais e UUIDs em sistemas distribuídos
• O que são Snowflake IDs e como eles funcionam
• Por que grandes APIs adotam esse modelo
• Quando essa estratégia faz sentido (e quando não faz)

Unicidade é só o requisito mínimo

Quando falamos em identificadores, quase todo mundo concorda em um ponto:

Um ID precisa ser único.

Mas em sistemas reais, distribuídos e em produção, isso está longe de ser suficiente.

Em APIs modernas, bons identificadores também precisam:

• Ser gerados sem coordenação central
• Funcionar bem com múltiplas instâncias
• Não virar gargalo de performance
• Permitir paralelismo
• Não vazar informações sensíveis do negócio
• Ajudar (e não atrapalhar) observabilidade e operação

Ou seja: unicidade é o requisito mínimo, não o objetivo final.

O problema dos sistemas distribuídos

Em arquiteturas distribuídas lidamos com:

• Auto scaling
• Múltiplos serviços
• Concorrência real
• Execução paralela
• Múltiplas regiões
• Infraestrutura dinâmica

Nesse cenário, deixar a geração de IDs:

• centralizada no banco
• dependente de sequência
• ou altamente acoplada a um único ponto

é pedir para criar gargalos.

IDs sequenciais funcionam muito bem… até deixarem de funcionar.

UUIDs resolvem tudo? Mais ou menos

UUIDs (ou GUIDs) são extremamente populares — e com bons motivos.

Eles oferecem:

• Unicidade global
• Geração totalmente descentralizada
• Suporte nativo em praticamente todas as linguagens
• Facilidade para geração no frontend, backend ou offline

Isso os torna uma excelente escolha para:

• Integrações externas
• Sistemas sem controle rígido de infraestrutura
• Sincronizações offline
• Casos onde flexibilidade é mais importante que controle

Mas essa flexibilidade vem com um custo.

UUIDs:

• Não carregam significado operacional
• São ruins para ordenação temporal (especialmente V4)
• Geram índices grandes (128 bits)
• Podem degradar performance em tabelas massivas
• Não ajudam na observabilidade

Em muitos casos, unicidade global não é tudo o que o negócio precisa.

Quando você quer mais controle que o UUID oferece

Agora imagine que você queira:

• Saber quando um registro foi criado apenas olhando o ID
• Garantir ordenação temporal forte
• Evitar gargalo no banco
• Melhorar eficiência de índices
• Facilitar particionamento
• Ter previsibilidade operacional

É nesse ponto que entra o Snowflake ID.

O que é um Snowflake ID?

Snowflake IDs são identificadores numéricos de 64 bits, criados originalmente pelo Twitter por volta de 2010 para identificar tweets em um sistema altamente distribuído.

A ideia central não é apenas gerar um ID único, mas controlar como ele é gerado.

A estrutura clássica do Snowflake é:

• 1 bit: sempre zero (sinal)
• 41 bits: timestamp (baseado em uma época customizada)
• 10 bits: identificador do nó / instância
• 12 bits: sequência local naquele nó

Isso permite:

• Até 4.096 IDs por milissegundo por nó
• Milhões de IDs por segundo em escala horizontal
• Geração totalmente local, sem coordenação central

IDs que já nascem distribuídos

Uma característica fundamental do Snowflake é que:

cada nó é responsável por gerar seus próprios IDs.

Isso elimina:

• Locks globais
• Dependência do banco
• Gargalos de sequência
• Contenção em ambientes paralelos

O banco deixa de ser o “gerador de IDs” e passa a ser apenas um consumidor deles.

IDs que contam uma história

Um efeito colateral (positivo) dessa estrutura é que os Snowflake IDs são temporalmente ordenáveis.

Isso significa que:

• Você pode ordenar registros pelo ID
• Extrair data e hora de criação
• Identificar picos de tráfego
• Analisar padrões operacionais

Tudo isso sem metadados adicionais.

O próprio ID já carrega essas informações.

Por que grandes APIs usam Snowflakes?

Agora fica mais fácil entender por que grandes plataformas adotam esse modelo.

Entre os principais benefícios:

• Menor acoplamento ao banco de dados
• Melhor eficiência de índices (64 bits)
• Ordenação temporal natural
• Excelente suporte a particionamento
• Melhor observabilidade
• Geração previsível e controlada

No Instagram, por exemplo, os bits que representariam o nó físico são usados para identificar shards lógicos.
No Discord, esses bits são divididos entre worker e processo.

Ou seja: o conceito é o mesmo, mas a implementação se adapta à infraestrutura.

Os custos e riscos dessa estratégia

Snowflake IDs não são uma bala de prata.

Eles exigem:

• Configuração correta de infraestrutura
• Garantia absoluta de unicidade do ID do nó
• Disciplina arquitetural
• Sincronização de relógio (clock drift)
• Estratégia clara de deploy e autoscaling

Além disso:

• Snowflake não é um padrão formal
• Não existe uma RFC
• Cada implementação é uma variação

Isso traz flexibilidade, mas também responsabilidade.

Outro ponto importante:
Snowflakes vazam informação temporal.
Se isso for um problema para o seu negócio, essa estratégia pode não ser adequada.

Snowflake vs UUID: um resumo honesto

UUIDs

• Simples
• Amplamente suportados
• Flexíveis
• Ótimos para começar
• Pouco controle
• Pior performance em escala extrema

Snowflake IDs

• Controle explícito
• Excelente para sistemas distribuídos
• Melhores índices
• Ordenação temporal
• Mais complexidade
• Forte dependência da infraestrutura

Não existe “melhor ID universal”.
Existe o ID certo para o seu contexto.

Identificadores são decisão arquitetural

Talvez o ponto mais importante de todo esse artigo seja este:

A escolha do identificador não é detalhe de implementação.

Ela impacta:

• Escalabilidade
• Observabilidade
• Performance
• Segurança
• Evolução do sistema

Escolher entre ID sequencial, UUID ou Snowflake é escolher como seu sistema cresce, opera e se mantém.

E isso é, por definição, uma decisão arquitetural.

Conclusão

Grandes APIs não escolhem Snowflake IDs por moda ou acaso.

Elas escolhem porque:

• Precisam de controle
• Precisam de escala
• Precisam de previsibilidade
• Precisam operar sistemas distribuídos reais

UUIDs continuam sendo excelentes ferramentas.
Snowflakes são ferramentas mais especializadas.

Saber quando usar cada uma é o que separa uma decisão técnica de uma decisão arquitetural.

Se quiser, no próximo artigo a gente pode explorar:

• UUID V7 vs Snowflake
• NanoID, KSUID, ULID
• IDs naturais
• Estratégias híbridas
• Impacto direto em bancos relacionais

Se esse tema te fez repensar a forma como você cria IDs nas suas APIs, comenta lá no blog ou compartilha com o time.
Essa discussão vale muito a pena continuar.

The post Snowflake IDs: por que grandes APIs evitam UUIDs como identificadores públicos appeared first on essencia.dev.

Chamadas duplicadas vão acontecer.

Elas surgem por retry automático, timeout de rede, instabilidade de internet, falhas intermediárias, consumidores paralelos ou, simplesmente, pelo famoso “dedo nervoso” do usuário clicando várias vezes no mesmo botão.

E o problema não é a duplicação em si — o problema é o que o seu sistema faz quando ela acontece.

Neste artigo, vamos entender:

O que é idempotência (de verdade, sem buzzword)

Por que chamadas duplicadas são a regra, não a exceção

Exemplos reais de problemas causados por falta de idempotência

Estratégias para tratar duplicidade corretamente

Quando idempotência é obrigatória, desejável ou overengineering

O problema das chamadas duplicadas

Vamos começar com alguns exemplos comuns do mundo real.

1. Retry e timeout no frontend

Imagine um endpoint POST /pagamentos.

O fluxo é simples:

O cliente chama a API

O backend processa o pagamento

O banco é atualizado

O cliente recebe a resposta

Agora adicione uma variável muito comum: internet instável.

O pagamento é processado com sucesso, mas o cliente não recebe a resposta por causa de um timeout. O frontend, bem programado, aplica uma política de retry e dispara a mesma requisição novamente.

Resultado:

O sistema “funcionou”

Não houve erro técnico

Mas o usuário pode ser cobrado duas vezes

Tecnicamente resiliente. Arquiteturalmente frágil.

2. Confirmação de e-mail e tokens inválidos

Outro exemplo clássico: POST /usuarios/confirmar-email.

O usuário clica no botão para receber o token.
Clica de novo.
Clica de novo.
Clica de novo.

Cada clique gera um novo token, invalidando o anterior.

Resultado:

O usuário recebe vários e-mails

Nenhum token funciona

A experiência degrada

O suporte recebe chamados

Tudo isso porque o sistema assumiu que a chamada aconteceria uma única vez.

3. Geração de relatórios pesados

Agora imagine um endpoint que gera um relatório complexo:

Várias queries

Processamento pesado

Geração de PDF

Se múltiplas requisições iguais chegam ao mesmo tempo, você pode:

Saturar o banco

Travar o sistema

Gerar o mesmo relatório várias vezes desnecessariamente

O erro conceitual por trás de tudo isso

Esses exemplos têm algo em comum:

Assumem que a chamada acontece uma única vez

Geram efeitos colaterais indesejados quando isso não acontece

Em ambientes distribuídos, isso nunca é uma premissa válida.

É aqui que entra o conceito de idempotência.

O que é idempotência?

O termo vem da matemática, mais especificamente da álgebra abstrata.

Uma operação idempotente é aquela que:

não importa quantas vezes seja aplicada com as mesmas entradas, o resultado final é sempre o mesmo.

Exemplos do mundo real:

Botão de elevador

Botão de emergência

Botão de “parar” de uma máquina

A expectativa é simples:
apertar uma vez ou dez vezes produz o mesmo efeito.

Em APIs e backends, deveria ser exatamente assim.

Idempotência em sistemas

Aplicar idempotência significa garantir que:

Chamadas duplicadas não quebram o sistema

Efeitos colaterais não se repetem

O estado só muda quando realmente precisa mudar

Gerar um token?
Apenas uma vez dentro da regra definida.

Criar um pagamento?
Apenas uma vez para aquela transação.

Gerar um relatório?
Apenas uma vez para aquele conjunto de parâmetros.

Como identificar chamadas duplicadas?

Antes de tratar duplicidade, precisamos responder uma pergunta fundamental:

Como saber que duas chamadas são, de fato, a mesma operação?

Existem várias estratégias, mas duas são as mais comuns.

1. Identidade lógica (baseada no domínio)

Aqui, usamos dados do próprio negócio para garantir unicidade.

Exemplos:

E-mail

CPF

Data/hora

Tipo de operação

Estado atual

Exemplo prático:

Um token de confirmação só pode ser gerado a cada 5 minutos para o mesmo e-mail

Se uma nova requisição chega dentro desse intervalo, reutilizamos o token existente

Vantagens:

Simples de entender

Alinhada ao domínio

Pode usar índices únicos no banco

Pouca ou nenhuma mudança no payload

Desvantagens:

Regras precisam estar muito bem alinhadas entre sistemas

Mudanças exigem coordenação entre times

Acoplamento forte ao domínio

2. Chave de idempotência

Aqui, o cliente gera um identificador único e envia junto com a requisição.

Essa chave:

Identifica a operação

Independe dos dados de negócio

É armazenada no backend junto com o estado da operação

Fluxo típico:

O cliente gera uma chave

Envia a requisição com essa chave

O backend verifica se ela já existe

Decide se processa, reutiliza ou ignora

Vantagens:

Menos acoplamento ao domínio

Muito comum em APIs públicas e pagamentos

Excelente para retrys automáticos

Cuidados:

A chave precisa ser persistida

O cliente precisa armazená-la corretamente

Exige storage, locks e controle de estado

Quando idempotência é obrigatória?

Idempotência não é “nice to have” em alguns cenários — é requisito de negócio.

Ela é obrigatória quando:

Há efeitos colaterais relevantes

Envolve dinheiro, contratos ou confiança

O sistema é distribuído

Existe mensageria, filas, eventos e consumidores paralelos

Se repetir a operação causa prejuízo ou caos, idempotência é obrigatória.

Quando idempotência é desejável?

Ela é altamente recomendada quando:

Existe retry automático

O sistema lida com redes instáveis

O estado final não pode ser repetido

A operação representa uma transição de estado

Exemplos:

Confirmação de e-mail

Ativação de conta

Finalização de pedido

Cancelamento de assinatura

Quando idempotência pode ser overengineering?

Nem tudo precisa ser idempotente.

Alguns exemplos:

Operações somente leitura

Geração de logs

Métricas

Auditoria

Eventos que devem ser repetidos

Se:

O impacto da duplicação é baixo

O custo de implementação é alto

Não há identidade clara da operação

Talvez o risco seja aceitável.

Arquitetura também é saber onde não colocar complexidade.

E quanto ao REST?

De forma geral:

GET → naturalmente idempotente

PUT → geralmente idempotente

POST → geralmente não idempotente

Mas isso não é regra escrita em pedra.

Tudo depende:

Do domínio

Dos efeitos colaterais

Das garantias que seu sistema precisa oferecer

Conclusão

Chamadas duplicadas não são exceção.
Elas são a regra em sistemas reais.

Retry, timeout, instabilidade, falhas intermediárias e comportamento humano fazem parte do jogo.

Nosso papel como arquitetos e desenvolvedores é:

Antecipar esse cenário

Tratar duplicidade corretamente

Proteger o estado do sistema

Evitar efeitos colaterais indesejados

Idempotência é uma decisão de arquitetura, não um detalhe de implementação.

Ela tem custo.
Ela tem complexidade.
E exatamente por isso não deve ser aplicada cegamente.

Garantir idempotência é garantir que o estado do sistema só muda quando realmente precisa mudar.

The post Idempotência: como lidar corretamente com chamadas duplicadas em APIs e backends appeared first on essencia.dev.