UUID: O Que É, Para Que Serve e Como Gerar em Qualquer Linguagem

Se você já trabalhou com bancos de dados, APIs ou microsserviços, provavelmente esbarrou em UUIDs. Esses identificadores universais aparecem em toda parte: IDs de usuários, tokens de sessão, nomes de arquivos, rastreamento de eventos e muito mais.

Neste guia, vamos explicar o que são, quando usá-los, as diferenças entre as versões e como gerar em diversas linguagens.

O Que É UUID?

UUID (Universally Unique Identifier), também chamado de GUID (no ecossistema Microsoft), é um identificador de 128 bits representado como uma string de 36 caracteres no formato:

550e8400-e29b-41d4-a716-446655440000

A especificação é definida pela RFC 4122 e garante que cada UUID gerado seja — na prática — único no universo, sem necessidade de coordenação centralizada.

UUID vs. Auto Increment: Quando Usar Cada Um?

Use UUID quando:

• Seu sistema é distribuído (microsserviços, multi-tenancy)
• Precisa gerar IDs no client-side antes de enviar ao servidor
• Segurança é importante (evitar enumeração de recursos)
• Faz merge de bancos de dados de diferentes fontes

Use auto-increment quando:

• Performance de leitura é crítica
• Sistema é centralizado (um único banco)
• Precisa de IDs legíveis por humanos

Versões de UUID: Qual Escolher?

UUID v1 — Baseado em Timestamp + MAC Address

Usa o horário atual e o endereço MAC da máquina. É sequencial no tempo, mas expõe informações de hardware. Raramente recomendado hoje em dia por questões de privacidade.

UUID v4 — Totalmente Aleatório

A versão mais popular. Usa 122 bits de dados aleatórios. Segura, simples e sem dependência de hardware. É a escolha padrão na maioria das aplicações.

// Exemplo de UUID v4
f47ac10b-58cc-4372-a567-0e02b2c3d479

UUID v7 — Timestamp + Aleatório (a melhor dos dois mundos)

Introduzida mais recentemente, a v7 combina um timestamp Unix em milissegundos com bits aleatórios. Resultado: UUIDs que são ordenáveis cronologicamente e ao mesmo tempo únicos — ideal para bancos de dados.

// UUID v7 mantém ordem cronológica
0190a6e2-7b3a-7f1c-8b5d-1c2d3e4f5a6b  (gerado primeiro)
0190a6e2-7b4f-7a2d-9c6e-2d3e4f5a6b7c  (gerado depois → maior)

Como Gerar UUID em Diferentes Linguagens

JavaScript / Node.js

// Nativo (Node.js 14.17+ e browsers modernos)
const uuid = crypto.randomUUID();
console.log(uuid);
// "f47ac10b-58cc-4372-a567-0e02b2c3d479"

// Com a biblioteca 'uuid'
import { v4 as uuidv4, v7 as uuidv7 } from 'uuid';

console.log(uuidv4()); // UUID v4
console.log(uuidv7()); // UUID v7 (ordenável)

Python

import uuid

# UUID v4 (aleatório)
print(uuid.uuid4())
# 550e8400-e29b-41d4-a716-446655440000

# UUID v1 (baseado em timestamp)
print(uuid.uuid1())

# Para UUID v7, use a lib 'uuid6'
# pip install uuid6
import uuid6
print(uuid6.uuid7())

Java

import java.util.UUID;

public class Main {
    public static void main(String[] args) {
        // UUID v4
        UUID uuid = UUID.randomUUID();
        System.out.println(uuid);
        // 550e8400-e29b-41d4-a716-446655440000
    }
}

Terminal (Linux/macOS)

# Gerar UUID v4
uuidgen

# Gerar vários de uma vez
for i in {1..5}; do uuidgen; done

UUID como Chave Primária no PostgreSQL

Usar UUID como PK é cada vez mais comum. Veja como configurar:

-- Habilitar extensão
CREATE EXTENSION IF NOT EXISTS "pgcrypto";

-- Criar tabela com UUID como chave primária
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Inserir sem especificar ID (gerado automaticamente)
INSERT INTO users (name, email) VALUES ('Maria', 'maria@email.com');

-- Para UUID v7 (PostgreSQL 17+)
-- SELECT uuidv7();

Validando um UUID

Para verificar se uma string é um UUID válido, use regex:

function isValidUUID(str) {
    const regex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
    return regex.test(str);
}

console.log(isValidUUID('550e8400-e29b-41d4-a716-446655440000')); // true
console.log(isValidUUID('not-a-uuid'));                            // false

Perguntas Frequentes

UUID e GUID são a mesma coisa?

Sim, tecnicamente. GUID é o termo usado pela Microsoft, enquanto UUID é o padrão da RFC 4122. A implementação é idêntica.

UUID é seguro para tokens de autenticação?

Não. Apesar de ser difícil de adivinhar, UUID não foi projetado para segurança criptográfica. Para tokens de sessão ou API keys, use geradores criptográficos como crypto.randomBytes() ou secrets.token_hex().

Posso usar UUID em URLs?

Sim, é uma prática comum: /api/users/550e8400-e29b-41d4-a716-446655440000. É melhor que IDs sequenciais pois previne enumeração de recursos (IDOR).