zod

Q: Zod em todas as camadas ou apenas em controllers?

Valide nas fronteiras (HTTP, env, fila, webhooks externos). Dentro da lógica de domínio, confie em valores tipados. Não analise o mesmo objeto três vezes por requisição.

Q: Como evito vazar internos do Zod em erros de API?

Mapeie error.flatten().fieldErrors para o seu padrão de erro de API. Nunca retorne o stack ou issues brutos do ZodError em produção.

Q: Zod vs JSON Schema para OpenAPI?

Use Zod como fonte da verdade e gere OpenAPI com zod-to-openapi ou mantenha JSON Schema paralelo para documentação pública. Escolha uma fonte - não edite ambas manualmente.

Zod valida dados nos limites de API e configuração para que entradas inválidas nunca cheguem à lógica de negócios. Um único esquema fornece verificações em tempo de execução e tipos TypeScript sem desvios.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { z } from "zod";
 
export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(120),
  role: z.enum(["member", "admin"]).default("member"),
});
 
export type CreateUserInput = z.infer<typeof createUserSchema>;
 
// Rota Fastify
app.post("/users", async (req, reply) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return reply.status(400).send({ errors: parsed.error.flatten() });
  }
  return createUser(parsed.data);
});

Quando usar isso:

Toda superfície pública de corpo HTTP, query e parâmetros
Validação de process.env na inicialização (veja também Validação de Esquemas de Ambiente e Zod)
Payloads de jobs BullMQ antes da execução do handler
Payloads de assinatura de webhook de Stripe, GitHub, etc.

Exemplo de Trabalho

// src/schemas/order.ts
import { z } from "zod";
 
export const orderItemSchema = z.object({
  sku: z.string().uuid(),
  quantity: z.coerce.number().int().positive(),
});
 
export const createOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(orderItemSchema).min(1),
  shipBy: z.string().datetime().optional(),
});
 
export type CreateOrderInput = z.infer<typeof createOrderSchema>;
 
// src/routes/orders.ts
import type { FastifyInstance } from "fastify";
import { createOrderSchema } from "../schemas/order.js";
 
export async function orderRoutes(app: FastifyInstance): Promise<void> {
  app.post("/orders", async (req, reply) => {
    const result = createOrderSchema.safeParse(req.body);
    if (!result.success) {
      req.log.warn({ validation: result.error.flatten() }, "invalid_order");
      return reply.status(400).send({
        error: "validation_failed",
        details: result.error.flatten().fieldErrors,
      });
    }
    const order = await createOrder(result.data);
    return reply.status(201).send(order);
  });
}

// src/workers/email.worker.ts
import { z } from "zod";
 
const emailJobSchema = z.object({
  to: z.string().email(),
  templateId: z.string(),
  vars: z.record(z.string()),
});
 
export async function processEmailJob(raw: unknown): Promise<void> {
  const job = emailJobSchema.parse(raw); // lança → BullMQ retry/DLQ
  await sendEmail(job);
}

Comportamentos chave:

safeParse para HTTP - mapeia para 400 sem lançar exceção
parse para workers - permite que a fila tente novamente em mensagens corrompidas
z.coerce.number() para query strings e variáveis de ambiente
.refine() para regras entre campos (ex: shipBy deve ser uma data futura)

Comparação

Abordagem	Prós	Contras
Zod	Inferência TS, composável, ótima DX	Custo de tempo de execução em caminhos críticos (geralmente negligenciável)
Apenas JSON Schema	Nativo do Fastify, exportação OpenAPI	Sem tipos TS compartilhados sem geração de código
Verificações manuais if	Zero dependências	Desvia dos tipos; padrões não testáveis
class-validator (Nest)	Ecossistema Nest	Magia de decoradores; menos portável

Equipes Fastify frequentemente usam Zod + @fastify/type-provider-typebox ou convertem Zod para JSON Schema para serialização de resposta.
Equipes NestJS podem usar nestjs-zod ou pipes globais com DTOs Zod.

Testando

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createOrderSchema } from "./order.js";
 
describe("createOrderSchema", () => {
  it("rejeita itens vazios", () => {
    const result = createOrderSchema.safeParse({
      customerId: "550e8400-e29b-41d4-a716-446655440000",
      items: [],
    });
    assert.equal(result.success, false);
  });
});

Teste esquemas diretamente - mais rápido que testes de integração HTTP para casos extremos.
Mantenha fixtures inválidos dourados em __fixtures__/invalid-orders.json.

FAQs

Zod em todas as camadas ou apenas em controllers?

Valide nas fronteiras (HTTP, env, fila, webhooks externos). Dentro da lógica de domínio, confie em valores tipados. Não analise o mesmo objeto três vezes por requisição.

Como evito vazar internos do Zod em erros de API?

Mapeie error.flatten().fieldErrors para o seu padrão de erro de API. Nunca retorne o stack ou issues brutos do ZodError em produção.

Zod vs JSON Schema para OpenAPI?

Use Zod como fonte da verdade e gere OpenAPI com zod-to-openapi ou mantenha JSON Schema paralelo para documentação pública. Escolha uma fonte - não edite ambas manualmente.

Relacionado

Validação de Esquemas de Ambiente e Zod - análise de ambiente no boot
Validação de JSON Schema - alternativa nativa do Fastify
Padrões de Resposta de Erro - formato 400
Noções Básicas de Bibliotecas Essenciais - quando Zod é o padrão

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

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import { z } from "zod";
 
export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(120),
  role: z.enum(["member", "admin"]).default("member"),
});
 
export type CreateUserInput = z.infer<typeof createUserSchema>;
 
// Rota Fastify
app.post("/users", async (req, reply) => {
  const parsed = createUserSchema.safeParse(req.body);
  if (!parsed.success) {
    return reply.status(400).send({ errors: parsed.error.flatten() });
  }
  return createUser(parsed.data);
});

Quando usar isso:

Toda superfície pública de corpo HTTP, query e parâmetros
Validação de process.env na inicialização (veja também Validação de Esquemas de Ambiente e Zod)
Payloads de jobs BullMQ antes da execução do handler
Payloads de assinatura de webhook de Stripe, GitHub, etc.

Exemplo de Trabalho

// src/schemas/order.ts
import { z } from "zod";
 
export const orderItemSchema = z.object({
  sku: z.string().uuid(),
  quantity: z.coerce.number().int().positive(),
});
 
export const createOrderSchema = z.object({
  customerId: z.string().uuid(),
  items: z.array(orderItemSchema).min(1),
  shipBy: z.string().datetime().optional(),
});
 
export type CreateOrderInput = z.infer<typeof createOrderSchema>;
 
// src/routes/orders.ts
import type { FastifyInstance } from "fastify";
import { createOrderSchema } from "../schemas/order.js";
 
export async function orderRoutes(app: FastifyInstance): Promise<void> {
  app.post("/orders", async (req, reply) => {
    const result = createOrderSchema.safeParse(req.body);
    if (!result.success) {
      req.log.warn({ validation: result.error.flatten() }, "invalid_order");
      return reply.status(400).send({
        error: "validation_failed",
        details: result.error.flatten().fieldErrors,
      });
    }
    const order = await createOrder(result.data);
    return reply.status(201).send(order);
  });
}

// src/workers/email.worker.ts
import { z } from "zod";
 
const emailJobSchema = z.object({
  to: z.string().email(),
  templateId: z.string(),
  vars: z.record(z.string()),
});
 
export async function processEmailJob(raw: unknown): Promise<void> {
  const job = emailJobSchema.parse(raw); // lança → BullMQ retry/DLQ
  await sendEmail(job);
}

Comportamentos chave:

safeParse para HTTP - mapeia para 400 sem lançar exceção
parse para workers - permite que a fila tente novamente em mensagens corrompidas
z.coerce.number() para query strings e variáveis de ambiente
.refine() para regras entre campos (ex: shipBy deve ser uma data futura)

Comparação

Abordagem	Prós	Contras
Zod	Inferência TS, composável, ótima DX	Custo de tempo de execução em caminhos críticos (geralmente negligenciável)
Apenas JSON Schema	Nativo do Fastify, exportação OpenAPI	Sem tipos TS compartilhados sem geração de código
Verificações manuais if	Zero dependências	Desvia dos tipos; padrões não testáveis
class-validator (Nest)	Ecossistema Nest	Magia de decoradores; menos portável

Equipes Fastify frequentemente usam Zod + @fastify/type-provider-typebox ou convertem Zod para JSON Schema para serialização de resposta.
Equipes NestJS podem usar nestjs-zod ou pipes globais com DTOs Zod.

Testando

import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createOrderSchema } from "./order.js";
 
describe("createOrderSchema", () => {
  it("rejeita itens vazios", () => {
    const result = createOrderSchema.safeParse({
      customerId: "550e8400-e29b-41d4-a716-446655440000",
      items: [],
    });
    assert.equal(result.success, false);
  });
});

Teste esquemas diretamente - mais rápido que testes de integração HTTP para casos extremos.
Mantenha fixtures inválidos dourados em __fixtures__/invalid-orders.json.

FAQs

Zod em todas as camadas ou apenas em controllers?

Valide nas fronteiras (HTTP, env, fila, webhooks externos). Dentro da lógica de domínio, confie em valores tipados. Não analise o mesmo objeto três vezes por requisição.

Como evito vazar internos do Zod em erros de API?

Mapeie error.flatten().fieldErrors para o seu padrão de erro de API. Nunca retorne o stack ou issues brutos do ZodError em produção.

Zod vs JSON Schema para OpenAPI?

Use Zod como fonte da verdade e gere OpenAPI com zod-to-openapi ou mantenha JSON Schema paralelo para documentação pública. Escolha uma fonte - não edite ambas manualmente.

Relacionado

Validação de Esquemas de Ambiente e Zod - análise de ambiente no boot
Validação de JSON Schema - alternativa nativa do Fastify
Padrões de Resposta de Erro - formato 400
Noções Básicas de Bibliotecas Essenciais - quando Zod é o padrão

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

zod

Buscar na documentação

zod