Ferramentas para desenvolvedores · Gerador UUID
O que torna uma string UUID bem formada e o que um verificador não pode saber
· Como funciona
uuid criptografia APIs do navegador
Maiúsculas, colchetes, urna: prefixos e hifens ausentes aparecem na entrada real. Esta postagem define a forma canônica, mostra o que um validador tolerante deve aceitar e separa a boa formação da existência.
O 400 que deveria ter sido um 404 — quão desleixada a validação UUID produz erros confusos de API
Um endpoint API recebe um identificador de um cliente: {12345678-90AB-CDEF-1234-567890ABCDEF}. O código de validação verifica se corresponde a /[0-9a-f]{32}/ e o rejeita como inválido. O cliente recebe uma solicitação incorreta 400 onde se referia 404 Not Found. O identificador está bem formado – é um UUID válido em formato entre chaves – mas o validador é muito rígido. Por outro lado, um endpoint que aceita qualquer string hexadecimal de 32 caracteres (sem traços) aceitará 123456789012345678901234567890123456, analisará-o como válido e perderá o erro de digitação. RFC 9562 define a representação textual canônica, mas a entrada do mundo real chega em cinco formatos diferentes, e um validador que aceita apenas a forma canônica rejeitará 1 a 5 por cento da entrada bem intencionada.
A forma textual canônica - 32 dígitos hexadecimais minúsculos em 8-4-4-4-12, exatamente 36 caracteres, conforme o padrão especifica para saída
A forma textual canônica é composta por 32 dígitos hexadecimais minúsculos em cinco grupos separados por hífens: 8-4-4-4-12. Representado como 550e8400-e29b-41d4-a716-446655440000. O padrão exige letras minúsculas para saída; na entrada, a correspondência sem distinção entre maiúsculas e minúsculas é recomendada. Este formulário é inequívoco, analisa bytes da mesma maneira em todas as plataformas e é o que toda biblioteca UUID gera por padrão. Se você estiver gerando um novo UUID a partir de um CSPRNG, a forma canônica é o que você deve produzir e o que ToolAcre produz. A entrada do mundo real se desvia de maneiras previsíveis. Identificadores maiúsculos (550E8400-E29B-41D4-A716-446655440000) são comuns em sistemas que usam letras maiúsculas como padrão; eles representam os mesmos bytes e devem ser aceitos após a normalização para letras minúsculas.
Variantes que você encontrará na natureza - hexadecimal maiúsculo, {braces}, o prefixo urn:uuid: e formas sem hífen de caracteres 32, e que o padrão diz para aceitar
O formato entre chaves ({550e8400-e29b-41d4-a716-446655440000}) é a saída padrão do módulo uuid do Python e dos sistemas da Microsoft; remover as chaves fornece uma forma canônica válida. O prefixo URN (urn:uuid:550e8400-e29b-41d4-a716-446655440000) é definido por RFC 8141 para nomes de recursos uniformes; remover o esquema e o prefixo do identificador de remoção deixa a forma canônica. A forma sem hífen (550e8400e29b41d4a716446655440000) tem 32 dígitos hexadecimais sem estrutura; são bytes válidos, mas perde o agrupamento 8-4-4-4-12 que torna as versões e variantes legíveis. Todas essas variantes são mapeadas para o mesmo valor de 128 bits. A seção RFC 9562 3 afirma que na entrada, variantes maiúsculas SHOULD serão aceitas. Não proíbe outras variantes; diz que na saída, a forma canônica minúscula MUST deve ser usada.
Sanidade de versão e variante - se deve rejeitar um UUID cujo terceiro grupo começa com 0 ou cujo quarto grupo começa com f
Um validador bem formado deve: aceitar o formato canônico 8-4-4-4-12 em letras minúsculas ou maiúsculas; aceitar variantes braced e urn: removendo-as e validando o formulário principal; aceite strings hexadecimais de 32 dígitos sem hífen e formate-as como canônicas para comparação; rejeitar strings com o número errado de dígitos hexadecimais ou caracteres não hexadecimais. O erro mais comum é rejeitar entradas em maiúsculas ou entre colchetes porque o validador foi escrito à mão para corresponder apenas à forma canônica. Uma verificação de integridade da versão e variante pode detectar erros de digitação. Se o terceiro grupo começar com 0 ou 9, o UUID é inválido ou reservado; se o quarto grupo começar com e ou f, a variante não é RFC 9562.
Exemplo resolvido - seis strings candidatas passam por uma verificação rigorosa e uma branda, com os motivos pelos quais cada uma é aprovada ou reprovada
Um validador tolerante aceita esses valores; um validador estrito pode rejeitá-los. A verificação bem formada ToolAcre realiza validação estrita: confirma a forma canônica do caractere 36 com traços nos lugares certos, verifica dígitos hexadecimais em todas as posições e verifica se a versão e os bits variantes estão dentro do intervalo. Ele não verifica se UUID existe em seu banco de dados ou se foi gerado a partir de uma fonte criptograficamente segura; essas são verificações separadas feitas pela lógica do seu aplicativo. Bem formado não é o mesmo que real. Uma string UUID que é analisada corretamente de acordo com seu formato pode não identificar nenhuma linha em seu banco de dados.
Bem formado não é real - por que um UUID sintaticamente perfeito pode não existir em seus dados e por que o verificador nunca deve ser sua camada de autorização
UM UUID que está perfeitamente formado pode ter sido adivinhado ou copiado incorretamente. A validação do formato é a primeira porta; verificações de existência e verificações de autorização são o segundo e o terceiro. Executar uma pesquisa no banco de dados para cada entrada de formato inválido é um desperdício; rejeitar entradas com formato inválido antes das consultas ao banco de dados economiza tempo. O ToolAcre padrão de saídas do gerador 36UUIDs de caracteres; se você estiver construindo seu próprio validador, aceite variantes braced e urn: para corresponder à entrada do mundo real e rejeite strings que falhem nas regras básicas de forma antes de perguntar ao seu banco de dados. A implementação de um validador estrito requer expressões regulares e tratamento de casos extremos. A forma canônica é direta: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i (não diferencia maiúsculas de minúsculas). A forma entre colchetes adiciona chaves: /^\{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\}$/i. A variante urn: adiciona um esquema: /^urn:uuid:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.
O que isso não cobre: normalizar IDs para armazenamento e escolher um tipo de coluna, que são decisões separadas
Um único regex que lide com todas as variantes é menos legível, mas possível. A maioria dos validadores normaliza primeiro: retira colchetes e urn: prefixo, converte para minúsculas e, em seguida, corresponde ao padrão canônico. Os bits de versão e variante podem ser verificados após a correspondência de padrões examinando a posição 14 e a posição 19 conforme descrito no artigo 403. Lidar com entradas inválidas normalmente faz parte do design de validação. Quando um cliente envia um UUID malformado, não exponha o padrão regex ou as regras de validação interna na mensagem de erro. Retorne um erro claro: "Formato UUID inválido. Formato 8-4-4-4-12 esperado, como 550e8400-e29b-41d4-a716-446655440000. " Não tente para corrigir a entrada; peça ao cliente para reenviar.
Conclusão: valide a forma antecipadamente, procure a existência separadamente - a verificação ToolAcre confirma a forma no navegador antes de você tocar em um banco de dados
Alguns sistemas registram entradas inválidas para auditoria de segurança (detectando tentativas de injeção ou ataques de confusão de formato). O validador ToolAcre rejeita formulários não canônicos com uma mensagem de erro clara e não tenta corrigir automaticamente. Por que a forma canônica é importante para a interoperabilidade: se um sistema armazena UUIDs como hexadecimal sem hífen e outro os armazena como 8-4-4-4-12 canônico, compará-los quanto à igualdade requer normalização. Maiúsculas versus minúsculas requerem comparação sem distinção entre maiúsculas e minúsculas. Apoiado versus nu requer remoção. Essas variações dificultam as operações em massa (importações, migrações, comparações). Ferramentas padrão que geram formato canônico reduzem o atrito. O gerador ToolAcre sempre gera formato canônico com 36 caracteres minúsculos; ao importar UUIDs de outros sistemas, normalize-os para este formato em seu processo ETL para garantir consistência.