UUID parece um identificador sem manutenção: gerar, salvar e expor. Os problemas aparecem ao redor dele. Uma coluna textual permissiva, um índice inadequado, um validator limitado, um retry que gera novo valor ou uma API que trata o ID como segredo transformam uma solução de coordenação em dívida. O formato não elimina engenharia de dados.
Texto arbitrário perde garantias
Uma coluna longa aceita espaços, caixa inconsistente e strings que apenas parecem UUID. Também aumenta índices. Tipo nativo ou binário fixo oferece representação compacta e validação estrutural.
Se texto é necessário, imponha formato canônico e comprimento. Normalize na fronteira, não depois que várias formas já estão armazenadas.
Primary key aleatória afeta escrita
UUID v4 insere em pontos diferentes de um índice ordenado. Em workload intenso, isso aumenta fragmentação e I/O. Não significa que v4 seja sempre lento, mas o efeito precisa ser medido.
v7, chave interna sequencial ou outra estratégia de índice podem melhorar. Use query plans e dados reais.
Regex casual não é validator completo
Verificar grupos hexadecimais não garante variant e version. Um validator que aceita só v4 pode rejeitar v7 legítimo. Defina policy e use biblioteca UUID.
Não tente reparar automaticamente hífens ou texto extra. Rejeitar força o produtor a corrigir o contrato e evita apontar para outro recurso.
UUID não substitui autorização
IDs vazam em logs e links. Um endpoint que entrega recurso apenas para quem conhece o UUID depende de obscurity. Verifique usuário, tenant e ação em toda request.
Capability links devem usar token separado e revogável. Identidade e credencial possuem lifecycles diferentes.
Retries podem duplicar o negócio
Gerar novo UUID a cada tentativa cria várias linhas para a mesma operação. Reuse o ID ou uma idempotency key. Unique constraint só impede repetir o mesmo valor, não a mesma intenção.
Jobs e imports também precisam de replay seguro. Um mapping persistente mantém identidade após falha.
IDs públicos e internos podem se misturar
Se a aplicação possui integer interno e UUID público, nomes e tipos devem ser claros. Expor o integer pode revelar sequência; usar UUID no lugar errado pode afetar joins.
DTOs, routes e serializers devem dizer qual ID esperam. Erros de mistura podem virar falhas de autorização.
Bulk endpoints precisam de limites
Mil UUIDs válidos ainda podem produzir uma consulta cara. Limite quantidade, valide cada item, verifique acesso e tenha índice adequado.
Respostas não devem revelar quais recursos existem para quem não possui permissão. A política de erro faz parte da segurança.
Schema precisa alinhar foreign keys
Primary UUID binário e foreign UUID textual complicam constraints e joins. Revise tipo, collation e ordem dos bytes em todas as tabelas.
Exports devem declarar a representação. Parceiros não deveriam adivinhar se recebem canonical text ou hex compacto.
Serialização precisa preservar o valor
JSON usa string. Queues, caches e logs não devem truncar, converter em número ou mudar formato sem policy. O ID é opaco para consumidores.
Ferramentas de suporte podem adicionar contexto, mas precisam permitir copiar o valor integral e buscar exatamente.
Erros de API precisam ser consistentes
Malformed UUID deve falhar antes da consulta. Recurso ausente e proibido podem ter resposta externa semelhante para evitar enumeration, enquanto logs internos preservam a causa.
Métricas de valores rejeitados apontam clientes quebrados e tentativas automatizadas. Não espere uma colisão para investigar o gerador.
Operações em lote precisam preservar autorização
Não basta validar a lista e executar uma query where in. Cada recurso precisa estar no tenant correto e dentro da permissão do caller. A resposta também deve evitar revelar quais IDs pertencem a outros usuários.
Limites de quantidade, paginação e queries indexadas evitam que uma lista válida se torne um ataque de custo.
Cleanup não deve “consertar” identidade
Remover caracteres extras ou completar um UUID truncado pode transformar input inválido em outro identificador válido. Rejeite e faça o produtor corrigir. Identidade deve ser exata, não interpretada.
Se dados antigos possuem formas não canônicas, migre com mapping auditável em vez de aplicar heurísticas durante requests.
Erros raros merecem alerta específico
Uma collision real é improvável, mas duplicate-key pode indicar generator substituído, estado clonado ou retry mal implementado. Registre versão, biblioteca, host e request ID para investigar a origem.
Imports precisam de um mapping durável
Ao consolidar sistemas, gerar um UUID novo a cada execução quebra referências e torna o retry não determinístico. Uma tabela de correspondência entre origem, identificador externo e UUID interno preserva a identidade durante reprocessamento.
Esse mapping também permite auditar conflitos, desfazer lotes e explicar ao suporte por que dois sistemas mostram chaves diferentes para o mesmo recurso.
Governança evita convenções divergentes
Todos os serviços precisam concordar sobre quem gera, qual versão usa, quando o ID se torna permanente e quais versões são aceitas. Independência de geração não significa ausência de padrão.
UUID funciona bem com storage compacto, índices medidos, validação, idempotência e autorização explícita. O identificador resolve allocation; o restante continua sendo design de sistema.