Schema A (alt)

Schema B (neu)

Diff

Füge ein Schema in jedes Panel ein — der Diff aktualisiert sich beim Tippen.

Was ist der GraphQL-Schema-Diff?

Jede API-Änderung bricht irgendwessen Client. Das Erste, was du brauchst, bevor du einen Schema-PR mergst, ist eine klare Liste, was sich tatsächlich geändert hat — nicht ein 600-Zeilen-GitHub-Diff, der Whitespace, Reformatierung und echte Änderungen zu einer einzigen Wand aus Rot und Grün vermengt. Füge dein altes Schema links ein, das neue rechts, und dieses Tool gibt dir drei Listen: was hinzugefügt wurde, was entfernt wurde und welche bestehenden Felder den Typ geändert haben. Die Schemata werden gemäß der GraphQL-Spezifikation Oktober 2021 geparst, also stimmt das, was das Tool als "Typ" oder "Feld" betrachtet, mit dem überein, was dein Server als solches betrachtet.

Der Diff ist strukturell, nicht textuell. Felder innerhalb eines Typs umzuordnen, ist unsichtbar. Den SDL umzuformatieren, ist unsichtbar. Ein Argument umzubenennen, taucht auf. Int auf Order.total in Float zu ändern, taucht auf. Neue Enum-Werte wie OrderStatus.REFUNDED tauchen unter Hinzugefügt auf. Einen Union-Member zu entfernen, taucht unter Entfernt auf. Der Ausgabestil entspricht der Kategorisierung, die GraphQL Inspector und Apollo Schema Checks verwenden, sodass der Workflow auf diese Tools übertragbar ist, wenn du den Check schließlich in CI verlagerst.

Alles läuft in deinem Browser. Kein Upload, nichts wird geloggt. Sicher für unveröffentlichte interne Schemata.

So benutzt du den GraphQL-Schema-Diff

Einfügen, einfügen, lesen. Es gibt keinen Vergleichen-Button — der Diff aktualisiert sich beim Tippen.

Füge das alte Schema in Panel A ein

Wirf das aktuelle Produktionsschema in das linke Panel mit der Bezeichnung Schema A (alt). Klicke auf Hochladen für eine .graphql-, .graphqls- oder .gql-Datei, oder drücke Beispiel, um ein gepaartes Starter-/Iterations-Beispiel zu laden. Das Schema muss nicht hübsch sein — Formatierungsunterschiede werden ignoriert.

Füge das neue Schema in Panel B ein

Wirf das Kandidaten-Schema (das in deinem PR) in das rechte Panel mit der Bezeichnung Schema B (neu). Das Tool tokenisiert beide Schemata, läuft jede Typdefinition durch und berechnet den Diff Bruchteile einer Sekunde, nachdem du aufhörst zu tippen, neu. Die Semantik des Referenz-Parsers folgt graphql-js nahe genug, dass das, was hier angezeigt wird, dem entspricht, was dein Server sehen würde.

Lies die drei Listen

Das untere Panel hat drei Abschnitte. Hinzugefügt (grün) listet neue Typen, neue Felder, neue Enum-Werte und neue Union-Member. Entfernt (rot) listet die gleichen Kategorien rückwärts — das sind meist die Breaking Changes, also überfliege diese Liste zuerst. Geändert (orange) listet Felder und Argumente, deren Typ sich geändert hat, wie Order.total: Int → Float. Wenn die Schemata äquivalent sind, bekommst du ein einzelnes grünes Banner mit dieser Aussage.

Wann du das wirklich nutzen würdest

PR-Review

Ein Teamkollege öffnet einen PR, der fünf neue Felder hinzufügt und ein Argument umbenennt. Der GitHub-Diff ist unleserlich, weil er das Schema auch durch einen Formatter laufen ließ. Füge beide Versionen hier ein und bekomm die echte Änderungsliste — meist drei oder vier Einträge lang, nicht dreihundert. Reviewer können über die tatsächliche Semantik streiten, statt über Einrückung.

Breaking Changes erkennen

Ein Feld zu entfernen, einen Rückgabetyp einzuengen oder ein erforderliches Argument umzubenennen sind Breaking Changes für Clients in freier Wildbahn. Die Listen Entfernt und Geändert bringen sie direkt an die Oberfläche. Lass den Diff vor dem Merge laufen, um zu bestätigen, dass der Breaking Change beabsichtigt ist. Derselbe Check gehört letztendlich in CI — siehe die Apollo Schema Checks-Doku für die Produktionsversion dieses Workflows.

Onboarding-Dokumentation

Wenn ein neuer Engineer fragt "was hat sich im letzten Sprint geändert?", füge die Montag-Version und die Freitag-Version in die Panels ein und kopiere den Diff in deine Sprint-Notizen. Schneller als durch Commits zu scrollen und deutlich besser lesbar.

Federation-Composition-Sanity-Check

Nach dem Lauf eines föderierten Composers wie Apollo Rover füge das vorherige zusammengesetzte Schema und das neue ein. Der Diff sagt dir, ob die Composition die erwartete Änderung aus dem Subgraph-PR aufgegriffen hat — oder ob sich anderswo still und leise etwas geändert hat.

Häufige Fragen

Erkennt der Diff Breaking Changes spezifisch?

Alles in den Listen Entfernt und Geändert ist potenziell breaking — ein Feld entfernen, einen Rückgabetyp einengen, ein Argument umbenennen. Das Tool klassifiziert nicht jede Änderung als "breaking" vs. "non-breaking" wie GraphQL Inspector, aber die strukturierte Liste macht offensichtlich, welche du dir anschauen solltest.

Gilt die Reihenfolge der Felder als Änderung?

Nein. Felder innerhalb eines Typs umzuordnen, ist strukturell identisch und wird ignoriert. Dasselbe für die Umordnung von Enum-Werten, Union-Membern und Argumenten. Nur hinzugefügte, entfernte oder typgeänderte Einträge werden gemeldet.

Was ist mit Beschreibungen und Kommentaren?

Block-String-Beschreibungen und Kommentare werden beim Strukturvergleich ignoriert. Eine Beschreibung zu einem Feld hinzuzufügen, taucht im Diff nicht auf. Wenn du Doku-Änderungen verfolgen willst, mach das im formatierten SDL-Diff in deinem PR, nicht hier.

Werden meine Schemata an einen Server gesendet?

Nein. Tokenizer und Diff laufen vollständig in deinem Browser. Nichts wird hochgeladen, nichts wird geloggt. Sicher zum Einfügen interner oder unveröffentlichter Schemata.

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

Die Seite begrenzt jede Eingabe auf 5 MB. Darüber hinaus fängt der Ace-Editor selbst an zu lahmen. Schemata mit ein paar hundert Typen sind kein Problem.

Kann ich das in CI laufen lassen?

Für lokale Sanity Checks vor dem Pushen eines PR ist diese Seite okay. Für CI-Gates, die den Build bei einem Breaking Change scheitern lassen, nutze die dedizierte GraphQL Inspector-CLI oder Apollo Schema Checks — beide haben ordentliche Exit-Code-Semantik und Policy-Konfiguration.

Weitere GraphQL-Tools

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