O que é um UUID? v4 vs v7 e quando usar cada um

Um UUID é um ID único que pode criar em qualquer lado, sem consultar um servidor. Veja como funcionam as versões 4 e 7 e qual serve melhor o seu projeto.

Desenvolvimento 6 min de leitura

Mais cedo ou mais tarde, toda a aplicação precisa de identificadores únicos para utilizadores, encomendas, ficheiros ou eventos. Um contador funciona até haver mais do que uma base de dados, um cliente offline ou uma API pública que não deve revelar quantos registos existem. É aqui que entram os UUID.

Neste guia vai aprender o que é um UUID, como a versão 4 (aleatória) difere da versão 7 (ordenada por tempo), porque é que a v7 costuma ser a melhor escolha para chaves primárias e como evitar os erros mais comuns.

Gere UUID agora Crie um ou vários UUID no seu browser. Nada é enviado para um servidor. Abrir o gerador de UUID

O que é um UUID (ou GUID)?

Um UUID (Universally Unique Identifier, ou identificador único universal), também chamado GUID no mundo Microsoft, é um valor de 128 bits usado para identificar algo. Normalmente escreve-se como 32 dígitos hexadecimais separados por hífenes em cinco grupos, no padrão 8-4-4-4-12, o que dá 36 caracteres no total.

Exemplo: 018f4e2a-7c3b-7d4e-9a1b-2c3d4e5f6a7b. Um dígito indica a versão (o primeiro do terceiro grupo) e alguns bits marcam a variante; o resto transporta os dados propriamente ditos.

Porquê usar UUID?

  • Sem contador central: qualquer servidor, dispositivo ou browser cria um ID sozinho, sem pedir o número seguinte à base de dados.
  • Seguro em sistemas distribuídos: vários serviços, regiões ou clientes offline criam registos e juntam-nos depois sem conflitos.
  • Gerar antes de guardar: o cliente conhece o ID do novo registo antes de o servidor confirmar, o que simplifica aplicações offline e novas tentativas.
  • Não revela o número de registos: um ID como 1042 mostra a estranhos quantos registos existem e facilita adivinhar os vizinhos. Um UUID não.

UUID v4: totalmente aleatório

A versão 4 é a mais comum. Além dos poucos bits que marcam versão e variante, todos os restantes 122 bits são aleatórios. Não há ordem, nem data, nem informação sobre a máquina que o gerou.

Isto torna a v4 simples, amplamente suportada e uma boa opção por omissão para uso geral, sobretudo quando não quer que o ID revele quando algo foi criado.

UUID v7: ordenado por tempo e aleatório

A versão 7 foi normalizada na RFC 9562 (2024), que atualizou a especificação antiga de UUID. Os primeiros 48 bits guardam um timestamp Unix em milissegundos e a maior parte dos bits restantes é aleatória.

Como o timestamp vem primeiro, os valores v7 ordenam-se pela data de criação: um UUID criado depois é maior do que um criado antes (com precisão ao milissegundo). E continua a gerá-los sem qualquer coordenação central.

Em resumo: a v4 é toda aleatória; a v7 é "timestamp primeiro, aleatório depois".

Porque é que a v7 é melhor para chaves primárias

A maioria das bases de dados guarda a chave primária num índice ordenado por valor. Com chaves v4 aleatórias, cada nova linha cai num ponto qualquer do índice, o que provoca divisões de página, mais fragmentação, pior aproveitamento da cache e inserções mais lentas em tabelas grandes.

Com a v7, as novas chaves ficam sempre perto do fim do índice, tal como um número auto-incremento. Mantém as vantagens do UUID e ganha muito mais localidade no índice. As listagens dos mais recentes e as consultas por intervalo de tempo também ficam mais fáceis.

A contrapartida: uma v7 revela aproximadamente quando o registo foi criado. Se isso for sensível, use v4 ou não exponha o UUID em URL públicos.

Outras versões, em resumo

  • v1: formada por timestamp mais um identificador de nó, historicamente o endereço MAC. Pode revelar informação da máquina e hoje raramente é recomendada.
  • v5: baseada em nome. Aplica SHA-1 a um namespace e a um nome, pelo que a mesma entrada dá sempre o mesmo UUID. Útil para IDs determinísticos.
  • A v3 é a mesma ideia da v5, mas com MD5, e a v6 é uma v1 reordenada. Em projetos novos vai normalmente escolher v4 ou v7.

Dois UUID podem colidir?

Em teoria sim; na prática, a probabilidade é desprezável. Com 122 bits aleatórios numa v4, seria preciso gerar uma quantidade enorme de IDs para um duplicado ser minimamente provável, muito mais do que quase qualquer sistema vai criar.

Isto pressupõe uma boa fonte de aleatoriedade. Use o gerador aleatório seguro da sua plataforma, não um feito em casa. Se a unicidade for crítica, mantenha de qualquer forma uma restrição única na coluna.

UUID vs auto-incremento

  • O auto-incremento é pequeno (4 ou 8 bytes), rápido, legível e perfeito para uma única base de dados. Mas precisa de uma autoridade que distribua os números e expõe volume e ordem.
  • Os UUID ocupam 16 bytes, são mais difíceis de ler e escrever e tornam os índices maiores. Em troca, funcionam entre sistemas e não são adivinháveis.
  • Um meio-termo comum é uma chave auto-incremento interna mais um UUID como identificador público. Outro é simplesmente usar v7 como chave primária.

Como gerar UUID com a ferramenta gratuita

  1. Abra o gerador de UUID. Funciona inteiramente no seu browser, por isso nada é enviado para um servidor.
  2. Escolha a versão de que precisa (v4 ou v7) e quantos UUID criar.
  3. Gere e copie um ou a lista inteira para o seu código, seed da base de dados ou dados de teste.

Erros comuns a evitar

  • Usar um UUID como segredo ou token de acesso. Um UUID é um identificador, não uma credencial. A v7 é parcialmente previsível por causa do timestamp e nem a v4 foi pensada para autenticação. Para isso, use um token aleatório adequado.
  • Confiar no UUID no URL como único controlo de acesso. Verifique sempre as permissões.
  • Guardar UUID como texto de 36 caracteres quando a base de dados tem tipo nativo (como UUID no PostgreSQL) ou coluna binária de 16 bytes. Desperdiça espaço e torna os índices mais lentos.
  • Misturar v4 e v7 na mesma coluna à espera de ordem por tempo.
  • Criar o seu próprio gerador com Math.random() ou outra aleatoriedade fraca.

Conclusão

Um UUID dá-lhe IDs únicos sem contador central. Use v7 quando o ID for chave primária de base de dados e a ordem por tempo ajudar, use v4 quando quiser aleatoriedade pura e sem data de criação, e nunca trate nenhum dos dois como segredo. Guarde-os em coluna nativa ou binária e gere-os com a nossa ferramenta gratuita sempre que precisar.

Perguntas frequentes

Qual é a diferença entre UUID e GUID?

São a mesma coisa. GUID é o nome usado sobretudo em ambientes Microsoft; UUID é o nome padrão. Ambos são identificadores de 128 bits.

Devo usar UUID v4 ou v7?

Use v7 para chaves primárias de base de dados e sempre que ordenar por criação ajude. Use v4 para uso geral ou quando não quiser que o ID revele quando foi criado.

Um UUID é seguro como palavra-passe ou token?

Não. Um UUID serve para identificar, não para proteger. Para tokens de sessão, chaves de API ou recuperação de palavra-passe, use um token longo de um gerador aleatório criptograficamente seguro.

Os UUID podem colidir?

Na prática a probabilidade é desprezável quando são gerados com boa aleatoriedade. Mantenha uma restrição de unicidade na base de dados como garantia extra.

O gerador de UUID envia os meus IDs para um servidor?

Não. Os UUID são criados localmente no seu browser e não são enviados nem armazenados em lado nenhum.

Ferramentas gratuitas referidas neste artigo

Continue a ler

Todos os artigos