01
Die bisherige Version links einfügen
Die Prüfung läuft von alt nach neu. Wer die Seiten vertauscht, ändert Entfernen in Hinzufügen und damit auch die Risikoeinstufung. Die Tauschfunktion berechnet den Vergleich neu.
GraphQL-Dokumente
GraphQL-Schema-VergleichÄnderungen vor dem Release verstehen
Das veröffentlichte vollständige SDL gehört links, der geplante Stand rechts. Die Richtung entscheidet über Entfernen und Hinzufügen.
GraphQL-Schema-Vergleich
Altes Schema-SDL
Neues Schema-SDL
Unterschiede
Zwei vollständige Schema-SDLs eingeben oder das Beispiel laden.
Beide SDL-Texte werden nur in diesem Browser analysiert. Keine API-Abfrage, kein Upload, kein Verlauf und keine Eingabe in der URL.
Optionen
GraphQL.js stuft Breaking Changes und potenziell gefährliche Änderungen ein. Weitere Struktur- und Deprecated-Änderungen gelten dadurch nicht automatisch als sicher.
Je SDL höchstens 100.000 Zeichen, 20.000 Tokens und 100 Verschachtelungsebenen. Nach 8 Sekunden endet der Vergleich.
Zwei vollständige Schema-SDLs eingeben oder das Beispiel laden.
Ein GraphQL-Schema-Vergleich hilft, wenn ein Pull Request viele Zeilen durch neue Reihenfolge oder Einrückung verändert. Entscheidend für bestehende Clients sind jedoch Feldnamen, Typen und Argumente, nicht die Position der Definitionen im Text.
Der Bericht trennt die strukturelle Sicht von den Regeln für Breaking Changes. Neue Felder und Deprecated-Markierungen bleiben sichtbar, selbst wenn GraphQL.js dafür keine Gefährdung meldet; eine fehlende Warnung ist kein Beweis für Sicherheit. Diese Schemaänderungen lassen sich so ohne Textdiff-Rauschen lesen.
Warum ein GraphQL-Schema-Vergleich hilfreich ist
Änderungen am Vertrag sehen, ohne Formatierung als Risiko zu zählen.
Feldpfade statt Zeilenrauschen
Der GraphQL-Schema-Vergleich baut aus beiden SDL-Texten gültige Schemata und vergleicht Typen, Felder und Argumente nach Pfad. Umgestellte Definitionen lösen keinen Treffer aus; ein entferntes Feld erscheint mit seinem Namen und bisherigen Typ.
Risiko und Deprecation getrennt halten
Ein neuer Enum-Wert kann Client-Code mit vollständiger Fallunterscheidung überraschen. Ein neues @deprecated-Attribut entfernt dagegen kein Feld. Der GraphQL-Schema-Vergleich führt beide Ereignisse getrennt und nennt unbewertete Ergänzungen nicht pauschal sicher.
Richtung und Aktualität des Berichts prüfen
02
Automatik bei Bedarf ausschalten
Nach Änderungen wartet die Automatik ungefähr 350 ms. Bei langen SDL-Dateien lässt sie sich abschalten; Vergleichen oder Strg/Cmd+Enter verarbeitet dann erst das aktuelle Paar.
03
Nur frische Ergebnisse exportieren
Jede Eingabeänderung macht den bisherigen Bericht ungültig und sperrt Kopieren sowie Download. Eine Fehlermeldung nennt das betroffene SDL und nach Möglichkeit Zeile und Spalte. Der Export enthält alle Einträge, auch wenn zunächst nur 100 angezeigt werden.
Was die Strukturprüfung sichtbar macht
Pfade aus dem GraphQL-Modell
Typen, Felder, Argumente, Input-Felder, Enums, Unions und Direktiven werden strukturell verglichen. Leerraum und Definitionsreihenfolge sind keine Vertragsänderung.
Einstufung durch GraphQL.js
Die Bibliothek liefert die Breaking- und Dangerous-Regeln; der Regelcode steht beim Befund. Andere Strukturänderungen bleiben prüfbar, ohne ein unverdientes „sicher“ zu erhalten.
Deprecation und vollständiger Bericht
Änderungen am @deprecated-Grund erscheinen gesondert. Wird ein längst veraltetes Feld tatsächlich entfernt, bleibt es nach der Standardregel ein Breaking Change.
Grenzen des statischen SDL-Vergleichs
- Zwei vollständige Schemata erforderlich
- Ein einzelner Typ ohne Query-Wurzel oder ein Verweis auf einen unbekannten Typ ist hier kein gültiges Schema. Der GraphQL-Schema-Vergleich stoppt dann und zeigt die fehlerhafte Seite samt verfügbarer Position, statt null Unterschiede vorzutäuschen.
- Keine Kenntnis der realen Clients
- Breaking bedeutet, dass vorhandene Operationen scheitern könnten. Das Tool kennt weder Traffic noch tatsächlich eingesetzte Abfragen und kann die Folgen für einen bestimmten Client nicht beweisen.
- Nur SDL-Text, keine entfernten Quellen
- Es werden keine Endpunkte abgefragt und keine Dateien hochgeladen. Introspection-JSON wird nicht als SDL interpretiert; wandeln Sie es vor dem Vergleich in ein vollständiges Schema um.
- Umbenennen ist Entfernen plus Hinzufügen
- Aus zwei Ständen geht die Absicht einer Migration nicht hervor. Auch ein zuvor als deprecated markiertes Feld bleibt bei seiner Entfernung ein potenziell brechender Befund. Auch veraltete Felder dürfen nicht stillschweigend entfernt werden.
Fragen zum GraphQL-Schema-Vergleich
Ist ein nullable Mutation-Argument eine Breaking Change?
Ein zuvor verpflichtendes Mutation-Argument nullable zu machen, erweitert normalerweise die akzeptierten Werte. GraphQL.js bewertet diese Richtung nicht als Breaking Change; die umgekehrte Richtung kann alte Aufrufe ohne Argument zurückweisen.
Ist ein zusätzlicher Enum-Wert in GraphQL eine Breaking Change?
Ein weiterer Enum-Wert ist ein potenziell gefährlicher Wechsel: Eine bestehende Abfrage bleibt zwar gültig, aber ein Client mit erschöpfender Fallunterscheidung könnte den neuen Wert nicht behandeln.
Wie kann ich einen GraphQL-Typ ohne Breaking Change umbenennen?
Zwei SDL-Stände enthalten keine Information, dass eine Umbenennung beabsichtigt war. Der GraphQL-Schema-Vergleich zeigt daher den alten Typ als entfernt und den neuen als hinzugefügt. Eine Übergangsphase muss im API-Design geplant werden.
Kann man eine GraphQL-Mutation als veraltet markieren?
Eine Mutation ist ein Feld des Mutation-Wurzeltyps und kann @deprecated tragen. Die Kennzeichnung erhält alte Aufrufe; erst das spätere Löschen wird nach den Standardregeln als Breaking Change erfasst.
Ist die Änderung eines Non-Null-Feldes zu nullable eine Breaking Change?
Wird ein Rückgabefeld von non-null zu nullable geändert, können Annahmen generierter Clients ungültig werden. GraphQL.js stuft das als Breaking Change ein. Auch die Gegenrichtung braucht Resolver-Tests.
Ein konkretes Dokument macht Probleme?
Jetzt den GraphQL-Schema-Vergleich starten
Altes und geplantes SDL nebeneinander prüfen, alle Risikoklassen lesen und den aktuellen Bericht herunterladen.