Eingabe

Ausgabe

Was ist der GraphQL-Formatter?

Ein GraphQL-Schema, das aus einem Code-Generator, einem Federation-Composer oder einem Copy-Paste aus dem Chatfenster kommt, hat fast nie das Whitespace, das du willst. Typen kleben aneinander, Felder teilen sich eine Zeile, Beschreibungen werden gegen die nächste Definition gequetscht. Die GraphQL Schema Definition Language soll der lesbare Vertrag zwischen Frontend und Backend sein — aber nur, wenn sie tatsächlich formatiert ist. Füg dein SDL ins linke Panel ein und das rechte Panel gibt es schön zurück: zwei Leerzeichen Einrückung, ein Feld pro Zeile, Argumente inline, und Block-String-Beschreibungen werden über dem Typ oder Feld gehalten, das sie dokumentieren.

Der Pretty-Printer ist handgeschrieben — kein graphql npm-Paket wird auf der Seite geladen, also bleibt der erste Paint klein. Er tokenisiert das SDL, läuft die Klammerstruktur ab und gibt es mit konsistentem Spacing gemäß der GraphQL-Spec von Oktober 2021 wieder aus. Jedes SDL-Konstrukt, das in echten Schemas vorkommt, wird behandelt: type, interface, union, enum, input, scalar, extend, schema, directive, List- und Non-Null-Modifier ([Foo!]!), Default-Werte, Direktiven und Triple-Quoted-Beschreibungen. Der Formatter ist idempotent — bereits hübsches SDL läuft unverändert durch, du kannst ihn also bedenkenlos in einem CI-Gate oder Pre-Commit-Hook laufen lassen.

Alles läuft in deinem Browser. Kein Upload, kein Schema irgendwo gespeichert. Einfügen, formatieren, kopieren.

So nutzt du den GraphQL-Formatter

Drei schnelle Schritte. Die unten beschriebenen Buttons sind die echten Buttons auf dieser Seite.

Einfügen, hochladen oder Beispiel laden

Füg ein GraphQL-Schema ins linke Eingabe-Panel ein — die Formatierung passiert automatisch eine Sekundenbruchteile, nachdem du aufhörst zu tippen, einen Convert-Button musst du also nicht suchen. Klick auf Hochladen für eine .graphql-, .graphqls- oder .gql-Datei, oder auf Beispiel, um ein realistisches E-Commerce-Order-Schema zu laden. Ein typischer messy Paste sieht so aus:

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

Server-Style-Schemas (mit extend type Query) und eigenständige Typdefinitionen funktionieren beide. Die akzeptierten Formen entsprechen dem, was Tools wie Apollo Server beim Start parsen.

Lies die schöne Ausgabe

Das rechte Ausgabe-Panel zeigt das schöne SDL mit zwei Leerzeichen Einrückung. Jedes Feld, jeder Enum-Wert und jedes Union-Member bekommt seine eigene Zeile. Argumente bleiben inline in der Feldzeile, damit sich Signaturen natürlich lesen. Beschreibungen, die als Block Strings ("""...""") geschrieben sind, werden über dem Typ oder Feld gehalten, das sie beschreiben — so empfiehlt es die Relay-GraphQL-Spec für die Schema-Dokumentation. Wenn das SDL unbalancierte Klammern oder einen anderen Parse-Fehler hat, zeigt der Formatter eine freundliche Inline-Meldung — er wirft nie eine Exception oder stürzt ab.

Kopieren oder herunterladen

Klick auf Kopieren, um das formatierte Schema für einen Pull Request, ein Doc oder einen Chat zu greifen. Klick auf Herunterladen, um es als .graphql zu speichern. Der Clear-Button im Eingabe-Panel setzt dich auf einen leeren Stand zurück. Die Formatierung passiert komplett clientseitig — dein Schema verlässt die Seite nie.

Wann du das wirklich brauchst

PR-Review-Lesbarkeit

Ein Teammitglied öffnet einen PR, der fünf neue Typen zum Schema hinzufügt. Der Diff sieht aus wie ein riesiger Block, weil die Codegen-Ausgabe die Formatierung verloren hat. Lass die Datei durch den Formatter laufen und kleb die schöne Version in die PR-Beschreibung — dann können Reviewer tatsächlich lesen, was hinzugefügt wird. GraphQL-Schema-Best-Practices zu folgen ist viel einfacher, wenn Reviewer die Struktur sehen.

Schema-Registry-Diffs

Die meisten Schema-Registries (Apollo Studio, GraphQL Hive, Hasura) zeigen Diffs als zeilenweisen Text. Wenn eine Revision minifiziert war und die nächste hübsch, taucht jede Zeile als geändert auf und die echte Änderung verschwindet im Rauschen. Beide Versionen vor dem Upload schön machen — gleicher Formatter, gleiche Ausgabe, echter Diff.

Docs und Onboarding

Du schreibst öffentliche Docs für eine GraphQL-API oder onboardest einen neuen Engineer? Schema einfügen, formatierte Version ins Wiki oder README kopieren. Ein Schema mit sichtbaren Beschreibungen über jedem Typ ist ein viel freundlicherer Startpunkt als der unformatierte Klumpen, den das Codegen-Tool ausgespuckt hat.

Pre-Commit- und CI-Gates

Weil der Formatter idempotent ist, kannst du ihn als Pre-Commit-Hook oder CI-Check laufen lassen: Schema formatieren, Build failen lassen, wenn das Ergebnis von der committeten Datei abweicht. Kein Whitespace-Drift mehr zwischen Contributors und keine PRs mehr, in denen die Hälfte des Diffs Reformat-Rauschen ist.

Häufige Fragen

Validiert er mein Schema oder formatiert er nur?

Nur formatieren. Der Formatter prüft Klammer- und Anführungszeichen-Balance gerade so weit, dass Pretty-Print funktioniert, aber er verifiziert nicht, dass Query existiert, dass referenzierte Typen definiert sind oder dass Direktiv-Argumente zu ihren Definitionen passen. Für volle Validierung lass dein Schema durch die Referenz-Implementierung graphql-js oder die Startup-Checks deines Servers laufen.

Wird mein Schema an einen Server gesendet?

Nein. Die Formatierung läuft komplett im Browser. Nichts wird hochgeladen, nichts geloggt. Du kannst interne oder unveröffentlichte Schemas bedenkenlos einfügen.

Behandelt er Block-String-Beschreibungen?

Ja. Triple-Quoted-Beschreibungen ("""Eine von einem Kunden aufgegebene Bestellung.""") bleiben erhalten und werden in der Zeile über dem Typ oder Feld emittiert, das sie dokumentieren. Das ist die kanonische Art, SDL-Doku gemäß der GraphQL-Spec zu schreiben.

Was ist mit Direktiven und Custom Scalars?

Beide bleiben erhalten. @deprecated, @key und alle Custom Directives bleiben inline am Feld. Custom Scalars wie scalar DateTime kommen auf eigene Zeilen. Der Formatter versucht nicht, die Semantik der Direktiven zu interpretieren — das ist Sache deines Servers.

Wird bereits formatiertes SDL nochmal formatiert?

Er ist idempotent — schon schönes SDL nochmal zu formatieren ergibt dieselbe Ausgabe. Du kannst den Formatter also in einem CI-Check oder einem Paste-und-Compare-Workflow laufen lassen, ohne dir Sorgen um Whitespace-Drift zu machen.

Wie groß darf das Schema sein, das ich einfüge?

Alles, was dein Browser entspannt rendert. Schemas mit ein paar hundert Typen sind kein Problem. Ab 5 MB wird der Ace-Editor selbst langsam — das ist der Bottleneck, nicht der Parser.

Andere GraphQL-Tools

Formatieren ist nur ein Teil der Arbeit mit GraphQL. Diese Tools übernehmen den Rest: