Gerador UUID v8 Customizado

UUID v8: o UUID customizável

O UUID versão 8 é o novo formato "custom" de UUID introduzido formalmente pela RFC 9562 em maio de 2024, a mesma RFC que padronizou v6 e v7. Ele reserva 122 bits do espaço de 128 bits para a aplicação definir como quiser, mantendo intactos o formato wire e todos os parsers das outras versões de UUID.

Bits fixos e bits livres

Apenas 6 bits são reservados: 4 bits para o nibble de versão (1000 = 8) na 13ª posição e 2 bits para a variante (10) na 17ª. Os outros 122 bits são totalmente seus — quase uma tela em branco dentro do formato de ID mais ubíquo do software.

xxxxxxxx-xxxx-8xxx-yxxx-xxxxxxxxxxxx
                  ^   ^
                  ver variant (10xx)

Layouts customizados úteis

• 48 bits timestamp + 14 bits tenant + 60 bits random — SaaS multi-tenant sharded, ordenável por tenant.
• 48 bits timestamp + 80 bits hash — IDs content-addressed em formato UUID, similar a hashes de objetos git.
• 32 bits type tag + 90 bits random — IDs autodescritivos onde o tipo é codificado no prefixo.
• Epoch customizado + node-id + contador — um ID estilo Snowflake vestido de UUID padrão.

v8 vs v7

O UUID v7 é o time-ordered padronizado e opinativo — 48 bits de milissegundos Unix seguidos de aleatoriedade. Use v7 quando quer ordenação sem pensar muito. O UUID v8 é para quando o v7 não cobre o seu domínio — quando você precisa embutir tenant id, shard, hash de conteúdo ou qualquer outro sinal específico de negócio. v7 é o default seguro; v8 é a válvula de escape.

Compatibilidade e suporte de parsers

Qualquer parser padrão de UUID aceita v8 — é apenas um UUID com nibble de versão diferente. O tipo uuid do PostgreSQL, consumidores de crypto.randomUUID() em JavaScript, UUID.fromString() em Java, uuid.UUID em Python — todos aceitam v8. O detalhe: a maioria das libs não gera v8 por padrão. Use uuidv8 (JS), a crate uuid em Rust, ou monte o layout de bits na mão.

Armadilhas e boas práticas

• Sempre inclua bits aleatórios — layouts v8 totalmente determinísticos colidem fácil.
• Documente o layout de bits no wiki de engenharia; senão ninguém vai conseguir decodificar.
• Versione o seu esquema — codifique uma versão de layout no primeiro nibble para poder evoluir sem quebrar IDs antigos.
• Cuidado com previsibilidade — se lógica de negócio vaza para o ID, um atacante pode enumerar.
• Não use v8 para tokens de segurança — use CSPRNG com no mínimo 128 bits de entropia.

Perguntas frequentes

Quando usar v8 em vez de v7? Quando você precisa customizar o layout — embutir tenant id, shard key, hash de conteúdo. Se só quer IDs aleatórios ordenáveis, v7 é mais simples e tem melhor suporte.

Qual o risco do v8? Um layout mal projetado quebra unicidade ou vaza informação. Com grande liberdade vem grande responsabilidade — projete com cuidado e sempre inclua bits aleatórios.

v8 é um formato UUID padrão? Sim — a RFC 9562 inclui v8 explicitamente, e qualquer parser UUID vai aceitar como UUID válido. O formato wire continua 128 bits em 8-4-4-4-12.

Posso usar v8 como chave primária? Sim, desde que o layout seja único e estável. Muitos times usam um layout v8 que imita o v7 mas adiciona uma tag de shard de 14-16 bits para particionamento.