Eingabe

Ausgabe

Was ist der GraphQL Query Formatter?

Jede GraphQL-Anfrage, die jemand von Hand schreibt, fängt als einzeilige Mauer aus geschweiften Klammern an. Sie ohne vorheriges Formatieren in einen Code Review zu werfen ist der sicherste Weg, "bitte reformatieren" als ersten Kommentar zu kassieren. Genauso bei Queries, die ein Frontend-Build ausspuckt, die ein Server loggt oder die in einem Slack-Thread landen, wenn ein Kollege fragt: "warum kommt da null zurück?". Diese Seite nimmt eine Query, Mutation, Subscription oder ein Fragment und macht sie schön: zwei Leerzeichen Einrückung, ein Feld pro Zeile, Argumente inline wenn sie passen, Variablen aufgeräumt, und die Operations-Grammatik aus der GraphQL-Spec wird durchgängig respektiert.

Beachte: diese Seite ist das Operations-Pendant zum GraphQL Formatter. Das andere Tool formatiert Schema Definition Language — deine type Order, interface Node, enum Status. Dieses Tool formatiert das, was dein Client sendet und dein Server empfängt: query OrderDetails($id: ID!) { order(id: $id) { ... } }, Mutations, Subscriptions und Fragment-Definitionen. Die zwei Grammatiken teilen sich Tokens, aber die strukturellen Regeln sind unterschiedlich — Selection Sets, Aliase, Fragment Spreads, Inline Fragments und Direktiven-Anwendungen gibt es nur bei Operations. Wenn du SDL versehentlich eingefügt hast, geh stattdessen zum Schema-Formatter.

Das Formatieren ist von Hand in TypeScript geschrieben — kein graphql-js-Bundle wird in die Seite geladen, der erste Paint bleibt also klein. Die Ausgabe entspricht für die üblichen Fälle dem, was Prettier mit seinem GraphQL-Plugin produziert, also sollte das Einfügen der formatierten Query in eine Codebase, die bereits Prettier benutzt, kein Diff erzeugen. Alles läuft lokal — deine Query verlässt den Browser nie.

So benutzt du den GraphQL Query Formatter

Drei Schritte. Es gibt keinen Convert-Button — das Formatieren läuft automatisch einen Moment, nachdem du aufhörst zu tippen.

Einfügen, Hochladen oder Beispiel laden

Füge eine GraphQL-Operation in das linke Eingabe-Panel ein. Klicke auf Hochladen für eine .graphql- oder .gql-Datei oder auf Beispiel für eine realistische E-Commerce-OrderDetails-Query plus ein kleines Fragment. Ein typisch unaufgeräumter Paste sieht so aus:

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}}}

Der Formatter behandelt jede Operations-Konstruktion, die in echtem Client-Code auftaucht: Variablen-Definitionen mit Defaultwerten, Listen-Defaultwerte, @include- / @skip- / Custom-Direktiven, Aliase, Fragment Spreads (...Money) und Inline Fragments (... on PaidOrder { ... }). Mehrere Operations oder Fragments in einem Dokument bleiben getrennt, mit einer Leerzeile dazwischen — so erwarten Apollo Client und die meisten GraphQL-Tools Dokumente angeordnet.

Lies die verschönerte Ausgabe

Das rechte Ausgabe-Panel zeigt die formatierte Operation. Jedes Feld bekommt seine eigene Zeile. Argumente bleiben inline, wenn das Feld in 80 Zeichen passt, und brechen auf separate Zeilen um, wenn nicht — dieselbe Regel, die das GraphQL-Plugin in Prettier verwendet. Variablen-Definitionen folgen derselben Regel im Operations-Header. Aliase behalten ein einzelnes Leerzeichen nach dem Doppelpunkt (aliasedAs: fieldName). Kommentare (# ...) werden auf der Einrückung der Zeile beibehalten, an der sie hingen. Wenn die Eingabe kaputt ist — nicht passende Klammern, ein verirrtes $, ein fehlendes : — schreibt der Formatter einen freundlichen Inline-Fehler statt zu crashen.

Kopieren oder Herunterladen

Drück Kopieren, um die formatierte Query für einen PR, ein Doc oder eine Chatnachricht zu greifen. Drück Herunterladen, um sie als query.graphql zu speichern. Clear setzt die Eingabe zurück. Die ganze Pipeline ist client-seitig — praktisch, wenn du eine Query gegen eine interne API debuggst und sie nicht in ein Drittanbieter-Tool kopieren willst.

Wann du das wirklich nutzt

Code Review und PR-Hygiene

Ein Frontend-PR fügt eine neue Mutation hinzu. Der Query-String wurde von einem Build-Schritt ausgegeben, der den Whitespace entfernt hat, und jetzt ist der Diff eine 400-Zeichen-Mauer. Schick die Mutation durch den Formatter, klatsch die verschönerte Version in die PR-Beschreibung, und der Reviewer kann tatsächlich sehen, welche Felder du liest. Derselbe Trick funktioniert für graphql-react, urql, Relay und jeden anderen Client, in dem Queries als Template Literals inline stehen.

Eine Production-Query debuggen

Eine Query in Production gibt für ein Feld null zurück, wo du etwas erwartet hattest. Du holst dir den Request-Body aus dem Network-Tab, fügst ihn hier ein und siehst jetzt die Variablenwerte, welche Felder @include nutzen und wo die Fragment Spreads landen. Schlägt das Schielen auf eine lange Zeile. Kombiniere es mit dem offiziellen Leitfaden zu GraphQL über HTTP, wenn du den Request manuell mit curl oder Postman reproduzieren musst.

Lernen und Onboarding

Neu bei GraphQL-Operations? Füg eine Query aus einem Tutorial ein, formatiere sie, und die Struktur wird offensichtlich — Operations-Header, Selection Set, verschachtelte Selection Sets, Fragment-Definitionen unten. Die Ausgabe spiegelt das Layout, das du im Queries-Guide von graphql.org sehen wirst, also ist es einfach, beim Lernen zur Doku zurückzumappen.

Pre-commit und CI-Gates

Da der Formatter deterministisch ist — bereits verschönerte Queries laufen unverändert hin und zurück — kannst du diese Seite als schnellen "ist meine Query schon hübsch?"-Check vor dem Commit benutzen. Für eine vollständig automatisierte Pipeline schickst du dieselbe Quelle durch Prettier mit seinem GraphQL-Plugin und lässt den Build bei einem nicht-leeren Diff scheitern. Selbe Idee, nur skaliert.

Häufige Fragen

Worin unterscheidet sich das von der GraphQL-Formatter-Seite?

Die GraphQL Formatter-Seite formatiert Schema Definition Language — deine type-, interface-, enum-, union-, scalar- und directive-Deklarationen. Diese Seite formatiert Operations: query, mutation, subscription und fragment. Die zwei Grammatiken teilen sich Tokens, haben aber sehr unterschiedliche strukturelle Regeln, also ergibt der Versuch, eine Operation auf der Schema-Seite zu formatieren (oder umgekehrt) durcheinandergewürfelte Ausgabe. Such dir das richtige Tool für das, was du eingefügt hast.

Validiert es meine Query gegen ein Schema?

Nein. Der Formatter prüft Klammer-, Runde- und Eckige-Klammer-Balance gerade so weit, wie es fürs Pretty-Printing nötig ist, kennt aber dein Schema nicht und kann dir deshalb nicht sagen, dass order id: ID! erwartet und nicht id: Int!. Für echte Validierung schick deine Operation durch die Startup-Checks deines Servers oder gegen den Referenz-graphql-js-Validator über den GitHub-Link oben.

Wird meine Query an einen Server geschickt?

Nein. Das Formatieren ist reines Client-side-JavaScript — nichts wird hochgeladen, nichts geloggt. Sicher für interne Queries, Queries mit sensiblen Variablenwerten oder Queries gegen private APIs.

Werden meine Variablenwerte oder Argumente verändert?

Nein. Argumentwerte, Defaultwerte und Listen-Defaults werden genau so ausgegeben, wie sie geschrieben wurden, nur mit konsistentem Spacing um :, = und ,. Der Formatter erfindet, entfernt oder sortiert nie Felder, Argumente oder Variablen um — was du eingefügt hast, kommt raus, nur sauber angeordnet.

Behandelt es Inline Fragments und Fragment Spreads?

Ja. Inline Fragments (... on PaidOrder { ... }) bekommen die Standard-Selection-Set-Behandlung mit zwei Leerzeichen Einrückung. Fragment Spreads (...Money) sitzen in einer einzigen Zeile auf Feld-Einrückung, Direktiven bleiben in derselben Zeile. Mehrere Fragment-Definitionen in einem Dokument bleiben als separate Top-Level-Definitionen mit einer Leerzeile dazwischen.

Was ist mit anonymen Queries — <code>{ field }</code> — erweitert es sie zu <code>query { field }</code>?

Nein. Die Kurzform ist Teil der Spec, und der Formatter behält sie, wie sie ist. Wenn du eine benannte Query willst, benenne sie selbst — der Formatter schreibt Operations nicht stillschweigend um.

Andere GraphQL-Tools

Ein Query-Formatter ist nur ein Stück der Arbeit mit GraphQL. Die anderen GraphQL-Tools auf der Seite: