No desenvolvimento de back-end, é comum nos depararmos com uma variedade de strings que parecem semelhantes, mas desempenham papéis cruciais e distintos: id, uuid, slug, token, request_id, entre outros. Embora possam ter a mesma representação textual, suas responsabilidades arquitetônicas são fundamentalmente diferentes. A falha em reconhecer e respeitar essas diferenças pode levar a problemas de segurança, dificuldades de manutenção e um aumento significativo do débito técnico.
Um dos erros mais frequentes não reside na escolha entre UUID ou um integer como tipo de dado, mas sim na falta de clareza sobre a função que esse valor deve desempenhar. Uma mesma string pode representar um identificador único, um endereço público, um segredo temporário, um token de acesso ou um endereço legível por humanos. Quando essas funções são misturadas, criamos arquiteturas onde UUIDs são erroneamente usados como medidas de segurança, slugs como chaves primárias, reset-tokens como user_ids e JWTs como sessões permanentes. Embora o sistema possa continuar funcionando, ele começa a operar sob premissas falsas, gerando um débito técnico que se acumula com o tempo.
ID: O Identificador Estável da Entidade
Um ID tem como principal objetivo distinguir uma entidade de outra. Ele é a representação da identidade de uma entidade, e não um método de acesso a ela. Um bom ID é geralmente estável, único dentro de seu escopo, bem indexado e não muda com atributos mutáveis como nome, e-mail ou status. Por exemplo, um usuário pode alterar seu e-mail, mas isso não deve transformá-lo em uma nova entidade. Da mesma forma, um artigo pode ter seu título alterado, mas comentários, curtidas e histórico de publicação devem continuar associados à mesma entidade. O ID mantém essa identidade enquanto outros atributos podem ser modificados livremente. Construir um ID a partir de dados mutáveis, como um endereço de e-mail, é uma má prática, pois uma simples alteração pode fazer o sistema tratar a entidade como nova, gerando inconsistências.
UUID: Um Formato, Não uma Função Arquitetônica
O UUID é frequentemente discutido como se fosse um papel arquitetônico em si, mas na verdade, é um formato de valor. Ele não especifica a finalidade do valor. UUIDv4, por exemplo, é escolhido quando se necessita de um identificador aleatório que possa ser gerado sem um contador centralizado. UUIDv7 oferece a vantagem de valores ordenados por tempo, melhorando a performance de escrita em índices. No entanto, essas propriedades do formato não respondem à pergunta fundamental: o que exatamente está sendo modelado? Problemas surgem quando as equipes veem um UUID e param de pensar sobre o papel do valor. Um UUID pode parecer robusto, mas é apenas um formato.
ID Interno vs. ID Público: Contratos Diferentes
Nem todo ID interno precisa ser exposto externamente. Uma base de dados pode conter um id interno e um public_id. Enquanto o id interno otimiza o armazenamento e as relações internas, o public_id estabiliza o mundo externo, incluindo APIs, eventos, integrações e links. O id interno pode ser alterado com a base de dados ou modelo de armazenamento, mas o public_id deve ser mantido o mais estável possível para não quebrar dependências externas. Prefixo como usr_ ou ord_ não adicionam segurança, mas melhoram a usabilidade, indicando claramente o tipo de entidade em um ticket de suporte, por exemplo. A ideia central é que o ID interno pertence à implementação, enquanto o ID público pertence ao contrato externo.
Slug: Endereço para Humanos, Não Identidade da Entidade
Um slug é projetado para tornar URLs legíveis por humanos, sendo ideal para publicações, perfis, categorias e conteúdo visível. No entanto, o texto é mutável. Se um slug for alterado (por exemplo, ao renomear um artigo), e ele for usado como identidade da entidade, isso causará problemas. É preferível manter a ligação através de um ID estável e usar o slug apenas como um endereço legível na interface humana, com mecanismos para lidar com redirecionamentos caso o slug mude.
Token: Missão e Prazo de Validade Definidos
Um token difere de um ID não pela sua aparência ou comprimento, mas pelo seu propósito. Enquanto um ID aponta para uma entidade, um token concede a permissão para executar uma ação específica ou confirmar um contexto. Um reset-token, por exemplo, deve ter um ciclo de vida claro: propósito, entidade associada, data de expiração, se é reutilizável e se foi revogado. Armazenar um token como um campo comum ao lado de um user_id é uma falha de segurança. O token bruto deve ser apresentado apenas uma vez (em um e-mail, link ou resposta de API) e, posteriormente, o sistema deve operar com seu hash. Se um valor tem um prazo de validade, pode ser revogado ou tem um propósito específico, ele se assemelha mais a um token do que a um ID.
API Key: Um Segredo, Não um Nome de Cliente
Uma API key é frequentemente confundida com um client_id. Enquanto o client_id identifica quem é o cliente, a API key prova que ele tem permissão para usar a integração. Uma modelagem inadequada pode expor o segredo e dificultar a rotação ou o rastreamento da chave. Uma modelagem mais robusta separa essas responsabilidades, permitindo o rastreamento de uso, datas de criação e revogação, e a exibição de um prefixo da chave para o cliente, sem expor o segredo completo.
Session ID e JWT: Diferentes Formas de Contexto
Um Session ID é um ponteiro para um estado no servidor, sendo opaco por si só e dependendo do servidor para recuperar as informações da sessão. Já um JWT (JSON Web Token) é um token compacto que transmite informações entre as partes. Ele contém declarações (claims) sobre o assunto (sub), emissor (iss), audiência (aud) e expiração (exp). É crucial entender que session_id é um identificador de sessão no servidor, enquanto JWT é um token com valores embarcados. O sub dentro de um JWT é o identificador do sujeito. São três papéis distintos, mesmo que todos sejam representados como strings.
Request ID: ID do Evento, Não da Entidade de Negócio
Um request_id, trace_id ou correlation_id é usado para correlacionar eventos em logs, ajudando a entender o que aconteceu dentro de um request específico. Ele não deve ser usado como o ID de um pedido, usuário ou pagamento. Sua função é a observabilidade, não a modelagem de negócio. Usar um request_id para buscar entidades de negócio indica um desvio na arquitetura.
Nome do Campo Deve Refletir o Papel, Não o Formato
Nomes de campos genéricos como uuid ou token escondem o propósito do valor. É preferível usar nomes que indiquem o papel, como user_id ou reset_token. Isso minimiza a chance de uso indevido ao longo do tempo. A regra de ouro é: primeiro o papel, depois o formato.
Conclusão
A confusão entre formato e papel de um identificador é a raiz dos problemas. Seja UUID ou integer, string ou JSON, o que importa é a função que cada valor desempenha no sistema. A ordem correta de prioridade no design é: papel, tempo de vida, limites de visibilidade, armazenamento e, por último, o formato. Ignorar essa ordem leva a sistemas onde a renomeação de um campo pode exigir migrações complexas, onde dados sensíveis são expostos ou onde a lógica de negócio se torna obscura. Compreender e aplicar essas distinções é fundamental para construir sistemas robustos, seguros e fáceis de manter.
