GraphQL Workshop

Nils Hartmann | @nilshartmann

GraphQL

Dein Praxis-Einstieg

BaselOne, 18. Oktober 2023

Slides (online)

https://graphql.schule/baselone23

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

* Teil 1: GraphQL
  * Was ist GraphQL?
  * [Die Abfragesprache](#/graphql-sprache)

* Teil 2: [GraphQL Anwendungen bauen](#/graphql-apis-bereitstellen)
    * [Das Schema definieren](#/schema)
    * [GraphQL APIs mit Spring for GraphQL](#/spring-for-graphql)
    * Optimierungen: [DataLoader](#/dataloader)
* Jeder Zeit: Eure Fragen!

---

## Zeitplan

* 13:30-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](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))

---
## Die Beispiel-Anwendung "Publy"

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

---
### Eine API für Publy

* Ansatz 1: Backend bestimmt Aussehen der Endpunkte / Daten
  * REST
* <img src="images/arten-von-apis_rest.png" width="2400px" style="margin-top:120px"/>
---
### Eine API für Publy

* Ansatz 2: Client diktiert die API nach seinen Anforderungen
  * "Backend for Frontend"          
* <img src="images/arten-von-apis_02_bff.png" width="2400px" style="margin-top:120px"/>

---
### Eine API für Publy

* Ansatz 3: GraphQL
  * Aus Ansatz 1: Server bestimmt, wie Datenmodell aussieht
* <img src="images/arten-von-apis_03_graphql_01.png" width="2400px" style="margin-top:120px"/>  
  
---
### Eine API für Publy

* Ansatz 3: GraphQL
  * Aus Ansatz 1: Server bestimmt, wie Datenmodell aussieht
  * ...aber Client kann pro Ansicht wählen, welche Daten er daraus benötigt
* <img src="images/arten-von-apis_03_graphql_02.png" width="2400px" style="margin-top:120px"/>

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

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

```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
* ```graphql
  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:

```graphql
  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

* ```graphql
  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

* ```graphql
  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?
* Bau eine Fragment (`Author`), das aus dem `Member` dessen Id, sowie `name` und `id` des Users enthält
  * Verwende das Fragment, um in den Stories und den Kommentaren jeweils die Member-Informationen abzufragen
  * In den Stories zusätzlich noch `skills` des Members abfragen
* 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](https://graphql.schule/queries)

---

### GraphQL Requests

*  HTTP Request an die GraphQL API
  *  `app/demo/request.http` im publy-Ordner
  *  Fehler (falsches Feld) 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)
* Eine Spezifikation dafür ist [in Arbeit](https://github.com/graphql/graphql-over-http/blob/main/spec/GraphQLOverHTTP.md)

---

### 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, z.B. mit Annotations
  * **Spring for GraphQL** verwendet Schema-first
  * **MicroProfile GraphQL** (z.B. Quarkus) verwendet Code-first

---

### Beschreibung des Schemas

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

---

### Die SDL

*  Demo: Schema-Definition 
  *  Im workspace-Ordner
  *  Story und Member
  *  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

* ```graphql
  """
  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

* ```graphql
  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

* 
  ```graphql
  enum ReactionType {
    like,
    laugh,
    thumbUp
  }
  ```

---

### Referenzen

* Referenzen auf andere Objekt-Typen

* 
  ```graphql
  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!

* ```graphql
  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

* ```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!
  }
  ```
---

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

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

* ```graphql
  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

* ```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 
  }
  ```

---

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

* ```graphql
  type Query {
    # Ausgangspunkt 
    getStoryById(id: ID!): Story
  }
  ```

* ```graphql
  type Query {
    getStoryById(id: ID!): Story

# Neues Feld, beeinträchtigt bestehenden Client nicht
    stories: [Story!]!
  }
  ```

* ```graphql
  type Query {
    getStoryById(id: ID!): Story @deprecated("Use story instead")
    story(id: ID!): Story

stories: [Story!]!
  }
  ```
---

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

* <img style="height:350px" src="images/java-graphql-frameworks.png" />
* [graphql-java](https://www.graphql-java.com/) 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

---

### 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* oder *Mapping-Funktion* 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

---

## Spring for GraphQL

* [Spring for GraphQL](https://spring.io/projects/spring-graphql) bietet eine Abstraktion von GraphQL-Java an
* Erstes Release von Spring for GraphQL enthalten in Spring Boot 2.7 (Mai 2022)

* Features:
  * HTTP-Endpunkt für Requests und Subscriptions automatisch
  * GraphiQL Integration per Property
  * Gewohntes Spring-Programmiermodell mit Annotationen etc.
  * [`spring-boot-starter-graphql`](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#web.graphql) für Spring Boot

---

### Das Schema in Spring for GraphQL

* Das Schema wird in Dateien mit der Endung `.graphqls` abgelegt
  * Verzeichnis: `src/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>
---

## Spring for GraphQL

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

---

## Handler-Funktionen

* *Handler-Funktionen* werden an `Controller`-Klassen implementiert

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

---
### 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 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
* ```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(); 
  }
  ```  
---

## 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 GraphQL-Typ explizit gesetzt werden

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

---

### Ü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!):
  * ```graphql
      query {
        stories {
          id title body

writtenBy { id profileImage }
        }
      }
      ```
  * ```graphql
      query {
        story(storyId: 1) {
          id title body

writtenBy { id profileImage }
        }
      }
      ```
* Eine mögliche Lösung findest Du in `steps/10_handler_function`

---

### 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:
* ```graphql
  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
* ```graphql
  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

---

### Eine Mutation, um Kommentare hinzuzufügen

* Fertige Mutation
* ```graphql
  input AddCommentInput {
      storyId: ID!
      memberId: ID!
      content: String!
  }

type AddCommentPayload {
    newComment: Comment!
  }

type Mutation {
    addComment(input: AddCommentInput!): AddCommentPayload!
  }
  ```
---
# Optimierungen

--- 
### Neues Feature: User kommen aus einem Microservice

*  Schema aus `steps/15_schema_mapping` kopieren
*  SchemaMapping-Funktion für `Member.user` mit `userService.findUserWithId` implementieren
*  SlowDown im UserService einstellen

### Ein einfacher Query...

* 🤔 Was passiert, wenn wir folgenden Query ausführen:
* ```graphql
  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

* <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 ...`)
* DataLoader sind ein allgemeines GraphQL-Konzept
  * Nicht in der Spec, aber de-facto Standard
* Java-Implementierung kommt aus dem [java-dataloader](https://github.com/graphql-java/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
* ```java
  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](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html)
* ```java
  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](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html)-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.
* ```java
  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
  @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
  }
  ```

---
## 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](https://relay.dev/graphql/connections.htm)
* 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](https://docs.spring.io/spring-graphql/reference/request-execution.html#execution.pagination.types)
* Wenn ihr in Eurem Schema ein Query-Feld mit dieser Signatur habt:
* ```graphql
  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](https://docs.spring.io/spring-data/rest/reference/data-commons/repositories/scrolling.html) 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
  *  stories(first:Int, after:String, last:Int, before:String): StoryConnection
  *  Story: createdAt String!
*  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
  *  Wie sieht das Ergebnis aus?
  *  Union-Type als Ergebnis

---

### Fehlerbehandlung

* Fehler, die nicht in einer Handler-Funktion verarbeitet werden, werden im `errors`-Feld zurückgeliefert:
* ```json
  {
    "errors": [
      {
        "message": "addComment.input.content: Größe muss zwischen 5 und 2147483647 sein",
        "locations": [
          {
            "line": 2,
            "column": 3
          }
        ],
        "path": [
          "addComment"
        ],
        "extensions": {
          "classification": "INTERNAL_ERROR"
        }
      }
    ]
  }
  ```
* ```json
  {
    "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**
* ```graphql
  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! 😢
* ```graphql
  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:
  * ```graphql
    type Mutation {
      addComment: [Comment!]!
    }
    ```
* Mit einem eigenen Rückgabe-Objekt können wir weitere Informationen hinzufügen:
  * ```graphql
    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:
  * ```graphql
    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.
  * ```graphql
    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`

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

Mastodon: @nilshartmann@norden.social

Twitter: @nilshartmann