Análise defensiva e envelopes de erros
Crie um tratamento robusto de requisições: faça a análise de forma defensiva, mapeie todas as falhas para um envelope compacto de erro em JSON e evite expor detalhes internos.
Análise defensiva e envelopes de erros é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 2 de 2. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 2 aulas no total.
Introdução
Objetivo: Analisar entradas de forma defensiva e sempre responder com um envelope de erro JSON previsível. Manteremos a validação próxima da fronteira, padronizaremos as falhas e manteremos registros detalhados enquanto as respostas permanecem mínimas.
- safeParse em todas as entradas não confiáveis
- { error, code, details? } consistente
- Disciplina entre 4xx e 5xx
Mapeador de envelopes
Defina um ErrorEnvelope pequeno e reutilizável. Mapeie erros unknown para ele sem expor rastreamentos de pilha.
export type ErrorEnvelope = { error: string; code?: string; details?: unknown }
export function toEnvelope(u: unknown): ErrorEnvelope {
if (u instanceof Error) return { error: u.message }
if (typeof u === "string") return { error: u }
try { return { error: JSON.stringify(u) } } catch { return { error: "Unknown error" } }
}Auxiliar de validação
Encapsule os esquemas em um auxiliar de validate que retorne um resultado discriminado. Os manipuladores permanecem pequenos e consistentes.
import { z, type ZodTypeAny } from "zod"
export function validate<T extends ZodTypeAny>(schema: T, value: unknown) {
const r = schema.safeParse(value)
if (!r.success) {
return { ok: false as const, issues: r.error.format() }
}
return { ok: true as const, data: r.data as z.infer<T> }
}Manipulador defensivo
Valide cedo; retorne 400 com os detalhes dos problemas. Falhas inesperadas propagam-se para o middleware de erros como um 500 com o envelope.
import type { Request, Response, NextFunction } from "express"
import { z } from "zod"
import { validate } from "./validate"
import { toEnvelope, type ErrorEnvelope } from "./envelope"
const bodySchema = z.object({ email: z.string().email(), newsletter: z.boolean().default(false) })
export function subscribe(req: Request, res: Response<{ ok: true } | ErrorEnvelope>, next: NextFunction) {
const r = validate(bodySchema, req.body)
if (!r.ok) return res.status(400).json({ error: "Invalid body", details: r.issues })
try {
// pretend to persist
return res.status(201).json({ ok: true })
} catch (e) {
return next(e)
}
}
export function errorMiddleware(err: unknown, _req: Request, res: Response<ErrorEnvelope>, _next: NextFunction) {
const env = toEnvelope(err)
res.status(500).json(env)
}Envelopes comuns
Forneça pequenos auxiliares para resultados comuns: 404/401 com strings code estáveis, para que os clientes possam tomar decisões com confiabilidade.
export function notFound(resource: string): { status: 404; body: { error: string; code: string } } {
return { status: 404, body: { error: `${resource} not found`, code: "NOT_FOUND" } }
}
export function unauthorized(): { status: 401; body: { error: string; code: string } } {
return { status: 401, body: { error: "unauthorized", code: "UNAUTHORIZED" } }
}Registros versus resposta
Equilibre os registros e a resposta: registre o erro completo no servidor (pilha, identificador da requisição, identificador do usuário), mas retorne um envelope mínimo ao cliente. Considere limites de taxa e mascaramento de PII.
Verificação da prática de envelopes
Verificação rápida: Como os erros de validação devem ser retornados?
Recapitulação
Recapitulação: Valide as entradas com safeParse, mapeie as falhas para um envelope compacto e separe registros detalhados das respostas mínimas ao cliente.
Perguntas Frequentes
A aula “Análise defensiva e envelopes de erros” é grátis?
Sim — o texto completo de “Análise defensiva e envelopes de erros” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 2 aulas no total.
O que vou aprender em “Análise defensiva e envelopes de erros”?
Crie um tratamento robusto de requisições: faça a análise de forma defensiva, mapeie todas as falhas para um envelope compacto de erro em JSON e evite expor detalhes internos. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar TypeScript Academy?
Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 2.
Quanto tempo leva a aula “Análise defensiva e envelopes de erros”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de TypeScript Academy?
Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Esquemas zod/valibot + inferência
- Análise defensiva e envelopes de erros