Av Vitor Odorico Bueno

Como lidar com erros de validação no dia a dia — guia prático

Eu já perdi horas pensando que um script estava quebrado quando na verdade o problema era só uma regra de negócio que ninguém documentou. Isso acontece todo dia em equipe que escala rápido e a validação vira um labirinto de checks que se contradizem. Não é um framework, não é uma ferramenta que você baixa e instala. É um conjunto de regras e padrões que aparecem quando alguém precisa garantir que dados entram certos num sistema que já tem décadas de histórico. Eu chamo assim num grupo de trabalho porque o Victor, nosso analista sênior, criou uma metodologia própria que ele batizou com esse nome como piada interna. A comunidade adotou o apelido e hoje todo mundo fala "tava bugado no av vitor" quando algum campo não passa na validação. O conceito central é simples: validar cedo, falhar com clareza, corrigir sem perder o rastro. Parece óbvio, mas na maioria dos projetos que eu vi isso é o que menos se aplica. As pessoas validam tarde demais, mandam erro genérico pra usuário, e aí ninguém sabe onde foi o defeito.

Método — como eu implemento hoje

Eu não comecei pela teoria. Comecei pelo problema. Tinha um sistema de envio de arquivos onde imagens de 4MB eram rejeitadas aleatoriamente, sem mensagem de erro, só HTTP 400. Passei três dias caçando. Descobri que o validador de MIME type estava rodando depois do parser de JSON, então requisições malformadas entravam no validator como texto puro e explodiam o regex. A solução que eu apliquei foi essa: reordenar o pipeline de validação para seguir estritamente a sequência parse tipagem regra de negócio persistência. Nada de misturar check de sintaxe com check semântico. Se o campo é obrigatório, checa antes de tentar converter tipo. Se precisa de regex, faz depois da conversão, não antes. Isso reduziu o tempo de debugging de validação de 2-3 horas para algo em torno de 15 minutos, dependendo da complexidade da regra. O ganho não é só técnico, é organizacional: quando o erro vem com mensagem clara de onde falhou, o desenvolvedor não precisa ler logs de 47 linhas pra entender que o campo "email" tava vindo como número inteiro.

Armadilhas que eu encontrei e contornei

A primeira vez que implementei validação rigorosa num sistema legado de 2018, quebrei três integrações com parceiros que mandavam dados no formato errado mas que funcionavam porque o código antigo era indulgente. Meu trabalho foi criar um camain degradação: quando o dado não passa no validator novo, ele cai no velho com log de alerta. Assim a validação nova vai ativando gradualmente, sem quebrar produção. Outra pegadinha: validar tudo em série é lento. Eu tinha um endpoint que fazia 12 checks sequenciais e cada um gastava uns 50ms. Total de 600ms só de validação, o que era insuportável pro SLA. A solução foi paralelizar os checks independentes (os que não dependem do resultado dos outros) e manter sequencial só os que têm dependência. Isso cortou o tempo pra cerca de 180ms no pior caso. Também tem o problema da mensagem de erro. Eu vi muita gente usando "Entrada inválida" como mensagem padrão. Isso é inútil. O usuário precisa saber o quê estava errado e como corrigir. Minha regra prática: se o campo exige um valor numérico entre 1 e 100, a mensagem tem que dizer exatamente isso, não "valor fora do permitido".

Cenários onde isso não funciona

Validação rigorosa não é bala de prata. Em sistemas que recebem dados de fontes externas não confiáveis — APIs de terceiros que mudam o schema sem aviso, feeds RSS quebrados, uploads de usuário com arquivo corrupto — o validator novo pode gerar mais trabalho do que resolver. Nesses casos, eu recomendo um approach diferente: validar o mínimo possível no caminho crítico e fazer saneamento pós-processamento em fila assíncrona. Também não recomendo usar esse método em protótipos rápidos ou MVPs. A validação rigorosa tem custo de desenvolvimento e manutenção. Se o projeto vai existir por duas semanas e depois ser descartado, gastar tempo construindo validators robustos é desperdício. Use validação básica, faça fallback, e só aprofunde quando o sistema tiver tração real.

Download e recursos

Eu não tenho um pacote pronto pra baixar porque a metodologia depende demais do contexto de cada projeto. O que eu fiz foi documentar os patterns num repositório interno da empresa, com exemplos práticos de validação para JavaScript, Python e Go. Se você quiser ver como ficaria aplicado no seu stack, posso compartilhar o link do Gist público com os trechos principais. O material cobre desde validação simples de formulário até schemas complexos com dependências entre campos. Tem também um checklist de revisão de validação que eu uso antes de cada deploy — leva uns 10 minutos e já evitou dois incidentes graves nos últimos seis meses.

Como começar hoje

Não precisa refazer tudo de uma vez. Comece pelos endpoints que mais dão problema. Identifique os três campos que mais causam erro na sua aplicação e aplique validação rigorosa neles primeiro. Meça o tempo de resposta antes e depois, colete os dados, e só então expandir para o resto do sistema. Se você está num time pequeno e não tem documentação de validação, escreva as regras no código mesmo. Comments não bastam porque ninguém lê comments. Tenha uma lista explícita de checks em algum arquivo central que todo mundo consulte. E o mais importante: nunca esconda o erro. Se algo falhou na validação, o consumidor da API precisa receber informação clara. Mensagem genérica é sinal de preguiça ou de sistema mal desenhado. Trate erro como feature, não como algo que você esconde nos logs.