Consumo de APIs e Validação Zod no TypeScript: Guia
⚡ Curso de TypeScript • Web-ZoneWare

Consumo Tipado de APIs com Fetch e Validação de Esquemas em Runtime com Zod

Lição 42 de 50

Consumo Tipado de APIs com Fetch e Validação de Esquemas em Runtime com Zod

Módulo 6: DOM, APIs, Arquitetura Enterprise & Projeto Final
Lição 42 de 50
Nível: Avançado
⏱ Tempo de Leitura e Prática: 30 minutos

Consumo Tipado de APIs com Fetch e Validação de Esquemas em Runtime com Zod

💡
O Que Você Vai Aprender Hoje: Você sabia que escrever 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!

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:

TypeScript: A Falsa Sensação de Segurança com Type Assertion

TypeScript 21 linhas
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:

TypeScript: Esquema Zod e Derivação de Tipo Estático

TypeScript 27 linhas
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ção ZodError.
  • .safeParse(dados): Valida o dado de forma puramente funcional, retornando um objeto de união discriminada (Discriminated Union) contendo success: true com os dados tipados ou success: false com o relatório detalhado de erros:
TypeScript: Uso Elegante de .safeParse()

TypeScript 18 linhas
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:

TypeScript: Coerção e Transformação de Dados

TypeScript 24 linhas
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:

TypeScript: Cliente de API Enterprise com Fetch e Zod

TypeScript 84 linhas
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}`);
    }
});
⚗️ Teste no Playground IDE Web-ZoneWare
Compile esquemas Zod, inspecione a inferência de tipos com z.infer e teste validações com safeParse.

Abrir Playground TypeScript →

7. Armadilhas Comuns e Boas Práticas Sênior

  • Evite a Tentação de Validar com z.any(): Usar z.any() desliga completamente os benefícios de integridade do Zod. Se houver propriedades cujos formatos ainda são desconhecidos, prefira z.unknown() ou z.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 com z.infer<typeof MeuEsquema>.

Resumo da Lição 42

  • Fazer as Tipo no retorno de fetch cria 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 blocos try/catch verbosos.
  • 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.

🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima