Kluczowe punkty
- 01Formatuje zapytania, mutacje, subskrypcje i schematy SDL przy użyciu oficjalnego parsera graphql.js.
- 02Waliduje składnię i podaje dokładny numer wiersza i kolumny błędu — nie wymaga schematu.
- 03Komentarze GraphQL (#) są usuwane podczas formatowania; użyj ciągów opisowych, aby zachować dokumentację.
- 04Działa całkowicie w przeglądarce — wewnętrzne zapytania API i prywatne schematy pozostają poufne.
Dlaczego warto formatować dokumenty GraphQL?
Zapytania GraphQL mogą szybko się skomplikować — zagnieżdżone fragmenty, zmienne inline, wiele definicji operacji i definicje typów SDL z interfejsami i dyrektywami. Spójne formatowanie przyspiesza przegląd kodu i ułatwia dostrzeżenie brakujących nawiasów lub niedopasowanych argumentów na pierwszy rzut oka.
Formatter wykorzystuje referencyjny parser graphql.js — ten sam parser, który jest dostarczany ze specyfikacją GraphQL. Oznacza to, że kanoniczne formatowanie, które otrzymujesz tutaj, odpowiada temu, co generuje wtyczka GraphQL Prettier i większość narzędzi GraphQL. Wszystko, co parsuje się tutaj bez błędów, będzie parsować się prawidłowo w Apollo, Relay i graphql-request.
Jak sformatować dokument GraphQL
- 01
Wklej swój GraphQL
Wklej zapytanie, mutację, subskrypcję, fragment lub definicję schematu SDL do panelu wejściowego.
- 02
Kliknij Formatuj
Parser emituje dokument z kanonicznym wcięciem — dwuspacyjowe wcięcie, jedno pole na linię, spójne wyrównanie argumentów. Wynik pojawia się w panelu wyjściowym.
- 03
Opcjonalnie zwaliduj
Kliknij Waliduj, aby potwierdzić, że dokument parsuje się bez błędów. Wynik to potwierdzenie lub lista błędów składni z numerami wierszy i kolumn.
- 04
Skopiuj wynik
Kliknij Kopiuj, aby skopiować sformatowany dokument. Wklej go do swojego kodu, opisu PR lub pliku dokumentacji.
Bezpieczne dla wewnętrznych schematów i zapytań API
Parser graphql.js działa całkowicie w Twojej przeglądarce. Żaden tekst operacji ani definicja schematu nie jest wysyłana na żaden serwer. To czyni go bezpiecznym do formatowania zapytań, które odwołują się do prywatnych nazw pól lub wewnętrznych systemów typów, które nie chcesz ujawniać narzędziom stron trzecich.
Walidacja tutaj jest tylko składniowa — narzędzie sprawdza, czy dokument jest prawidłowym dokumentem GraphQL, ale nie sprawdza, czy nazwy pól istnieją w rzeczywistym schemacie, czy zmienne pasują do typów argumentów, czy dyrektywy są stosowane prawidłowo. Walidacja świadoma schematu wymaga załadowania docelowego schematu wraz z dokumentem.
Często zadawane pytania dotyczące formattera GraphQL
Czy formatowanie GraphQL waliduje względem schematu?
Nie — tylko walidacja składni. Sprawdzenie, czy pola i argumenty istnieją, wymaga docelowego schematu. To narzędzie potwierdza, że dokument jest prawidłowym dokumentem GraphQL, nic więcej.
Czy komentarze w moim GraphQL będą zachowane?
Nie. Linie zaczynające się od # są usuwane przez parser. Użyj potrójnych cudzysłowów dla dokumentacji, która powinna przetrwać formatowanie.
Która wersja specyfikacji GraphQL jest obsługiwana?
Specyfikacja z października 2021 r., w tym obiekty wejściowe OneOf i dyrektywa @specifiedBy.
Czy mogę formatować definicje schematu SDL, a nie tylko dokumenty operacji?
Tak. Definicje typów, deklaracje interfejsów, typy unii, wyliczenia, dyrektywy i opisy prawidłowo przechodzą przez formatter.
Czy zapytanie lub schemat są przesyłane gdziekolwiek?
Nie. Parser graphql.js działa całkowicie w Twojej przeglądarce — nic nie opuszcza Twojego urządzenia.