GraphQL Schema Reviews für Teams: Was vor dem Merge geprüft werden sollte

1. Warum Schema Reviews kein optionaler Prozess sind

Ein GraphQL-Schema ist ein öffentlicher Vertrag – zwischen dem Backend-Team, das das Schema definiert, und dem Frontend-Team, das Queries und Mutations dagegen schreibt. Ein Code-Review für Backend-Klassen und Frontend-Komponenten ist in den meisten Teams etabliert. Ein dedizierter Review-Prozess für das GraphQL-Schema fehlt dagegen oft. Das hat Folgen: Breaking Changes landen unbemerkt in der Produktion, Typnamen folgen inkonsistenten Konventionen, und neue Felder sind undokumentiert, weil niemand @doc-Annotationen als Review-Kriterium betrachtet.

Der Unterschied zum normalen Code-Review: bei Code-Reviews prüft man Implementierungen – Logik, Lesbarkeit, Tests. Bei Schema-Reviews prüft man den Vertrag – Kompatibilität, Konsistenz und Verständlichkeit. Diese beiden Dimensionen überschneiden sich kaum, weshalb Schema-Reviews ein eigener Prozessschritt sein sollten, nicht ein Unteraspekt des normalen Code-Reviews. Das gilt besonders in Teams, in denen Backend- und Frontend-Entwickler separat arbeiten und das Schema die einzige Koordinationsschicht ist.

2. Breaking Changes: was sie sind und warum sie schaden

Ein Breaking Change im GraphQL-Schema ist jede Änderung, die bestehende Queries oder Mutations ungültig macht oder ihr Verhalten ändert. Das Umfasst: das Entfernen eines Feldes oder Typs, das Ändern des Typs eines Feldes (z.B. von String zu Int), das Hinzufügen eines Non-Null-Constraints auf ein bisher nullable Feld, das Umbenennen eines Typs oder Feldes und das Ändern von Enum-Werten. Jede dieser Änderungen kann einen bereits deployten Frontend-Client brechen, ohne dass eine Fehlermeldung im Backend erscheint.

Besonders tückisch: non-breaking auf den ersten Blick, breaking in der Praxis. Das Hinzufügen eines neuen Pflichtarguments zu einer bestehenden Query ist ein Breaking Change – bestehende Queries, die das Argument nicht übergeben, werden ungültig. Das Ändern der Semantik eines Feldes ohne Typänderung – zum Beispiel ein Preisfeld, das plötzlich Netto statt Brutto liefert – ist kein technischer Breaking Change, aber ein fachlicher. Ein gutes Schema-Review erkennt beide Kategorien.

3. Die Review-Checkliste: was manuell geprüft werden sollte

Eine Schema-Review-Checkliste für GraphQL-Teams sollte mindestens diese Punkte abdecken: Erstens, sind alle neuen Felder und Argumente mit @doc-Annotationen versehen? Ein Feld ohne Beschreibung ist für Frontend-Teams und neue Entwickler schwer nutzbar. Zweitens, folgen neue Typnamen der vereinbarten Namenskonvention? Prefixing, CamelCase, keine Abkürzungen – was das Team vereinbart hat, muss konsequent gelten. Drittens, sind alle Mutations-Argumente in Input-Types gekapselt? Vierte: sind Breaking Changes bewusst getroffen und kommuniziert worden?

Fünftens: sind neue Non-Null-Markierungen (!) auf Output-Feldern sorgfältig geprüft? Ein non-null Output-Feld, das in bestimmten Zuständen null zurückgibt, schlägt Queries fehl. Sechstens: sind neue Enums vollständig dokumentiert und sind alle Werte in der Implementierung abgedeckt? Siebtens: ist die Granularität der Typen angemessen – gibt es neue generische "god types", die zu viele Verantwortlichkeiten sammeln? Achtens: funktionieren Introspection und GraphiQL mit den neuen Typen korrekt?

# Breaking changes to catch in schema review

# ❌ Breaking: field removed
# Before:  type Product { description: String }
# After:   type Product { }   # existing queries break

# ❌ Breaking: field type changed
# Before:  price: Float
# After:   price: String      # type incompatibility

# ❌ Breaking: nullable changed to non-null
# Before:  thumbnail: String
# After:   thumbnail: String! # null return causes query failure

# ✓ Non-breaking: adding optional field
type Product {
  sku: String!
  name: String!
  # New field — nullable, so existing queries still work:
  sustainability_rating: Int @doc(description: "Eco score 1-10; null if not rated")
}

4. Tooling: GraphQL Inspector und automatische Checks

GraphQL Inspector ist das wichtigste Tool für automatische Schema-Reviews. Es vergleicht zwei Schema-Versionen und identifiziert Breaking Changes, Dangerous Changes und Safe Changes – mit klaren Kategorisierungen und menschenlesbaren Fehlermeldungen. Integration in Pull-Request-Workflows: GraphQL Inspector kann als GitHub-Action oder GitLab-CI-Step ausgeführt werden und kommentiert automatisch, welche Schema-Änderungen in einem PR Breaking sind, bevor ein Reviewer überhaupt geschaut hat.

Neben GraphQL Inspector gibt es weitere Werkzeuge: Hive CLI von The Guild ermöglicht Schema-Registry mit versionierter History und Policy-basiertem Breaking-Change-Management. Apollo Studio bietet ähnliche Funktionalität für Apollo-Ökosysteme. Für Magento-spezifische Schema-Reviews gibt es keinen dedizierten Tool-Support, aber GraphQL Inspector funktioniert schema-agnostisch und kann mit jedem SDL-basierten Schema genutzt werden – auch für Magento-Module.

# Schema diff example — what GraphQL Inspector reports
# Running: graphql-inspector diff old-schema.graphqls new-schema.graphqls

# ✓ SAFE: new nullable field added (non-breaking)
type CustomerProfile {
  email: String!
  name: String!
  # + loyalty_points: Int   <-- newly added, nullable = safe
}

# ⚠ DANGEROUS: default value changed
# input SearchInput { pageSize: Int = 10 }  ->  pageSize: Int = 20

# ✗ BREAKING: required argument added to existing field
# Before: products(search: String): ProductList
# After:  products(search: String!, category: String!): ProductList
#                                   ↑ new required arg = breaking

5. Schema Reviews in CI-Pipelines integrieren

Die Integration von Schema-Reviews in CI-Pipelines stellt sicher, dass Breaking Changes nicht durch schnelle Merges in die Hauptbranch gelangen. Der minimale Setup: ein CI-Step, der graphql-inspector diff zwischen dem Schema im Feature-Branch und dem Schema im Hauptbranch ausführt. Bei Breaking Changes schlägt der Step fehl und blockiert den Merge – oder er erzeugt einen Report als PR-Kommentar, der eine bewusste Entscheidung erfordert.

Ein erweiterter CI-Schema-Check umfasst zusätzlich: Validierung gegen definierte Naming-Convention-Regeln (konfigurierbar in .graphqlrc.yml), Prüfung auf fehlende @doc-Annotationen via Custom-Rules, Validierung der Schema-Syntax und ein Snapshot-Test, der das vollständige Schema-SDL in der Versionskontrolle hält. Dieser Schema-Snapshot dient gleichzeitig als Dokumentation und als Baseline für den nächsten Diff. Teams mit mehreren Modulen können jeden Modul-Schema-Snapshot separat verwalten und bei Merge-Konflikten gezielt auflösen.

6. Schema Reviews in Magento-Teams

In Magento-Teams gibt es eine zusätzliche Komplexität bei Schema-Reviews: das Gesamtschema entsteht erst beim Merge aller Modul-Schemata zur Laufzeit. Ein Review der einzelnen schema.graphqls-Datei eines Moduls erfasst nicht die Auswirkungen auf das globale Schema – Namenskonflikte mit anderen Modulen oder Breaking Changes durch Extend-Anweisungen auf Core-Typen sind erst im Kontext des gesamten Schemas sichtbar.

Die Lösung: das vollständige introspizierte Schema nach jeder Änderung exportieren (bin/magento graphql:introspect oder via GraphQL-Introspection-Query) und dieses als Snapshot in der Versionskontrolle halten. Der CI-Step vergleicht dann immer das vollständige generierte Schema – nicht nur die Modul-Datei. So werden Namenskonflikte und globale Breaking Changes erkannt, bevor sie in die Produktion gelangen. In Projekten mit vielen Modulen empfiehlt sich zusätzlich ein dediziertes Test-Environment, das alle Modulen merged und das Schema vor dem Deploy validiert.

7. Falsch / Richtig bei Schema-Änderungen

Der häufigste Fehler bei Schema-Änderungen in Teams: Umbenennen ohne Deprecation-Phase. Ein Feld wird umbenannt, weil der neue Name semantisch treffender ist – aber bestehende Queries brechen sofort. Das korrekte Vorgehen: das alte Feld mit @deprecated(reason: "Use newFieldName instead") markieren, das neue Feld parallel hinzufügen, Frontend-Teams über einen vereinbarten Zeitraum migrieren lassen, dann das alte Feld entfernen. Dieser Prozess ist aufwendiger, aber er verhindert ungeplante Produktionsfehler.

8. Den Review-Prozess als Teamritual etablieren

Ein Schema-Review-Prozess funktioniert nur, wenn er als fester Bestandteil des Merge-Workflows verankert ist – nicht als optionaler Schritt, der unter Zeitdruck weggelassen wird. Das bedeutet: Schema-Änderungen erfordern immer einen Pull Request, nie direktes Pushen in den Hauptbranch. Jeder PR mit Schema-Änderungen braucht mindestens ein Approval von einem Backend- und einem Frontend-Entwickler. Der CI-Check mit GraphQL Inspector läuft automatisch und muss grün sein, bevor ein Merge möglich ist.

Die kulturelle Dimension ist genauso wichtig wie die technische: Schema-Reviews sind kein Qualitätskontrollmechanismus, der Entwicklern misstraut – sie sind ein Koordinationsinstrument zwischen Teams. Ein gut dokumentiertes, konsistentes Schema macht Frontend-Entwickler selbständiger, reduziert Abstimmungsbedarf und verhindert Missverständnisse. Teams, die Schema-Reviews als Investition in bessere Zusammenarbeit verstehen, halten den Prozess aufrecht; Teams, die sie als Bürokratie sehen, umgehen sie sobald möglich.

9. Vergleich: Schema-Review-Methoden

Es gibt verschiedene Methoden für Schema-Reviews, die sich in Aufwand, Zuverlässigkeit und Automationsgrad unterscheiden. Rein manuelle Reviews sind flexibel, aber fehleranfällig und skalieren nicht mit der Teamgröße. Vollständig automatisierte CI-Checks sind zuverlässig für technische Kriterien, erkennen aber keine semantischen Probleme wie geänderte Bedeutungen von Feldern. Die beste Strategie kombiniert beide: automatische Checks als Pflichtschritt, manueller Review für semantische und fachliche Aspekte.

10. Zusammenfassung

Ein GraphQL Schema Review ist keine Bürokratie, sondern eine notwendige Koordinationsmaßnahme zwischen Backend und Frontend. Die technischen Aspekte – Breaking Changes, Naming Conventions, Nullability, Dokumentation – lassen sich größtenteils automatisch prüfen. GraphQL Inspector als CI-Step macht die meisten technischen Verstöße sichtbar, bevor ein menschlicher Reviewer überhaupt liest.

Was Tooling nicht leisten kann: semantische Reviews, fachliche Korrektheit und die Prüfung, ob ein neues Feld wirklich das modelliert, was der Client braucht. Dafür bleibt der manuelle Review unersetzlich – insbesondere das Approval durch einen Frontend-Entwickler, der die Perspektive des API-Konsumenten einbringt. Teams, die beide Dimensionen kombinieren – automatische technische Checks und manuellen semantischen Review – schützen ihr Schema vor den häufigsten Kategorie von Produktionsproblemen in GraphQL-basierten Systemen.

11. FAQ: GraphQL Schema Reviews für Teams

Ein konsequent durchgeführter Schema-Review-Prozess verhindert nicht nur Breaking Changes — er verbessert die API-Qualität nachhaltig und schafft Vertrauen zwischen Backend- und Frontend-Teams.