Validace API v runtime s Zod a TypeScript

Validace API odpovědí za běhu: Proč TypeScript nestačí

TypeScript poskytuje kontrolu typů pouze ve fázi kompilace. Za běhu data z API přicházejí bez záruky souladu s rozhraními. Bez dodatečné validace se nesrovnalosti projevují jako chyby u uživatelů: nedefinovaná pole, nesprávné typy, chybějící objekty.

Problémy bez runtime kontroly

Rozhraní TypeScript vytvářejí falešný pocit kontroly. Příklad typického kódu bez validace:

interface User {
  id: number;
  name: string;
  email: string;
}

const getUser = async (): Promise<User> => {
  const res = await fetch('/api/user');
  return res.json(); // Není kontrola skutečných dat
};

TypeScript důvěřuje anotaci, ignoruje skutečnou odpověď serveru. Hlavní rizika:

• Změna struktury na backendu: full_name → fullName vede k undefined.
• Nesoulad typů: řetězec "123" místo number 123 způsobí zřetězení místo sčítání.
• Podmíněná pole: address chybí v edge případech, pád na user.address.city.
• Externí API se zastaralou dokumentací.

Knihovny pro validaci schémat

Řešení — knihovny pro runtime kontrolu schémat. Parsují skutečná data a vyhazují chyby při nesouladu. Populární možnosti v TypeScriptu:

• Zod: odvozuje typy ze schémat, široká ekosystém.
• Yup: integrace s Formik.
• Valibot: optimalizace balíčku, tree-shaking.
• Joi: z Node.js, orientovaný na backend.
• ArkType: zaměření na výkon.

Implementace s Zod

Zod kombinuje schéma, typy a validaci. Příklad pro User:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

const getUser = async (): Promise<User> => {
  const res = await fetch('/api/user');
  const data = await res.json();
  return UserSchema.parse(data); // Chyba při nesouladu
};

Metoda parse() vyhodí ZodError s detaily při neúspěchu. Alternativa safeParse() vrací objekt s success a error.

Škálování v projektech

Ve velkých aplikacích vytvářejte centralizovaná schémata pro všechny endpointy. Integrujte s fetch obálkami:

const apiFetch = async <T>(url: string, schema: z.ZodSchema<T>): Promise<T> => {
  const res = await fetch(url);
  const data = await res.json();
  return schema.parse(data);
};

const users = await apiFetch('/api/users', z.array(UserSchema));

Zpracování chyb: logujte do Sentry, zobrazujte uživatelsky přívětivé zprávy. Pro pole kontrolujte každý prvek.

• Používejte z.array(UserSchema) pro seznamy.
• z.union() pro polymorfní odpovědi.
• z.lazy() pro rekurzivní struktury.
• z.transform() pro normalizaci dat.

Co je důležité

• TypeScript nezaručuje typy za běhu pro externí data: API, localStorage, URL parametry.
• Validace schémat odhalí nesoulady okamžitě, snižuje čas na ladění.
• Zod — standard pro frontend: typy ze schémat, jednoduchá integrace.
• V týmech s nezávislým backendem validace předchází tichým selháním.
• Škálujte přes fetch obálky pro jednotnost.

Runtime validace doplňuje TypeScript, uzavírá mezeru mezi kompilací a prováděním. V produkci minimalizuje chyby z nesynchronizovaných API kontraktů.

— Editorial Team