GraphQL formatieren

Warum GraphQL formatieren

GraphQL-Queries werden oft im Code zusammengebaut, einzeilig geloggt oder aus Netzwerkmitschnitten im Browser kopiert. Eine Query mit ein paar Verschachtelungsebenen ist in dieser Form kaum zu lesen. Du erkennst nicht, welche Felder zu welchem Objekt gehören oder wo ein Fragment endet.

Ein GraphQL Formatter setzt jedes Feld in eine eigene Zeile und rückt jedes Selection Set eine Ebene tiefer ein als sein Elternelement. Die Struktur der Query entspricht dann der Struktur der Antwort, die du zurückbekommst, und lässt sich leicht prüfen.

Dieses Tool nutzt Prettier 3 mit dem GraphQL-Plugin, direkt in deinem Browser.

So nutzt du es

1. Füge eine Query, eine Mutation oder ein Schema in das linke Feld ein. Es wird direkt nach dem Einfügen formatiert.
2. Oder klicke auf Datei öffnen, um eine .graphql-Datei zu laden, oder auf Beispiel für ein Beispiel.
3. Wähl die Einrückung: 2 Leerzeichen, 4 Leerzeichen oder Tabs.
4. Wähl die Zeilenbreite. Argumente und Variablenlisten, die nicht passen, werden auf mehrere Zeilen verteilt.
5. Klicke auf Formatieren oder drück Strg+Enter.
6. Klicke auf Kopieren oder auf Herunterladen, um eine .graphql-Datei zu speichern.

Nach dem ersten Formatieren folgt die Ausgabe deinem Tippen. Bei einem Syntaxfehler nennt die Meldung Zeile und Spalte, und In der Eingabe zeigen springt dorthin.

Vorher und nachher

Eine Query in einer Zeile:

query GetUser($id:ID!,$first:Int=5){user(id:$id){id name email posts(first:$first){edges{node{id title publishedAt}}}}}

Nach Formatieren mit 2 Leerzeichen:

query GetUser($id: ID!, $first: Int = 5) {
  user(id: $id) {
    id
    name
    email
    posts(first: $first) {
      edges {
        node {
          id
          title
          publishedAt
        }
      }
    }
  }
}

Variablen bekommen ein Leerzeichen nach dem Doppelpunkt, der Standardwert 5 bekommt Leerzeichen um das =, und jedes verschachtelte Selection Set ist eingerückt. Jetzt siehst du, dass title ein Feld von node ist, innerhalb von edges, innerhalb von posts.

Mutations und Input-Objekte

Input-Objekte, die in die Zeilenbreite passen, bleiben in einer Zeile:

mutation {
  createPost(input: { title: "Hello", tags: ["news", "update"] }) {
    id
  }
}

Passt es nicht, werden die Argumente aufgeteilt. Hier ist dieselbe Mutation mit einer Zeilenbreite von 40:

mutation {
  createPost(
    input: {
      title: "Hello"
      tags: ["news", "update"]
    }
  ) {
    id
  }
}

Bei mehrzeiligen Objekten fallen die Kommas zwischen den Input-Feldern weg. In GraphQL sind Kommas optional und zählen als Leerraum.

Fragmente

Fragmente und Spreads bleiben in der Reihenfolge, in der du sie geschrieben hast:

fragment UserParts on User {
  id
  name
}
query {
  me {
    ...UserParts
  }
}

Schema-Dateien

Die Schema Definition Language wird nach denselben Regeln formatiert. Ein Feld pro Zeile, und Enum-Werte stehen jeweils in einer eigenen Zeile:

type User {
  id: ID!
  name: String!
  posts(first: Int): [Post!]!
}
enum Role {
  ADMIN
  EDITOR
}

Mit der Einrückung auf 4 Leerzeichen wird aus query{viewer{login}}:

query {
    viewer {
        login
    }
}

Syntaxfehler

Der GraphQL-Parser ist streng, und seine Meldungen sind kurz und auf Englisch. Nur die Angabe von Zeile und Spalte davor ist deutsch. Zwei häufige:

• Eine fehlende schließende Klammer am Ende ergibt Zeile 4, Spalte 1: Syntax Error: Expected Name, found <EOF>. Der Parser hat das Ende der Eingabe erreicht, während er noch in einem Selection Set war.
• Ein Argument ohne Wert, wie in user(id: ), ergibt Zeile 2, Spalte 12: Syntax Error: Unexpected ")".

Zähl deine Klammern ab der angezeigten Position. Ein Formatter ist auch ein schneller Weg, eine fehlende Klammer in einer langen Query zu finden: Einfügen, und wenn der Fehler auf das Ende der Eingabe zeigt, wurde ein Selection Set nie geschlossen.

Grenzen

• Geprüft wird nur die Syntax. Feldnamen, Argumenttypen und Pflichtvariablen werden gegen kein Schema validiert.
• Der Formatter sortiert keine Felder um, ordnet keine Typen und entfernt keine ungenutzten Fragmente.
• Bei Queries in gql-Template-Strings in JavaScript oder TypeScript fügst du hier nur den Query-Text ein und setzt das Ergebnis dann zurück. Der JavaScript Formatter und der TypeScript Formatter formatieren den Code drumherum, lassen den Template-String aber, wie er ist.
• Variablen werden als JSON gesendet, nicht als GraphQL. Formatiere ein Variablenobjekt im JSON Formatter.

Andere Wege, GraphQL zu formatieren

• VS Code: Mit der Prettier-Erweiterung formatiert Dokument formatieren (Umschalt+Alt+F unter Windows, Umschalt+Option+F unter macOS) .graphql- und .gql-Dateien nach denselben Regeln wie diese Seite.
• Kommandozeile: npx prettier --write schema.graphql.
• GraphQL-IDEs wie GraphiQL haben einen Prettify-Button, der die Query im Editor formatiert. Beim Testen ist das praktisch, und diese Seite hilft dir, wenn du nur den Text hast und keine IDE zur Hand ist.