Wejście

Wyjście

Czym jest Minifikator GraphQL?

Kiedy wysyłasz schemat GraphQL jako część artefaktu deployu, paczki Lambda lub łańcucha SDL serwowanego z CDN, opisy i komentarze `#` szybko się sumują. Realny schemat produkcyjny może bez problemu mieć 40-60% bajtów w postaci dokumentacji — przydatne, gdy czytają go ludzie, martwy ciężar gdy idzie po sieci, by uruchomić klienta. Specyfikacja GraphQL definiuje komentarze, opisy w blokach i większość białych znaków jako tokeny ignorowane, co znaczy, że każdy rozsądny parser i tak je pomija. Ten minifikator usuwa to wszystko i zwraca jednoliniowy SDL, który z punktu widzenia parsera jest co do bajtu równoważny oryginałowi.

Minifikator napisany jest ręcznie — żaden pakiet npm graphql nie ląduje na stronie, więc pierwsze rysowanie pozostaje lekkie. Tokenizuje SDL, odrzuca każdy token komentarza i opisu w bloku, a następnie ponownie emituje tokeny strukturalne z absolutnym minimum białych znaków potrzebnych, by sąsiednie tokeny name pozostały rozróżnialne (jedyne miejsce, gdzie SDL zgodny ze specyfikacją naprawdę potrzebuje spacji). Wynik weryfikuje ten sam lekki parser, który napędza formatter, więc round-trip przez graphql-js lub Apollo Server przy starcie zachowuje się identycznie jak z oryginałem.

Wszystko działa w Twojej przeglądarce. Bez uploadu, bez przechowywania schematu gdziekolwiek. Wklej, zminifikuj, skopiuj.

Jak używać Minifikatora GraphQL

Trzy szybkie kroki. Przyciski opisane poniżej to faktyczne przyciski na tej stronie — nie ma przycisku Minifikuj, bo minifikacja odpala się sama.

Wklej, wgraj albo wczytaj przykład

Wklej schemat GraphQL w lewym panelu Wejście — minifikacja uruchamia się sama ułamek sekundy po tym, jak przestaniesz pisać, więc nie szukaj przycisku Konwertuj. Kliknij Wgraj dla pliku .graphql, .graphqls lub .gql, albo naciśnij Przykład, aby wczytać realistyczny schemat zamówienia e-commerce z komentarzami i opisami w blokach, który możesz obserwować w trakcie usuwania. Typowe wejście wygląda tak:

"""An order placed by a customer."""
type Order {
  # The unique order identifier
  id: ID!
  placedAt: DateTime!
  customer: Customer!
  items: [OrderItem!]!
  status: OrderStatus!
}

Działają zarówno schematy w stylu serwerowym (z extend type Query), jak i samodzielne definicje typów. Akceptowane formy odpowiadają temu, co wspiera język definicji schematu GraphQL.

Odczytaj zminifikowane wyjście

Prawy panel Wyjście wyświetla zminifikowany SDL w jednej linii, a w nagłówku panelu znajduje się pigułka z liczbą zaoszczędzonych bajtów, dzięki czemu od razu widzisz, ile zyskałeś. Komentarze (# ...) i opisy w blokach ("""...""") są usuwane całkowicie — według specyfikacji GraphQL od Relay nie mają znaczenia semantycznego, a każde narzędzie oparte na introspekcji pobierze opisy z warstwy resolverów. Jeśli SDL ma niezbalansowane nawiasy klamrowe lub inny błąd parsowania, minifikator pokaże uprzejmy komunikat inline — nigdy nie rzuca wyjątku ani się nie wywala.

Kopiuj lub pobierz

Naciśnij Kopiuj, aby chwycić zminifikowany schemat i wkleić go w skrypt deployu, zmienną środowiskową Lambdy albo plik konfiguracyjny. Naciśnij Pobierz, aby zapisać jako .graphql. Przycisk czyszczenia w panelu wejścia wraca do pustego stanu. Minifikacja odbywa się w całości po stronie klienta — Twój schemat nigdy nie opuszcza strony.

Kiedy faktycznie się to przyda

Mniejsze artefakty deployu

Pakujesz schemat w funkcję serverless lub warstwę Dockera? Usunięcie opisów i komentarzy zazwyczaj zmniejsza liczbę bajtów o połowę. Pomnóż to przez każdy cold start i każde pobranie warstwy, a oszczędność widać na rachunku. Parserowi w runtime jest to obojętne — opisy to metadane służące tylko do introspekcji, a większość deployów produkcyjnych i tak wyłącza introspekcję zgodnie z zaleceniami produkcyjnymi Apollo Routera.

Schematy serwowane z CDN

Jeśli twój gateway pobiera SDL z CDN przy starcie (kompozycja supergrafu Federation, pobieranie ze schema registry), każdy bajt to opóźnienie na zimnej ścieżce. Zminifikowany SDL parsuje się identycznie i ścina spory kawałek z rozmiaru po sieci — często więcej, niż dałby gzip, bo gzip nie skompresuje tego, czego już nie ma.

Wstawianie schematów do kodu

Czasem trzeba wstawić ciąg schematu do pliku konfiguracyjnego, zmiennej środowiskowej czy własnego narzędzia. Zminifikowana wersja w jednej linii ładnie wpada w template literal TypeScripta lub w skalar YAML bez konieczności escapowania każdej nowej linii.

Zmniejszenie szumu w diffach

Kiedy dwie wersje schematu różnią się tylko opisami albo komentarzami, prawdziwy diff strukturalny ginie pod zmianami doc-stringów. Zminifikowanie obu stron przed diffem izoluje rzeczywistą deltę schematu, co jest przydatne przy zarządzaniu zmianami i wykrywaniu breaking changes.

Najczęstsze pytania

Czy zminifikowany schemat to nadal poprawny GraphQL?

Tak — każdy token, który specyfikacja definiuje jako pomijalny (komentarze, opisy, zbędne białe znaki, przecinki), zostaje usunięty, ale każda nazwa, znak interpunkcyjny, literał stringa i liczba pozostaje. Wyjście parsuje się do dokładnie tego samego AST co wejście. Możesz to zweryfikować, przepuszczając oba przez graphql-js i porównując otrzymane dokumenty.

Czy stracę dokumentację schematu?

Tak — o to właśnie chodzi. Opisy i komentarze `#` są usuwane. Trzymaj swoje niezminifikowane źródło w systemie kontroli wersji i minifikuj dopiero, gdy zaraz wysyłasz artefakt. Dokumentacja, którą naprawdę chcesz pokazywać klientom, żyje w odpowiedzi introspekcyjnej, generowanej z metadanych resolverów w runtime, a nie z wdrożonego stringa SDL.

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

Nie. Minifikacja odbywa się w całości w Twojej przeglądarce. Nic nie jest wysyłane, nic nie jest logowane. Bezpiecznie wklejaj wewnętrzne lub niewydane schematy.

Ile mogę zaoszczędzić?

Zależy, jak bardzo udokumentowany jest twój schemat. Goły SDL bez opisów oszczędza 10-15% (same białe znaki). Dobrze udokumentowany schemat z opisami w blokach na każdym typie i polu zwykle daje 40-60% oszczędności. Pigułka zaoszczędzonych bajtów w nagłówku panelu wyjścia podaje dokładną liczbę dla twojego wejścia.

Czy obsługuje dyrektywy, własne skalary i federation?

Tak. @deprecated, @key, @external, scalar DateTime oraz wszystkie własne dyrektywy i skalary są zachowywane. Minifikator usuwa tylko tokeny pomijalne — wszystko, co semantyczne, zostaje. Dyrektywy Federation przechodzą round-trip czysto.

Jak duży schemat mogę zminifikować?

Tak duży, jaki przeglądarka ogarnia bez bólu. Schematy z kilkuset typami nie stanowią problemu. Powyżej około 5 MB zaczyna zwalniać sam edytor Ace — to on jest wąskim gardłem, nie minifikator.

Inne narzędzia GraphQL

Minifikacja to jeden element pracy z GraphQL. Resztę ogarniają te narzędzia: