Wejście

Wyjście

Czym jest przeglądarka GraphQL?

Jeśli kiedykolwiek wkleiłeś kawałek GraphQL SDL, który wrócił w jednej linii, i próbowałeś to przeczytać, znasz problem. Typy, pola, argumenty, dyrektywy i członkowie unii zlewają się ze sobą, a struktura znika. To narzędzie to naprawia. Wklej schemat w lewy panel, a prawy renderuje go z wcięciem dwóch spacji, jednym polem na linię, argumentami w linii i opisami w block-stringach umieszczonymi nad typem lub polem, które dokumentują.

Pretty-printer jest pisany ręcznie — żaden pakiet npm graphql nie jest ładowany na stronę, więc pierwsze renderowanie pozostaje lekkie. Tokenizuje SDL, przechodzi po strukturze klamer i wypluwa go z powrotem ze spójnymi odstępami zgodnie ze specyfikacją GraphQL z października 2021. Obsługuje każdą konstrukcję SDL, jaką spotkasz w realu: type, interface, union, enum, input, scalar, extend, schema, modyfikatory listy i non-null ([Foo!]!), wartości domyślne, dyrektywy i opisy w potrójnych cudzysłowach. Już sformatowane wejście wraca niezmienione.

Wszystko działa w twojej przeglądarce. Brak uploadu, schemat nigdzie nie jest zapisywany. Wklejasz, czytasz, kopiujesz.

Jak używać przeglądarki GraphQL

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

Wklej, wgraj lub załaduj przykład

Wklej schemat GraphQL w lewy panel Wejście. Kliknij Wgraj dla pliku .graphql, .graphqls lub .gql, albo naciśnij Przykład, żeby załadować realistyczny schemat e-commerce. Szybki przykład tego, jak wygląda zminifikowany SDL:

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

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

Czytaj sformatowane wyjście

Prawy panel Wyjście renderuje sparsowany SDL z wcięciem dwóch spacji. Każde pole, wartość enuma i członek unii dostaje własną linię. Argumenty pozostają w linii pola, więc sygnatury czyta się naturalnie. Opisy zapisane jako block-stringi ("""...""") trzymają się nad typem lub polem, które opisują, co jest sposobem, jaki specyfikacja GraphQL Relay rekomenduje przy dokumentowaniu schematu. Jeśli SDL ma niezbalansowane klamry albo inne błędy parsowania, przeglądarka wyświetla przyjazny komunikat zamiast paść.

Skopiuj lub pobierz

Naciśnij Kopiuj, żeby zabrać sformatowany schemat do pull requesta, dokumentu albo czatu. Naciśnij Pobierz, żeby zapisać jako .graphql. Przycisk czyszczenia w panelu wejścia resetuje cię do pustego stanu. Parsowanie odbywa się w całości po stronie klienta — twój schemat nigdy nie opuszcza strony.

Kiedy faktycznie tego użyjesz

Review pull requestów ze schematem

Robisz review PR-a ze schematem, a diff jest trudny do czytania, bo plik przeszedł przez generator kodu, który zdarł formatowanie? Wklej tu nową wersję, prześledź strukturę okiem, a potem wracaj do diffa z czystszym modelem mentalnym tego, co się zmieniło. Szczególnie przydatne, kiedy zespół iteruje nad tym, co się liczy jako dobry projekt schematu.

Debugowanie federacji i subgrafów

Debugujesz gateway federacji Apollo i złożony schemat supergrafu wraca jako jeden gigantyczny blok? Wklej zmergowany SDL, znajdź typ, który się dziwnie zachowuje, zobacz, który subgraf wniósł które pole. Dyrektywy federacji, które pojawiają się w wyjściu, są pokazywane razem z resztą składni schematu.

Dokumentowanie API

Piszesz publiczną dokumentację dla GraphQL API utrzymywanego przez twój zespół? Wrzuć schemat w przeglądarkę, skopiuj sformatowaną wersję na wiki albo do README. Drzewiasta forma typów, interfejsów i unii czyta się naturalnie, kiedy jest rozłożona z jednym polem na linię.

Onboarding nowych inżynierów

Nowy członek zespołu próbuje nauczyć się kształtu twojego GraphQL API. Sformatowany schemat z opisami widocznymi nad każdym typem to znacznie przyjaźniejszy punkt startowy niż niesformatowany blok z wyjścia codegenu.

Częste pytania

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

Tylko formatuje. Przeglądarka sprawdza balans klamer i cudzysłowów na tyle, by ładnie wydrukować, ale nie weryfikuje, czy Query istnieje, czy referencjonowane typy są zdefiniowane, ani czy argumenty dyrektyw zgadzają się z ich definicjami. Do pełnej walidacji użyj referencyjnej implementacji graphql-js albo przepuść to przez startupowe checki swojego serwera.

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

Nie. Pretty-printer działa w całości w twojej przeglądarce. Nic się nie wgrywa, nic się nie loguje. Można bezpiecznie wklejać schematy wewnętrzne albo niewydane.

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 niestandardowymi skalarami?

Oba są zachowywane. @deprecated, @key i każda niestandardowa dyrektywa zostają w linii pola. Niestandardowe skalary jak scalar DateTime są wypisywane we własnej linii. Przeglądarka nie próbuje interpretować semantyki dyrektyw — to sprawa twojego serwera.

Czy już sformatowany SDL będzie sformatowany ponownie?

Jest idempotentny — pretty-print już sformatowanego SDL daje to samo wyjście. Więc możesz odpalić przeglądarkę w checku CI albo w workflow „wklej i porównaj” bez zmartwień o dryf białych znaków.

Jak duży schemat mogę wkleić?

Wszystko, co twoja przeglądarka wyrenderuje bez problemu. Schematy z kilkoma setkami typów to żaden problem. Powyżej 5 MB sam edytor Ace zaczyna zwalniać — to jest wąskie gardło, nie parser.

Inne narzędzia GraphQL

Przeglądanie to jedna część pracy z GraphQL. Te narzędzia załatwiają resztę:

Przeglądarka GraphQL