GraphQL formatieren

So funktioniert es

Eine GraphQL-Abfrage aus dem Netzwerk-Tab des Browsers, einem Fehlerprotokoll oder JavaScript-Code ist meist eine lange Zeile, in der man nicht erkennt, welches Feld in welchem steckt. Fügen Sie die Abfrage links ein. Rechts steht danach jedes Feld in einer eigenen Zeile, verschachtelte Auswahlen sind um 2 Leerzeichen eingerückt, und Argumente (erste: $anzahl, status: GELIEFERT) bekommen nach Doppelpunkt und Komma je ein Leerzeichen. Aus {user(id:1){name}} wird so eine lesbare fünfzeilige Abfrage. Fragmente, Variablendefinitionen ($kunde: ID!), Direktiven (@include) und Schemadefinitionen (type, input, enum) erscheinen im selben Standardstil. Mit Eine Zeile geht es umgekehrt: Überflüssige Leerzeichen fallen weg, Text in Anführungszeichen bleibt unberührt, und die Abfrage passt in eine URL oder in Code. Bei einem Syntaxfehler sehen Sie Zeile und Spalte. Kommentare mit # übernimmt der Standard-Printer nicht; die Ergebniszeile nennt, wie viele entfallen sind.

Dieses Werkzeug ist auch als graphql formatieren, graphql formatter, graphql abfrage formatieren, graphql beautifier, graphql einruecken online, graphql schema formatieren bekannt.

Was ist GraphQL?

GraphQL ist eine Abfragesprache, in der der Client genau beschreibt, welche Daten er von einer API möchte. Bei REST liefert jede Adresse eine feste Antwort; bei GraphQL zählt eine Abfrage an eine einzige Adresse die gewünschten Felder in verschachtelten geschweiften Klammern auf, und die Antwort kommt genau in dieser Form zurück. Entwickelt wurde es bei Facebook; GitHub, Shopify und viele App-APIs nutzen es. Queries, Mutations (Änderungen) und Fragmente (wiederverwendbare Feldgruppen) sind die Grundbausteine.

Was ist Fragment?

Ein Fragment ist in GraphQL eine benannte Gruppe von Feldern, die in mehreren Abfragen vorkommt: fragment Adresse on Bestellung { strasse stadt } wird einmal definiert und mit ...Adresse überall eingefügt, wo es gebraucht wird. So muss dieselbe Feldliste nicht in jeder Abfrage neu geschrieben werden, und ein neues Feld ändert nur eine Stelle. Der Formatierer schreibt die Fragment-Definition als eigenen Block und die Verwendungsstelle als Zeile ...Adresse.

Was ist der Unterschied zwischen einer GraphQL-Abfrage und einem GraphQL-Schema?

Eine Abfrage (query, mutation) sagt, was der Client von der API möchte: welche Felder, mit welchen Argumenten. Ein Schema (SDL) legt fest, was der Server anbietet: Typen wie type Bestellung { id: ID! betrag: Float }, ihre Felder und deren Typen. Abfragen werden gegen das Schema geprüft; fragt man ein Feld ab, das es dort nicht gibt, meldet der Server einen Fehler. Dieses Werkzeug formatiert beides, prüft eine Abfrage aber nicht gegen ein Schema, sondern nur ihre Syntax.

Ändert das Formatieren das Ergebnis der Abfrage?

Nein. In GraphQL tragen Leerzeichen, Zeilenumbrüche und Kommas keine Bedeutung; der Server antwortet auf die formatierte und die einzeilige Abfrage gleich. Das Werkzeug liest die Abfrage mit dem Parser von graphql-js und schreibt denselben Baum im Standardstil; Feldreihenfolge, Aliasse, Argumentwerte und Zeichenketten bleiben.

Der einzige Unterschied sind Kommentare: Zeilen mit # gehören nicht zum Syntaxbaum, deshalb lässt der Standard-Printer sie weg. Sind Ihnen die Kommentare wichtig, behalten Sie den Originaltext; die Ergebniszeile nennt die Zahl der entfallenen Kommentarzeilen. Beschreibungen ("""...""") gehören zum Schema und bleiben erhalten.

Was prüft das Werkzeug, und was nicht?

Das Werkzeug prüft die Syntax: Eine offene geschweifte Klammer, ein fehlender Doppelpunkt, ein falsch gesetztes Komma oder Anführungszeichen erscheint mit Zeile und Spalte. Das genügt, um zu wissen, ob eine Abfrage kaputt ist, bevor sie den Server erreicht.

Gegen ein Schema prüft es nicht: Ob das abgefragte Feld existiert oder ein Argument den richtigen Typ hat, kann es nicht wissen, weil ihm das Schema der API fehlt. Dafür nutzen Sie die GraphiQL- oder Apollo-Studio-Oberfläche der API.

• Einzeilige Abfrage aus dem Log lesen → Lesbar
• Abfrage in einen URL-Parameter oder in Code einbauen → Eine Zeile
• Gibt es das Feld, stimmt der Typ → GraphiQL der API

Häufige Fragen

Wie mache ich eine einzeilige GraphQL-Abfrage lesbar?

Fügen Sie die Abfrage links auf dieser Seite ein. Jedes Feld bekommt eine eigene Zeile, verschachtelte Auswahlen werden um 2 Leerzeichen eingerückt. Das Ergebnis können Sie kopieren oder als .graphql-Datei herunterladen.

Lassen sich auch Schemadefinitionen (type, input, enum) formatieren?

Ja. Neben der Abfragesprache liest das Werkzeug die Schemadefinitionssprache (SDL): type-, interface-, input-, enum-, union- und scalar-Definitionen erscheinen im selben Standardstil, Beschreibungen bleiben erhalten.

Warum sind meine Kommentare verschwunden?

Der offizielle GraphQL-Printer übernimmt keine #-Kommentare, weil sie nicht zum Syntaxbaum der Abfrage gehören. Die Ergebniszeile nennt, wie viele Kommentarzeilen entfallen sind; brauchen Sie sie, behalten Sie den Originaltext.

Wird meine Abfrage an einen Server geschickt?

Nein. Das Formatieren läuft vollständig in Ihrem Browser; die Abfrage samt IDs oder Werten darin verlässt diese Seite nicht und geht an keine API.