Gerar UUID (v1, v4, v5, v7)
- Painel
- Documentação
- API
Porquê utilizar UUIDs?
Os UUID (Universally Unique Identifier) são identificadores únicos utilizados para garantir a unicidade em diferentes sistemas e bases de dados sem necessidade de coordenação central. São habitualmente utilizados em sistemas distribuídos e aplicações web para gerar identificadores únicos para os recursos.
Versões de UUID suportadas
Esta ferramenta suporta as seguintes versões de UUID:
- Versão 1: baseada no carimbo temporal e no endereço MAC.
- Versão 4: gerada de forma aleatória (a mais utilizada).
- Versão 5: baseada numa impressão SHA-1 de um namespace e de um nome (determinista: um mesmo par namespace + nome produzirá sempre o mesmo UUID).
- Versão 7: ordenada temporalmente, recomendada para chaves primárias de bases de dados modernas (ordenação lexicográfica = ordenação cronológica).
UUID v5: namespace e nome
Para gerar um UUID v5, deve escolher um namespace padrão e fornecer um nome:
- DNS: a utilizar quando o nome é um nome de domínio (por exemplo
cdrn.fr). - URL: a utilizar quando o nome é um URL (por exemplo
https://cdrn.fr/). - OID: a utilizar quando o nome é um identificador de objeto ISO.
- X500: a utilizar quando o nome é um nome distinto X.500.
Sendo a geração determinista, o UUID v5 é particularmente adequado para produzir identificadores reproduzíveis a partir de um dado estável.
Como gerar UUIDs
Na página inicial, pode gerar UUIDs selecionando a versão pretendida num menu pendente e clicando no botão de geração. Para a versão 5, preencha adicionalmente o namespace e o nome.
Assim que um UUID é gerado, aparece numa linha de resultado verde a indicar que foi gerado com sucesso. Se ocorrer um erro, uma linha vermelha apresenta a mensagem de erro correspondente.
Exemplos de código para utilizar os UUIDs gerados
Pode utilizar os UUIDs gerados nas suas aplicações integrando-os diretamente no seu código. Eis um exemplo em PHP:
<?php
use Ramsey\Uuid\Uuid;
// Générer un UUID v4 (aléatoire)
$uuidV4 = Uuid::uuid4();
// Générer un UUID v5 (déterministe à partir d'un namespace et d'un nom)
$uuidV5 = Uuid::uuid5(Uuid::NAMESPACE_DNS, 'cdrn.fr');
// Générer un UUID v7 (ordonnancé temporellement)
$uuidV7 = Uuid::uuid7();
echo "UUID v4 : " . $uuidV4->toString() . PHP_EOL;
echo "UUID v5 : " . $uuidV5->toString() . PHP_EOL;
echo "UUID v7 : " . $uuidV7->toString() . PHP_EOL;
?>
Validar e analisar UUIDs
Também pode validar e analisar UUIDs existentes para determinar a sua versão e validade. Eis um exemplo de código em PHP:
<?php
use Ramsey\Uuid\Uuid;
// Valider un UUID
$uuidString = '123e4567-e89b-12d3-a456-426614174000';
if (Uuid::isValid($uuidString)) {
$uuid = Uuid::fromString($uuidString);
echo "UUID valide de version : " . $uuid->getFields()->getVersion();
} else {
echo "UUID invalide";
}
?>
Perguntas frequentes
Qual a diferença entre UUID v1, v4, v5 e v7?
v1 combina um carimbo temporal e o endereço MAC da máquina, o que pode revelar informações sensíveis. v4 é puramente aleatório (122 bits de aleatório), é a versão mais utilizada. v5 é determinista: um mesmo par namespace + nome produz sempre o mesmo UUID graças a um hash SHA-1. v7 integra um timestamp em milissegundos no início do identificador, o que o torna ordenado cronologicamente e ideal para chaves primárias.
Qual a probabilidade de colisão de um UUID v4?
Um UUID v4 dispõe de 122 bits aleatórios, ou seja cerca de 5,3 × 10^36 valores possíveis. Para atingir 50 % de probabilidade de colisão (paradoxo dos aniversários), seria preciso gerar cerca de 2,7 × 10^18 UUIDs. Na prática, numa aplicação padrão, a probabilidade de colisão é negligenciável. É o que permite gerar identificadores no lado do cliente sem coordenação com um servidor central.
Porquê privilegiar UUID v7 para uma chave primária de base de dados?
Um UUID v4 inserido num índice B-tree provoca uma forte fragmentação: cada inserção cai numa posição aleatória, o que degrada o desempenho e o uso da cache. UUID v7 começa por um timestamp em milissegundos, portanto as novas linhas inserem-se sempre no final do índice. O desempenho de inserção aproxima-se então do de um BIGSERIAL, mantendo as vantagens de um identificador universal.
Para que servem os namespaces DNS, URL, OID e X500 do UUID v5?
Esses namespaces são UUIDs predefinidos na RFC 4122 que agem como prefixo contextual para a geração determinista. DNS utiliza-se com um nome de domínio, URL com um URL completo, OID com um identificador ISO de objeto, X500 com um nome distinto LDAP. Também pode definir o seu próprio namespace privado: um UUID v4 gerado uma vez para a sua aplicação, reutilizado como raiz determinista para todos os seus identificadores v5.
UUID ou autoincremento para identificadores em base?
O autoincremento continua muito eficiente para bases monolíticas e revela facilmente a sequência de escrita, o que pode ser indesejável no lado da API pública. Os UUIDs convêm melhor a arquiteturas distribuídas, à geração no lado do cliente, às fusões de bases, e à exposição pública de identificadores opacos. O compromisso ideal em 2026: UUID v7 em chave primária, que combina universalidade, opacidade razoável e bons desempenhos de índice.
Os UUIDs gerados transitam por um servidor terceiro?
A geração efetua-se no ambiente de cdrn.fr, sem chamada a um serviço externo. Para as versões puramente aleatórias (v4) ou temporais (v7), nenhuma informação sensível é necessária na entrada. Para a v5, o namespace e o nome que fornece servem unicamente para o cálculo SHA-1 local. Nenhum identificador gerado é registado, pode utilizar a ferramenta para produzir UUIDs destinados a contextos confidenciais.
Exemplo de pedido
curl -X POST https://cdrn.fr/api/v1/tools/uuid-generator/execute \
-H "Content-Type: application/json" \
-d '{"version":"uuid_version_1","quantity":3,"namespace":"namespace_dns","name":"..."}'
Esquema de entrada
| Campo | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
version |
choice (uuid_version_1, uuid_version_4, uuid_version_5, uuid_version_7) | ✓ | – |
quantity |
integer | ✓ | 3 |
namespace |
choice (namespace_dns, namespace_url, namespace_oid, namespace_x500) | – | – |
name |
string | – | – |
Pontos de acesso
GET https://cdrn.fr/api/v1/tools- lista todas as ferramentas disponíveisGET https://cdrn.fr/api/v1/tools/uuid-generator- obtém o esquema desta ferramentaPOST https://cdrn.fr/api/v1/tools/uuid-generator/execute- executa esta ferramenta com um payload JSON