GraphQL Workshop

Nils Hartmann | @nilshartmann

GraphQL APIs

Eine praktische Einführung mit Spring for GraphQL

21. Juni 2022, API Summit, München

Slides (online)

https://graphql.schule/api2022

Workspace Installation

https://graphql.schule/install

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

* Was ist GraphQL?

* Die Abfragesprache
* APIs beschreiben
* GraphQL APIs mit Spring for GraphQL implementieren

---

## Zeitplan

* 13:30 bis 15:00  Teil 1

* 15:00-15:30 Kaffeepause ☕️ 🍰

* 15:30 bis 17:00 Teil 2

---

## Grundsätzliches

* **Jederzeit:** Fragen und Diskussionen!
* Motto: Es gibt keine dummen Fragen!
* Ich zeige viel direkt im Editor, aber ihr könnt die Slides als Referenz benutzen

---

# GraphQL

_"GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data"_ ([https://graphql.org](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](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](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](https://graphql.org))

---

## 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 Beispiel-Anwendung

[http://localhost:3000](http://localhost:3000)

---

## Beispiel: GraphiQL

[http://localhost:8080](http://localhost:8080)

---

## Beispiel: GraphQL Tooling

*  IntelliJ IDEA
  *  graphql-Extension (hello.graphql)
  *  GraphQL.md im publy-Verzeichnis
  *  language=GraphQL in einer leeren Java-Datei

*  TypeScript (optional)
  *  publy-frontend, npm run codegen:watch
  *  StoryPage.query.graphql zeigen und story-Feld entfernen

---

# Die GraphQL Abfrage-Sprache

---

### Sprache, um **Felder** aus einem **Objekt-Graphen** abzufragen

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

---

### Felder können **Argumente** haben

<pre><code class="graphql">
  query {
    story(storyId: 5) {
      id title writtenBy {
        id user { name }
      }
    }
  }
</code></pre>

---

### 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

<pre class="fragment"><code class="graphql">
query NewestStory {
    story {
      id
      title
    }
}
</code></pre>

---

### Fragmente

Mit einem **Fragment** beschreibst Du eine wiederverwendbare Menge von Feldern
<pre><code class="graphql">
fragment BaseMember on Member {
    id joined
    user { is username }
}

query {
    story {
      writtenBy { ...BaseMember }

reactions {
        givenBy { ...BaseMember }
      }
    }
}
</code></pre>

---

### Union-Typen

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

<pre><code class="graphql">
mutation  addComment
    (input: { storyId: "1", content: "..." }) {

...on AddCommentSuccessPayload {
      newComment { id }
    }

...on AddCommentFailurePayload {
      errorMessage
    }
}
</code></pre>

---
### 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

<pre><code class="graphql">
query {
    node(id: "...") {

id
      createdAt

...on Story { title body }
      ...on Comment { content }
    }
}
</code></pre>

---

### 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

<pre class="fragment"><code class="graphql">query ($storyId: ID!) {
    story(id: $storyId) {
      id
      title body
    }
}
</code></pre>

---

## Übung: Einen Query ausführen

_Mach' dich mit der GraphQL-Abfragesprache vertraut_

* Öffne GraphiQL auf meinem Computer (URL gebe ich euch)
* 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 (rechts oben) verwenden, um die API zu untersuchen
* Mögliche Lösung: [https://graphql.schule/queries](https://graphql.schule/queries)

---

### GraphQL Requests

*  HTTP Request an die GraphQL API
  *  request.http im publy-Ordner
  *  Fehler zeigen
---

## GraphQL Requests

* Üblicherweise nur HTTP POST-Request
  * andere HTTP Verben spielen keine Rolle
  * HTTP Status-Code meist 200 OK, auch im Fehlerfall!
  * Großer Unterscheid 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)

---
 
# Das GraphQL Schema

---

### 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)

---

### Beschreibung des Schemas

* Mit der [Schema Definition Language](https://graphql.org/learn/schema/) 
* Per [Java API](https://www.graphql-java.com/documentation/schema) in
  GraphQL-Java 
* In der Regel wird die **SDL** verwendet

---

### Die SDL

*  Demo: Schema-Definition 
  *  ping-Feld mit Message Object
  *  Argument!
  *  Rückgabewert-String
  *  Doku

---

### Die SDL

Beschreibung eines *Objekt Types*

<pre><code class="graphql">
  type Story {
    id: ID!

title: String!
    body: String!
  }
</code></pre>

* 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

<pre class="fragment"><code class="graphql">
  """
  A `Story` is the main object in our service.
  """
  type Story {
    """Identifies this object"""
    id: ID!

# todo: implement new tags-field (PROJ-666)
  }
  
</code></pre>

---

## 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

<pre class="fragment"><code class="graphql">
  type Member {
    id: ID!

username: String!

# no exclamation mark: can be null
    likes: Int

amount: Float!

activeMember: Boolean
}
</code></pre>

* Man kann eigene skalare Typen bauen
---

### Aufzählungstypen (enum)

* Wie in Java

<pre class="fragment"><code class="graphql">
  enum ReactionType {
    like,
    laugh,
    thumbUp
  }
</code></pre>

---

### Referenzen

* Referenzen auf andere Objekt-Typen

<pre class="fragment"><code class="graphql">
  type Member {
    # ...
  }

type Comment {
    # ...
  }

type Story {
    """Reference to the Member that has written this Story"""
    writtenBy: Member!

comments: [Comment!]!

}
</code></pre>

---

### 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!

<pre class="fragment"><code class="graphql">
type Story {

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

}  
</code></pre>

---

### 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

<pre class="fragment"><code class="graphql">
  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!
  }
</code></pre>

---

### 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

<pre class="fragment"><code class="graphql">
  input AddCommentInput {
    storyId: ID!
    memberId: ID!
    content: String!
  }

type Mutation {
    addComment(input: AddCommentInput!): Comment!
  }
</code></pre>

---

### Union Types

* Union Types bilden eine Menge von anderen Typen
* Ein Feld kann ein Typen aus dieser Menge zurückliefern ("A _oder_ B")

<pre class="fragment"><code class="graphql">
  type AddCommentSuccess { newComment: Comment! }
  type AddCommentFailed { errorMessage: String! }

union AddCommentResult = AddCommentSuccess | AddCommentFailed

type Mutation {
    addComment(input: AddCommentInput!): AddCommentResult!
  }

</code></pre>

---

### Interfaces

* Mit einem Interface wird erzwungen, dass Objekte über gleiche Felder verfügen
  * Vergleichbar mit Interfaces in Java

<pre class="fragment"><code class="graphql">
  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 
  }
</code></pre>

---

### 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

<pre class="fragment"><code class="graphql">
  type Query {
    # Ausgangspunkt 
    getStoryById(id: ID!): Story
  }
</code></pre>

<pre class="fragment"><code class="graphql">
  type Query {
    getStoryById(id: ID!): Story

# Neues Feld, beeinträchtigt bestehenden Client nicht
    stories: [Story!]!
  }
</code></pre>

<pre class="fragment"><code class="graphql">
  type Query {
    getStoryById(id: ID!): Story @deprecated("Use story instead")
    story(id: ID!): Story

stories: [Story!]!
  }
</code></pre>

---

### Das Schema in Spring 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

<pre class="fragment"><code class="graphql">
  # story.graphqls
  extend type Query {
    story(id: ID!): Story
  }

# comment.graphqls
  extend type Query {
    comment(id: ID): Comment
  }
</code></pre>

---

### Übung: Schema beschreiben

---

### Vorbereitung: Das Repository

* Workspace klonen und Anwendungen starten: [https://graphql.schule/install](https://github.com/nilshartmann/spring-graphql-training/blob/main/INSTALL.md)

### Übung: Schema beschreiben

*  
* Vervollständige die Datei `resources/graphql/publy.graphqls` und beschreibe darin eine API, die folgende Objekt-Typen enthält:
  * **Member** mit `id` und `profileImage`
  * **Story** mit `id`, `title` und `body` 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
* Füge für ein oder zwei Felder Dokumentation hinzu
* Die Implementierung für die API machen wir später! Du musst also nichts programmieren.
* Sieh dir das API-Schema in GraphiQL an (http://localhost:8090).
  * Prüfe, ob Code Completion funktioniert und ob die Dokumentation im "Docs"-Tab findest
  * Wenn Du Änderungen an der `graphqls`-Datei gemacht hast, musst Du die Anwendung neu bauen, und in GraphiQL
    die Seite im Browser neu laden.
  * Du kannst mal probieren, was passiert, wenn Du einen `stories` bzw `story`-Query ausführst.    
    * Eine gültige ID für eine Story ist z.B. `1`
* Eine mögliche Lösung findest Du in `steps/01-schema`

---

# Implementieren der GraphQL API

---

### Die Beispiel-Anwendung

---

### graphql-java (und andere GraphQL Frameworks für Java)

* graphql-java ist die Grundlage aller(?) Java-Frameworks für GraphQL
  * Parsen und Validieren der Queries
  * Optimierte Ausführung der `DataFetcher` zum Ermitteln der Daten (später mehr)
  * Kein Abhängigkeit zu anderen Bibliotheken, auch kein HTTP Endpunkt
  * Alle anderen Frameworks abstrahieren davon und bieten "High-Level" API

---

### Verarbeitung eines GraphQL Queries (allgemein)

1. Query kommt an (HTTP Endpunkt)
2. Query wird geparst und validiert 
3. Ungültige Queries werden abgewiesen (`errors`-Feld in der Antwort) 
4. Für jedes Feld wird eine *Resolver-Funktion* (auch DataFetcher genannt) aufgerufen, die verantwortlich dafür ist, die Daten für das jeweilige Feld zu liefern
5. Die Ergebnisse der Resolver werden validiert (insb. hinsichtlich der Typen)
6. Das Ergebnis wird als `data`-Feld bereitsgestellt
7. Das Ergebnis wird an den Client zurückgeschickt

*  Unsere Aufgabe ist es, die Resolver zu implementieren

---

### 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`
  * Hier nur zur Kenntnis, in Spring GraphQL abstrahiert
  * In anderen GraphQL Frameworks auch `Resolver` genannt

* ```java  
  interface DataFetcher<T> {
    T get(DataFetchingEnvironment environment); 
  }  
  ```

* Beispiel:
* ```java  
  public class PublyDataFetchers {

public DataFetcher<String> pingFetcher = new DataFetcher() {

@Override
      public String get(DataFetchingEnvironment env)  {

String msg = env.getArgumentOrDefault("msg", "Pong!");
        return msg;

}
    };
  }
  ```

* Jeder DataFetcher wird im **RuntimeWiring** einem Feld der API zugewiesen

---

## GraphQL Java Architektur

<img src="images/graphql-java-architektur.png" />
---

## Spring for GraphQL

* [Spring for GraphQL](https://spring.io/projects/spring-graphql) bietet eine Abstraktion von GraphQL-Java an
* Erstes Release von Spring GraphQL enthalten in Spring Boot 2.7 (Mai 2022)
  * Projekte können mit dem [Spring initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.7.0-M3&packaging=jar&jvmVersion=11&groupId=com.example&artifactId=demo&name=demo&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.demo&dependencies=graphql) 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`](https://docs.spring.io/spring-boot/docs/2.7.0-SNAPSHOT/reference/htmlsingle/#web.graphql) für Spring Boot
  * Actuator-Endpunkte für Spring Boot

---

## Spring GraphQL

*  Demo: Handler-Funktionen mit `ping`-Feld
*  Query-Mapping!
*  Argumente!

---

## Handler-Funktionen

* Anstatt `DataFetcher` werden *Handler-Funktionen* an `Controller`-Klassen implementiert
  * Vorsichtig vergleichbar mit `@RequestMapping`

```java fragment  
    @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
* ```graphql
  type Query {
    ping(msg: String): String!
  }
  ```
* ```java
  @QueryMapping
  public String ping(@Argument String msg) { 
    return "Hello " + msg; 
  }
  ```  
* `@Arguments`, um Parameter in einer Java-Klasse zusammenzufassen
* ```graphql
  type Query {
    greet(name: String, msg: String): String!
  }
  ```

* ```java
    class GreetingParams { private String name; private String msg; /* getter+setter... */ }

@QueryMapping
    public String greet(@Arguments GreetingParams params) { 
      return "Hello " + params.getName(); 
    }
  ```
* `@ProjectedPayload` um einzelne Parameter in einem Interface zusammenzufassen
* ```graphql
    type Query {
      greet(name: String, msg: String): String!
    }
  ```

* ```java
    @ProjectedPayload
    interface GreetingParams { String getName(); String getMsg(); }

@QueryMapping
    public String greet(@Argument GreetingParams params) { 
      return "Hello " + params.getName(); 
    }
  ```

---
### Parameter von Handler-Funktionen  
  
* Für Input-Typen kann ein Pojo angegeben werden:
* ```graphql
  input GreetingInput { name: String, msg: String }

type Query {
    greet(input: GreetingInput!): String!
  }
  ```
* ```java
  class GreetingInput { private String name; private String msg; /* getter+setter... */ }

// oder JDK 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
* ```java
  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: Handler-Funktionen

_Implementiere zwei Handler-Funktionen_

* Eine Handler-Funktion `Query.stories` und für `Query.story(id: ID!)`
* Die Handler-Funktionen kannst Du in der Klasse `nh.publy.backend.graphql.PublyGraphQLController` implementieren.
* 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:

<pre class="fragment"><code class="graphql">
  query {
    stories {
      id title body
     
      writtenBy {
        id profileImage
      }
    }
  }
</code></pre>

<pre class="fragment"><code class="graphql">
  query {
    story(storyId: 1) {
      id title body
     
      writtenBy {
        id profileImage
      }
    }
  }
</code></pre>

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

---

## Handler-Funktionen an Objekt-Typen

*  Demo: Excerpt-Feld hinzufügen
  *  `SchemaMapping` Implementieren !

---

### 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

* ```java
  @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 Typ explizit gesetzt werden

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

* `@QueryMapping` und `@MutationMapping` sind nur Aliase für 
  * `@SchemaMapping(typeName="Query")` bzw.
  * `@SchemaMapping(typeName="Mutation")`

---

## Asynchrone Handler-Funktionen

*  Instrumentation hinzufügen
  *  excerpt-Feld slowdown aktivieren
  *  stories abfragen und Report auswerten
  *  CompletableFuture

---

### 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

```java fragment  
  @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: Zugriff auf externen Service

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

* ```graphql
  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)
* ```java
  @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

* Ergänze das Schema
  * Neuer Type `User`, Felder: `id` (ID), `name` (String) und `email` (String). Alle non-nullable. 
  * Erweiter den `Member`-Typen um das Feld `user` (Type: `User`, nullable).
* Führe den untenstehenden Query aus. Was kommt für `user` zurück und warum?  
* Implementiere die Schema-Mapping-Funktion für das Feld
  * Die Schema-Mapping-Funktion soll asynchron funktionieren
  * Der `UserService` ist bereits implementiert
* Der folgende Query sollte dann einen User zurückliefern:

<pre class="fragment"><code class="graphql">
  query {
    story(storyId: 1) {
      id 
      writtenBy {
        id

# Hier sollten nun Daten kommen:
        user {
          id name email
        }

}
    }
  }
</code></pre>

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

---

## Optimierungen

---

### DataLoader

* Was passiert, wenn wir folgenden Query ausführen:

<pre class="fragment"><code class="graphql">
  query {
    stories {
      writtenBy { user { id email } }
    }
  }
</code></pre>

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

---

### Problem

---

### DataLoder

* Ein `DataLoader` "verzögert" das Laden von Daten

* <img src="images/dataloader-02.png" />

---

### 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 ...`)
  * Du bekommmst jede ID auch nur einmal übergeben

---

### Verwenden vom DataLoader

* Den DataLoader kannst Du dir in deine Handler-Funktionen übergebenlassen
* 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

```java fragment
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
* ```java
  public PublyGraphQLController(/* ... */, BatchLoaderRegistry registry) {

registry.forTypePair(String.class, User.class).registerBatchLoader(

(List<String> keys, BatchLoaderEnvironment env) -> {
        // 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 werden auch nicht in die Map aufgenommen.

```java fragment  
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!

```java fragment  
@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
}
```

---

### DataFetchingFieldSelectionSet

* Das `DataFetchingFieldSelectionSet` enthält eine Liste aller Felder, die im aktuellen Query abgefragt sind
* Hiermit kannst Du weitere Optimierungen der Query-Verarbeitung vornehmen, zum Beispiel optimale
  SQL-Queries generieren
* Das `DataFetchingFieldSelectionSet` kannst Du an deine Handler-Funktionen übergeben lassen.

```java fragment  
@QueryMapping List<Story> stories(DataFetchingFieldSelectionSet selectionSet) {

if (s.contains("comments") ) {
    // SQL Statement mit JOIN auf Comment-Tabelle
    return ...;
  }

// SQL Statement nur mit Stories
  return ...;
  
}  
```

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

Xing

Twitter: @nilshartmann