Seminar NestJS – GraphQL, Subscriptions und Federation

GraphQL verschiebt viele API-Entscheidungen vom Endpunkt in das Schema. Flexible Clients erzeugen neue Anforderungen an Typmodell, Berechtigungen, Abfragekosten, Caching und Beobachtbarkeit.

Der Kurs entwickelt einen Graphen von der einzelnen Anwendung bis zur föderierten Architektur. Jede Stufe enthält messbare Qualitätskriterien für Schemaentwicklung, Datenzugriff, Sicherheit, Echtzeitkommunikation und Betrieb.

Inhaltsübersicht

• Lernziele
• Schema-Design und API-Vertrag
• Resolver, Module und Datenzugriff
• Sicherheit und Abfragekontrolle
• Subscriptions und Echtzeitdaten
• Federation und verteilter Graph
• Praxisprojekt: Föderierter Produkt- und Bestellgraph
• Prüfpunkte und typische Fehler

Lernziele

• Code-first- und Schema-first-Ansätze anhand konkreter Projektbedingungen auswählen.
• Stabile Typen, Eingaben, Mutationen, Verbindungen und Fehlerverträge modellieren.
• Resolver modular strukturieren und Datenzugriff ohne N+1-Probleme implementieren.
• Authentifizierung, feld- und objektbezogene Autorisierung sowie Abfragebegrenzung umsetzen.
• Subscriptions mit Authentifizierung, Filterung, Lebenszyklus und Skalierung betreiben.
• Federation, Ownership, Entity-Auflösung, Verträge und verteilte Tests planen.

Schema-Design und API-Vertrag

Das Schema wird als langfristiger Vertrag behandelt. Fachliche Begriffe, Nullbarkeit, Identitäten und Mutationsgrenzen werden unabhängig von internen Tabellen modelliert.

1. Typen nach fachlichen Ressourcen und Anwendungsfällen statt nach Tabellen modellieren.
2. Nullbarkeit bewusst einsetzen und fehlend, unbekannt und nicht berechtigt unterscheiden.
3. Input Types von Output Types trennen und Mutationen eindeutig benennen.
4. Globale Objektidentitäten und stabile Cursor für Pagination definieren.
5. Deprecation statt abruptem Entfernen von Feldern verwenden.
6. Fehler als konsistenten Vertrag aus Transport-, Validierungs- und Fachfehlern gestalten.

Entscheidungskriterien und Hinweise

• Schemaänderungen werden auf Client-Kompatibilität geprüft.
• Nullbarkeit ist Teil des Vertrags und keine bloße Implementierungsbequemlichkeit.

Resolver, Module und Datenzugriff

Resolver bleiben dünne Adapter. Fachlogik liegt in Application Services; Datenzugriffe werden pro Request geplant und gebündelt.

1. GraphQL-Modul konfigurieren und Kontext mit Identität sowie Loader-Registry bereitstellen.
2. Object Types, Inputs, Queries und Mutations nach Fachmodulen organisieren.
3. Resolver an Application Services anbinden.
4. Batch Loader für relationale und servicebasierte Abhängigkeiten pro Request erzeugen.
5. N+1-Szenario messen, Loader ergänzen und Zahl der Datenzugriffe erneut prüfen.
6. Cursor-Pagination mit stabiler Sortierung und begrenzter Seitengröße implementieren.
7. Resolver-Ausnahmen in einen einheitlichen Fehlervertrag übersetzen.

Entscheidungskriterien und Hinweise

• Loader sind requestgebunden und dürfen keine Daten zwischen Nutzern vermischen.
• Resolver erzeugen keine versteckten Kaskaden über mehrere Dienste.

Sicherheit und Abfragekontrolle

Sicherheitsentscheidungen müssen auf Operation, Feld, Objekt und Datenmenge bezogen werden. Netzwerkregeln am einzelnen HTTP-Endpunkt reichen nicht aus.

1. Identität im GraphQL-Kontext bereitstellen und Guards für Queries, Mutationen und Resolver kombinieren.
2. Objekt- und feldbezogene Policies für Mandant, Besitz und sensible Attribute einsetzen.
3. Introspection und Entwicklungsoberflächen je Umgebung kontrollieren.
4. Abfragetiefe, Komplexität, Aliase, Batch-Größe und Ausführungszeit begrenzen.
5. Persistierte oder zugelassene Operationen für kontrollierte Clients bewerten.
6. Fehlermeldungen und Logs von Variablen, Tokens und personenbezogenen Daten bereinigen.
7. Rate Limiting anhand von Identität und Abfragekosten planen.

Entscheidungskriterien und Hinweise

• Top-Level-Autorisierung schützt nicht automatisch untergeordnete sensible Felder.
• Abfragekosten werden mit realen Resolvern und Datenzugriffen gemessen.

Subscriptions und Echtzeitdaten

Subscriptions verbinden langlebige Abonnements mit fachlichen Ereignissen. Authentifizierung, Reconnect, Filterung und Backpressure werden ausdrücklich definiert.

1. Fachliche Ereignisse und abonnierbare Zustandsänderungen auswählen.
2. Verbindungsaufbau authentifizieren und Token-Ablauf berücksichtigen.
3. Topics und Payloads mandantenfähig und minimal gestalten.
4. Berechtigungsprüfung bei jeder relevanten Auslieferung durchführen.
5. Reconnect, verpasste Ereignisse und Wiederaufnahme semantisch definieren.
6. Mehrere Instanzen über einen gemeinsamen Ereigniskanal synchronisieren.
7. Last, langsame Clients und Verbindungsabbau automatisiert testen.

Entscheidungskriterien und Hinweise

• Subscriptions ersetzen keine persistente fachliche Historie.
• Verpasste Ereignisse benötigen Snapshot oder nachvollziehbare Nachlieferung.

Federation und verteilter Graph

Federation wird als Verantwortungsstruktur behandelt. Jeder Teilgraph besitzt klare Felder und Entitäten; Änderungen werden über Verträge und Kompatibilitätsprüfungen abgesichert.

1. Domänengrenzen, Feld-Ownership und Entity-Schlüssel festlegen.
2. Referenzauflösung ohne versteckte Kaskaden implementieren.
3. Schema-Komposition und Breaking-Change-Prüfung in die Pipeline integrieren.
4. Fehler, Timeouts und partielle Ergebnisse für abhängige Teilgraphen definieren.
5. Tracing und Korrelationsdaten über Gateway und Teilgraphen weitergeben.
6. Contract-, Kompositions- und End-to-End-Tests für den Gesamtgraphen aufbauen.

Entscheidungskriterien und Hinweise

• Teilgraphen folgen fachlichen Verantwortlichkeiten und nicht nur Teamstrukturen.
• Entity-Auflösung darf keine unkontrollierten Netzwerkfächer erzeugen.

Praxisprojekt: Föderierter Produkt- und Bestellgraph

Ein Produkt- und Bestellsystem wird zunächst als modularer Graph umgesetzt. Danach werden Produkt, Bestand und Bestellung in getrennte Teilgraphen überführt. Ein Client verwendet Queries, Mutationen und eine Status-Subscription.

Messungen zu Datenzugriffen, Abfragekomplexität und Fehlerpfaden begleiten die Umsetzung. Ein ausgefallener Teilgraph sowie ein inkompatibles Schema-Update werden gezielt simuliert.

1. Fachliches Schema mit Typen, Inputs, Pagination und Fehlervertrag entwerfen.
2. Modulare Resolver und Application Services implementieren.
3. N+1-Abfrage nachweisen und durch requestgebundene Loader beseitigen.
4. Policies, Komplexitätsgrenzen und kontrollierte Fehlerausgaben ergänzen.
5. Statusänderungen als authentifizierte Subscription bereitstellen.
6. Anwendung in Teilgraphen zerlegen und Entity-Auflösung implementieren.
7. Kompositions-, Contract- und End-to-End-Tests ausführen.
8. Timeout, Teilgraph-Ausfall und Schema-Inkompatibilität behandeln.

Prüfpunkte und typische Fehler

• Das Schema spiegelt keine internen Tabellen ungefiltert wider.
• Resolver enthalten keine umfangreiche Fachlogik und keine unkontrollierten Datenzugriffe.
• Berechtigungen werden auch unterhalb der Top-Level-Operation geprüft.
• Abfragekosten und Seitengrößen besitzen harte, getestete Grenzen.
• Subscriptions definieren Reconnect, Token-Ablauf und verpasste Ereignisse.
• Federation folgt fachlichen Verantwortlichkeiten und stabilen Verträgen.