Jak funguje odvození JSON-to-TypeScript
Odvození je jeden průchod přes parsovaný JSON strom. Nástroj čte každou hodnotu, vybere pro ni TypeScript typ a pak zapíše jedno rozhraní na každý objekt, který našel.
- Parse JSON vzorek nativním parserem prohlížeče a odmítněte chybný vstup s nápovědou řádek/sloupec.
- Zjistěte TypeScript typ pro každou hodnotu —
string,number,boolean,null, pole nebo vnořený objekt. - Dejte každému vnořenému objektu název rozhraní odvozený z klíče rodičovské vlastnosti (takže
user.addressse stane rozhranímAddress). - Slučte typy položek napříč polem, takže seznam
{id: 1}a{id: 2, label: "x"}vytvoří unii se správnými volitelnými poli. - Aplikujte své volby (interface vs. type, readonly, optional-nullable) a vypište deklarace v pořadí závislostí, takže soubor kompiluje bez dopředných referencí.
Proč generovat TypeScript typy z JSON?
- Většina chyb tvaru je chytitelná v čase kompilace, pokud je typ odpovědi zapsán. Odvození rozhraní z reálného payloadu napíše většinu za vás a `strict` mód chytí pole, které dokumentace zapomněla zmínit.
- Párování odvozených rozhraní s runtime validátorem jako Zod nebo io-ts dává stejnému tvaru dvě práce: autocomplete editoru při vývoji a 400 na hranici, když produkce pošle něco neočekávaného.
- Language server TypeScriptu zobrazuje pouze pole, o kterých ví. Jakmile importujete odvozené rozhraní, autocomplete funguje ve chvíli, kdy napíšete tečku — žádné víc `as any` castů na odpovědi a frustrovaného grepování napříč repozitářem.
- Pokud se chystáte psát OpenAPI spec, odvozené rozhraní je rychlý první návrh schématu odpovědi. Stále budete chtít ručně psané příklady a omezení, ale názvy vlastností a typy jsou již správné.
Běžná použití
Odvození pomáhá nejvíce, když reálný payload existuje, ale schéma ne.
- Typování webhook payloadů třetích stran ze Stripe, GitHubu nebo Twilio před psaním handleru.
- Bootstrapování typů pro interní REST API, aby frontend tým mohl začít kódovat proti němu ve stejný den, kdy backend přistane.
- Generování výchozího bodu pro Zod, io-ts nebo Valibot schéma z pozorované API odpovědi.
Jak vypadá výstup?
Pro daný vzorový JSON dokument a název kořene generátor vytvoří strom rozhraní, jedno na vnořený objekt. Pro vstup níže s názvem kořene User:
Vložte {"id":1,"name":"Alice","tags":["a","b"],"address":{"city":"Paris"}} s názvem kořene User a generátor vytvoří:
export interface User {
id: number;
name: string;
tags: string[];
address: Address;
}
export interface Address {
city: string;
}
Všimněte si, že address byl povýšen na vlastní pojmenované rozhraní — to je výstup seřazený podle závislostí. Stejný JSON se stylem deklarace type by místo toho vydal export type User = {...}; s přepnutým readonly má každá vlastnost modifikátor readonly.
Možnosti generátoru
Styl deklarace
Vyberte interface (standardní TypeScript idiom pro tvary objektů) nebo type (užitečné, pokud budete potřebovat mapované typy, podmíněné typy nebo průniky později). Oba produkují identické runtime chování; volba je záležitostí stylu kódování.
Volitelná nullovatelná pole
Když je vzorkovaná hodnota null, typ pole se stává T | null. Zapnutí této volby také přidá modifikátor ?, takže pole je na TypeScript straně volitelné — užitečné, když API někdy klíč zcela vynechá místo vrácení null.
Readonly modifikátor
Přidá readonly před každou deklaraci vlastnosti, takže emitované rozhraní odpovídá neměnnému datovému modelu. Užitečné pro Redux state slice, zmrazené API odpovědi nebo kdekoli, kde chcete, aby kompilátor flagoval náhodnou mutaci.
Podporuje to vnořené objekty a pole?
Ano. Každý vnořený objekt se stává pojmenovaným rozhraním odvozeným z klíče rodičovské vlastnosti a pole odvozují typ položky ze svého obsahu. Pole objektů dostanou rozhraní na každý tvar objektu, s union typy, kde se tvary neshodují.
Jak jsou odvozována volitelná pole?
Zapněte přepínač "Označit nullovatelná pole jako volitelná" a každé pole, jehož vzorkovaná hodnota je null, dostane modifikátor ? na klíč plus | null v typu. Bez přepínače zůstává pole povinné a typ je prostě T | null.
Podporuje to diskriminované unie?
Základní union typy vzniknou, když pole obsahuje položky smíšeného tvaru nebo když pole nese jak hodnotu, tak null. Plné odvození diskriminované unie (výběr type nebo kind jako tagu a rozdělení variant) vyžaduje více vzorků — to je plánováno, ale není v dnešním buildu.
Mohu odvodit typy z více JSON vzorků?
Zatím ne — dnešní inferrer čte jeden vzorek najednou. Pokud máte dva payloady, které by měly sdílet rozhraní (např. list endpoint a single-item endpoint), praktické řešení je sloučit je do jednoho pole, vygenerovat z něj a pak přejmenovat výsledné union typy. Odvození z více vzorků je na roadmapě, protože je to jediný způsob, jak odhalit pole, která jsou přítomna v jedné odpovědi a chybí v jiné.
Vložte payload, pojmenujte kořen, zkopírujte rozhraní. Celý pipeline běží ve vašem prohlížeči, takže nevydané API nebo podepsané webhook tělo zůstává na vašem stroji.