GraphQL SDL

TypeScript

Co robi ten konwerter

Masz schemat GraphQL. Twój frontend to TypeScript. Gdzieś pomiędzy potrzebujesz zestawu typów, który zgadza się ze schematem pole po polu, i potrzebujesz ich teraz — nie po pięciominutowym buildzie codegen, nie po podpięciu graphql-code-generator w świeżym projekcie, nie po tłumaczeniu juniorowi, jaki plugin zainstalować. Wklej GraphQL SDL do lewego panelu, a prawy zwróci idiomatyczny TypeScript: interface dla typów object i input, enum dla enumów, zwykłe aliasy type dla unionów i skalarów.

Mapowanie idzie zgodnie z regułami, których oczekuje większość kodu TypeScript. Wbudowane skalary układają się na odpowiednikach prymitywnych w TypeScript: String i ID stają się string, Int i Float stają się number, Boolean staje się boolean. Skalary własne, jak DateTime, domyślnie spadają na string ze znacznikiem // custom scalar, żebyś pamiętał je później rozszerzyć. Pola non-null (name: String!) wychodzą jako wymagane property; pola nullable wychodzą z modyfikatorem ?. Typy listowe [Order!]! stają się Order[]. type Order implements Node staje się interface Order extends Node — relacja interface w GraphQL mapuje się czysto na strukturalne extends w TS.

Bez wgrywania, bez sieci, bez AI. Konwersja dzieje się po stronie klienta w ręcznie napisanym tokenizerze SDL — twój schemat nigdy nie opuszcza strony, czyli dokładnie to, czego chcesz, kiedy schemat jest wewnętrzny lub przed publikacją.

Jak tego używać

Trzy kroki. Konwersja jest automatyczna — bez przycisku Convert.

Wklej, wgraj albo wczytaj przykład

Wrzuć swoje SDL do lewego panelu GraphQL SDL. Jak tylko przestaniesz pisać, prawy panel się odświeża. Kliknij Wgraj dla pliku .graphql / .graphqls / .gql, albo Przykład, żeby załadować realistyczny schemat e-commerce. Mały kawałek SDL wygląda tak:

type Order implements Node { id: ID! placedAt: DateTime! status: OrderStatus! items: [OrderItem!]! } enum OrderStatus { PENDING PAID SHIPPED DELIVERED CANCELLED }

Działają zarówno schematy w stylu serwerowym (z extend type Query), jak i samodzielne definicje typów. Opisy w block-stringach ("""...""") są wyłapywane i emitowane jako komentarze JSDoc nad wygenerowanym typem — to konwencja, którą dokumentuje referencyjna implementacja GraphQL.

Czytaj wygenerowany TypeScript

Prawy panel emituje typy pogrupowane według rodzaju: najpierw skalary, potem enumy, uniony, interfejsy, typy input, a na końcu typy object. W obrębie każdej grupy definicje pozostają w kolejności źródłowej, więc diff względem twoich ręcznie napisanych typów jest tak mały, jak to możliwe. Jeśli SDL ma błąd parsowania (niezbalansowane nawiasy klamrowe, niedomknięty block-string itd.), panel wyjścia pokazuje pojedynczy komentarz // Invalid GraphQL: ... zamiast rzucać wyjątek — to ten sam wzorzec, którego używa Apollo Server, kiedy parsowanie startowe mu pada.

Skopiuj albo pobierz

Wciśnij Kopiuj, żeby wkleić typy prosto do pliku schema.types.ts w projekcie. Wciśnij Pobierz, żeby zapisać je jako plik .ts. Wyjście to czysty tekst — żadnych importów modułów, żadnego runtime — pasuje do dowolnego projektu TS, frontendowego lub backendowego.

Kiedy faktycznie tego użyjesz

Szybkie typy bez stawiania codegen

Prototypujesz frontend pod istniejący endpoint GraphQL i nie chce ci się rozkręcać pełnego pipeline’u codegen tylko po to, żeby mieć typy do trzech zapytań. Wklejasz schemat, kopiujesz wyjście do types.ts, wypuszczasz prototyp. Na porządny pipeline codegen przesiądziesz się później, jak projekt zrobi się prawdziwy.

Sanity-check tego, co wypluje codegen

Zanim dorzucisz nowy typ do schematu, wklej proponowane SDL tutaj, żeby zobaczyć, jaką postać przyjmą twoi konsumenci po stronie TypeScripta. Czasem pole, które dobrze się czyta w SDL, daje nieprzyjemny TS — opcjonalna lista nullable’i, enum z wartością kolidującą z zarezerwowanym słowem TS — i o wiele taniej wyłapać to tutaj niż po zmergowaniu PR-a.

Dokumentacja schematu dla zespołu skupionego na TypeScript

Onboarding zespołu TS-first do API GraphQL? Wklej schemat, skopiuj wygenerowane typy do wiki. Inżynierowie myślący w interfejsach TS łapią schemat szybciej z widoku TS niż z surowego SDL — kształty danych są te same, składnia to po prostu ta, którą czytają płynnie codziennie.

Jednorazowe skrypty walące w endpoint GraphQL

Jednorazowy CLI, skrypt w Node, zadanie admina — cokolwiek, gdzie chcesz mieć trochę typów wokół odpowiedzi bez angażowania się w pełny setup codegen. Wklej, skopiuj, otypuj odpowiedź, odpal skrypt. Jednorazówka, ale na tyle otypowana, żeby się nie skompromitować.

Częste pytania

Czy generuje typy operacji (typy wyników Query / Mutation), czy tylko typy schematu?

Tylko typy schematu — typy zadeklarowane w SDL. Typy wyniku operacji zależą od konkretnej kwerendy lub mutacji uruchamianej przez klienta i właśnie do tego jest graphql-code-generator z pluginem typed-document-node. Ta strona ogarnia połówkę schematu: każdy type, interface, enum, input, union i scalar w twoim SDL staje się deklaracją TS.

Jak są obsługiwane pola nullable vs non-null?

Pola non-null (name: String!) wychodzą jako wymagane, nieopcjonalne property TS: name: string;. Pola nullable (name: String) wychodzą jako opcjonalne: name?: string;. Wyjście pozostaje czyste — bez unionów | null wszędzie — czego chce większość konsumentów. Jeśli wolisz strict null checks, przepuść wyjście przez find-and-replace.

A typy listowe jak [Order] albo [Order!]!?

Listy stają się tablicami TS. [Order!]! wychodzi jako Order[] przy wymaganym polu. [Order] wychodzi jako Order[] przy opcjonalnym polu. Nullability na poziomie elementu jest spłaszczana dla czytelności — jeśli musisz ją zachować, ręcznie zmień wygenerowane T[] na (T | null)[], ale w praktyce prawie żadna prawdziwa codebase nie czyta wewnętrznej nullability osobno.

Jak obsługiwane są skalary własne?

Skalary własne (cokolwiek poza ID, String, Int, Float i Boolean) domyślnie spadają na string ze znacznikiem // custom scalar, żeby łatwo się je znajdowało i rozszerzało. Dla skalara DateTime możesz rozszerzyć do string | Date; dla skalara JSON do unknown albo do otypowanej formy. Domyślny string pasuje do tego, co większość serwerów wysyła po sieci jako JSON.

Czy mój schemat jest wysyłany na serwer?

Nie. Konwersja dzieje się w całości w twojej przeglądarce — SDL jest tokenizowany po stronie klienta, a wyjście TypeScript renderowane bezpośrednio w prawym panelu. Nic nie jest wgrywane, nic nie jest logowane. Bezpiecznie wklej schematy wewnętrzne lub niepublikowane.

Czy wyjście wraca w round-tripie do tego samego SDL?

Nie — i nie to jest celem. Wyjście to TypeScript, czyli inny język. Wklejenie wyjścia TS z powrotem do panelu SDL da błąd parsowania. Jeśli chcesz sformatować swoje GraphQL SDL, użyj GraphQL Formattera podlinkowanego niżej; jest do tego stworzony.

Inne narzędzia GraphQL

Generowanie typów to jeden kawałek. Te narzędzia ogarniają resztę pracy z GraphQL:

Schemat GraphQL na TypeScript