Wejście

Wyjście

Czym jest Formater GraphQL?

Schemat GraphQL, który wyszedł z generatora kodu, composera federacji albo z kopiuj-wklej z okna czatu, prawie nigdy nie ma whitespace’u, jakiego byś chciał. Typy się zlewają, pola dzielą jedną linię, opisy są wciśnięte w następną definicję. Język definicji schematu GraphQL ma być czytelnym kontraktem między frontendem a backendem — ale tylko jeśli rzeczywiście jest sformatowany. Wklej swój SDL do lewego panelu, a prawy zwróci go upiększony: wcięcie dwóch spacji, jedno pole na linię, argumenty inline, a wszelkie opisy w block stringach trzymane nad typem lub polem, które dokumentują.

Pretty-printer jest napisany ręcznie — żaden pakiet npm graphql nie jest ładowany na stronę, więc pierwszy paint pozostaje lekki. Tokenizuje SDL, przechodzi strukturę nawiasów klamrowych i wypluwa go z powrotem ze spójnym odstępem zgodnie ze specyfikacją GraphQL z października 2021. Każda konstrukcja SDL, która pojawia się w prawdziwych schematach, jest obsługiwana: type, interface, union, enum, input, scalar, extend, schema, directive, modyfikatory listy i non-null ([Foo!]!), wartości domyślne, dyrektywy oraz opisy w potrójnych cudzysłowach. Formater jest idempotentny — już ładny SDL wraca bez zmian, więc bez obaw uruchomisz go w gate’cie CI albo pre-commit hooku.

Wszystko działa w twojej przeglądarce. Bez uploadu, bez schematu zapisywanego gdziekolwiek. Wklej, upiększ, skopiuj.

Jak korzystać z Formatera GraphQL

Trzy szybkie kroki. Przyciski opisane poniżej to prawdziwe przyciski na tej stronie.

Wklej, wgraj albo załaduj przykład

Wklej schemat GraphQL do lewego panelu Wejście — formatowanie dzieje się automatycznie ułamek sekundy po tym, jak przestaniesz pisać, więc nie musisz szukać przycisku Convert. Kliknij Wgraj, żeby załadować plik .graphql, .graphqls lub .gql, albo Przykład, żeby załadować realistyczny schemat e-commerce Order. Typowe bałaganiarskie wklejenie wygląda tak:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Działają zarówno schematy server-style (z extend type Query), jak i samodzielne definicje typów. Akceptowane formy odpowiadają temu, co narzędzia takie jak Apollo Server parsują przy starcie.

Przeczytaj upiększone wyjście

Prawy panel Wyjście renderuje upiększony SDL z wcięciem dwóch spacji. Każde pole, wartość enuma i element union dostaje swoją linię. Argumenty zostają inline w linii pola, żeby sygnatury czytało się naturalnie. Opisy zapisane jako block stringi ("""...""") są trzymane nad typem lub polem, które opisują — tak specyfikacja GraphQL Relay zaleca dokumentowanie schematu. Jeśli SDL ma niesparowane nawiasy klamrowe albo inny błąd parsowania, formater wyświetla przyjazny komunikat inline — nigdy nie rzuca wyjątku ani się nie wywala.

Skopiuj albo pobierz

Kliknij Kopiuj, żeby zabrać sformatowany schemat do pull requesta, dokumentu lub czatu. Kliknij Pobierz, żeby zapisać jako .graphql. Przycisk czyszczenia w panelu wejściowym przywraca pusty stan. Formatowanie odbywa się w pełni po stronie klienta — twój schemat nigdy nie opuszcza strony.

Kiedy naprawdę z tego skorzystasz

Czytelność w PR review

Kolega z zespołu otwiera PR, który dodaje pięć nowych typów do twojego schematu. Diff wygląda jak jeden wielki blok, bo output codegenu zjadł formatowanie. Przepuść plik przez formater, a upiększoną wersję wklej do opisu PR, żeby reviewerzy naprawdę mogli przeczytać, co jest dodawane. Trzymanie się dobrych praktyk schematów GraphQL jest dużo łatwiejsze, kiedy reviewerzy widzą strukturę.

Diffy w schema registry

Większość schema registry (Apollo Studio, GraphQL Hive, Hasura) pokazuje diffy jako tekst linia po linii. Jeśli jedna rewizja była zminifikowana, a kolejna ładna, każda linia wygląda na zmienioną i prawdziwa zmiana ginie w szumie. Upiększ obie wersje przed uploadem — ten sam formater, ten sam output, prawdziwy diff.

Dokumentacja i onboarding

Piszesz publiczną dokumentację GraphQL API albo onboardujesz nowego inżyniera? Wklej schemat, skopiuj sformatowaną wersję na wiki lub do README. Schemat z widocznymi opisami nad każdym typem to dużo bardziej przyjazny punkt startu niż pozbawiony formatowania klops, który wypluło narzędzie codegenu.

Pre-commit i CI gate

Skoro formater jest idempotentny, możesz go uruchamiać jako pre-commit hook albo CI check: sformatuj schemat, zwal builda, jeśli wynik różni się od scommitowanego pliku. Koniec z whitespace driftem między kontrybutorami i koniec z PR-ami, gdzie połowa diffu to szum z reformatowania.

Częste pytania

Czy waliduje mój schemat, czy tylko go formatuje?

Tylko formatuje. Formater sprawdza balans nawiasów i cudzysłowów na tyle, żeby pretty-print zadziałał, ale nie weryfikuje, czy Query istnieje, czy referencowane typy są zdefiniowane ani czy argumenty dyrektyw zgadzają się z ich definicjami. Po pełną walidację puść swój schemat przez referencyjną implementację graphql-js albo przez startup checki swojego serwera.

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

Nie. Formatowanie działa w całości w twojej przeglądarce. Nic nie jest wysyłane, nic nie jest logowane. Bezpiecznie wklejać schematy wewnętrzne lub jeszcze nieopublikowane.

Czy obsługuje opisy w block stringach?

Tak. Opisy w potrójnych cudzysłowach ("""Zamówienie złożone przez klienta.""") są zachowywane i wypisywane w linii nad typem lub polem, które dokumentują. To kanoniczny sposób pisania dokumentacji SDL według specyfikacji GraphQL.

A co z dyrektywami i custom scalar?

Oba są zachowywane. @deprecated, @key i każda custom dyrektywa pozostają inline przy polu. Custom scalary jak scalar DateTime trafiają do własnej linii. Formater nie próbuje interpretować semantyki dyrektyw — to robota twojego serwera.

Czy już sformatowany SDL będzie reformatowany?

Jest idempotentny — upiększanie już upiększonego SDL daje ten sam output. Możesz więc puszczać formater w CI checku albo workflowie wklej-i-porównaj bez obawy o whitespace drift.

Jak duży schemat mogę wkleić?

Tyle, ile twoja przeglądarka komfortowo wyrenderuje. Schematy z kilkoma setkami typów to żaden problem. Powyżej 5 MB sam edytor Ace zaczyna zwalniać — wąskie gardło jest tam, nie w parserze.

Inne narzędzia GraphQL

Formatowanie to tylko część pracy z GraphQL. Te narzędzia ogarniają resztę: