Nils Hartmann

https://nilshartmann.net / @nilshartmann

Freiberuflicher Software-Entwickler, Berater und Trainer aus Hamburg

Java | JavaScript, TypeScript | React | GraphQL

https://graphql.schule/video-kurs

https://reactbuch.de

Agenda

• Teil 1: GraphQL

  • Was ist GraphQL?
  • Die Abfragesprache

• Teil 2: GraphQL Anwendungen bauen

  • Die Basis:
    • Das Schema Definieren
    • GraphQL APIs mit Spring for GraphQL
      • Handler-Funktionen für Queries
      • Mutations
  • Optimierungen:
    • DataLoader
    • Fehlerbehandlung
    • Security
    • Testen

• Jeder Zeit: Eure Fragen!

Zeitplan

• 09:00-17:00

• Zwischendurch Pausen ☕️ 🍰

GraphQL

"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data" (https://graphql.org)

GraphQL

"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data" (https://graphql.org)

GraphQL

"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data" (https://graphql.org)

GraphQL

"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data" (https://graphql.org)

Die Beispiel-Anwendung "Publy"

http://localhost:3000

Eine API für Publy

• Ansatz 1: Backend bestimmt Aussehen der Endpunkte / Daten
  • REST
• 

Eine API für Publy

• Ansatz 2: Client diktiert die API nach seinen Anforderungen
  • "Backend for Frontend"
• 

Eine API für Publy

• Ansatz 3: GraphQL
  • Aus Ansatz 1: Server bestimmt, wie Datenmodell aussieht
• 

Objekt Graphen

• GraphQL APIs stellen einen Graphen mit Objekten bereit

• Objekte enthalten Felder und die Felder haben Rückgabe-Typen (vergleichbar mit Java)

• Aus dem Graphen kann mit der Query-Sprache eine Untermenge der Felder ausgewählt werden

• Dazu gibt es ein spezielles Root-Objekt, mit dem ein Query beginnt

  • (Analog bei Bedarf Root-Objekte für Mutations und Subscriptions)
• 

Beispiel: GraphiQL

http://localhost:8080

Beispiel: GraphQL Tooling

• IntelliJ IDEA
• TypeScript (optional)

Spezifikation

• https://spec.graphql.org/
• Umfasst:
  • Query Sprache und -Ausführung
  • Schema Definition Language
• Kein fertiges Produkt, keine fertige Bibliothek
  • Es gibt Bibliotheken, die dir helfen, GraphQL APIs zu implementieren und bereitzustellen
  • Die abgefragten Daten müssen wir selbst ermitteln
  • GraphQL macht keine Aussage darüber, wo diese Daten herkommen (Datenbank, Micro-Service, Berechnung ...)

Die GraphQL Abfrage-Sprache

Sprache, um Felder aus einem Objekt-Graphen abzufragen

  query {
    story {
      id title writtenBy {
        id user { name }
      }
    }
  }

Felder können Argumente haben

  query {
    story(storyId: 5) {
      id title writtenBy {
        id user { name }
      }
    }
  }

Die Antwort sieht immer so aus, wie die Abfrage

Operation-Type

Ausgeführt werden Operationen. Der Operation-Type beschreibt, was in der Anfrage getan werden soll

• query: Daten lesen (Default-Operation, Schlüsselwort "query" kann weggelassen werden)
• mutation: Daten verändern
• subscription: Daten vom Server bekommen, sobald sie erzeugt wurden (ähnlich wie Events)

Operation-Type

Der Operation-Type bestimmt auch den Einstiegspunkt in den Objekt-Graphen

Namen von Operationen

• Operationen können Namen haben.

• Das ist vor allem für Debugging und Code-Generatoren relevant

• 
  query NewestStory {
    story {
      id
      title
    }
  }
  

Fragmente

• Mit einem Fragment beschreibst Du eine wiederverwendbare Menge von Feldern

• fragment BaseMember on Member {
      id joined
      user { is username }
  }
  
  query {
      story {
        writtenBy { ...BaseMember }
  
        reactions {
          givenBy { ...BaseMember }
        }
      }
  }

Union-Typen

Ein Union-Type kann mehr als einen Typ zurückliefern:

  mutation  addComment
      (input: { storyId: "1", content: "..." }) {

      ...on AddCommentSuccessPayload {
        newComment { id }
      }

      ...on AddCommentFailurePayload {
        errorMessage
      }
  }

Interfaces

• Ein Interface erzwingt gemeinsame Felder an den Objekten, die das Interface implementieren (ähnlich wie in Java mit Methoden)

• Beispiel: id und createdAt sind am Node-Interface definiert

• query {
      node(id: "...") {
  
        id
        createdAt
  
        ...on Story { title body }
        ...on Comment { content }
      }
  }

Variablen

• Queries können Variablen haben.

• Variablen müssen im Query deklariert werden

• Werte für Variablen werden in einem eigenen JSON-Objekt an den Server geschickt

• query ($storyId: ID!) {
    story(id: $storyId) {
      id
      title body
    }
  }

Übung: Einen Query ausführen

Mach' dich mit der GraphQL-Abfragesprache vertraut

• Öffne GraphiQL auf diesem Demo-Server: https://graphql.schule/publy
• Versuche einen Query auszuführen, der die ersten zehn Stories zurückliefert und folgende Felder abfragt:
  • Id, Titel, Excerpt, Veröffentlichungsdatum, Wer hat die Story geschrieben und die jeweils ersten zehn Kommentare
• Kannst Du den Query so erweitern, dass er die ersten zehn neusten Stories zurückliefert?
• 💡 Du kannst Code-Completion und den Docs-Explorer (Buch-Symbol links oben) verwenden, um die API zu untersuchen
• Mögliche Lösung: https://graphql.schule/queries

GraphQL Requests

• HTTP Request an die GraphQL API

GraphQL Requests

• Üblicherweise nur HTTP POST-Request
  • andere HTTP Verben spielen in der Regel keine Rolle
  • HTTP Status-Code meist 200 OK, auch im Fehlerfall!
  • Großer Unterschied zu REST APIs
• Antwort JSON-Objekt besteht aus maximal drei Feldern:
  • data: Die gelesenen Daten (Struktur darunter entspricht der Abfrage)
  • errors: Liste mit (technischen) Fehlern, u.a. Fehlermeldung
  • extensions: Freibelegbares Objekt für proprietäre Erweiterungen (z.B. Debug-Informationen)
• Eine Spezifikation dafür ist in Arbeit

Teil II

GraphQL APIs bereitstellen

Wir veröffentlichen mit GraphQL eine fachliche API

• Welche Daten wir zur Verfügung stellen ist unsere Aufgabe
• Wir legen fest, in welcher Form die Daten zur Verfügung gestellt werden
  • 👉 Wir legen damit explizit selbst fest, wie unsere API aussehen soll
  • 👉 GraphQL erzeugt die API nicht auf "magische" Weise selbst
  • 🛠️ Es gibt allerdings Tools, die z.B. für eine Datenbank eine API erzeugen können

Das GraphQL Schema

• GraphQL APIs müssen in einem Schema beschrieben werden.
• In dem Schema werden Objekte (Typen) mit Feldern beschrieben.
• Das Schema selbst ist zur Laufzeit mit einem Introspection Query abfragbar
  • 🧑‍💻 Beispiel in GraphiQL
• Je nach Framework gibt's unterschiedliche Möglichkeiten, das Schema zu definieren
  • Schema-first: erst Schema beschreiben, dann implementieren
  • Code-first: Schema wird aus (Java-)Code generiert
  • Java-Frameworks verwenden i.d.R. Schema-first (bis auf MicroProfile GraphQL)
  • DGS (GraphQL Bibliothek von Netflix) kann auch Code generieren

Beschreibung des Schemas

• Mit der Schema Definition Language
• Per Java API
• In der Regel wird die SDL verwendet

Die SDL

• Demo: Schema-Definition

Die SDL

Beschreibung eines Objekt Types

  type Story {
    id: ID!

    title: String!
    body: String!
  }

• Beschrieben werden Felder mit Return Types
• Ein Ausrufezeichen zeigt an, dass das Feld nicht nullable ist

Dokumentation und Kommentare

• Dokumentation mit drei doppelten Anführungszeichen

  • Markdown zur Formatierung erlaubt

• Kommentare mit Hash-Zeichen

  • Dokumentation ist Bestandteil der API, Kommentare nicht

• """
  A `Story` is the main object in our service.
  """
  type Story {
    """Identifies this object"""
    id: ID!
  
    # todo: implement new tags-field (PROJ-666)
  }

Skalare Typen

• Skalare Typen entsprechen primitiven Typen in Java

  • Sind die Enden im Objekt-Graphen

• Standard-Typen: ID, String, Boolean, Int, Float

  • ID wird als String gelesen und geschrieben, soll aber nicht interpretiert werden

• type Member {
    id: ID!
  
    username: String!
  
    # no exclamation mark: can be null
    likes: Int
  
    amount: Float!
  
    activeMember: Boolean
  }

• Man kann eigene skalare Typen bauen

Aufzählungstypen (enum)

• Wie in Java

• enum ReactionType {
    like,
    laugh,
    thumbUp
  }

Referenzen

• Referenzen auf andere Objekt-Typen

• type Member {
    # ...
  }
  
  type Comment {
    # ...
  }
  
  type Story {
    """Reference to the Member that has written this Story"""
    writtenBy: Member!
  
    comments: [Comment!]!
  
  }

Argumente

• Felder können Argumente haben

  • Solche Felder werden auch Methoden genannt

• Die Felder mit ihren Namen und Typen müssen in der API definiert werden

  • Namen sind entscheidend (wie "named arguments" in Kotlin), nicht Reihenfolge (wie in Java)

• Argumente können Default-Werte haben

• Achtung! Argumente dürfen keine Objekt-Typen sein!

• type Story {
  
    # Mandatory argument maxLength, defaults to 20
    #  if not specified by the client
    excerpt(maxLength: Int! = 20): String!
  
  }

Root-Typen

• Root-Typen bilden den Einstiegspunkt für Queries in den Objekt-Graphen

• Root-Typen sind Query, Mutation und Subscription

  • Query ist Pflicht, die beiden anderen Typen optional

• Syntax und Verhalten genauso wie bei Objekt-Typen

• Felder an den Root-Typen werden auch Root-Felder genannt

• type Query {
    """Returns a List of all stories"""
    stories: [Story!]!
  
    """Returns a story by its ID or null"""
    story(id: ID!): Story
  }
  
  type Mutation {
    addComment(storyId: ID!, memberId: ID!, content: String!): Comment!
  }

Input-Typen

• Objekt-Typen können nicht als Argument an ein Feld übergeben

• Als Argumente an Feldern können nur skalare Typen, Enums und Input-Typen übergeben werden.

• Ein Input-Type wird mit input definiert, sieht ansonsten aus wie ein Objekt-Type

  • Ein Input-Type darf keine Objekt-Typen referenzieren

• input AddCommentInput {
    storyId: ID!
    memberId: ID!
    content: String!
  }
  
  type Mutation {
    addComment(input: AddCommentInput!): Comment!
  }

Union Types

• Union Types bilden eine Menge von anderen Typen

• Ein Feld kann ein Typen aus dieser Menge zurückliefern ("A oder B")

• type AddCommentSuccess { newComment: Comment! }
  type AddCommentFailed { errorMessage: String! }
  
  union AddCommentResult = AddCommentSuccess | AddCommentFailed
  
  type Mutation {
    addComment(input: AddCommentInput!): AddCommentResult!
  }

Interfaces

• Mit einem Interface wird erzwungen, dass Objekte über gleiche Felder verfügen

  • Vergleichbar mit Interfaces in Java

• interface Node {
    id: ID!
  }
  
  type Story implements Node {
    id: ID!  # Field defined in Node-Interface
  
    title: String! # additional Story fields
  }
  
  type Comment implements Node {
    id: ID! 
  
    content: String!
  }
  
  type User {
    id: ID!
    email: String
  }
  
  type Query {
    # Returns either Story or Comment, but not User
  
    node(id: ID!): Node 
  }

Schema-Evolution

• In GraphQL gibt es nur eine Version der API (kein /api/v1, /api/v2)

• Das Schema kann jederzeit erweitert werden

  • Clients fragen explizit Felder ab, d.h. durch neue Felder werden sie nicht beeinträchtigt

• Man kann Felder mit deprecated markieren, um anzuzeigen, dass sie nicht genutzt werden sollen

• type Query {
    # Ausgangspunkt 
    getStoryById(id: ID!): Story
  }

• type Query {
    getStoryById(id: ID!): Story
  
    # Neues Feld, beeinträchtigt bestehenden Client nicht
    stories: [Story!]!
  }

• type Query {
    getStoryById(id: ID!): Story @deprecated("Use story instead")
    story(id: ID!): Story
  
    stories: [Story!]!
  }

Eine API für ganze Anwendung

• Üblicherweise hat eine Anwendung eine GraphQL API
  • In REST gibt es mehrere Endpunkte, die auf unterschiedliche Server verteilt sein können
  • GraphQL soll zentrale API sein
  • Untereinander kommunizieren die Services per REST o.ä.

Übung: Schema beschreiben

Vorbereitung: Das Repository

• workspace: Hier arbeiten wir, bitte in der IDE öffnen

  • workspace/publy-backend: Spring Boot-Projekt, in dem wir die GraphQL API implementieren
  • workspace/publy-userservice: Spring Boot-Projekt mit dem UserService
  • workspace/steps: Lösungen für die einzelnen Übungen

• Nach dem Öffnen in der IDE sollte es keine Compilier-Fehler geben.

  • Bitte verwende mindestens JDK 17

• Starten des Backends

  • Bitte führe in deiner IDE die Klasse nh.publy.backend.PublyApplication aus (darin enthalten ist eine main-Methode)
  • Wenn Du http://localhost:8090 öffnest, sollte GraphiQL geöffnet werden.
  • Wenn Du Änderungen im Code machst und speicherst bzw. compilierst/baust, sollte sich das Backend automatisch neu starten.

Übung: Schema beschreiben

• Vervollständige die Datei publy-backend/resources/graphql/publy.graphqls und beschreibe darin eine API, die folgende Objekt-Typen enthält:
  • Member mit id und profileImage
  • Story mit id, title, body, excerpt und einer Referenz (writtenBy) auf den Member
  • Alle Felder in den beiden Typen sind Pflicht (non-nullable), das id-Feld ist vom Typ ID alle anderen Strings
• Lege den Query-Typen mit folgenden Feldern an:
  • stories: Liefert eine Liste der Story-Objekte zurück. Nicht nullable.
  • story: Liefert eine einzelne Story zurück. Das Feld soll ein Argument haben: storyId. Das Feld kann null zurückgeben
• Du kannst dir das Schema in GraphiQL anzeigen lassen (http://localhost:8090)
  • Zum Beispiel im "Documentation Explorer"
  • Wenn Du in der IDE Änderungen machst, musst Du die GraphiQL-Seite im Browser neu laden.
• Eine mögliche Lösung findest Du in steps/01-schema

Implementieren der GraphQL API

Die Beispiel-Anwendung

Die Basis: graphql-java

• 
• graphql-java ist die Basis für alle (?) Java-basierten GraphQL-Frameworks
• Zuständig für die eigentliche Ausführung einer GraphQL Operation:
  • Schema-Definition mit der SDL (oder per Java API)
  • Parsen und validieren einer GraphQL Operation
• Andere GraphQL Frameworks abstrahieren davon und stellen weitere Features zur Verfügung

Hintergrund: DataFetcher (graphql-java)

• Zentrales Interface in GraphQL-Java: Ermitteln die Daten für ein Feld eines Queries

  • Zum Beispiel für das Feld Query.story oder Story.title
  • In Spring for GraphQL wird davon abstrahiert
  • In anderen GraphQL Frameworks auch Resolver genannt

• interface DataFetcher<T> {
    T get(DataFetchingEnvironment environment); 
  }  

• T ist der Typ, der von diesem DataFetcher zurückgeliefert wird

• Beispiel:

• class PingDataFetcher implements DataFetcher<String> {
  
      @Override
      public String get(DataFetchingEnvironment env)  {
        return "Pong";
      }
  }

• Jeder DataFetcher wird im RuntimeWiring einem Feld der API zugewiesen

GraphQL Java Architektur

Spring for GraphQL

• Spring for GraphQL bietet eine Abstraktion von GraphQL-Java an

• Erstes Release von Spring for GraphQL enthalten in Spring Boot 2.7 (Mai 2022)

  • Projekte können mit dem Spring initializr erzeugt werden

• Features:

  • Automatische Konfiguration des RuntimeWirings
  • HTTP-Endpunkt für Requests und Subscriptions automatisch
  • GraphiQL Integration per Property
  • Gewohntes Spring-Programmiermodell mit Annotationen etc.
  • Integration in Spring Stack (z.B. Bean Validation, Security)
  • spring-boot-starter-graphql für Spring Boot
  • Actuator-Endpunkte für Spring Boot

Das Schema in Spring for GraphQL

• Das Schema wird in Dateien mit der Endung .graphqls abgelegt

  • Verzeichnis: main/resources/graphql

• Spring Boot sammelt alle Schema-Dateien ein und erzeugt ein Schema daraus

• Typen können erweitert werden

• 
  # story.graphqls
  extend type Query {
    story(id: ID!): Story
  }
  
  # comment.graphqls
  extend type Query {
    comment(id: ID): Comment
  }

Spring for GraphQL

• Demo: Handler-Funktionen für Story
• Query-Mapping!
• Argumente!

Handler-Funktionen

• Handler-Funktionen werden an Controller-Klassen implementiert

  • @Controller
    public GraphQLController {
    
      @QueryMapping
      public String ping() { return "Pong!" }
    
    }

  • Handler-Funktionen für Felder am Query-Typen werden mit @QueryMapping annotiert

    • Mutations: @MutationMapping, Subscription: @SubscriptionMapping

  • Der Name der Methode entspricht dem Namen des Feldes des entsprechenden Root-Typen (oder explizit mit value setzen)

Parameter von Handler-Funktionen

• @Argument um ein einzelnes Argument zu erhalten

• type Query {
    ping(msg: String): String!
  }

• @QueryMapping
  public String ping(@Argument String msg) { 
    return "Hello " + msg; 
  }

Parameter von Handler-Funktionen

• Für Input-Typen kann ein Pojo angegeben werden:

• input GreetingInput { name: String, msg: String }
  
  type Query {
    greet(input: GreetingInput!): String!
  }

• class GreetingInput { private String name; private String msg; /* getter+setter... */ }
  
  // oder Java 17 Records:
  record GreetingInput(String name, String msg) {}
  
  @QueryMapping
  public String greet(@Argument GreetingInput input) { 
    return "Hello " + input.getName(); 
  }

• Argumente können mit Bean Validation validiert werden

• class GreetingInput { @Size(min=5) private String name; private String msg; /* getter+setter... */ }
  
  @QueryMapping
  public String greet(@Valid @Argument GreetingInput input) { 
    return "Hello " + input.getName(); 
  }

Übung: QueryMapping-Funktionen

• Kopiere bitte das (fertige) Schema aus steps/01-schema nach publy-backend/src/main/resources/graphql (bestehendes Schema überschreiben)
• Erweitere die Klasse nh.publy.backend.graphql.PublyGraphQLController:
  • Implementiere zwei QueryMapping-Funktionen für die Root-Felder unserer API:
    • Eine Mapping-Funktion für Query.stories und für Query.story(id: ID!)
  • Du kannst in der Controller-Klasse das StoryRepository verwenden.
    • Darin sind Methoden zum Ermitteln der Stories aus der Datenbank enthalten.
• Folgende Queries sollten danach funktionieren (in GraphiQL http://localhost:8090 ausführen!):

  •   query {
        stories {
          id title body
    
          writtenBy { id profileImage }
        }
      }

  •   query {
        story(storyId: 1) {
          id title body
    
          writtenBy { id profileImage }
        }
      }

• Eine mögliche Lösung findest Du in steps/10_handler_function

Handler-Funktionen an Objekt-Typen

• Demo: Excerpt-Feld hinzufügen

Handler-Funktionen an Objekt-Typen

• Felder, die an einem Java-Objekt definiert sind, die von einer Handler-Funktion zurückgeliefert werden, werden automatisch per Reflektion von Spring-GraphQL abgefragt
  • Voraussetzung: Name des Java-Felder/getter-Methode entspricht Namen am GraphQL Schema
  • Beispiel: body- und writtenBy-Feld an der Story-Entity
• Wenn es kein Feld am Java-Objekt gibt, oder es sich anders verhält, als von der GraphQL API erwartet, müssen wir auch dafür Handler-Funktionen schreiben
• (Felder, die an Java Objekten existieren, aber nicht in der GraphQL API können nie vom Client abgefragt werden.)

SchemaMapping

• Die Funktion wird dann mit @SchemaMapping annotiert

  • Name muss dem Namen des Feldes in der API entsprechen
  • Parameter bestimmt das Source-Objekt, auf dem das Feld ermittelt werden soll
  • Das Source-Objekt stammt aus einem vorherigen DataFetcher

• @Controller
  class GraphQLController {
    @SchemaMapping
    public String excerpt(Story source, @Argument int maxLength) {
      return source.getBody().substring(0, maxLength);
    }
  }

• Wenn die als Parameter übergebene Klasse nicht so heißt, wie im GraphQL Schema, kann mit typename der GraphQL-Typ explizit gesetzt werden

• @SchemaMapping(typeName="Story")
  public String excerpt(StoryDto source) {
    // ...
  }

• @QueryMapping, @SubscriptionMapping und @MutationMapping sind nur Aliase für

  • @SchemaMapping(typeName="Query")
  • @SchemaMapping(typeName="Mutation")
  • @SchemaMapping(typeName="Subscription")

Asynchrone Handler-Funktionen

• Instrumentation hinzufügen

Asynchrone Handler-Funktionen

• Handler-Funktionen werden grundsätzlich nacheinander ausgeführt

• Handler-Funktionen können aber CompletableFuture, Flux oder Mono-Objekte zurückliefern

• Dann werden mehrere Handler-Funktionen parallel ausgeführt

• @Service
  public class DomainService {
    @Async
    CompletableFuture<String> determineExcerpt(Story story, int maxLenght) {
      // long running task...
    }
  }
  
  @Controller
  public class GraphQLController {
    @Autowired DomainService domainService;
  
    @SchemaMapping
    public CompletableFuture<String> excerpt(Story story, @Argument int maxLength) {
      return domainService.determineExcerpt(story, maxLength); // asynchron bzw. reaktiv
    }
  }

Übung: Schema-Mapping

• Wir erweitern den Member-Typen um das User-Objekt:

• type User {
    id: ID!
    name: String!
    email: String!
  }
  
  type Member {
    # ...
    user: User
  }

• Die Member-Klasse hat aber keine Referenz auf den User (nur dessen Id)

• @Entity
  public class Member {
    // ...
    @NotNull
    private String userId;
  
    public String getUserId() { return this.userId };
  }

• Der User kommt aus dem UserService (externer Micro-Service)

Übung: Schema-Mapping

• Vorbereitung 1: UserService starten

  • Bitte starte die Klasse nh.graphql.publy.userservice.UserserviceApplication aus dem publy-userservice-Verzeichnis (darin ist eine main-Methoden vorhanden)

• Vorbereitung 2: Ergänze das Schema

  • Bitte kopiere den Inhalt von material/15-schema-mapping/schema.graphqls an das Ende deiner publy.graphqls-Schema-Datei.
  • Darin ist ein User-Typ definiert und der Member-Typ wird um ein user-Feld erweitert.

• Implementiere die Schema-Mapping-Funktion für das Feld Member.user

  • Die Schema-Mapping-Funktion soll asynchron funktionieren
  • Der UserService ist bereits implementiert
  • Falls Du in der vorherigen Übung nicht fertig geworden ist, kopiere dir den PublyGraphQLController aus steps/10_handler-function

• Der folgende Query sollte User zurückliefern, wenn Du die Schema-Mapping-Funktion korrekt implementiert hast:

• query {
    story(storyId: 1) {
      id 
      writtenBy {
        # Hier sollten nun Daten kommen:
        user {
          id name email
        }
      }
    }
  }

• Eine mögliche Lösung findest Du in steps/15_schema-mapping

Mutation und Subscriptions

• Funktionieren analog zum QueryMapping nur für den Mutation- und Subscription-Type
• Bei Mutations dürfen wir Daten verändern, ansonsten völlig identisch zu QueryMapping
• Bei Subscriptions werden die Daten erst zum Server geschickt, nachdem sie erzeugt wurde

Interaktiv: addComment-Mutation

• Material aus material/17-mutation
• Mit Payload als Rückgabe, ohne Union

Eine Mutation, um Kommentare hinzuzufügen

• Eine Story hat mehrere Kommentare:

• type Comment {
      id: ID!
  
      story: Story!
      writtenBy: Member!
      content: String!
  }
  
  type Story {
    # ...
    comments: [Comment!]!
  }

Eine Mutation, um Kommentare hinzuzufügen

• Eingabe-Parameter werden mit einem `input-Type ausgedrückt, der alle notwendigen Informationen entgegen nimmt

• input AddCommentInput {
      storyId: ID!
      memberId: ID!
      content: String!
  }
  
  type Mutation {
    addComment(input: AddCommentInput!): Comment!
  }

• 🤔 Ist der Rückgabe-Typ hier so gut?
  • Was könnte problematisch sein oder werden?

API Design von Mutations

• Wie ihr die Mutation designed ist natürlich Euch überlassen, es gibt aber Best-Practices:
  • Anstatt n einzelne Argumente zu verwenden, ein Input-Objekt
    • Das Objekt heißt immer wie die Mutation mit Input am Ende
    • Das Argument heißt immer input
  • Der Rückgabe-Typ sollte ebenfalls ein eigenes Objekt sein
    • Es heißt wie die Mutation mit Payload am Ende
    • Dieses Objekt enthält dann das erzeugte neue Objekt
    • Ihr könnt später diesen Typen um weitere Informationen, etwa zu Fehlern erweitern
      • Dazu später mehr
• Dadurch ist die API einheitlich und man findet sich schnell zurecht
• Diese Regeln könntet ihr grundsätzlich auch für Queries und Subscriptions verwenden

Übung: addComment Mutation implementieren

• Vorbereitung:
  • Wenn Du mit der vorherigen Übung nicht fertig geworden bist, kopiere dir den PublyGraphQLController aus steps/15_schema-mapping
  • Kopiere den Inhalt von material/17-mutation/schema.graphqls an das Ende deiner bestehenden publy.graphqls-Datei
  • Darin ist die Erweiterung des Schemas vorhanden:
    • Eine Story hat nun comments. Es gibt die addComment-Mutation.
• Implementiere die MutationMapping-Funktion am PublyGraphQLController
  • Baue dir jeweils eine Java-Klasse (POJO) für das input-Argument und den Rückgabetyp AddCommentPayload
    • Wichtig: mit getter- und setter-Funktionen für alle Felder (die genauso wie im GraphQL Schema heißen müssen).
  • Du kannst dir über den PublyGraphQLController-Konstruktor den fertigen PublyDomainService übergeben lassen
    • Daran gibt es eine Methode addComment, der einen Kommentar in der DB speichert
    • Ruf diese Methode auf und gib das Ergebnis an GraphQL zurück
• Danach sollte die Mutation in material/17-mutation/add-comment.graphql funktionieren
• Eine mögliche Lösung findest Du in steps/17_mutations

Optimierungen

Ein einfacher Query...

• 🤔 Was passiert, wenn wir folgenden Query ausführen:

• query {
    stories {
      writtenBy { user { id email } }
    }
  }

• Wir haben sehr viele einzelne Calls zum Micro-Service 😨
• Wir haben doppelte Aufrufe zum Micro-Service 😱 😱

Problem

DataLoader

• Ein DataLoader "verzögert" das Laden von Daten

• 

DataLoader

• Ein DataLoader "verzögert" das Laden von Daten
• In einem DataFetcher/Handler-Funktion übergibst Du an einen DataLoader eine ID o.ä.
• Der DataLoader sammelt die IDs ein
• Wenn alle IDs eingesammelt wurden, wird die Implementierung des DataLoaders aufgerufen
• In der Implementierung bekommst Du alle IDs übergeben und kannst einen optimierten Call machen
  • Zum Beispiel Zusammenfassung in SQL-Statements (where ID in ...)
• DataLoader sind ein allgemeines GraphQL-Konzept
  • Nicht in der Spec, aber de-facto Standard
• Java-Implementierung kommt aus dem java-dataloader-Project
  • Wie bei graphql-java abstrahiert Spring for GraphQL davon

Verwenden vom DataLoader

• Den DataLoader kannst Du dir in deine Handler-Funktionen übergeben lassen
• Es handelt sich dabei um ein Interface mit zwei Typ-Parametern:
  • Key: Typ des Keys, den Du beim Verwenden an den DataLoader übergeben willst
  • Value: Typ des Java-Objekts, das der DataLoader für einen Key zurückliefert
• Die Handler-Funktion muss dann ein CompletableFuture zurückliefern

• public CompletableFuture<User> user(Member member, DataLoader<String, User> userLoader) {
    String userId = member.getUserId();  // userId ist in DB gespeichert
  
    return userLoader.load(userId); // Laden des Users wird verzögert
  }

Implementierung und Registrieren vom DataLoader

• Es gibt mehrere Wege
• In der BatchLoaderRegistry gibt es Hilfsfunktionen
• Die BatchLoaderRegistry steht als Spring Bean zur Verfügung
• Mit forTypePair registrierst Du einen BatchLoader für ein Key-Value-Paar
• Die Methode erwartet eine Callback-Funktion:
  • zwei Parameter: die Liste mit den Keys und das BatchLoaderEnvironment
  • Rückgabe: die Liste mit den geladenen Objekten als Flux

• public PublyGraphQLController(/* ... */, BatchLoaderRegistry registry) {
  
    registry.forTypePair(String.class, User.class).registerBatchLoader(
  
      (List<String> keys, BatchLoaderEnvironment env) -> {
        // hier zum Beispiel DB-Aufruf oder REST-Aufruf
        // findUsers liefert Flux<User> zurück.
        return userService.findUsers(keys);
      }
    );
  
  }

• Jeder Key wird nur einmal in die Liste eingefügt, du bekommst also keine doppelten Keys
  • Selbst wenn Du also nicht alle Objekte mit einem Request laden/ermitteln kannst, verhinderst Du immerhin doppeltes Laden
• Wichtig! Die Funktion muss die Objekte in derselben Reihenfolge zurückliefern, in der die Keys übergeben wurden.
  • Konnte für einen Key kein Objekt ermittelt werden, muss an der Stelle null zurückgegeben werden

MappedBatchLoader

• Der BatchLoader liefert eine Liste von Objekten zurück
• Die enthaltenen Objekte müssen in derselben Menge und Reihenfolge wie die Keys zurückgeliefert werden.
• Alternativ kann ein MappedBatchLoader verwendet werden, der ein Mono-Objekt mit einer Map zurückliefert
• Die Map enthält dann Key-Value-Paare mit einem gelesenen Objekt jeweils für einen Key. Objekte, die nicht gefunden wurden werdenauch nicht in die Map aufgenommen.

• public PublyGraphQLController(/*... */, BatchLoaderRegistry registry) {
  
    registry.forTypePair(String.class, User.class).registerMappedBatchLoader(
  
      (List<String> keys, BatchLoaderEnvironment env) -> {
        // zurückgeben: Mono<Map<String, User>>
      }
  
    );
  }

BatchMapping

• In einfachen Fällen kann der MappedBatchLoader mit einer BatchMapping-Funktion implementiert werden
• Das ist eine Handler-Funktion, der automatisch eine Liste von Objekten übergeben wird (zum Beispiel Liste von Member-Objekten)
• Die Handler-Funktion liefert dann entweder ein Mono mit einer Map oder ein Flux mit Objekten zurück (wie vorher gesehen).
• Achtung! Darauf achten, dass equals und hashCode-Methoden in den Objekten, die als Keys verwendet werden, korrekt implementiert sind!

• @Controller
  public class PublyGraphQLController {
  
    @BatchMapping
    public Flux<User> user(List<Member> member) {
      List<String> keys = member.stream().map(Member::getUserId).collect(Collectors.toList());
  
      return userService.findUsers(keys);
    }
  
    // -- oder: --
  
    @BatchMapping
    public Mono<Map<Member, User>> user(List<Member> member) {
      // ...
    }
  
  
    // BatchLoaderRegistry und SchemaMapping für User-Feld entfallen jetzt
  }

Optimierung 2

• Ein Query...

  • query {
      story(storyId: 1) {
        title
        body
      }
    }

• Ein anderer Query...

  • query {
      story(storyId: 1) {
        title
        body
        comments { id content }
      }
    }

• 🤔 Wie generieren wir optimale Datenbank-Zugriffe
  • Je nach Query mit oder ohne Comments?

DataFetchingFieldSelectionSet

• Das DataFetchingFieldSelectionSet aus graphql-java enthält eine Liste aller Felder, die im aktuellen Query unterhalb des Feldes einer Handler-Funktion abgefragt sind
• Das DataFetchingFieldSelectionSet kannst Du an deine Handler-Funktionen übergeben lassen.
• Mit contains kannst Du mit einem Pattern fragen, ob bestimmte Felder im Query vorhanden sind
• Hiermit kannst Du weitere Optimierungen der Query-Verarbeitung vornehmen, zum Beispiel optimale SQL-Queries generieren

• @QueryMapping
  List<Story> stories(DataFetchingFieldSelectionSet selectionSet) {
  
    if (s.contains("comments/**") ) {
      // SQL Statement mit JOIN auf Comment-Tabelle
      return ...;
    }
  
    // SQL Statement nur mit Stories
    return ...;
  
  }

Übung: DataLoader

Implementiere den DataLoader zum Laden des Users für einen Member aus dem User-Microservice

• Erweitere den Konstruktur von PublyGraphQLController und füge als neuen Parameter die BatchLoaderRegistry hinzu
• Registriere an der BatchLoaderRegistry eine DataLoader-Funktion, die für die Keys der User die entsprechenden User laden kann
  • Zum Laden der User kannst Du wieder die Klasse UserService verwenden (findUsers)
• Führe folgenden Query aus. Wieviele User sind im Ergebnis vorhanden? Wieviele User(-Ids) werden im BatchLoader geladen?

• query {
    stories {
      writtenBy { user { id name } }
      comments { writtenBy { user { id name } } }
    }
  }

• Eine Lösung findest Du in steps/20_dataloader

Pagination

Pagination

• GraphQL sagt nichts über Pagination, Sortierungen, Filtern etc. aus
• Das was man braucht, muss man im Schema beschreiben
• ...und dann auch implementieren im Backend 😱
• Beispiel mit PageRequest

GraphQL/Relay Cursor Spezifikation

• Es gibt eine Spezifikation für Pagination
• Die stammt aus der Relay-Bibliothek, wird aber von vielen genutzt
• Die Idee: man bekommt zu jedem Objekt einen Cursor geliefert
• Dann kann man bei jedem Request ausdrücken, ob wieviele Objekte vor oder nach einem Cursor bekommen möchte
• Demo im App-Projekt (oder https://publy.graphql.schule/)

Pagination mit Spring for GraphQL

• Seit der Version 3.1 von Spring Boot gibt es in Spring for GraphQL Support for Pagination
• Wenn ihr in Eurem Schema ein Query-Feld mit dieser Signatur habt:

• type Query {
    stories(first:Int, after:String, last:Int, before:String): PostConnection!
  }

• ...dann generiert euch Spring for GraphQL zur Laufzeit die fehlenden GraphQL Typem im Schema
  • PostConnection, PostEdge, PageInfo
• In der QueryMapping-Funktion für posts könnt ihr einen Parameter vom Typ ScrollSubrange angeben
• Darin legt Spring for GraphQL die übergebenen Parameter ( first, last etc ab)
• Aus diesem Objekt könnt ihr Euch u.a. eine ScrollPosition von Spring Data geben lassen
• Damit könnt ihr dann einen Query in eurem Spring Data Repository ausführen, das ein Window-Objekt zurückliefern muss
• Dieses Window-Objekt enthält die gefundenen Ergebnisse
• Spring for GraphQL kümmert sich dann darum, dass dafür die Edge-Objekte und das PageInfo-Objekt erzeugt und zum Client zurück gegeben wird

Beispiel: Paginierung von Stories

• Schema anpassen
• QueryMapping fuer stories um ScrollSubrange erweitern

Sortierung

• Auch für Sortierung gibt es nichts fertiges
• 🤔 Wie können wir das Ergebnis der Stories sortieren?
• Sortierung konfigurierbar machen

Fehlerbehandlung

• Beispiel: addComment mit "falschem" Kommentar

Fehlerbehandlung

• Fehler, die nicht in einer Handler-Funktion verarbeitet werden, werden im errors-Feld zurückgeliefert:

• {
    "errors": [
      {
        "message": "addComment.input.content: Größe muss zwischen 5 und 2147483647 sein",
        "locations": [
          {
            "line": 2,
            "column": 3
          }
        ],
        "path": [
          "addComment"
        ],
        "extensions": {
          "classification": "INTERNAL_ERROR"
        }
      }
    ]
  }

• {
    "errors": [
      {
        "message": "Unauthorized",
        "locations": [
          {
            "line": 2,
            "column": 3
          }
        ],
        "path": [
          "addComment"
        ],
        "extensions": {
          "classification": "UNAUTHORIZED"
        }
      }
    ]
  }

Fehlerbehandlung

• Das errors-Objekt ist nur eingeschränkt spezifiziert:
  • message: Fehlermeldung
  • locations: Auf welche Code-Stelle im Query bezieht sich der Fehler (wenn vorhanden)
  • path: Pfad zum Feld, das den Fehler verursacht hat (wenn vorhanden)
  • extensions: Proprietäre Erweiterungen (classification kommt von Spring for GraphQL)
  • Keines dieser Felder ist im Schema beschrieben!
• errors-Objekt nur für "Request Errors" verwenden, wenn der Query gar nicht oder nicht vernünftig ausgeführt werden kann
• Sonst lieber "fachliche" Fehler-Objekte zurückliefern
  • Das ist insbesondere bei Mutations sinnvoll, da hier Fehler nicht unwahrscheinlich sind
  • Auch für andere Felder überlegen, um API abwärtskompatibel zu halten

Explizite Rückgabetypen

• Beispiel 1: Query-Ergebnisse

• type Query {
    stories: [Story!]!
  }

• Was machen wir, wenn wir dem Ergebnis weitere Informationen hinzufügen wollen, z.B. wie viele Stories gibt es eigentlich?
• Änderung am Rückgabetyp wäre hier nicht abwärtskompatibel! 😢

• type StoriesPayload {
    stories: [Story!]!
  
    maxStories: Int!
  }
  
  type Query {
    stories: [Story!]!
  }

Explizite Rückgabetypen

• Beispiel 2: Behandlung von Fehlern
• Hier können wir keine Informationen hinterlegen, warum das Anlegen eines Kommentars möglicherweise nicht geklappt hat:

  • type Mutation {
      addComment: [Comment!]!
    }

• Mit einem eigenen Rückgabe-Objekt können wir weitere Informationen hinzufügen:

  • type AddCommentPayload {
      newComment: Comment
      errorMessage: String
    }
    
    type Mutation {
      addComment: AddCommentPayload!
    }

• Dieses Objekt können wir jederzeit erweitern, ohne das Clients angepasst werden müssen.

Explizite Rückgabetypen

• Fehler- und nicht-Fehlerfall können mit jeweils eigenen Typen ausgedrückt werden.
• Zusammengefasst werden sie in einem union-Typen:

  • type AddCommentSuccessPayload { newComment: Comment! }
    type AddCommentFailedPayload { errorMsg: String! }
    union AddCommentPayload = AddCommentSuccessPayload | AddCommentFailedPayload
    
    type Mutation {
      addComment(inpit: AddCommentInput!): AddCommentPayload!
    }

• Der Server liefert je nach Situationen einen der beiden Typen zurück.

  • mutation {
      addComment(input: {storyId: 1, memberId: 1, content: "Toll"}) {
        ... on AddCommentSuccessPayload {
          newComment { id content }
        }
        ... on AddCommentFailedPayload { errorMsg }
      }
    }

  • Achtung! Umstellung von type- auf union-Type im Rückgabewert ist nicht abwärtskompatibel!

Übung: Fehlerbehandlung mit Union Types

• Stelle die addComment-Mutation auf einen Union-Type um
• Vorbereitung:
  • Lösche die Mutation und den AddCommentPayload-Typen aus deinem Schema.
  • Kopiere die Anpassungen aus material/30-error-handling/schema.graphqls in dein Schema.
  • Falls Du mit der vorherigen Übbung nicht fertig geworden bist, verwende als Basis den PublyGraphQLController aus steps/20_dataloader
• Passe die Implementierung der addComment-Mutation an
  • Deinen bestehenden Java-Typen für AddCommentPayload kannst Du in AddCommentSuccessPayload umbennen
  • Du brauchst einen neuen Java-Typen für AddCommentFailedPayload
  • Wenn beim Aufruf des PublyDomainService eine Exception fliegt, gib AddCommentFailedPayload zurück mit einer Fehlermeldung
  • Sonst gib den neuen Kommentar in AddCommentSuccessPayload zurück
• Führe addComment aus und frag den neuen Kommentar bzw. die errorMsg ab
  • Um den Fehlerfall zu testen, kannst Du einen Kommentar speichern, der kürzer als fünf Zeichen ist.
• Mögliche Lösung: steps/30_error_handling

Security

• Wie üblich Spring Security verwenden
• 🤔Überlegung: wo wird GraphQL API abgesichert?
  • /graphql-Endpunkt absichern
  • und/oder einzelne Handler-Funktionen mit @PreAuthorize absichern
  • und/oder Domain-Layer absichern mit @PreAuthorize absichern

Beispiel: Security

• AddCommentMutation

Handler-Funktionen mit Security

• Handler-Funktionen können mit @AuthenticationPrincipal sich den aktuellen Principal übergeben lassen

• @MutationMapping
  @PreAuthorize("hasRole('USER')")
  public AddCommentPayload addComment(@Argument AddCommentInput input, @AuthenticationPrincipal User user) {
  
    Long memberId = publyDomainService.getMemberForUser(user);
  
    // ...
    Comment newComment = publyDomainService.addComment(
      input.getStoryId(),
      memberId,
      input.getContent()
    );
  
    return ...;
  }

GraphQL APIs testen

Test

• Zum Testen deiner Anwendung gibt es einen @GraphQLTest.

• Dieser erzeugt u.a. Controller-Klassen und RuntimeWirings (also GraphQL Infrastruktur)

• In diesem Test kann ein GraphQlTester verwendet werden, um GraphQL Queries auszuführen

• Das Ergebnis des Queries kann dann validiert werden

  • Mit JSON-Path ausdrücken kann auf Teile des Ergebnisses zugegriffen werden
  • Die Teile können in unterschiedliche Formate konvertiert werden

• 
  @GraphQlTest
  public class PublyGraphQLControllerTest {
  
    // ausgelassen: Mocks konfigurieren, z.B. für Repositories mit @MockBean
  
    @Autowired
    GraphQlTester graphQlTester;
  
    private final String query = "query { ping }";
  
    @Test
    void pingReturnsPong() {
      // Query ausführen
      GraphQlTester.Response response = graphQlTester.document(query)
        .execute();
  
      // Ergebnis validieren
      response
        .path("ping").entity(String.class).isEqualTo("pong");
  
    }

GraphQlTester

• Der Query kann entweder direkt als String übergeben werden (wie gesehen)

• oder in einer Datei abgelegt werden (xyz.graphql), die im Klassenpfad sein muss

• @Test
  void pingReturnsPong() {
  
    graphQlTester.document("query { ping } "); // ...
  
    graphQlTester.documentName("ping-test-query"); // erwartet ping-test-query.graphql im Klassenpfad
  }
  

Der WebGraphQlTester

• Mit dem WebGraphQlTester können GraphQL Requests über HTTP gemacht werden

• An einen laufenden Server oder in-place

• Dazu kann ein gewohnten @SpringBootTest geschrieben werden

• Die Testklasse muss außerdem mit @AutoConfigureHttpGraphQlTester annotiert werden

• API ansonsten wie GraphQlTester

• @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
  @AutoConfigureHttpGraphQlTester
  public class PublyGraphQLControllerWebTest {
    @Autowired
    private WebGraphQlTester webGraphQlTester;
  
    @Test
    void pingReturnsPong() {
      // Query ausführen
      webGraphQlTester.document("query { ping }")
        .execute()
        .validate(/* ... */);
    }
  }

WebGraphQlTester

• Der injizierte WebGraphQlTester ist fertig konfiguriert

• Kann aber pro Request angepasst werden, z.B. um HTTP Header zu setzen

• dazu muss eine neue Instanz mit mutate erzeugt werden

• graphQlTester
      .mutate() // erzeugt neue Instant, die konfiguriert werden kann
      .header("Authorization", "Bearer user-mock-token")
      .build()
      .document(query) /* konfigurierte Instanz verwenden... */

Übung: Tests

Schreibe einen Test für unsere GraphQL-API

• Verwende den @GraphlTest

  • Der Controller wird dabei erzeugt, aber die Repositories müssen gemockt werden

• Im Workspace findest Du im test-Verzeichnis eine Klasse AbstractPublyGraphQLTest, die Du als Basis verwenden kannst

  • Darin sind schon die Mock-Beans konfiguriert
  • Es gibt Hilfsfunktionen zum Aufsetzen der Mockdaten (given_), die Du je nach Testfall aufrufen kannst
  • Du kannst natürlich auch eigene Mocks für andere Tests schreiben

• Leite deine Testklasse davon ab

  • Du musst deine Testklasse mit @GraphQlTest annotieren

• Bespiele findest Du in steps/50_test

Geschafft! 😊

Vielen Dank für Eure Teilnahme!

Viel Spaß und Erfolg mit GraphQL!

Wenn ihr noch Fragen habt, könnt ihr mich erreichen:

nils@nilshartmann.net

https://nilshartmann.net

LinkedIn

Xing

Mastodon: @nilshartmann@norden.social

Twitter: @nilshartmann