Generator interfejsów TypeScript

Generator interfejsów TypeScript z JSON

TypeScript dodaje do JavaScriptu statyczne typy. Zamiast ręcznie opisywać odpowiedź API, wklej przykładowy JSON, a generator utworzy gotowe interfejsy.

Jak powstają typy?

Zalety typowania

• Błędy wychwytywane już na etapie kompilacji.
• Autouzupełnianie w edytorze dla pól obiektu.
• Bezpieczniejszy refaktor — zmiana typu pokaże wszystkie miejsca do poprawy.
• Lepsza dokumentacja kontraktu API.

Jak generator zamienia JSON na interfejsy TypeScript

Generator działa na zasadzie wnioskowania typu z jednego przykładu danych. Najpierw parsuje wklejony JSON do drzewa wartości: obiektów, tablic, tekstów, liczb, wartości logicznych i null. Następnie przechodzi to drzewo od korzenia i dla każdego klucza ustala typ w TypeScript. Jeśli wartość jest obiektem, tworzy osobny interfejs i wstawia w miejscu użycia nazwę tego interfejsu. Jeśli wartość jest tablicą, sprawdza typ elementów i zapisuje go jako T[]. W kodzie narzędzia nie ma tablic stałych, więc nie ma wbudowanego słownika typów ani wyjątków. Wynik zależy wyłącznie od wklejonego JSON-a.

Kluczowa zasada jest prosta: typ opisuje tylko to, co widać w przykładzie. Generator nie zgaduje intencji, lecz odtwarza strukturę danych. Obiekty są rozwijane do osobnych interfejsów, a tablice do typu elementu z nawiasami kwadratowymi. Nazwy interfejsów są zwykle tworzone od nazwy klucza, z zachowaniem poprawnej składni identyfikatora. Warto je przejrzeć, bo automatyczne nazwy mogą nie pasować do konwencji projektu. To podejście sprawdza się przy prostych odpowiedziach API, ale wymaga korekty przy bardziej złożonych kontraktach.

Wnioskowanie z jednej próbki ma ograniczenia. Generator nie wie, czy pole może zniknąć, czy może przyjąć inny typ, ani czy null jest dopuszczalny. Dlatego po wygenerowaniu kodu często trzeba dodać znak zapytania, unię typów albo alias. Sam mechanizm jest jednak deterministyczny: te same dane wejściowe dają ten sam wynik, a każda zmiana JSON wpływa na kształt interfejsów. Warto więc traktować generator jako szybki sposób na szkic typów, a nie jako źródło prawdy o kontrakcie API.

Przykład krok po kroku

1. Wklej do pola przykładowy JSON: { "id": 1, "name": "Anna", "active": true, "address": { "city": "Kraków", "zip": "30-001" }, "tags": ["nowy", "klient"] }.
2. Generator rozpoznaje obiekt główny i tworzy dla niego interfejs, np. Root. W nim znajdą się pola: id, name, active, address oraz tags.
3. Pola id, name i active są mapowane na number, string i boolean. To trzy właściwości proste, które nie wymagają osobnego interfejsu.
4. Pole address jest obiektem zagnieżdżonym, więc generator tworzy osobny interfejs Address z polami city i zip. W interfejsie Root pojawia się odwołanie address: Address.
5. Pole tags jest tablicą tekstów, więc otrzymuje typ string[]. Nazwa interfejsu elementu nie jest potrzebna, bo elementem jest typ prosty.
6. Wynik zawiera dwa interfejsy i siedem właściwości: Root ma pięć pól (id, name, active, address, tags), a Address ma dwa pola (city, zip). Po wklejeniu do projektu wystarczy dodać opcjonalność lub unie tam, gdzie API może zwrócić inny kształt.

Tabela referencyjna: przypadki w JSON i typy w TypeScript

Praktyczne wskazówki

• Wklej reprezentatywny JSON. Im więcej wariantów pól w próbce, tym mniej ręcznych poprawek. Jeśli API zwraca różne kształty, przygotuj przykład obejmujący najważniejsze przypadki, ale pamiętaj, że generator i tak wnioskuje typ z jednego zestawu danych.
• Dodawaj opcjonalność ręcznie. Generator nie zgadnie, które pola mogą być pominięte. Po wygenerowaniu przejrzyj kontrakt i oznacz znakiem zapytania pola, które nie zawsze występują w odpowiedzi API.
• Ujednolicaj nazwy interfejsów. Automatyczne nazwy od kluczy mogą być poprawne składniowo, ale niepasujące do projektu. Zmień je na takie, które wynikają z domeny, np. User, Address, ApiResponse.
• Traktuj wynik jako punkt startowy. Wygenerowany kod warto porównać z dokumentacją API i testami. Typy z próbki nie zastępują walidacji danych w czasie działania ani nie chronią przed błędnym JSON-em z serwera.
• Uważaj na null i unie. Jeśli pole bywa null albo ma różne typy, popraw typ ręcznie. W TypeScript lepiej opisać rzeczywisty zakres wartości niż zawęzić go do jednej próbki.

Ograniczenia i co zaburza wynik

• Brak wielu próbek. Narzędzie wnioskuje typ z jednego wklejonego JSON-a. Jeśli inne odpowiedzi API mają inne pola lub typy, wygenerowany interfejs może być niekompletny i wymaga scalenia z pozostałymi wariantami.
• Brak wiedzy o opcjonalności. Z jednego obiektu nie wynika, czy pole może zniknąć. Wszystkie pola są traktowane jako obecne, dopóki nie oznaczysz ich ręcznie znakiem zapytania.
• Brak reguł biznesowych. Generator nie rozpozna, że string jest datą, adresem e-mail, identyfikatorem UUID ani że liczba ma określony zakres. To trzeba opisać osobno, najlepiej w komentarzu lub typie pomocniczym.
• Puste tablice i null. Pusta tablica nie mówi, jaki typ będzie miał element. Wartość null nie mówi, czy pole może być null na stałe, czy tylko w jednym przypadku. Wynik wymaga ręcznej weryfikacji i często dodania unii.

Najczęstsze pytania