GraphQL Server
Diese Seite beschäftigt sich hauptsächlich mit GraphQL auf Server-Ebene. Für Client-GraphQL werden Grundlagen auf folgender Seite erklärt: Frontend FrEDA ReactJS-Basics-Basics
GraphQL ganz einfach erklärt kann man sich wie ein single REST-Endpoint vorstellen. Per HTTP-Post-Request an einen GraphQL-Endpunkt wird über den Body des POST-Requests dem Server mitgeteilt was denn der Client für Daten abfragen (Query) oder ändern (Mutation) möchte. Außerdem erlauben GraphQL-Schnittstellen Echtzeitkommunikation über einen Websocket aufzubauen (subscription). GraphQL ist Programmiersprachenunabhängig.
Eine Liste an Tools und Implementierungen findet man hier: https://graphql.org/code/
Für eine detaillierte Dokumentation gehe bitte auf die offiziellen Docs: https://graphql.org/learn/
Guter Start um GraphQL zu lernen: https://www.howtographql.com/
Basics
Root-Types
Ein GraphQL-Server besteht aus den Root-Typen:
- Query (Query wird zum Abfragen von Daten genutzt)
- Mutation (Mutation wird zum Schreiben oder anstoßen von Logiken genutzt)
- Subscription (Wird für Echtzeitkommunikation genutzt und verbindet sich mit einem Websocket)
Root-Fields
Root-Fields sind die ersten Felder nach dem eine Query fragt. Sie stehen also zu Beginn jeder Abfrage untereinander
. Hier eine Beispiel Query in welchem fredaPublic ein Root-Field ist, welches ein Object vom Typ FredaPublicQuery
zurückliefert, welcher wiederum ein Feld Namens me hat, welches ein Object von Typ User zurückgibt:
query myExampleQueryName {
fredaPublic {
me {
id
name
lastName
firstName
email
}
}
}
Das Beispiel fragt den aktuell angemeldeten Nutzer ab.
Hier eine Beispiel Mutation:
mutation myExampleMutationName {
fredaPublic {
signIn(email: "info@devtim.de", password: "123456") {
id
name
lastName
firstName
email
}
}
}
Dieses Beispiel loggt den Nutzer ein.
Fragments
In den oberen Abfrage-Beispielen fragen wir die Felder eines User-Types ab. Damit wir nicht immer wieder die Feldbezeichnungen der gewünschten abgefragten Felder auflisten müssen, können wir diese einmalig als Fragment definieren, welches wir dann in den Queries, Mutations oder Subscription wiederverwenden können. Vollständiges Beispiel:
query myExampleQueryNameWithFragment {
fredaPublic {
me {
... myCustomFieldsFragment
}
}
}
mutation myExampleMutationNameWithFragment {
fredaPublic {
signIn(email: "info@devtim.de", password: "123456") {
... myCustomFieldsFragment
}
}
}
fragment myCustomFieldsFragment on User {
id
name
lastName
firstName
email
}
Scalars
Scalars sind Standard-Datentypen wie INT, STRING, FLOAT, BOOLEAN. Es gibt die Möglichkeit den GraphQL-Server mit eigenen Scalars zu erweitern, wie DATE oder DATETIME o.ä. Es gibt auch ein Node-Submodule welches die Standard-Scalars von GraphQL-Server erweitert: https://github.com/Urigo/graphql-scalars
(Custom) GraphQL-Types
Jedes Abfragefeld kann entweder ein Scalar-Typ oder ein GraphQL-Typ zurückgeben. Scalar-Types sind die Felder, welche tatsächliche Daten zurückliefern, während GraphQL-Types neue Objekte zurückliefern, welche Strukturen/Schemas beschreiben.
Resolvers
Resolver sind die Serverseitigen Funktionen, welche die Feldabfragen der Query auflösen und in Logik umwandeln. In MVC wären das die Controller. Diese Funktionen können standardmäßig auf folgende Parameter zugreifen:
Root
Über dieses Objekt lässt sich auf das darüberliegende Objekt der Abfrage zugreifen. Bei Abfrage von Root-Fields macht das wenig Sinn.
Args
Dieses Objekt enthält alle Argumente der Query/Mutation/Subscription, insofern das Feld Argumente unterstützt. In den
oberen Beispielen kann das Feld signIn Argumente beinhalten (E-Mail und Passwort). Diese Felder lassen sich im
Resolver über den zweiten Objekt-Paramter 'Args' auslesen.
Context
Der Dritte Prameter einer Resolver-Funktion beinhaltet ein Objekt, welches den Context der Abfrage enthält. Dieser wird oft für Session-Variablen, Zugang zu Datenbank oder Dependency-Injection genutzt.
Info
Das info-Object, der vierte Parameter des Resoverls, enhält Informationen über die aktuelle Abfrage und das allgemeine Schema des GraphQL-Servers.
SDL (Schema Definition Language)
Die SDL dient dazu die custom GraphQl-Types und deren Relation + Rückgabetypen zu definieren. Es ist eine Art Interface-Definition, in eigener Sprache.
Hier findet man ein komplettes Sheet Cheat dazu:
erster simpler Beispiel GraphQL-Server
Für ein simples GraphQL-Beispiel bitte folgende Anleitung nutzen. Das Beispiel verwendet Apollo-Server, ein Framework zum leichten erstellen von GraphQL-Server in NodeJS:
https://www.apollographql.com/docs/apollo-server/getting-started/