JSON do TypeScript
Generuj interfejsy TypeScript z przykładowego JSON-a.
O tym narzędziu
Wklej odpowiedź JSON i otrzymaj dla niej interfejsy TypeScript. Zagnieżdżone obiekty stają się osobnymi nazwanymi interfejsami, tablice obiektów są scalane, więc pola opcjonalne są oznaczane ?, a wartości mieszane stają się typami unii.
Jak z tego korzystać
- Wklej przykładową odpowiedź JSON ze swojego API.
- Ustaw nazwę typu głównego, np. User lub OrderResponse.
- Wybierz deklaracje interface lub type oraz to, czy je eksportować.
- Skopiuj wygenerowany kod TypeScript do projektu i popraw to, czego próbka nie mogła pokazać.
Pytania
- Jak wykrywane są pola opcjonalne?
- Gdy tablica zawiera kilka obiektów, pole, którego brakuje w niektórych z nich, jest oznaczane jako opcjonalne znakiem ?. Pojedynczy obiekt nie ujawni pól opcjonalnych, więc jeśli możesz, podaj próbkę z kilkoma elementami.
- Dlaczego pole ma typ null?
- Bo w próbce miało wartość null, więc jego prawdziwy typ jest nieznany. Zastąp go czymś w rodzaju string | null, gdy już wiesz, co zwraca API.
- Wybrać interface czy type?
- Oba nadają się do opisu JSON. Interfejsy można rozszerzać i scalać, dają też nieco czytelniejsze komunikaty błędów; aliasy typów są potrzebne do unii. Wybierz to, czego już używa Twój kod.
- Czy sprawdza dane w czasie działania?
- Nie. Typy TypeScript znikają po kompilacji. Aby sprawdzać dane w czasie działania, używaj obok tych typów biblioteki schematów, np. Zod.
- Co się stanie, jeśli korzeniem JSON jest tablica?
- Typ główny staje się aliasem typu tablicowego. Przy nazwie typu głównego User i próbce takiej jak [{"id": 1}] dostajesz type User = UserItem[] oraz interfejs UserItem dla elementów. Nadaj typowi głównemu nazwę w liczbie mnogiej, np. Users, aby zamiast tego dostać type Users = User[].
- Czy mogę wkleić obiekt JavaScript zamiast ścisłego JSON?
- Tak. Apostrofy, klucze bez cudzysłowów, przecinki na końcu oraz pythonowe True, False i None są konwertowane na JSON przed wygenerowaniem typów, więc zadziała wynik skopiowany z console.log w Node albo z powłoki Pythona. Wartości, których JSON nie potrafi wyrazić, takie jak funkcje czy instancje klas, nadal powodują błąd.
- Dlaczego typ elementu tablicy nazywa się DataItem?
- Typy elementów są nazywane przez zamianę klucza tablicy na liczbę pojedynczą: users daje User, a entries daje Entry. Gdy klucz nie ma końcówki liczby mnogiej, jak data czy children, dopisywane jest Item, co daje DataItem i ChildrenItem. Jeśli wolisz inne nazwy, zmień je w edytorze po wklejeniu.
Jak wygenerować interfejsy TypeScript z JSON?
Wklej prawdziwą odpowiedź API, a każdy obiekt JSON stanie się nazwanym interfejsem TypeScript. Nazwy pól są zachowywane, wartości mapowane na string, number i boolean, a zagnieżdżony obiekt dostaje własną deklarację nazwaną od swojego klucza, więc pole address daje interfejs Address. Tablice obiektów są nazywane w liczbie pojedynczej: orders daje Order[], a categories daje Category[]. Ustaw nazwę typu głównego na typ, którego użyje Twój kod, np. User.
Wygenerowany TypeScript kompiluje się bez zmian, więc możesz wkleić go do pliku types.ts albo pobrać. Klucze, które nie są poprawnymi identyfikatorami, takie jak "first-name" czy "2fa", są zapisywane w cudzysłowach. Gdy dwa zagnieżdżone obiekty dostałyby tę samą nazwę, drugi dostaje numer, np. Address2. Pusta tablica staje się unknown[], a pusty obiekt Record<string, unknown>, bo próbka nic nie mówi o ich zawartości.
Jak z JSON wnioskowane są typy union?
Gdy to samo pole zawiera różne rodzaje wartości, jego typ staje się unią. Tablica taka jak [1, "two", null] dostaje typ (string | number | null)[], a pole, które w jednym elemencie jest ciągiem znaków, a w innym liczbą, staje się string | number. Obiekty w tej samej tablicy są scalane w jeden interfejs, a nie w unię kształtów, a pola występujące tylko w niektórych z nich są oznaczane jako opcjonalne.
Scalanie pasuje do list rekordów, ale ukrywa unie tagowane. Jeśli tablica events miesza {"type": "click", "x": 3} i {"type": "key", "code": "Enter"}, dostaniesz jeden interfejs Event z type jako string i opcjonalnymi polami x oraz code. Przepisz go ręcznie jako unię dyskryminowaną dwóch interfejsów, jednego z type: "click" i drugiego z type: "key", aby TypeScript mógł zawężać typ po polu type.
JSON do TypeScript: z próbki czy ze schematu?
Próbka JSON pokazuje jedną odpowiedź, a nie kontrakt. Ciągów, które w rzeczywistości są datami, enumów takich jak "active" | "banned", numerycznych ID, które mogą przekroczyć 2^53, ani pól obecnych tylko czasami nie widać w jednym przykładzie. Traktuj wygenerowane interfejsy jako pierwszy szkic: wklej odpowiedź z kilkoma elementami tablicy, a potem zawęź typy tam, gdzie wiesz więcej, np. zastępując status: string unią dozwolonych wartości.
Jeśli API publikuje dokument OpenAPI albo JSON Schema, generuj typy z niego, bo opisuje każde pole, które serwer może zwrócić. Generowanie typów z JSON to szybka droga dla zewnętrznych API bez specyfikacji, payloadów webhooków i starych wewnętrznych endpointów. Dla danych, których nie kontrolujesz, dodaj walidację w czasie działania o tym samym kształcie, np. schemat Zod, aby zmieniona odpowiedź głośno zgłosiła błąd, zamiast prześlizgnąć się niezauważona.
Coś nie działa albo wynik wygląda na błędny? Zgłoś problem z tym narzędziem