Zod nas Fronteiras

O TypeScript não consegue validar corpos HTTP, strings de consulta ou variáveis de ambiente em tempo de execução - esquemas Zod nas fronteiras do sistema transformam entrada desconhecida em dados tipados e confiáveis.

Receita

import { z } from 'zod';
 
const EnvSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
});
 
export const env = EnvSchema.parse(process.env);

const CreateUser = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});
type CreateUser = z.infer<typeof CreateUser>;

Quando usar isso:

• Inicialização de configuração a partir de process.env
• Validação de corpo JSON POST/PUT no Express 5 ou Fastify 5
• Análise de payloads de webhook de Stripe, Twilio, etc.
• Substituição de as MyType inseguros em req.body

Exemplo de Trabalho

import { z } from 'zod';
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 
const EnvSchema = z.object({
  PORT: z.coerce.number().default(3000),
});
const env = EnvSchema.parse(process.env);
 
const CreateItem = z.object({
  name: z.string().min(1),
  qty: z.number().int().positive(),
});
 
async function readJson(req: IncomingMessage): Promise<unknown> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
}
 
function sendJson(res: ServerResponse, status: number, body: unknown): void {
  res.writeHead(status, { 'content-type': 'application/json' });
  res.end(JSON.stringify(body));
}
 
const server = createServer(async (req, res) => {
  if (req.method === 'POST' && req.url === '/items') {
    try {
      const raw = await readJson(req);
      const item = CreateItem.parse(raw);
      sendJson(res, 201, { id: '1', ...item });
    } catch (err) {
      if (err instanceof z.ZodError) {
        sendJson(res, 400, { error: 'validation_failed', issues: err.flatten() });
        return;
      }
      throw err;
    }
    return;
  }
  sendJson(res, 404, { error: 'not_found' });
});
 
server.listen(env.PORT);

O que isso demonstra:

• parse lança ZodError em caso de falha - mapeie para 400, não 500
• z.coerce.number() lida com variáveis de ambiente string como "3000"
• z.infer deriva tipos TypeScript do mesmo esquema que em tempo de execução
• flatten() produz erros em nível de campo seguros para clientes

Mergulho Profundo

Como Funciona

• Zod constrói uma cadeia de validadores; parse executa de forma síncrona - mantenha os esquemas modestos em caminhos quentes ou compile esquemas em cache.
• safeParse retorna { success, data | error } - estilo funcional sem try/catch.
• Transforms (z.string().transform(s => s.trim())) executam após a validação - documente efeitos colaterais.
• Refinements (.refine()) expressam regras entre campos - confirmação de senha, intervalos de datas.

Mapa de Fronteiras

Notas de TypeScript

import { z } from 'zod';
 
const IdParams = z.object({ id: z.string().uuid() });
 
// Padrão de middleware reutilizável
function parseParams<T extends z.ZodType>(schema: T, input: unknown): z.infer<T> {
  return schema.parse(input);
}

Armadilhas

• Usar .parse em cargas úteis enormes repetidamente - compile uma vez, reutilize objetos de esquema. Correção: const Schema = z.object(...) no nível do módulo.
• Vazar pilhas de ZodError para clientes - use flatten() ou um mapa de erros personalizado. Correção: registre o erro completo apenas no lado do servidor.
• Duplicar esquema e interface - desvio garantido. Correção: use apenas z.infer, sem interface paralela.
• Variáveis de ambiente opcionais sem padrões - undefined falha em esquemas rigorosos. Correção: .optional(), .default(), ou documente as variáveis necessárias.
• Confiar em z.string() para colunas HTML/JSON - validação != sanitização. Correção: escape na saída, SQL parametrizado.

Alternativas

FAQs

Relacionado

• Tipando Manipuladores Express/Fastify - genéricos de manipulador
• Noções Básicas de Configuração - padrões de carregamento de env
• Zod - receitas focadas na biblioteca
• Padrões de Resposta de Erro - formato 400

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.