Consumo Tipado de APIs com Fetch e Validação de Esquemas em Runtime com Zod
Consumo Tipado de APIs com Fetch e Validação de Esquemas em Runtime com Zod
const dados = await response.json() as MeuTipo é uma das maiores armadilhas de falsas garantias no desenvolvimento TypeScript? Em tempo de execução, se o backend mudar o nome de um campo ou falhar, sua aplicação quebrará sem nenhum aviso estático. Hoje você aprenderá a construir clientes de API à prova de falhas utilizando o ecossistema Zod para validação de esquemas em runtime e inferência automática de tipos estáticos com z.infer!
📑 Índice do Conteúdo
1. A “Mentira de Tipo” (Type Lie) no Consumo de APIs
A Fetch API nativa do navegador retorna uma Promise cujo método response.json() é tipado internamente pelo TypeScript como Promise<any>. Isso ocorre por um motivo óbvio: o compilador do TypeScript não pode prever o que o servidor remoto enviará através dos cabos de rede.
Diante disso, a imensa maioria dos desenvolvedores comete o erro clássico de forçar a tipagem com uma asserção:
interface PerfilUsuario {
id: number;
nome: string;
emailCorporativo: string;
}
async function buscarUsuarioPerigoso(id: number): Promise<PerfilUsuario> {
const res = await fetch(`https://api.empresa.com/usuarios/${id}`);
// PERIGO: Estamos dizendo ao TypeScript "confie em mim, o JSON retornado é exatamente PerfilUsuario".
const dados = (await res.json()) as PerfilUsuario;
return dados;
}
// O compilador acha que está tudo bem, mas em produção:
// Se o backend retornar { erro: "Token expirado" } ou { id: 10, nome: "Ana", email: "..." },
// a linha abaixo lançará: TypeError: Cannot read properties of undefined!
buscarUsuarioPerigoso(42).then(user => {
console.log(user.emailCorporativo.toLowerCase());
});
2. A Regra de Ouro: Validação na Borda do Sistema com Zod
Na engenharia de software moderna, dados que cruzam a fronteira externa do sistema (respostas HTTP de APIs externas, WebSockets, LocalStorage, entradas de formulários) devem ser tratados como desconhecidos (unknown) e validados rigorosamente no momento exato em que entram na aplicação.
O Zod é a biblioteca de validação de esquemas em tempo de execução (*Schema Validation*) mais adotada do ecossistema TypeScript. Ele foi projetado com uma filosofia TypeScript-First: você escreve o validador uma única vez e o Zod deriva automaticamente a interface estática do TypeScript!
3. Declarando Esquemas e a Inferência com z.infer
Vamos criar nosso primeiro esquema de dados corporativo com regras rigorosas de validação:
import { z } from "zod";
// 1. Definimos o esquema de validação em runtime:
export const UsuarioSchema = z.object({
id: z.number().int().positive(),
nome: z.string().min(2, "O nome deve ter pelo menos 2 caracteres"),
email: z.string().email("Formato de e-mail inválido"),
cargo: z.enum(["ADMIN", "DESENVOLVEDOR", "SUPORTE", "ANALISTA"]),
ativo: z.boolean().default(true),
tags: z.array(z.string()).optional()
});
// 2. A MÁGICA: O tipo TypeScript é gerado automaticamente pelo compilador!
// Não precisamos criar "interface Usuario" manualmente:
export type Usuario = z.infer<typeof UsuarioSchema>;
/*
Tipo resultante estritamente inferido:
type Usuario = {
id: number;
nome: string;
email: string;
cargo: "ADMIN" | "DESENVOLVEDOR" | "SUPORTE" | "ANALISTA";
ativo: boolean;
tags?: string[] | undefined;
}
*/
4. Validando Dados: .parse() vs .safeParse()
O Zod fornece dois métodos principais para submeter um objeto JSON bruto à validação:
.parse(dados): Valida o dado. Se houver qualquer divergência de tipo ou regra violada, lança uma exceçãoZodError..safeParse(dados): Valida o dado de forma puramente funcional, retornando um objeto de união discriminada (Discriminated Union) contendosuccess: truecom os dados tipados ousuccess: falsecom o relatório detalhado de erros:
const payloadVindoDaApi: unknown = {
id: 101,
nome: "Marcos Vinicius",
email: "[email protected]",
cargo: "DESENVOLVEDOR"
// "ativo" foi omitido pelo servidor, mas o Zod preencherá o default(true)!
};
const resultado = UsuarioSchema.safeParse(payloadVindoDaApi);
if (resultado.success) {
// Afunilamento perfeito: resultado.data é estritamente Usuario!
console.log(`Usuário validado com sucesso: ${resultado.data.nome}`);
console.log(`Status ativo automático: ${resultado.data.ativo}`); // true
} else {
// resultado.error é do tipo ZodError:
console.error("Falha de conformidade na resposta da API:", resultado.error.format());
}
5. Coerções e Transformações Inteligentes com Zod
Muitas APIs REST legadas retornam números ou datas em formato de texto (ex: "150.50" em vez de 150.50, ou strings de data ISO). O Zod possui o recurso z.coerce que converte os dados automaticamente antes da validação:
const FaturaSchema = z.object({
id: z.string(),
// Converte automaticamente a string numérica para number nativo:
valorCentavos: z.coerce.number().positive(),
// Converte a string ISO "2026-11-19T..." em uma instância real de Date:
dataVencimento: z.coerce.date(),
// Transforma o código de status sempre para maiúsculas:
status: z.string().transform(s => s.toUpperCase())
});
type Fatura = z.infer<typeof FaturaSchema>;
// Payload recebido:
const dadosBrutos = {
id: "FAT-990",
valorCentavos: "24990",
dataVencimento: "2026-12-15",
status: "pendente"
};
const faturaValidada = FaturaSchema.parse(dadosBrutos);
console.log(typeof faturaValidada.valorCentavos); // ___WZW_STR_0___ (24990)
console.log(faturaValidada.dataVencimento instanceof Date); // true
console.log(faturaValidada.status); // ___WZW_STR_0___
6. Exemplo Enterprise: Cliente HTTP Resiliente (TypedApiClient)
Vamos construir a arquitetura completa de um cliente de requisições HTTP corporativo que realiza o fetch, valida o status HTTP, submete a resposta ao esquema Zod fornecido e retorna dados 100% seguros contra falhas de contrato:
import { z } from "zod";
// Estrutura padronizada de resposta do cliente
interface RespostaHttpSegura<T> {
sucesso: boolean;
dados?: T;
erroStatus?: number;
errosValidacao?: z.ZodIssue[];
mensagemErro?: string;
}
class ClienteHttpCorporativo {
constructor(private baseUrl: string) {}
public async getSeguro<TSchema extends z.ZodTypeAny>(
endpoint: string,
esquemaResposta: TSchema,
init?: RequestInit
): Promise<RespostaHttpSegura<z.infer<TSchema>>> {
const urlCompleta = `${this.baseUrl}${endpoint}`;
try {
console.log(`[HTTP GET] Solicitando: ${urlCompleta}`);
const response = await fetch(urlCompleta, {
headers: { "Accept": "application/json" },
...init
});
// 1. Verificação de status HTTP (2xx)
if (!response.ok) {
return {
sucesso: false,
erroStatus: response.status,
mensagemErro: `Falha HTTP ${response.status}: ${response.statusText}`
};
}
// 2. Parse do JSON bruto da rede
const jsonBruto: unknown = await response.json();
// 3. Validação do Contrato com Zod em Runtime
const resultadoValidacao = esquemaResposta.safeParse(jsonBruto);
if (!resultadoValidacao.success) {
console.error(`[QUEBRA DE CONTRATO] A API retornou dados fora do esquema esperado!`);
return {
sucesso: false,
mensagemErro: "Resposta da API não atende ao contrato esperado pelo front-end.",
errosValidacao: resultadoValidacao.error.issues
};
}
// 4. Sucesso absoluto: dados verificados em runtime e fortemente tipados!
return {
sucesso: true,
dados: resultadoValidacao.data
};
} catch (erroDeRede: any) {
return {
sucesso: false,
mensagemErro: `Falha de conexão ou rede: ${erroDeRede.message}`
};
}
}
}
// Demonstração de Consumo:
const ProdutoApiSchema = z.object({
id: z.string(),
titulo: z.string(),
preco: z.number(),
emEstoque: z.boolean()
});
const api = new ClienteHttpCorporativo("https://api.webzoneware.com");
api.getSeguro("/produtos/101", ProdutoApiSchema).then(resp => {
if (resp.sucesso && resp.dados) {
// Autocomplete total dos campos validados:
console.log(`Produto: ${resp.dados.titulo} por R$ ${resp.dados.preco.toFixed(2)}`);
} else {
console.warn(`Erro ao obter produto: ${resp.mensagemErro}`);
}
});
7. Armadilhas Comuns e Boas Práticas Sênior
- Evite a Tentação de Validar com
z.any(): Usarz.any()desliga completamente os benefícios de integridade do Zod. Se houver propriedades cujos formatos ainda são desconhecidos, prefiraz.unknown()ouz.record(z.string(), z.unknown()). - Não Reinstancie Esquemas em Loops: Esquemas Zod são imutáveis e podem ser declarados como constantes de módulo uma única vez. Evite declarar esquemas dentro de funções que rodam milhares de vezes por segundo.
- Substitua Interfaces Manuais por
z.infer: Sempre que você tiver uma entidade que depende de dados da rede ou de formulários, torne o esquema Zod a Fonte Única da Verdade (Single Source of Truth) e derive os tipos TypeScript comz.infer<typeof MeuEsquema>.
Resumo da Lição 42
- Fazer
as Tipono retorno defetchcria uma “mentira de tipo” que mascara quebras de contrato do backend. - O Zod fornece validação estrita em tempo de execução combinada com inferência estática de tipos.
- A sintaxe
z.infer<typeof Esquema>elimina a duplicação de interfaces no projeto. - O método
.safeParse()possibilita o tratamento funcional de erros com uniões discriminadas sem a necessidade de blocostry/catchverbosos. - Com coerções (
z.coerce) e transformações, o Zod padroniza dados imperfeitos da rede antes que eles atinjam o restante da sua aplicação.
📝 Exercício Prático Desafiador da Lição 42
1. Crie um esquema Zod chamado CotacaoMoedaSchema que valide um objeto contendo: parMoeda (string com exatamente 6 caracteres, ex: "USDBRL"), taxaCambio (número positivo com coerção automática) e atualizadoEm (coerção para Date).
2. Extraia o tipo estático CotacaoMoeda utilizando z.infer.
3. Escreva uma função validarCotacao(dadosBrutos: unknown) que utilize .safeParse() e exiba no console uma mensagem amigável contendo o valor formatado da taxa ou a lista detalhada de campos que reprovaram na validação.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE