Um Guia Prático para Gerar UUIDs em JavaScript

Introdução

Precisa de um identificador único para sua aplicação JavaScript? Seja construindo uma aplicação orientada a banco de dados, gerenciando sessões de usuário ou rastreando requisições distribuídas, a geração de UUID é uma habilidade fundamental que todo desenvolvedor precisa.

Este guia cobre as abordagens modernas para geração de UUID em JavaScript, desde o método nativo crypto.randomUUID() até o versátil pacote npm uuid. Você aprenderá qual método se adequa ao seu caso de uso específico—seja uma aplicação web de ponta, um serviço Node.js ou um sistema legado que requer ampla compatibilidade.

O que é um UUID e Por que Usá-lo?

Um UUID (Universally Unique Identifier - Identificador Universalmente Único) é um identificador de 128 bits formatado como 36 caracteres: 550e8400-e29b-41d4-a716-446655440000. Também conhecidos como GUIDs, esses identificadores são praticamente garantidos de serem únicos sem exigir uma autoridade central ou coordenação de banco de dados.

Para desenvolvedores frontend e Node.js, UUIDs resolvem problemas críticos:

• Registros de banco de dados: Gerar chaves primárias sem conflitos de auto-incremento
• Tokens de sessão: Criar identificadores de sessão únicos e imprevisíveis
• Nomenclatura de arquivos: Prevenir colisões de nomes em conteúdo enviado
• Rastreamento de requisições: Rastrear operações através de microsserviços

Método Moderno: crypto.randomUUID()

O método crypto.randomUUID() é o padrão atual para gerar valores de ID únicos em ambientes modernos. Ele está integrado nos navegadores e Node.js (14.17+), não requer dependências e produz valores UUID v4 criptograficamente seguros.

Implementação no Navegador

const uuid = crypto.randomUUID();
console.log(uuid); // "3b99e3e0-7598-4bf8-b9c1-e915af91713c"

Implementação no Node.js

import { randomUUID } from 'crypto';

const uuid = randomUUID();
console.log(uuid); // "b7e44f0a-811f-4c1c-b7f0-48d51f5dbc1f"

Suporte de Navegadores: Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+
Suporte Node.js: Versão 14.17.0+

Use crypto.randomUUID() quando precisar de UUIDs seguros e aleatórios em aplicações modernas sem dependências externas.

Método Alternativo: crypto.getRandomValues()

Para ambientes que não suportam crypto.randomUUID(), você pode implementar a geração de UUID v4 usando crypto.getRandomValues(). Este método funciona em navegadores tão antigos quanto Chrome 11 e versões do Node.js com o módulo crypto.

function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = crypto.getRandomValues(new Uint8Array(1))[0];
    const v = c === 'x' ? (r & 0x0f) : ((r & 0x03) | 0x08);
    return v.toString(16);
  });
}

const uuid = generateUUID();
console.log(uuid); // "42254574-affd-47cc-9915-0ecae592351b"

Esta abordagem mantém a segurança criptográfica enquanto suporta ambientes mais antigos.

O Pacote npm uuid para Máxima Flexibilidade

O pacote npm uuid permanece como a solução mais versátil para geração de UUID em JavaScript, especialmente quando você precisa de versões específicas de UUID ou máxima compatibilidade.

Instalação

npm install uuid

Uso Básico (UUID v4)

import { v4 as uuidv4 } from 'uuid';

const uuid = uuidv4();
console.log(uuid); // "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"

Outras Versões de UUID

import { v1, v3, v5 } from 'uuid';

// v1: Baseado em timestamp (ordenável)
const uuid1 = v1(); 

// v3/v5: Baseado em nome (determinístico)
const uuid5 = v5('hello.example.com', v5.DNS);

O pacote uuid suporta todas as versões de UUID (v1-v5), tornando-o ideal quando você precisa de:

• UUIDs baseados em timestamp para identificadores ordenáveis (v1)
• UUIDs determinísticos a partir de pares namespace/nome (v3, v5)
• Retrocompatibilidade com versões mais antigas do Node.js
• React Native ou outros ambientes não-padrão

Quando Evitar Math.random()

Embora você possa encontrar implementações de UUID usando Math.random(), estas devem ser usadas apenas para testes ou contextos não-seguros:

// ⚠️ NÃO SEGURO - Apenas para testes
function testUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = Math.random() * 16 | 0;
    const v = c === 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

Math.random() carece de segurança criptográfica e não deve ser usado para UUIDs em produção.

Melhores Práticas e Validação

Validação de UUID

Sempre valide UUIDs de fontes externas:

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

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

Escolhendo o Método Correto

• Aplicação web moderna ou Node.js 14.17+: Use crypto.randomUUID()
• Suporte a navegadores legados necessário: Implemente com crypto.getRandomValues()
• Versões específicas de UUID (v1, v3, v5): Use o pacote npm uuid
• Máxima compatibilidade: Use o pacote npm uuid
• Apenas testes rápidos/protótipos: Implementação com Math.random()

Conclusão

A geração de UUID em JavaScript não precisa ser complexa. Para a maioria das aplicações modernas, crypto.randomUUID() fornece uma solução simples e segura. Quando você precisa de compatibilidade mais ampla ou versões específicas de UUID, o pacote npm uuid tem tudo coberto. Apenas lembre-se de evitar Math.random() para uso em produção e validar quaisquer UUIDs de fontes externas.

Escolha o método que corresponde ao seu ambiente e requisitos—seu eu futuro (e sua equipe) agradecerão pelos identificadores únicos limpos e confiáveis em toda a sua base de código.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.