Chamar uma função “generate UUID” parece encerrar a decisão, mas a versão determina propriedades importantes. Alguns UUIDs são aleatórios, outros carregam tempo e outros são derivados de um nome. A escolha afeta privacidade, performance de índice, interoperabilidade e capacidade de reproduzir um ID. A versão deve ser selecionada por requisitos, não apenas pelo default da biblioteca.

Version 4 é o default aleatório conhecido

UUID v4 usa a maior parte do espaço para randomness. Ele possui amplo suporte, não revela horário de criação e funciona bem quando vários produtores criam IDs sem coordenação.

Seu trade-off está nos índices ordenados. Inserções se espalham pela árvore. Em alta escrita, isso pode aumentar page splits. Em muitos sistemas, o impacto é pequeno e a simplicidade vence.

Version 7 melhora ordenação temporal

UUID v7 combina Unix timestamp com randomness em um layout ordenável. Novos IDs tendem a chegar perto no índice, melhorando locality. Ele também permite ordenar aproximadamente por criação.

O tempo embutido não substitui um campo de criação. Clocks podem divergir e vários IDs podem compartilhar o mesmo intervalo. Chronology crítica precisa de mecanismos próprios.

Version 1 possui implicações de privacidade

UUID v1 combina timestamp e identificador de nó. Ele foi útil historicamente, mas pode revelar quando e onde o ID foi produzido. Para recursos públicos, essa exposição pode ser indesejada.

Sistemas legados podem continuar aceitando v1 sem gerar novos valores. Migração não exige reescrever IDs antigos.

Versões baseadas em nome são determinísticas

v3 e v5 usam namespace e name para produzir sempre o mesmo UUID. Isso ajuda quando sistemas separados precisam derivar a mesma identidade sem lookup central.

Normalization é crítica. Caixa, whitespace e encoding mudam o resultado. A origem também pode ser sensível, e o determinismo pode revelar que dois registros compartilham o mesmo nome de base.

Não invente uma versão privada

Uma string com aparência de UUID e layout proprietário engana parsers e operadores. Se outro esquema de ID atende melhor, use-o com nome claro. Compatibilidade vale mais que aparência.

Geradores devem vir de bibliotecas mantidas. Timestamp, process ID e PRNG comum não formam um UUID seguro por conta própria.

Policy de entrada e saída são diferentes

Um serviço pode gerar v7, aceitar v4 e v7, e rejeitar outras versões. Outro pode aceitar qualquer UUID padrão. Documente o que é válido em sintaxe, o que é aceito e o que é gerado.

Mensagens distintas ajudam clientes: malformed UUID é diferente de unsupported version.

Compatibilidade externa precisa ser testada

SDKs e validadores antigos às vezes aceitam somente v4. Antes do rollout, teste bancos, gateways, analytics e parceiros. Um canary limitado mostra incompatibilidades antes de afetar todos os recursos.

Fixtures devem conter mistura de versões. Assim uma atualização de geração não quebra leitura histórica.

Privacidade depende de todo o endpoint

v4 esconde melhor o momento de criação; v7 revela aproximadamente o tempo. Mas o endpoint pode expor data, contagem ou relações de qualquer forma. A versão é apenas uma parte do threat model.

Para recursos internos, ordenação pode valer mais. Para links públicos sensíveis, randomness pode ser preferível. Autorizações continuam obrigatórias nos dois casos.

Migração não deve trocar IDs existentes

Ao mudar o gerador, novos registros usam a nova versão e antigos permanecem válidos. Reescrever primary keys e referências externas cria risco enorme.

Validators e clients precisam aceitar o período misto. Métricas de versões observadas ajudam a entender o catálogo real.

Benchmark precisa refletir o schema real

Velocidade de geração raramente é o gargalo. Meça insertions, índices, joins, replication e backup. O resultado depende de engine, page size e access pattern.

Avalie também operação humana: busca em logs, ordenação em dashboards e suporte. Performance de banco não é a única propriedade relevante.

Rollout gradual encontra validadores antigos

Antes de gerar v7 em toda a plataforma, ative em uma tabela ou serviço limitado. Observe erros de SDKs, gateways, analytics e parceiros. Um validator antigo pode rejeitar a nova versão mesmo que ela seja padrão.

O servidor deve continuar aceitando IDs históricos. O rollout muda o que é gerado, não a validade das referências já existentes.

Sortability não substitui um campo temporal

Um UUID ordenado ajuda index e listagens, mas o timestamp embutido vem do clock do produtor. Para auditoria, SLA ou ordem de eventos, mantenha created_at e mecanismos de sequência.

A propriedade temporal do ID é uma otimização. Ela não deve virar fonte de verdade do domínio.

O padrão deve ser compartilhado

Depois da escolha, documente biblioteca, versão e forma canônica. Serviços independentes podem gerar IDs sem coordenação, mas precisam concordar sobre as regras.

A melhor versão é a que atende privacidade, storage, compatibilidade e operação do sistema específico. Novidade por si só não é requisito.

Fixtures mistas evitam compatibilidade acidental

Testes de contratos devem incluir versões antigas e novas, caixa canônica, valores inválidos e IDs próximos aos limites temporais. Isso revela SDKs que aceitam apenas v4, serializers que alteram a string e bancos que ordenam bytes de forma inesperada.

A decisão termina com uma política verificável: quais versões são geradas, quais são aceitas e onde a informação temporal pode ser observada.