Wejście

Wyjście

Czym jest Formater Zapytań GraphQL?

Każde napisane ręką zapytanie GraphQL zaczyna się jako jednoliniowa ściana klamerek. Wklejenie go w code review bez wcześniejszego sformatowania to pewny sposób, by jako pierwszy komentarz dostać "sformatuj proszę". To samo dotyczy zapytań, które wypluwa build frontendu, loguje serwer albo lądują w wątku Slacka, kiedy kolega pyta "czemu to zwraca null?". Ta strona bierze zapytanie, mutację, subskrypcję lub fragment i upiększa: wcięcie dwoma spacjami, jedno pole na linię, argumenty inline gdy się mieszczą, zmienne uporządkowane oraz gramatyka operacji ze specyfikacji GraphQL respektowana od początku do końca.

Pamiętaj, że ta strona to operacyjny odpowiednik GraphQL Formattera. Tamto narzędzie formatuje schema definition language — twoje type Order, interface Node, enum Status. To narzędzie formatuje to, co wysyła twój klient i co odbiera twój serwer: query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutacje, subskrypcje i definicje fragmentów. Obie gramatyki dzielą tokeny, ale zasady strukturalne są inne — selection sety, aliasy, fragment spready, inline fragmenty i zastosowania dyrektyw są tylko po stronie operacji. Jeśli przez pomyłkę wkleiłeś SDL, idź zamiast tego do formattera schematu.

Formatowanie napisane ręcznie w TypeScripcie — żaden bundle graphql-js nie jest ładowany do strony, więc pierwszy paint pozostaje lekki. Wyjście odpowiada temu, co dla typowych przypadków produkuje Prettier z wtyczką GraphQL, więc wrzucenie sformatowanego zapytania do bazy kodu, która już używa Prettiera, nie powinno wygenerować diffa. Wszystko działa lokalnie — twoje zapytanie nigdy nie opuszcza przeglądarki.

Jak Korzystać z Formatera Zapytań GraphQL

Trzy kroki. Nie ma przycisku Convert — formatowanie odpala się automatycznie chwilę po tym, jak przestaniesz pisać.

Wklej, Wgraj lub Załaduj Przykład

Wklej operację GraphQL w lewy panel Wejście. Kliknij Wgraj, aby załadować plik .graphql lub .gql, albo Przykład, aby zobaczyć realistyczne e-commerce zapytanie OrderDetails plus mały fragment. Typowe rozjechane wklejenie wygląda tak:

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

Formater radzi sobie z każdą konstrukcją operacji, jaka pojawia się w prawdziwym kodzie klienta: definicjami zmiennych z wartościami domyślnymi, wartościami domyślnymi typu lista, dyrektywami @include / @skip / własnymi, aliasami, fragment spreadami (...Money) i inline fragmentami (... on PaidOrder { ... }). Wiele operacji lub fragmentów w jednym dokumencie pozostaje rozdzielonych, z pustą linią pomiędzy — tak Apollo Client i większość narzędzi GraphQL spodziewa się układu dokumentów.

Przeczytaj Upiększone Wyjście

Prawy panel Wyjście renderuje sformatowaną operację. Każde pole dostaje własną linię. Argumenty pozostają inline, gdy pole mieści się w 80 znakach, i przechodzą do osobnych linii, gdy nie — taka sama zasada jak w pluginie GraphQL Prettiera. Definicje zmiennych podlegają tej samej zasadzie w nagłówku operacji. Aliasy zachowują pojedynczą spację po dwukropku (aliasedAs: fieldName). Komentarze (# ...) są zachowane na wcięciu linii, do której były przypięte. Jeśli wejście jest popsute — niedopasowane klamry, samotny $, brakujący : — formater wpisuje przyjazny błąd inline zamiast rzucać wyjątkiem.

Skopiuj lub Pobierz

Naciśnij Kopiuj, aby zabrać sformatowane zapytanie do PR-a, doca lub wiadomości na czacie. Naciśnij Pobierz, aby zapisać jako query.graphql. Clear resetuje wejście. Cały pipeline jest po stronie klienta — przydatne, gdy debugujesz zapytanie do wewnętrznego API i wolisz nie wklejać go w narzędzie zewnętrzne.

Kiedy Naprawdę Się to Przyda

Code Review i Higiena PR-ów

Frontendowy PR dodaje nową mutację. String zapytania powstał w kroku build, który zdjął whitespace, i teraz diff to ściana 400 znaków. Przepuść mutację przez formater, wrzuć upiększoną wersję do opisu PR-a, a recenzent w końcu zobaczy, jakie pola czytasz. Ten sam trik działa dla graphql-react, urql, Relay i każdego innego klienta, gdzie zapytania siedzą inline jako template literale.

Debugowanie Zapytania na Produkcji

Zapytanie na produkcji zwraca null dla pola, którego się spodziewałeś. Bierzesz body requesta z zakładki sieciowej, wklejasz tutaj i już widzisz wartości zmiennych, które pola używają @include i gdzie lądują fragment spready. Lepsze niż mrużenie oczu na jedną długą linię. Połącz z oficjalnym przewodnikiem o serwowaniu GraphQL przez HTTP, gdy musisz ręcznie odtworzyć request curl-em lub Postmanem.

Nauka i Onboarding

Jesteś nowy w operacjach GraphQL? Wklej zapytanie znalezione w tutorialu, sformatuj — struktura staje się oczywista: nagłówek operacji, selection set, zagnieżdżone selection sety, definicje fragmentów na końcu. Wyjście odzwierciedla układ, jaki zobaczysz w przewodniku po zapytaniach na graphql.org, więc łatwo zmapować z powrotem do dokumentacji w trakcie nauki.

Pre-commit i Bramki CI

Ponieważ formater jest deterministyczny — już upiększone zapytania wracają niezmienione — możesz używać tej strony jako szybkiego sprawdzenia "czy moje zapytanie jest już ładne?" przed commitem. Dla w pełni automatycznego pipeline'u przepuść to samo źródło przez Prettiera z pluginem GraphQL i zwal build na niezerowym diffie. Ten sam pomysł, tylko w skali.

Częste Pytania

Czym to się różni od strony GraphQL Formatter?

Strona GraphQL Formatter formatuje schema definition language — twoje deklaracje type, interface, enum, union, scalar i directive. Ta strona formatuje operacje: query, mutation, subscription i fragment. Obie gramatyki dzielą tokeny, ale mają bardzo różne zasady strukturalne, więc próba sformatowania operacji na stronie schematu (lub odwrotnie) daje pomieszane wyjście. Wybierz właściwe narzędzie do tego, co wkleiłeś.

Czy waliduje moje zapytanie wobec schematu?

Nie. Formater sprawdza balans klamr, nawiasów i nawiasów kwadratowych na tyle, by móc pretty-printować, ale nie zna twojego schematu, więc nie powie ci, że order przyjmuje id: ID!, a nie id: Int!. Po prawdziwą walidację puść swoją operację przez startupowe sprawdzenia serwera albo przez referencyjny walidator graphql-js z linku do GitHuba powyżej.

Czy moje zapytanie jest wysyłane do serwera?

Nie. Formatowanie to czysty JavaScript po stronie klienta — nic nie jest wysyłane, nic logowane. Bezpieczne dla wewnętrznych zapytań, zapytań z wrażliwymi wartościami zmiennych albo zapytań do prywatnych API.

Czy ruszy moje wartości zmiennych albo argumenty?

Nie. Wartości argumentów, wartości domyślne i wartości domyślne typu lista są wypisywane dokładnie tak, jak je napisałeś, jedynie ze spójnym odstępem wokół :, = i ,. Formater nigdy nie wymyśla, nie usuwa ani nie przestawia pól, argumentów ani zmiennych — to, co wkleiłeś, wychodzi, tylko poukładane czysto.

Czy radzi sobie z inline fragmentami i fragment spreadami?

Tak. Inline fragmenty (... on PaidOrder { ... }) dostają standardowe traktowanie selection set z wcięciem dwoma spacjami. Fragment spready (...Money) siedzą w jednej linii na wcięciu pola, dyrektywy zostają w tej samej linii. Wiele definicji fragmentów w jednym dokumencie zostaje osobnymi definicjami najwyższego poziomu z pustą linią pomiędzy.

A anonimowe zapytania — <code>{ field }</code> — czy rozwija je do <code>query { field }</code>?

Nie. Forma skrócona to część specyfikacji i formater zachowuje ją bez zmian. Jeśli chcesz nazwane zapytanie, sam je nazwij — formater nie przepisuje operacji po cichu.

Inne Narzędzia GraphQL

Formater zapytań to wycinek pracy z GraphQL. Inne narzędzia GraphQL na stronie: