Tipagem de Respostas de API

Q: Qual o benefício de um wrapper genérico de fetch como fetchJson?

Centraliza o tratamento de erros (verificação de response.ok, captura de erros de rede). Cada local de chamada especifica o formato de resposta esperado através do parâmetro de tipo. Reduz o boilerplate de fetch duplicado entre componentes.

Q: Como o Zod fornece segurança de tipo tanto em tempo de compilação quanto em tempo de execução?

z.infer deriva o tipo TypeScript do esquema. schema.parse(json) lança um ZodError se os dados não corresponderem em tempo de execução.

Q: Armadilha: O cast as T oferece alguma proteção em tempo de execução?

Não. as T é uma afirmação apenas em tempo de compilação, sem segurança em tempo de execução. Se a API mudar seu formato de resposta, seu código falhará silenciosamente até que o acesso a uma propriedade cause um erro. Para limites críticos de API, use Zod ou um type guard personalizado em vez disso.

Q: Por que o fetch não lança erros em respostas 4xx ou 5xx?

fetch só rejeita em falhas de rede (erros de DNS, sem conexão). Códigos de status de erro HTTP (400, 404, 500) são considerados requisições de rede bem-sucedidas. Você deve verificar response.ok ou response.status manualmente.

Q: Como você tipa uma união discriminada para resultados de API (sucesso vs erro)?

O campo success atua como o discriminador. O TypeScript refina o acesso a data e error com base na verificação de success.

Q: Armadilha: O que acontece se você esquecer de lidar com estados de carregamento e erro?

Acessar .data em um estado null causa um erro em tempo de execução. Sempre modele três estados: carregando, erro e sucesso. Use uma união discriminada ou variáveis de estado separadas para cada um.

Q: Qual a vantagem de usar unknown em vez de any para dados não validados?

unknown força você a refinar ou validar antes de acessar propriedades. any permite silenciosamente todo o acesso a propriedades sem verificações. Use const data: unknown = await response.json() como ponto de partida para validação.

Receita

Tipifique suas respostas de API de ponta a ponta, desde chamadas fetch até a renderização de componentes. Use type guards e validação em tempo de execução para preencher a lacuna entre dados de rede sem tipo e seus tipos TypeScript.

Exemplo de Trabalho

// Defina seus tipos de API
type ApiUser = {
  id: number;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};
 
type ApiResponse<T> = {
  data: T;
  meta: {
    page: number;
    totalPages: number;
    totalCount: number;
  };
};
 
// Wrapper de fetch type-safe
async function fetchJson<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  return response.json() as Promise<T>;
}
 
// Uso em um componente
function UserList() {
  const [result, setResult] = useState<ApiResponse<ApiUser[]> | null>(null);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    fetchJson<ApiResponse<ApiUser[]>>("/api/users")
      .then(setResult)
      .catch((err) => setError(err.message));
  }, []);
 
  if (error) return <p>Erro: {error}</p>;
  if (!result) return <p>Carregando...</p>;
 
  return (
    <ul>
      {result.data.map((user) => (
        <li key={user.id}>{user.name} ({user.role})</li>
      ))}
    </ul>
  );
}

Análise Detalhada

Como Funciona

fetch retorna Response, e response.json() retorna Promise<any>. O cast as Promise<T> informa ao TypeScript qual formato esperar, mas não valida os dados em tempo de execução.
Um wrapper genérico de fetch (fetchJson<T>) centraliza o tratamento de erros e a tipagem. Cada local de chamada especifica o formato de resposta esperado.
Para segurança real em tempo de execução, combine seus tipos com uma biblioteca de validação como Zod. Isso garante que a API realmente retornou o formato que você espera.
Separe seus tipos de API (o que o servidor envia) de seus tipos de domínio (o que seu aplicativo usa). Mapeie entre eles em uma camada de serviço.

Variações

Validação em tempo de execução com Zod:

import { z } from "zod";
 
const ApiUserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(["admin", "editor", "viewer"]),
});
 
type ApiUser = z.infer<typeof ApiUserSchema>;
 
const ApiResponseSchema = <T extends z.ZodType>(dataSchema: T) =>
  z.object({
    data: dataSchema,
    meta: z.object({
      page: z.number(),
      totalPages: z.number(),
      totalCount: z.number(),
    }),
  });
 
async function fetchValidated<T>(url: string, schema: z.ZodType<T>): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const json = await response.json();
  return schema.parse(json); // Lança ZodError se a validação falhar
}
 
// Uso
const result = await fetchValidated(
  "/api/users",
  ApiResponseSchema(z.array(ApiUserSchema))
);

Type guard personalizado:

function isApiUser(value: unknown): value is ApiUser {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value &&
    "email" in value &&
    "role" in value &&
    typeof (value as ApiUser).id === "number" &&
    typeof (value as ApiUser).name === "string"
  );
}
 
// Uso
const data: unknown = await response.json();
if (isApiUser(data)) {
  console.log(data.name); // TypeScript sabe que data é ApiUser
}

Tipagem de resposta de erro:

type ApiError = {
  message: string;
  code: string;
  details?: Record<string, string[]>;
};
 
type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };
 
async function fetchApi<T>(url: string): Promise<ApiResult<T>> {
  try {
    const response = await fetch(url);
    const json = await response.json();
    if (!response.ok) {
      return { success: false, error: json as ApiError };
    }
    return { success: true, data: json as T };
  } catch {
    return { success: false, error: { message: "Erro de rede", code: "NETWORK" } };
  }
}

Notas do TypeScript

response.json() retorna Promise<any>. O cast as Promise<T> é um compromisso necessário, pois a análise de JSON é inerentemente sem tipo.
z.infer<typeof Schema> deriva o tipo TypeScript de um esquema Zod, fornecendo uma única fonte de verdade.
Use unknown em vez de any para dados não validados. Isso força você a refinar ou validar antes de acessar propriedades.

Armadilhas

Fazer o cast com as T não oferece segurança em tempo de execução. Se a API mudar seu formato de resposta, seu código falhará silenciosamente até que o acesso a uma propriedade cause um erro.
fetch não lança erros em respostas 4xx ou 5xx. Você deve verificar response.ok ou response.status manualmente.
Tipos de API podem não corresponder aos tipos de domínio do seu frontend (por exemplo, datas vêm como strings, não como objetos Date). Transforme-os em uma camada de mapeamento.
Esquecer de lidar com estados de carregamento e erro leva ao acesso a .data em null, causando erros em tempo de execução.

Alternativas

Abordagem	Prós	Contras
Cast `as T`	Simples, sem dependências	Sem validação em tempo de execução
Validação Zod	Segurança em tempo de execução + compilação, única fonte de verdade	Dependência adicional, sobrecarga de análise
Type guards (`is` functions)	Sem dependências, refinamento explícito	Tedioso para tipos complexos, fácil de errar
tRPC	Segurança de tipo ponta a ponta, sem tipagem manual	Requer configuração de servidor + cliente
Geração de código GraphQL	Tipos gerados a partir do esquema	Etapa de compilação, ecossistema GraphQL necessário

FAQs

Por que `response.json()` retorna `Promise` e o que fazer a respeito?

A análise de JSON é inerentemente sem tipo -- o TypeScript não pode saber qual formato os dados terão.
Use as Promise<T> para fazer o cast, ou valide com schema.parse(json) do Zod para segurança em tempo de execução.
O cast não oferece segurança em tempo de execução -- a API pode retornar qualquer coisa.

Qual o benefício de um wrapper genérico de fetch como `fetchJson<T>`?

Centraliza o tratamento de erros (verificação de response.ok, captura de erros de rede).
Cada local de chamada especifica o formato de resposta esperado através do parâmetro de tipo.
Reduz o boilerplate de fetch duplicado entre componentes.

Como o Zod fornece segurança de tipo tanto em tempo de compilação quanto em tempo de execução?

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});
type User = z.infer<typeof UserSchema>; // tipo derivado
 
const data = UserSchema.parse(json); // validação em tempo de execução

z.infer<typeof Schema> deriva o tipo TypeScript do esquema.
schema.parse(json) lança um ZodError se os dados não corresponderem em tempo de execução.

Armadilha: O cast `as T` oferece alguma proteção em tempo de execução?

Não. as T é uma afirmação apenas em tempo de compilação, sem segurança em tempo de execução.
Se a API mudar seu formato de resposta, seu código falhará silenciosamente até que o acesso a uma propriedade cause um erro.
Para limites críticos de API, use Zod ou um type guard personalizado em vez disso.

Por que o `fetch` não lança erros em respostas 4xx ou 5xx?

fetch só rejeita em falhas de rede (erros de DNS, sem conexão).
Códigos de status de erro HTTP (400, 404, 500) são considerados requisições de rede bem-sucedidas.
Você deve verificar response.ok ou response.status manualmente.

Quando usar um type guard personalizado versus validação Zod?

Type guards personalizados não têm dependências, mas são tediosos e propensos a erros para tipos complexos.
Zod fornece uma única fonte de verdade (esquema = tipo + validação), mas adiciona uma dependência.
Use Zod para limites de API; use type guards para verificações simples e únicas.

Por que os tipos de API devem ser separados dos tipos de domínio?

APIs podem enviar datas como strings, usar snake_case ou incluir campos que seu aplicativo não precisa.
Uma camada de mapeamento converte tipos de API em tipos de domínio (por exemplo, analisando strings de data em objetos Date).
Isso desacopla seu frontend de alterações de esquema de backend.

Como você tipa uma união discriminada para resultados de API (sucesso vs erro)?

type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };

O campo success atua como o discriminador.
O TypeScript refina o acesso a data e error com base na verificação de success.

Armadilha: O que acontece se você esquecer de lidar com estados de carregamento e erro?

Acessar .data em um estado null causa um erro em tempo de execução.
Sempre modele três estados: carregando, erro e sucesso.
Use uma união discriminada ou variáveis de estado separadas para cada um.

Qual a vantagem de usar `unknown` em vez de `any` para dados não validados?

unknown força você a refinar ou validar antes de acessar propriedades.
any permite silenciosamente todo o acesso a propriedades sem verificações.
Use const data: unknown = await response.json() como ponto de partida para validação.

// Defina seus tipos de API
type ApiUser = {
  id: number;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
};
 
type ApiResponse<T> = {
  data: T;
  meta: {
    page: number;
    totalPages: number;
    totalCount: number;
  };
};
 
// Wrapper de fetch type-safe
async function fetchJson<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }
  return response.json() as Promise<T>;
}
 
// Uso em um componente
function UserList() {
  const [result, setResult] = useState<ApiResponse<ApiUser[]> | null>(null);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    fetchJson<ApiResponse<ApiUser[]>>("/api/users")
      .then(setResult)
      .catch((err) => setError(err.message));
  }, []);
 
  if (error) return <p>Erro: {error}</p>;
  if (!result) return <p>Carregando...</p>;
 
  return (
    <ul>
      {result.data.map((user) => (
        <li key={user.id}>{user.name} ({user.role})</li>
      ))}
    </ul>
  );
}

Análise Detalhada

Como Funciona

fetch retorna Response, e response.json() retorna Promise<any>. O cast as Promise<T> informa ao TypeScript qual formato esperar, mas não valida os dados em tempo de execução.
Um wrapper genérico de fetch (fetchJson<T>) centraliza o tratamento de erros e a tipagem. Cada local de chamada especifica o formato de resposta esperado.
Para segurança real em tempo de execução, combine seus tipos com uma biblioteca de validação como Zod. Isso garante que a API realmente retornou o formato que você espera.
Separe seus tipos de API (o que o servidor envia) de seus tipos de domínio (o que seu aplicativo usa). Mapeie entre eles em uma camada de serviço.

Variações

Validação em tempo de execução com Zod:

import { z } from "zod";
 
const ApiUserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(["admin", "editor", "viewer"]),
});
 
type ApiUser = z.infer<typeof ApiUserSchema>;
 
const ApiResponseSchema = <T extends z.ZodType>(dataSchema: T) =>
  z.object({
    data: dataSchema,
    meta: z.object({
      page: z.number(),
      totalPages: z.number(),
      totalCount: z.number(),
    }),
  });
 
async function fetchValidated<T>(url: string, schema: z.ZodType<T>): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const json = await response.json();
  return schema.parse(json); // Lança ZodError se a validação falhar
}
 
// Uso
const result = await fetchValidated(
  "/api/users",
  ApiResponseSchema(z.array(ApiUserSchema))
);

Type guard personalizado:

function isApiUser(value: unknown): value is ApiUser {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "name" in value &&
    "email" in value &&
    "role" in value &&
    typeof (value as ApiUser).id === "number" &&
    typeof (value as ApiUser).name === "string"
  );
}
 
// Uso
const data: unknown = await response.json();
if (isApiUser(data)) {
  console.log(data.name); // TypeScript sabe que data é ApiUser
}

Tipagem de resposta de erro:

type ApiError = {
  message: string;
  code: string;
  details?: Record<string, string[]>;
};
 
type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };
 
async function fetchApi<T>(url: string): Promise<ApiResult<T>> {
  try {
    const response = await fetch(url);
    const json = await response.json();
    if (!response.ok) {
      return { success: false, error: json as ApiError };
    }
    return { success: true, data: json as T };
  } catch {
    return { success: false, error: { message: "Erro de rede", code: "NETWORK" } };
  }
}

Notas do TypeScript

response.json() retorna Promise<any>. O cast as Promise<T> é um compromisso necessário, pois a análise de JSON é inerentemente sem tipo.
z.infer<typeof Schema> deriva o tipo TypeScript de um esquema Zod, fornecendo uma única fonte de verdade.
Use unknown em vez de any para dados não validados. Isso força você a refinar ou validar antes de acessar propriedades.

Armadilhas

Fazer o cast com as T não oferece segurança em tempo de execução. Se a API mudar seu formato de resposta, seu código falhará silenciosamente até que o acesso a uma propriedade cause um erro.
fetch não lança erros em respostas 4xx ou 5xx. Você deve verificar response.ok ou response.status manualmente.
Tipos de API podem não corresponder aos tipos de domínio do seu frontend (por exemplo, datas vêm como strings, não como objetos Date). Transforme-os em uma camada de mapeamento.
Esquecer de lidar com estados de carregamento e erro leva ao acesso a .data em null, causando erros em tempo de execução.

Alternativas

Abordagem	Prós	Contras
Cast `as T`	Simples, sem dependências	Sem validação em tempo de execução
Validação Zod	Segurança em tempo de execução + compilação, única fonte de verdade	Dependência adicional, sobrecarga de análise
Type guards (`is` functions)	Sem dependências, refinamento explícito	Tedioso para tipos complexos, fácil de errar
tRPC	Segurança de tipo ponta a ponta, sem tipagem manual	Requer configuração de servidor + cliente
Geração de código GraphQL	Tipos gerados a partir do esquema	Etapa de compilação, ecossistema GraphQL necessário

FAQs

Por que `response.json()` retorna `Promise` e o que fazer a respeito?

A análise de JSON é inerentemente sem tipo -- o TypeScript não pode saber qual formato os dados terão.
Use as Promise<T> para fazer o cast, ou valide com schema.parse(json) do Zod para segurança em tempo de execução.
O cast não oferece segurança em tempo de execução -- a API pode retornar qualquer coisa.

Qual o benefício de um wrapper genérico de fetch como `fetchJson<T>`?

Centraliza o tratamento de erros (verificação de response.ok, captura de erros de rede).
Cada local de chamada especifica o formato de resposta esperado através do parâmetro de tipo.
Reduz o boilerplate de fetch duplicado entre componentes.

Como o Zod fornece segurança de tipo tanto em tempo de compilação quanto em tempo de execução?

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
});
type User = z.infer<typeof UserSchema>; // tipo derivado
 
const data = UserSchema.parse(json); // validação em tempo de execução

z.infer<typeof Schema> deriva o tipo TypeScript do esquema.
schema.parse(json) lança um ZodError se os dados não corresponderem em tempo de execução.

Armadilha: O cast `as T` oferece alguma proteção em tempo de execução?

Não. as T é uma afirmação apenas em tempo de compilação, sem segurança em tempo de execução.
Se a API mudar seu formato de resposta, seu código falhará silenciosamente até que o acesso a uma propriedade cause um erro.
Para limites críticos de API, use Zod ou um type guard personalizado em vez disso.

Por que o `fetch` não lança erros em respostas 4xx ou 5xx?

fetch só rejeita em falhas de rede (erros de DNS, sem conexão).
Códigos de status de erro HTTP (400, 404, 500) são considerados requisições de rede bem-sucedidas.
Você deve verificar response.ok ou response.status manualmente.

Quando usar um type guard personalizado versus validação Zod?

Type guards personalizados não têm dependências, mas são tediosos e propensos a erros para tipos complexos.
Zod fornece uma única fonte de verdade (esquema = tipo + validação), mas adiciona uma dependência.
Use Zod para limites de API; use type guards para verificações simples e únicas.

Por que os tipos de API devem ser separados dos tipos de domínio?

APIs podem enviar datas como strings, usar snake_case ou incluir campos que seu aplicativo não precisa.
Uma camada de mapeamento converte tipos de API em tipos de domínio (por exemplo, analisando strings de data em objetos Date).
Isso desacopla seu frontend de alterações de esquema de backend.

Como você tipa uma união discriminada para resultados de API (sucesso vs erro)?

type ApiResult<T> =
  | { success: true; data: T }
  | { success: false; error: ApiError };

O campo success atua como o discriminador.
O TypeScript refina o acesso a data e error com base na verificação de success.

Armadilha: O que acontece se você esquecer de lidar com estados de carregamento e erro?

Acessar .data em um estado null causa um erro em tempo de execução.
Sempre modele três estados: carregando, erro e sucesso.
Use uma união discriminada ou variáveis de estado separadas para cada um.

Qual a vantagem de usar `unknown` em vez de `any` para dados não validados?

unknown força você a refinar ou validar antes de acessar propriedades.
any permite silenciosamente todo o acesso a propriedades sem verificações.
Use const data: unknown = await response.json() como ponto de partida para validação.

Tipagem de Respostas de API

Receita

Exemplo de Trabalho

Análise Detalhada

Como Funciona

Variações

Notas do TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

Tipagem de Respostas de API

Receita

Exemplo de Trabalho

Análise Detalhada

Como Funciona

Variações

Notas do TypeScript

Armadilhas

Alternativas

FAQs

Relacionado

Tipagem de Respostas de API

Buscar na documentação

Tipagem de Respostas de API