Formato e métodos de geração
Um UUID (Universally Unique Identifier) é um identificador de 128 bits usado para distinguir registros ou recursos. Sua representação textual habitual tem 32 caracteres hexadecimais separados por hífens em grupos de 8, 4, 4, 4 e 12 caracteres.
A versão indica como o identificador foi composto. O UUIDv4 utiliza 122 bits aleatórios e reserva os demais para indicar a versão e a variante do formato. O UUIDv7 inclui o tempo Unix em milissegundos no início do valor. Por isso, dois identificadores com a mesma aparência geral podem ter propriedades diferentes de geração e ordenação.
O identificador na consulta de um cadastro
No endereço de exemplo /cadastros/550e8400-e29b-41d4-a716-446655440000, a aplicação usa o UUID para localizar um cadastro. O primeiro caractere do terceiro grupo é 4, que indica a versão 4 nesse formato. A sequência completa seleciona o recurso, mas não informa se você tem permissão para abri-lo.
Ao receber essa consulta, a API precisa verificar a permissão para abrir o cadastro localizado. O formato válido do UUID não confirma a existência do registro nem substitui a autorização.
A geração distribuída permite que sistemas criem UUIDs sem consultar um contador central a cada novo registro. Isso exige um gerador adequado à versão escolhida. Ao usar o UUID como chave única, mantenha a restrição correspondente no banco para recusar valores repetidos, inclusive os recebidos de sistemas externos.
Dúvidas frequentes
Perguntas frequentes sobre UUID
- Qual é a diferença entre UUIDv4 e UUIDv7?
- A versão 4 reserva 122 bits para valores aleatórios. A versão 7 começa com um instante Unix em milissegundos e combina esse componente com outros bits definidos pelo método de geração.
- Conhecer o UUID autoriza a consulta ao cadastro?
- O UUID apenas identifica o recurso. A aplicação deve verificar a permissão de acesso e não pode usar a posse do identificador como autorização.
- Ainda preciso de uma restrição de unicidade no banco?
- A restrição permite ao banco recusar identificadores repetidos. Ela também cobre duplicações por importação ou por falha da aplicação, além de possíveis colisões na geração.
Para continuar
Recursos relacionados
Documentação
RFC 9562: UUIDs
A RFC 9562 especifica o formato dos UUIDs, seus métodos de geração e os cuidados de unicidade e uso em segurança.
Abrir recursoSite de referência
DevSide: desenvolvimento colaborativo
Orientação técnica ao vivo para revisar a identificação dos registros e a autorização nas rotas da aplicação.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao desenvolver uma API com agentes, você precisa conferir como os registros são identificados e como a aplicação verifica a permissão de acesso.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.