Validação de dados com Zod: por que os tipos do TypeScript não bastam

Existe um mal-entendido que custa caro em equipes que adotaram TypeScript com entusiasmo. A crença de que, por ter tipos, o sistema está protegido contra dados malformados. Não está. E essa confusão entre o que o compilador faz e o que ele não faz é a origem de uma categoria inteira de bugs que só aparecem em produção.

Quero desfazer esse mal-entendido de forma direta, porque ele molda decisões de arquitetura. Quem entende onde os tipos terminam passa a tratar as fronteiras do sistema com o cuidado que elas exigem.

O que o TypeScript realmente garante

O TypeScript é um sistema de tipos que vive inteiramente em tempo de compilação. Você escreve as anotações, o compilador as verifica, e depois elas são apagadas. O JavaScript que roda em produção não sabe que aquele objeto era um Usuario. Para o motor de execução, é só um objeto qualquer.

Isso é por design, não é uma falha. O TypeScript foi construído para não impor custo em runtime. A consequência é que toda garantia de tipo é uma promessa sobre o código que você escreveu, não sobre os dados que ele vai processar.

Enquanto os dados nascem dentro do seu código, a promessa se sustenta. Uma função que recebe um número e devolve um número está protegida pelo compilador do começo ao fim. O problema começa quando o dado vem de fora.

A fronteira onde a garantia evapora

Pense em tudo que entra no seu sistema sem ter sido criado por ele. A resposta de uma API externa. O corpo de uma requisição HTTP. Um formulário preenchido por um humano distraído. Uma linha lida do banco de dados depois de uma migração mal feita. Uma variável de ambiente. Uma mensagem numa fila.

Em todos esses pontos, você normalmente faz algo parecido com declarar que o dado recebido é de um certo tipo. Uma asserção. E aqui mora o engano: essa asserção não verifica nada. Ela apenas instrui o compilador a confiar em você e seguir em frente. Se a API mudou um campo de número para texto, o TypeScript continua acreditando que é número, porque você mandou ele acreditar.

O resultado é um sistema que parece tipado mas tem buracos exatamente nas bordas, onde o mundo real entra. O erro não acontece na fronteira, onde seria fácil diagnosticar. Ele acontece três camadas adentro, quando algo tenta usar aquele campo como se a promessa fosse verdadeira. O rastro fica frio, o stack trace aponta para o lugar errado, e alguém perde a tarde.

Validação em runtime é o que faltava

A solução conceitual é simples de enunciar e fácil de adiar: nos pontos de entrada, você precisa verificar de verdade, em tempo de execução, que o dado tem a forma que você espera. Não confiar, conferir.

Validação em runtime significa código que efetivamente olha para o dado e responde se ele é válido ou não. Se a API prometeu um número e mandou texto, a validação grita ali, na borda, com uma mensagem clara, antes que o valor contamine o resto do fluxo. Você troca um bug silencioso e profundo por uma falha barulhenta e localizada.

Historicamente, isso era trabalhoso e fácil de esquecer. Escrevíamos a interface TypeScript de um lado e, do outro, uma função de validação separada que checava os mesmos campos na mão. Duas descrições da mesma coisa, mantidas por pessoas diferentes, em momentos diferentes. Elas divergiam. Sempre divergem. O tipo dizia uma coisa, o validador checava outra, e o dado real seguia uma terceira regra.

Zod e a abordagem schema-first

É aqui que o Zod muda a forma de pensar o problema. A ideia central é inverter a ordem: em vez de escrever o tipo e depois um validador que tenta acompanhá-lo, você escreve um único schema, e o tipo é derivado dele automaticamente.

Você descreve uma vez a forma do dado, com suas regras, campos obrigatórios, formatos e limites. Desse schema, o Zod extrai duas coisas ao mesmo tempo. Uma é o validador que roda em produção e examina o dado de verdade. A outra é o tipo estático do TypeScript, gerado a partir da mesma definição, sem você precisar escrevê-lo à mão.

Esse é o ganho que importa: uma única fonte de verdade. O tipo e a validação não podem mais divergir, porque nascem do mesmo lugar. Se você mudar o schema, o tipo muda junto, e qualquer código que dependia do formato antigo passa a falhar na compilação. A divergência deixa de ser possível por construção, em vez de ser evitada por disciplina.

O dado externo entra, passa pelo schema, e sai do outro lado como um valor que o compilador agora pode tratar com confiança legítima, porque a confiança foi conquistada em runtime e não apenas declarada. A asserção cega vira uma verificação real, e a partir dali o resto do sistema volta a estar protegido pelos tipos de novo.

O que isso muda na cabeça de quem decide

Adotar validação schema-first não é uma escolha de ferramenta, é uma escolha de onde colocar a fronteira de confiança. A regra que proponho ao time é direta: nada que vem de fora entra sem passar por um schema. API, formulário, banco, fila, configuração. Tudo valida na borda.

Dentro dessa fronteira, você confia nos tipos plenamente, porque eles voltaram a corresponder à realidade. Fora dela, você não confia em nada que não tenha sido verificado. Essa separação clara entre o território validado e o mundo selvagem é o que torna o sistema previsível. Quem trabalha com TypeScript em projetos avançados sabe que o tipo é uma ferramenta de raciocínio, e ele só raciocina bem sobre dados que de fato têm a forma prometida.

Vale registrar o custo, que é honesto e pequeno. Há um esforço inicial de modelar os schemas e uma sobrecarga de execução por validar dados nas bordas. Em troca, você elimina uma classe de erros que é cara justamente porque se manifesta tarde e longe da causa. É um dos melhores retornos sobre investimento que conheço em qualidade de software, e conversa diretamente com práticas mais amplas de segurança em aplicações web, já que validar entrada também é a primeira linha de defesa.