Eingabe

Validierung

Füge links ein GraphQL-Schema ein, um hier die Validierungsergebnisse zu sehen.

Was ist der GraphQL-Validator?

Ein Schema, das aus einem Federation-Composer, einem Codegenerator oder einer Handbearbeitung im Code-Review zurückkommt, hat fast immer mindestens ein Syntaxproblem im ersten Durchgang. Eine verirrte }, ein nicht abgeschlossener Beschreibungs-String, ein Enum-Körper, der abgeschnitten wurde, als jemand einen halben Bildschirm SDL in einen Chat kopiert hat — und schon fliegt dir das Hochfahren deines Apollo Server mit einem Parser-Fehler um die Ohren, der auf Zeile 1 zeigt, was so gut wie nie da ist, wo das eigentliche Problem steckt. Dieser Validator läuft Token für Token durch das SDL und zeigt auf die echte Zeile.

Er prüft strukturelle Regeln aus der GraphQL-Spezifikation Oktober 2021: jedes {, ( und [ braucht einen passenden Schließer der richtigen Art; Beschreibungen, die als """...""" geschrieben sind, müssen abgeschlossen werden; Strings in Argumenten in Anführungszeichen müssen in derselben Zeile schließen. Der Validator prüft KEINE Semantik — er sagt dir nicht, dass Query fehlt oder dass ein Feld einen nicht deklarierten Typ referenziert. Dafür gib das Schema durch die Referenzimplementierung graphql-js. Was diese Seite gut kann, ist der Syntax-Durchgang und der Stat-Block, damit du auf einen Blick siehst, ob das Schema, das du gerade eingefügt hast, 14 Typen oder 4 hat, 187 Felder oder 12.

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

So nutzt du den GraphQL-Validator

Drei schnelle Schritte. Die Buttons unten entsprechen den tatsächlichen Buttons auf dieser Seite.

Einfügen, hochladen oder Beispiel laden

Füge ein GraphQL-Schema in das linke Eingabe-Panel ein — die Validierung läuft automatisch eine Sekundenbruchteile, nachdem du aufgehört hast zu tippen, also gibt es keinen Validate-Button. Klick auf Hochladen für eine .graphql-, .graphqls- oder .gql-Datei, oder auf Beispiel, um ein realistisches E-Commerce-Order-Schema zu laden. Eine typische Eingabe sieht so aus:

type Order { id: ID! placedAt: DateTime! customer: Customer! items: [OrderItem!]! status: OrderStatus! } enum OrderStatus { PENDING PAID SHIPPED }

Sowohl Schemas im Server-Stil (mit extend type Query) als auch eigenständige Typdateien funktionieren. Kommentare (#) und Block-String-Beschreibungen ("""...""") werden so behandelt, wie es die GraphQL learn-schema-Dokumentation beschreibt.

Den Stat-Block lesen

Das rechte Panel zeigt einen grünen Banner, wenn das Schema sauber geparst wird, einen roten, wenn nicht — und in beiden Fällen bekommst du eine Aufschlüsselung, wie viele type-, interface-, enum-, input-, union-, scalar- und directive-Definitionen das Schema deklariert, plus die Gesamtzahl der Felder, Argumente und Beschreibungen. Nützlich für Sanity-Checks bei einem Federation-Merge oder zum Vergleich zweier Revisionen desselben Schemas. Die Zählungen spiegeln das wider, was die Relay GraphQL-Spezifikation als die strukturellen Bestandteile einer Definition bezeichnet.

Beheben und neu einfügen

Wenn das Schema ungültig ist, sagt dir der Banner die genaue Zeile der unausgeglichenen Klammer oder des nicht abgeschlossenen Strings. Behebe es, füge es wieder ein, schau zu, wie der Banner grün wird. Der Kopieren-Button rechts gibt dir einen kleinen JSON-Stat-Bericht, den du in eine PR-Beschreibung oder eine Chat-Nachricht packen kannst — praktisch, wenn du einer Kollegin zeigen willst „ja, das Schema ist okay, hier sind die Stats", ohne das SDL selbst zu teilen.

Wann du das wirklich nutzt

Sanity-Check vor dem Merge

Bevor du eine Federation-Gateway-Änderung oder ein Schema-Stitching-Update mergest, füge das zusammengesetzte Schema hier ein. Wenn die Klammerbalance schief ist oder eine Beschreibung nicht abgeschlossen ist, siehst du das hier in zwei Sekunden statt in einem CI-Fehler zehn Minuten später. Passt gut zum Befehl rover subgraph check für die semantische Seite.

Diff zweier Revisionen

Füge Version A ein, notiere die Stat-Zahlen (28 Typen, 142 Felder, 6 Enums). Füge Version B ein, vergleiche. Wenn die Feldzahl um 40 gestiegen ist, aber nur ein neuer Typ hinzukam, hat wahrscheinlich jemand ein Fragment dupliziert. Der Stat-Block ist viel schneller, als durch ein 2000-zeiliges Diff zu scrollen.

Onboarding eines neuen Auftragnehmers

Gib ihm die Schema-Datei, zeig ihm diese Seite und sag „wenn das rot wird, ist deine Eingabe kaputt; wenn die Feldzahl plötzlich um 800 niedriger ist, hast du nur die Hälfte kopiert." Spart das Hin und Her von „ist das alles?", bevor er überhaupt anfängt, Resolver zu schreiben.

Aus dem Chat einfügen

Slack und Discord lieben es, Backticks und Anführungszeichen zu zerschießen, wenn sie lange Nachrichten umbrechen, also fehlt einem Schema, das jemand in einen Thread eingefügt hat, oft eine oder zwei schließende Klammern. Wirf es zuerst hier rein, um es herauszufinden, bevor du es in deiner IDE öffnest.

Häufige Fragen

Validiert er Semantik oder nur Syntax?

Nur Syntax — Klammerbalance, String-Abschluss und ein Stat-Walk über den Token-Stream. Er prüft NICHT, ob Query existiert, ob referenzierte Typen definiert sind, ob Argumente zu ihren Direktiven-Definitionen passen oder ob ein Feldtyp gültig ist. Für volle semantische Validierung nimm die Referenzbibliothek graphql-js oder die Startup-Checks deines Servers.

Wird mein Schema an einen Server geschickt?

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

Welche Syntaxprobleme fängt er tatsächlich ab?

Nicht passende { / ( / [ mit der Zeilennummer des Öffners, falsch zugeordnete Schließer wie ) dort, wo } erwartet war, nicht abgeschlossene "strings" oder """block strings""" und verirrte Zeichen, die nicht zur GraphQL-Token-Grammatik gehören.

Warum zeigt mein Schema 0 Typen, obwohl es offensichtlich Typen hat?

Der Stat-Zähler zählt eine Definition erst dann, wenn sowohl ihr Schlüsselwort (type, interface etc.) ALS AUCH die Körperklammern vorhanden sind. Wenn du ein Schema einfügst, das mitten im Typ abgeschnitten ist, bleibt die Zählung für diesen Typ bei 0, bis du den Körper fertigstellst. Der Validator-Banner ist in dem Fall auch rot und zeigt auf den nicht passenden Öffner.

Versteht er Block-String-Beschreibungen?

Ja. """An order placed by a customer.""" wird als Beschreibungs-Token erkannt und in der Beschreibungen-Stat gezählt. Der Validator schreibt nicht vor, wo Beschreibungen erscheinen — das ist eine Stilentscheidung — aber die Zählung gibt dir einen schnellen Eindruck davon, wie gut dokumentiert das Schema ist.

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

So groß wie dein Browser bequem rendern kann. Schemas mit ein paar hundert Typen und mehreren tausend Feldern validieren weit unter einer Sekunde. Ab 5 MB wird der Ace-Editor selbst langsam, das ist dann der Engpass — nicht der Validator.

Weitere GraphQL-Tools

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