Einstieg
Grundlegende Query
GraphQL lässt Clients exakt festlegen, welche Daten sie brauchen. Eine Query holt Daten, und die Antwort spiegelt die Query-Form wider. Das vermeidet das verbreitete Over- und Under-Fetching von REST-APIs.
# Query - read data
query {
user(id: 1) {
id
name
email
posts {
title
content
}
}
}
# Response
{
"data": {
"user": {
"id": 1,
"name": "Alice",
"email": "[email protected]",
"posts": [
{ "title": "Hello", "content": "World" }
]
}
}
}Query mit Variablen
Variablen parametrisieren Queries, sodass dieselbe Operation mit verschiedenen Inputs wiederverwendbar ist. Sie werden im Operations-Header mit $name: Type deklariert. Der Query-String bleibt statisch, nur das Variablen-JSON ändert sich pro Aufruf.
# Declare variables with operation name
query GetUser($id: ID!, $withPosts: Boolean!) {
user(id: $id) {
name
posts @include(if: $withPosts) {
title
}
}
}
# Variables sent alongside the query
{
"id": "1",
"withPosts": true
}Mutation-Grundlagen
Mutationen verändern Daten und geben eine Selection-Set zurück wie Queries. Konventionell sollte ihnen ein Auslesen der geänderten Daten folgen. GraphQL führt Mutationen seriell (eins nach dem anderen) aus, während Query-Felder parallel laufen.
# Mutation - write data, then return the result
mutation {
createUser(input: { name: "Bob", email: "[email protected]" }) {
id
name
}
}
# Response
{
"data": {
"createUser": {
"id": "42",
"name": "Bob"
}
}
}Felder und Selection-Sets
Ein selection set ist die Liste der Felder in geschweiften Klammern. Skalare und Enums geben Blattwerte zurück; Objekttypen verlangen ein verschachteltes Selection-Set. Ein vergessenes Sub-Selection auf einem Objekttyp ist ein häufiger Validierungsfehler.
# You must select fields - GraphQL never returns whole objects
query {
user(id: 1) {
# this block is a "selection set"
name
email
}
}
# Selecting a scalar returns its value directly
# Selecting an object REQUIRES a sub-selection set
query {
user(id: 1) {
name # scalar - OK
posts { # object - needs { ... }
title
}
}
}GraphQL vs. REST
REST exponiert viele Endpunkte mit fester Form; GraphQL exponiert einen Endpunkt, auf dem der Client die Form definiert. Das reduziert Round-Trips und verhindert Over-/Under-Fetching. Der Preis: ein komplexerer Server und Caching via POST.
# REST: multiple round trips, fixed shapes
GET /users/1 -> { id, name, email, address, ... }
GET /users/1/posts -> [ { id, title, body, author, ... } ]
# GraphQL: one request, client-defined shape
query {
user(id: 1) {
name
posts { title }
}
}
# One endpoint, one POST request
POST /graphql
{ "query": "...", "variables": { ... } }Introspection
Introspection lässt Clients das Schema zur Laufzeit entdecken. Tools wie GraphiQL, Apollo Studio und Code-Generatoren bauen darauf. Die Root-Felder __schema und __type sind die Einstiegspunkte. Produktionsserver können Introspection abschalten, um Interna zu verbergen.
# Ask the schema what types and fields it has
{
__schema {
types {
name
kind
}
}
}
# Inspect a specific type's fields
{
__type(name: "User") {
name
fields {
name
type { name kind ofType { name kind } }
}
}
}Schema & Typsystem
Schema-Deklaration
Der schema-Block verdrahtet die Root-Operation-Typen. Wenn deine Root-Typen Query, Mutation und Subscription heißen, leitet Apollo/GraphQL.js das Schema automatisch ab und du kannst die Deklaration ganz weglassen.
# SDL - Schema Definition Language
schema {
query: Query
mutation: Mutation
subscription: Subscription
}
# In most servers the schema is inferred from the
# Query/Mutation/Subscription types, so this block is optional.Root-Typen
Query, Mutation und Subscription sind die Einstiegspunkte eines Schemas. Query ist der einzige Pflicht-Root-Typ. Jedes Root-Feld wird zu einer Operation, die Clients ausführen können. Konvention: Verben für Mutationen (createUser), Nomen für Queries.
type Query {
user(id: ID!): User
users(limit: Int = 10): [User!]!
}
type Mutation {
createUser(input: CreateUserInput!): User!
}
type Subscription {
postAdded: Post!
}Typ-Definitionen
Typen werden mit dem type-Schlüsselwort gefolgt von Feldern definiert. Jedes Feld hat einen Namen und einen Rückgabetyp. Das !-Suffix bedeutet non-null; [Type!] eine Liste non-null Elemente; [Type!]! eine non-null Liste von non-null Elementen.
# Object type - the most common building block
type User {
id: ID!
name: String!
age: Int
email: String
posts: [Post!]!
}
type Post {
id: ID!
title: String!
author: User!
}Beschreibungen ergänzen
Dreifach-quoted Strings (oder einzeilige Strings vor einer Definition) werden Teil des Schemas als Beschreibungen. Sie erscheinen in GraphiQL-Docs und Introspection. Plain #-Kommentare sind nur für Devs und werden entfernt — für nutzergerichtete Docs dreifach-quoted Strings verwenden.
"""A registered user of the platform."""
type User {
"""The unique, immutable identifier."""
id: ID!
"Display name shown publicly."
name: String!
# plain # comments are NOT exposed to clients
email: String
}Schema mit Extensions
extend type ergänzt Felder zu einem anderswo deklarierten Typ. So lässt sich ein großes Schema über Dateien verteilen oder modulspezifische Felder ergänzen. Ein Typ darf einmal deklariert und oft extendiert werden, aber jedes Feld nur einmal definiert.
# Extend an existing type without redefining it
type User {
id: ID!
name: String!
}
extend type User {
age: Int
posts: [Post!]!
}
# Useful for splitting a schema across files,
# or for adding fields only in certain modules.Schema-first vs. Code-first
Schema-first schreibt SDL von Hand und hängt Resolver an (Apollos klassischer Ansatz). Code-first baut das Schema programmatisch mit TypeScript-Decoratoren/Buildern (Nexus, TypeGraphQL, Pothos) und gewinnt Typsicherheit zwischen Schema und Resolvern. Beide erzeugen dasselbe Runtime-Schema.
# 1) Schema-first: write SDL, bind resolvers
const typeDefs = `
type Query { hello: String }
`;
const resolvers = { Query: { hello: () => "world" } };
const server = new ApolloServer({ typeDefs, resolvers });
# 2) Code-first: build with builders (Nexus, TypeGraphQL)
export const Query = queryType({
definition(t) {
t.string("hello", { resolve: () => "world" });
},
});Skalar-Typen
Eingebaute Skalare
GraphQL bringt fünf eingebaute Skalare mit: Int, Float, String, Boolean und ID. ID wird als String serialisiert, meint semantisch aber einen Identifier — Clients sollten ihn als opak behandeln. Es gibt kein eingebautes Date oder DateTime; die definiert man selbst.
type Example {
id: ID! # unique identifier, serialized as string
name: String! # UTF-8 text
age: Int # 32-bit integer
score: Float # double-precision float
active: Boolean! # true / false
}Eigene Skalare
Eigene Skalare repräsentieren Domänen-Primitiva. Nach der Deklaration muss ein Resolver bereitgestellt werden, der serialisiert (nach JSON), parst (aus Variablen) und optional Literale parst (aus Inline-AST). Sonst wird der Wert unverändert durchgereicht.
# Declare a custom scalar in SDL
scalar DateTime
scalar URL
scalar JSON
type Event {
id: ID!
at: DateTime!
link: URL
metadata: JSON
}Skalar-Resolver
Ein Skalar-Resolver hat drei optionale Methoden. serialize wandelt einen internen Wert in die JSON-Ausgabe. parseValue wandelt einen Variablen-Input in die interne Form. parseLiteral wandelt ein Inline-Literal im Query-AST in die interne Form. Alle drei für einen vollständig typisierten Skalar definieren.
const resolvers = {
DateTime: {
// value -> JSON sent to client
serialize: (value: Date) => value.toISOString(),
// variable value -> internal value
parseValue: (value: string) => new Date(value),
// inline AST literal -> internal value
parseLiteral: (ast) => {
if (ast.kind === "StringValue") {
return new Date(ast.value);
}
return null;
},
},
};Date/DateTime-Skalar
Das graphql-scalars-Paket liefert erprobte Skalare: DateTime, Date, Time, EmailAddress, URL, UUID, BigInt, JSON und mehr. Dem Eigenbau vorziehen, besonders beim ISO-8601-Datumsparsen, wo Randfälle wimmeln.
# Use graphql-scalars for well-tested common types
import { DateTimeResolver } from "graphql-scalars";
const resolvers = {
DateTime: DateTimeResolver,
Date: DateResolver,
Time: TimeResolver,
};
# In SDL
scalar DateTime
type Query {
now: DateTime!
}JSON-Skalar
JSON-Skalare lassen beliebige Daten durch — nützlich für dynamische Konfiguration oder Metadaten. Der Preis: Typsicherheit und Feld-Ebene-Validierung gehen verloren, und Clients können keine Sub-Felder wählen. Sparsam einsetzen — ein typisiertes Objekt ist fast immer besser.
scalar JSON
type Query {
# accept arbitrary JSON as input or output
config: JSON
setConfig(value: JSON): JSON
}
# The simplest pass-through resolver
const resolvers = {
JSON: {
serialize: (v) => v,
parseValue: (v) => v,
parseLiteral: (ast) => parseJsonLiteral(ast),
},
};Objekttypen
Objekttypen definieren
Ein Objekttyp ist eine Sammlung benannter Felder mit Rückgabetypen. Objekttypen bilden den Graphen — sie referenzieren sich gegenseitig und bauen Beziehungen (User hat Posts, Post hat Author). Objekttypen sind Ausgabetypen; für Inputs Input-Typen verwenden.
type User {
id: ID!
name: String!
email: String
createdAt: String!
}
type Post {
id: ID!
title: String!
body: String!
published: Boolean!
}Felder und Feldtypen
Jedes Feld deklariert einen Rückgabetyp. Nullable ist der Standard; ! macht non-null. Listen umwickeln mit []. Die Position des ! zählt: [String] kann null sein und nulls enthalten; [String!] kann null sein, Elemente nicht; [String!]! kann weder null sein noch nulls enthalten.
type Product {
id: ID! # non-null ID
name: String! # non-null string
price: Float! # non-null float
discount: Float # nullable float
tags: [String!]! # non-null list of non-null strings
reviews: [Review] # nullable list of nullable reviews
}Non-Null und Listen
Die !-Platzierung steuert Nullability auf jeder Ebene. Non-null ist mächtig, aber riskant: gibt ein Resolver auf einem non-null Feld null zurück, bubbelt der Fehler hoch und nullt auch das Eltern-Feld. Nullable als Default, non-null nur, wo ein Wert wirklich garantiert ist.
type Example {
a: [String] # may be null; items may be null
b: [String!] # may be null; items NOT null
c: [String]! # NOT null; items may be null
d: [String!]! # NOT null; items NOT null
name: String # may be null
name2: String! # NOT null - errors if null returned
}Verschachtelte Objekte
Objekttypen referenzieren sich gegenseitig und formen den Graphen, der Queries ermöglicht, die Beziehungen durchqueren (user -> posts -> author -> profile). Zirkuläre Referenzen zwischen Typen sind erlaubt und üblich. Der Graph macht GraphQL zu einem Graphen, nicht zu einem Baum von Endpunkten.
type User {
id: ID!
name: String!
profile: Profile!
posts: [Post!]!
}
type Profile {
bio: String
avatar: String
}
type Post {
id: ID!
title: String!
author: User! # back-reference creates the graph
}Feld-Argumente an Objekten
Jedes Feld — nicht nur Root-Felder — kann Argumente nehmen. So exponiert ein einziger Typ gefilterte/paginierte Sichten verwandter Daten (z. B. user.posts(limit: 10)). Argumente mit Default-Werten sind in Queries optional.
type User {
id: ID!
name: String!
# an object field can take arguments
posts(limit: Int = 5, after: ID): [Post!]!
role(type: RoleType!): Role
}
type Query {
user(id: ID!): User
}Queries
Query-Typ
Der Query-Typ ist der Einstiegspunkt aller Leseoperationen. Jedes Feld hier ist eine Top-Level-Operation, die Clients anfordern können. Auf Leseoperationen konzentrieren; Schreiboperationen in die Mutation. Felder als Nomen benennen (users, user, search) ist Konvention.
type Query {
me: User!
user(id: ID!): User
users(limit: Int = 20, offset: Int = 0): [User!]!
search(term: String!): [SearchResult!]!
}
# Clients run these as operations:
# query { me { name } }
# query { user(id: "1") { name } }Mehrere Felder
Eine Query kann mehrere Root-Felder in einer Anfrage wählen. GraphQL führt sie parallel aus (außer bei Mutationen). Das batcht verwandte Fetches in einen einzigen Round-Trip — ein zentraler Effizienzgewinn gegenüber REST.
# Several fields in one request - executed in parallel
query {
me { name email }
user(id: "1") { name }
users(limit: 3) { id name }
}
# Response contains all three under "data"
{
"data": {
"me": { "name": "Alice", "email": "[email protected]" },
"user": { "name": "Bob" },
"users": [ { "id": "1", "name": "Bob" }, ... ]
}
}Aliases
Aliases benennen Felder in der Antwort um. Sie sind Pflicht, wenn dasselbe Feld mit verschiedenen Argumenten gewählt wird — JSON-Objekt-Keys müssen eindeutig sein. Aliases sind auch praktisch für kürzere oder aussagekräftigere Antwort-Keys.
# Same field twice with different args needs aliases
query {
alice: user(id: "1") { name }
bob: user(id: "2") { name }
}
# Response keys match the aliases
{
"data": {
"alice": { "name": "Alice" },
"bob": { "name": "Bob" }
}
}Verschachtelte Queries
Beziehungen zu durchqueren ist GraphQLs Superkraft. Der Client geht den Graphen in einer einzigen Query (user -> posts -> comments -> author). Der Server löst jedes Feld über seinen Resolver auf; tiefe Verschachtelung ist okay, aber auf dem Backend auf N+1-Queries achten.
query {
user(id: "1") {
name
posts { # traverse relationship
title
comments { # and another level
author {
name
}
}
}
}
}Query mit Argumenten
Argumente können Inline-Literale oder Variablen sein. Inline-Literale sind okay für statische Werte; Variablen immer dann, wenn ein Wert aus Nutzer-Input stammt oder pro Aufruf wechselt. Variablen halten die Query cachefähig und vermeiden String-Verkettung.
# Schema
type Query {
user(id: ID!, includeEmail: Boolean = false): User
}
# Inline arguments
query {
user(id: "1", includeEmail: true) {
name
email
}
}
# Prefer variables for dynamic values
query($uid: ID!, $withEmail: Boolean!) {
user(id: $uid, includeEmail: $withEmail) {
name
email
}
}Operations-Name
Operationen zu benennen (query GetUserProfile) ist optional, aber dringend empfohlen. Benannte Operationen sind leichter zu debuggen, erscheinen in Logs und Apollo Studio und sind Pflicht, wenn mehrere Operationen in einem Dokument gesendet oder persistierte Queries genutzt werden.
# Give operations a name - required in production
query GetUserProfile($id: ID!) {
user(id: $id) {
id
name
email
}
}
mutation CreatePost($input: CreatePostInput!) {
createPost(input: $input) {
id
}
}Mutationen
Mutation-Typ
Der Mutation-Typ ist der Einstiegspunkt für Schreiboperationen. Konventionell Mutation-Felder als Verben benennen (createUser, updatePost). Mutationen laufen seriell in der geschriebenen Reihenfolge, sodass reihenfolgeabhängige Seiteneffekte über mehrere Mutation-Felder in einer Anfrage sicher sind.
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
createPost(input: CreatePostInput!): Post!
}
# Client mutation
mutation {
createUser(input: { name: "Alice", email: "[email protected]" }) {
id
name
}
}Mutation mit Input
Input-Typen für Mutation-Argumente verwenden. Sie gruppieren verwandte Felder, halten die Signatur sauber und entwickeln sich sicher (optionale Felder ergänzen ohne zu brechen). Mutation-Payloads immer über Variablen übergeben, nie Inline-Literale.
input CreateUserInput {
name: String!
email: String!
age: Int
}
type Mutation {
createUser(input: CreateUserInput!): User!
}
mutation($input: CreateUserInput!) {
createUser(input: $input) {
id
name
}
}
# { "input": { "name": "Bob", "email": "[email protected]" } }Payloads zurückgeben
Ein verbreitetes Muster ist ein Payload-Objekt, das das Ergebnis mit errors, einem success-Flag oder einer client mutation ID umwickelt. Flexibler als Werfen — man kann Teilerfolg und strukturierte Validierungsfehler neben der Entität zurückgeben.
# Return the changed entity AND related fields like errors
type CreateUserPayload {
user: User
errors: [UserError!]!
}
type UserError {
field: String
message: String!
}
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
}Mehrere Mutationen
Anders als Queries (parallel) laufen Mutationen einer Operation seriell in der Deklarations-Reihenfolge. Das garantiert, dass die zweite Mutation die Effekte der ersten sieht. Fehlschlägt ein Mutation-Feld, laufen spätere trotzdem — Inputs validieren und wo nötig Transaktionen nutzen.
# Multiple mutations run SERIALLY in declared order
mutation {
createPost(input: { title: "A" }) {
id
}
publishPost(id: "1") {
publishedAt
}
}Idempotenz
Netzwerk-Retries können Schreiboperationen duplizieren. Ein Idempotenz-Key lässt den Server einen Retry erkennen und das Original-Ergebnis zurückgeben statt ein Duplikat zu erzeugen. Essenziell für Zahlungen, Bestellungen und jede nicht umkehrbare Aktion.
# Use a client mutation id or idempotency key
input CreateOrderInput {
idempotencyKey: String!
productId: ID!
quantity: Int!
}
type Mutation {
createOrder(input: CreateOrderInput!): Order!
}
# Clients retry with the SAME idempotencyKey on failure
# Server returns the original order instead of creating a duplicateSubscriptions
Subscription-Typ
Subscriptions pushen Daten vom Server zum Client, wenn Ereignisse auftreten, typischerweise über WebSocket. Sie sind langlaufende Operationen. Payloads klein halten — Clients holen Detaildaten üblicherweise mit einer Folge-Query, statt große Objekte zu streamen.
type Subscription {
postAdded: Post!
userJoined(roomId: ID!): User!
messageReceived(userId: ID!): Message!
}
# Client subscribes (usually over WebSocket)
subscription {
postAdded {
id
title
author { name }
}
}Ereignisse abonnieren
Ein Subscription-Resolver exponiert eine subscribe-Funktion, die einen AsyncIterator zurückgibt. Mutationen (oder jeder Server-Code) publizieren Ereignisse über pubsub auf dasselbe Topic. Die optionale resolve-Funktion transformiert die publizierte Payload in die Feldform.
# Server-side resolver with asyncIterator
const resolvers = {
Subscription: {
postAdded: {
subscribe: () => pubsub.asyncIterator(["POST_ADDED"]),
resolve: (payload) => payload.postAdded,
},
},
};
# Trigger from a mutation
const resolvers = {
Mutation: {
createPost: async (_, args, { pubsub }) => {
const post = await createPost(args);
await pubsub.publish("POST_ADDED", { postAdded: post });
return post;
},
},
};PubSub
Die PubSub von graphql-subscriptions funktioniert für eine einzelne Server-Instanz. Bei mehreren Server-Instanzen hinter einem Load Balancer braucht man einen geteilten Broker — redis-pubsub, MQTT oder einen Kafka-basierten pubsub — damit Ereignisse Clients an jeder Instanz erreichen.
import { PubSub } from "graphql-subscriptions";
const pubsub = new PubSub();
// publish an event
pubsub.publish("POST_ADDED", { postAdded: post });
// consume in a subscription resolver
subscribe: () => pubsub.asyncIterator(["POST_ADDED"])
# For multi-instance production, swap PubSub for
# Redis, NATS, or Kafka-based implementations.Subscription mit Filtern
withFilter lässt jeder verbundene Client nur relevante Ereignisse empfangen — z. B. an ihn adressierte Nachrichten. Die Filter-Funktion erhält die publizierte Payload und die Subscription-Variablen. Filter billig halten; sie laufen für jedes publizierte Ereignis je verbundenem Client.
const resolvers = {
Subscription: {
messageReceived: {
subscribe: withFilter(
() => pubsub.asyncIterator(["MESSAGE_RECEIVED"]),
(payload, variables) =>
payload.messageReceived.recipientId === variables.userId
),
resolve: (payload) => payload.messageReceived,
},
},
};
# Only events where the filter returns true reach this clientWebSocket-Transport
Subscriptions nutzen das graphql-ws-Protokoll (oder das ältere subscriptions-transport-ws) über WebSocket. Das neuere graphql-ws-Protokoll wird empfohlen. connectionParams tragen Auth-Tokens. Der Server muss den WS-Handler neben dem HTTP-Endpunkt installieren.
# Client uses graphql-ws over WebSocket
import { createClient } from "graphql-ws";
const wsClient = createClient({
url: "ws://localhost:4000/graphql",
connectionParams: { authToken: "..." },
});
wsClient.subscribe(
{ query: "subscription { postAdded { id title } }" },
{
next: (data) => console.log(data),
error: (err) => console.error(err),
complete: () => console.log("done"),
}
);Argumente
Feld-Argumente
Argumente sind benannt, nie positional. Sie können auf jedem Feld auftreten, nicht nur Root-Feldern. Benannte Argumente machen Queries selbstdokumentierend und reihenfolgeunabhängig. Bei dynamischen Werten Variablen statt Inline-Literalen verwenden.
type Query {
user(id: ID!): User
posts(limit: Int, offset: Int): [Post!]!
}
# Arguments can be inline literals
query {
user(id: "1") { name }
posts(limit: 10, offset: 0) { title }
}Default-Werte
Argumente mit Default-Werten werden optional — Clients können sie weglassen. Default-Werte werden pro Anfrage ausgewertet. Für non-null Argumente gibt es keinen Default; der Client muss einen Wert liefern. Defaults halten Queries knapp, bleiben aber bei Bedarf explizit.
type Query {
# default values make arguments optional
posts(limit: Int = 10, sort: String = "newest"): [Post!]!
user(id: ID!, includeDeleted: Boolean = false): User
}
# These are equivalent:
query { posts { title } }
query { posts(limit: 10, sort: "newest") { title } }Argument-Typen
Argumente können Skalare, Enums, Listen oder Input-Objekttypen sein — nie normale Objekttypen (diese sind nur für Ausgabe). Input-Objekte sind der idiomatiche Weg, komplexe strukturierte Argumente zu übergeben, besonders für Filter und Pagination.
type Query {
# scalar arguments
byId(id: ID!): User
byAge(min: Int!, max: Int!): [User!]!
# enum argument
byStatus(status: UserStatus!): [User!]!
# input object argument
search(filter: UserFilter!): [User!]!
# list argument
byIds(ids: [ID!]!): [User!]!
}Erforderlich vs. optional
Das !-Suffix macht ein Argument erforderlich. Fehlt ein erforderliches Argument, scheitert die Validierung, bevor der Resolver läuft, mit klarer Fehlermeldung. Erforderlich für wirklich nötige Inputs, optional-mit-Default für abstimmbares Verhalten.
type Query {
# required (non-null) - client MUST provide
user(id: ID!): User
# optional (nullable) - client may omit
posts(limit: Int): [Post!]!
# optional with default
recentPosts(limit: Int = 5): [Post!]!
}
# Omitting a required argument is a validation error
# before any resolver runs.Listen-Argumente
Listen-Argumente nutzen eckige Klammern. [ID!]! bedeutet eine non-null Liste von non-null IDs — der Client muss eine Liste übergeben und jedes Element darf nicht null sein. Listen über Variablen statt Inline-Literalen übergeben — sauberer und ohne Escaping-Probleme.
type Query {
usersByIds(ids: [ID!]!): [User!]!
tags(allOf: [String!]): [Post!]!
}
# Inline list literal
query {
usersByIds(ids: ["1", "2", "3"]) { name }
}
# Via variable
query($ids: [ID!]!) {
usersByIds(ids: $ids) { name }
}
# { "ids": ["1", "2", "3"] }Variablen
Variablen-Definition
Variablen parametrisieren Operationen. Im Operations-Header als $name: Type deklarieren, im Body als $name referenzieren und Werte in einem separaten JSON variables-Feld senden. Das trennt die statische Query von dynamischen Daten.
# Declare variables in the operation, then use them
query GetUser($id: ID!) {
user(id: $id) {
name
email
}
}
# Variables are sent in a separate JSON object
{
"id": "1"
}Variablen-Typen
Variablen-Typen müssen den Argument-Typen im Schema entsprechen. Variablen können nullable, non-null, Listen oder Input-Objekte sein. Der Typ einer Variablen muss ein Input-Typ sein (Skalar, Enum oder Input-Objekt) — nie ein Ausgabe-Objekttyp.
query Search(
$term: String!
$limit: Int = 10
$filters: PostFilter
$tags: [String!]
) {
search(term: $term, limit: $limit, filters: $filters, tags: $tags) {
title
}
}Default-Werte
Variablen-Defaults greifen, wenn der Client die Variable weglässt. Sie sind nur auf nullable Variablen legal — eine non-null Variable verlangt vom Client zwingend einen Wert. Defaults lassen Clients minimale Variablen-Sets senden, während der Server flexibel bleibt.
query Posts($limit: Int = 10, $sort: String = "newest") {
posts(limit: $limit, sort: $sort) { title }
}
# If the client omits "limit", it defaults to 10.
# Only nullable variables can have defaults - a non-null
# variable with a default is a contradiction.Erforderliche Variablen
Eine non-null Variable (!) ist erforderlich — das Weglassen scheitert an der Validierung, bevor der Resolver läuft. Der sicherste Weg, die Existenz eines Inputs zu garantieren. Non-null Variablen können keinen Default haben; wer einen Default will, macht die Variable nullable.
query User($id: ID!) { # ! means required
user(id: $id) { name }
}
# Missing required variable -> validation error
{ "id": "1" } # OK
{ } # ERROR: variable $id of type ID! is required
# A non-null variable cannot have a default value.Variablen mit Directives
Variablen treiben Directives wie @include und @skip an, sodass Clients Felder dynamisch ein-/ausschalten. Ideal für Feature-Flags, A/B-Tests oder bedingte Abschnitte — alles mit einem einzigen gecachten Query-Dokument.
query User($id: ID!, $withPosts: Boolean!) {
user(id: $id) {
name
posts @include(if: $withPosts) {
title
}
}
}
# { "id": "1", "withPosts": false } -> posts omitted
# { "id": "1", "withPosts": true } -> posts includedFragments
Benannte Fragments
Fragments sind wiederverwendbare Selection-Sets, die an einen konkreten Typ gebunden sind (fragment Name on Type). Überall mit ...Name ausbreiten, wo dieser Typ erscheint. Sie halten Queries DRY und lassen Clients Feldauswahlen über Operationen hinweg teilen.
# Define a reusable fragment
fragment UserFields on User {
id
name
email
}
# Spread it into queries
query {
user(id: "1") {
...UserFields
}
users {
...UserFields
}
}Fragment-Komposition
Fragments können andere Fragments ausbreiten und so zusammengesetzte Auswahlen bilden. Das modularisiert Feldentscheidungen (basic vs. full profile) und lässt UI-Komponenten je ihre Datenbedürfnisse deklarieren, die dann zu einer Query komponiert werden.
fragment UserBasic on User {
id
name
}
fragment UserWithEmail on User {
...UserBasic
email
}
fragment UserFull on User {
...UserWithEmail
posts { title }
}
# Fragments can spread other fragments of the same type.Fragment-Variablen
Relay-artige Fragment-Variablen lassen ein Fragment Parameter akzeptieren (etwa ein limit), die Aufrufer über @arguments übergeben. So sind Fragments wirklich wiederverwendbar mit verschiedenen Einstellungen. Apollo unterstützt das über die @arguments-Directive aus seinen Client-Directives.
fragment UserPosts on User
@argumentDefinitions(limit: { type: "Int", defaultValue: 5 }) {
posts(limit: $limit) {
title
}
}
query {
user(id: "1") {
...UserPosts @arguments(limit: 10)
}
}
# @argumentDefinitions and @arguments come from
# Relay; Apollo uses a similar pattern via client directives.Wiederverwendbare Fragments
Fragments neben den Komponenten abzulegen, die sie rendern, ist ein mächtiges Muster: jede Komponente deklariert ihre Datenbedürfnisse, und das Parent komponiert sie zu einer Query. So skaliert Datenabruf in großen Apps (Relay und Apollo unterstützen beide).
// Colocate fragments with the UI component that uses them
const USER_CARD = graphql`
fragment UserCard_user on User {
id
name
avatarUrl
}
`;
function UserCard({ user }) {
return <div>{user.name}</div>;
}
// The parent query spreads all needed fragments
query {
users {
...UserCard_user
}
}Fragment-Fallstricke
Ein auf Post deklariertes Fragment darf nur dort ausgebreitet werden, wo ein Post erwartet wird — auf einem User ist das ein Validierungsfehler. Inline-Fragments mit Typbedingungen verwenden, um bedingt auf Unions/Interfaces auszubreiten. Zirkuläre Fragment-Spreads vermeiden.
# A fragment must match the type where it's spread
fragment PostFields on Post { title body }
query {
user(id: "1") {
...PostFields # ERROR: user is not a Post
}
}
# Fragments can only spread on the declared type
# (or via type conditions with inline fragments).Inline-Fragments
Inline-Fragment-Grundlagen
Ein inline fragment ist ein unbenanntes Selection-Set mit Präfix ... on Type. Es wendet Felder nur an, wenn das Laufzeit-Objekt der Typbedingung entspricht. So greift man auf typspezifische Felder bei Interfaces und Unions zu.
# An inline fragment is a selection set with a type condition
query {
user(id: "1") {
id
name
# fields common to User
... on AdminUser {
permissions
}
}
}
# No name - declared inline in the query.Typbedingungen
Die Syntax ... on Type ist eine Typbedingung. Mehrere Inline-Fragments in einer Auswahl behandeln jeden möglichen Typ einer Union/eines Interfaces getrennt. Felder, die alle Typen teilen, können direkt außerhalb der Fragments gewählt werden.
query Search($term: String!) {
search(term: $term) {
... on User { name email }
... on Post { title author { name } }
... on Comment { body }
}
}Union-Zugriff
Unions haben außer __typename keine geteilten Felder, daher braucht man Inline-Fragments, um typspezifische Daten zu lesen. __typename ist immer wählbar und sagt dem Client, welcher konkrete Typ jedes Element ist — essenziell zum Rendern von Union-Ergebnissen.
union SearchResult = User | Post | Comment
query {
search(term: "graphql") {
# shared __typename is always available
__typename
... on User { name }
... on Post { title }
... on Comment { body }
}
}Interface-Zugriff
Interfaces deklarieren geteilte Felder. Diese lassen sich direkt auf dem Interface wählen; typspezifische Felder brauchen Inline-Fragments. Anders als Unions garantieren Interfaces eine gemeinsame Feldmenge, die jeder implementierende Typ liefern muss.
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }
query {
node(id: "1") {
id # shared interface field - selectable directly
... on User { name }
... on Post { title }
}
}Benanntes Fragment mit Typbedingung
Benannte Fragments tragen ihre eigene Typbedingung, sodass man sie auf einer Union-/Interface-Antwort ausbreiten kann und jedes nur auf seinen passenden Typ wirkt. Das kombiniert Wiederverwendbarkeit mit bedingter Auswahl — mehrere benannte Fragments ausbreiten, um alle Union-Mitglieder abzudecken.
# Named fragments can also carry a type condition
fragment UserFields on User { name email }
fragment PostFields on Post { title }
query {
search(term: "a") {
...UserFields
...PostFields
}
}
# Equivalent to inlining those fragments inline.Directives
Eingebaute Directives
GraphQL bringt zwei eingebaute Client-Directives mit: @skip(if: Boolean!) lässt das Feld weg, wenn true; @include(if: Boolean!) nimmt es nur auf, wenn true. Sie schließen sich gegenseitig aus und wirken auf Felder, Fragment-Spreads und Inline-Fragments.
# @skip - omit field if true
query($skip: Boolean!) {
user(id: "1") {
name
email @skip(if: $skip)
}
}
# @include - include field only if true
query($withPosts: Boolean!) {
user(id: "1") {
posts @include(if: $withPosts) { title }
}
}@skip und @include
@skip und @include lassen eine Query mehrere Formen bedienen. Sie nehmen eine Boolean-Variable, sodass dieselbe persistierte Query je nach Variablen eine Übersicht oder Detailansicht rendert — ohne zwei Query-Strings zu pflegen.
query User($id: ID!, $detailed: Boolean!) {
user(id: $id) {
name
email @skip(if: $detailed) # hide when detailed
profile @include(if: $detailed) { # show when detailed
bio
}
}
}
# { "id": "1", "detailed": false } -> name, email
# { "id": "1", "detailed": true } -> name, profile { bio }Eigene Directives
Eigene Directives beginnen mit einer directive-Deklaration, die Argumente und erlaubte Orte angibt. Ausführungssemantik ist nicht eingebaut — man implementiert sie mit Schema-Transforms (Apollo) oder Directive-Visitors (graphql-tools). Üblich: @auth, @cached, @deprecated.
# Declare a directive in SDL
directive @auth(requires: Role = ADMIN) on FIELD_DEFINITION
type Query {
adminData: String @auth(requires: ADMIN)
userData: String @auth(requires: USER)
}
# A directive needs a location: FIELD_DEFINITION, FIELD,
# OBJECT, ENUM, etc. Logic is implemented in the server
# (e.g. via schema transforms or a directive visitor).Directive-Orte
Jede Directive deklariert, wo sie legal ist — auf Operationen, Feldern, Fragments oder Schemadefinitionen (FIELD_DEFINITION, OBJECT usw.). Client-Directives (in Queries angewandt) und Schema-Directives (in SDL) nutzen unterschiedliche Ortsmengen. Beim Schema-Bau validieren.
# Where a directive can appear
directive @example on
| QUERY # operation
| FIELD # a field in a selection
| FRAGMENT_DEFINITION
| FRAGMENT_SPREAD
| INLINE_FRAGMENT
| FIELD_DEFINITION # in SDL (server-side)
| OBJECT | INTERFACE | UNION | ENUM
| ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION;
# Multiple locations use | between them.Directive-Argumente
Directives können typisierte Argumente mit Defaults nehmen. Das eingebaute @deprecated(reason:) markiert Felder und Enum-Werte als veraltet; Tools warnen Clients, die sie nutzen. Eigene Directives mit Argumenten treiben Verhalten wie Cache-TTLs oder erforderliche Rollen an.
directive @deprecated(
reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE
type Query {
oldField: String @deprecated(reason: "Use newField")
newField: String
}
enum Status {
ACTIVE
INACTIVE @deprecated(reason: "Use ARCHIVED")
ARCHIVED
}Enums
Enums definieren
Ein Enum ist eine endliche Menge benannter Werte. Enums sind Skalar-Typen — Blattwerte ohne Sub-Auswahl. Für jedes Feld mit fester Optionsmenge (status, role, kind) statt magischer Strings verwenden — man gewinnt Validierung und Selbstdokumentation.
enum Role {
ADMIN
USER
GUEST
}
enum PostStatus {
DRAFT
PUBLISHED
ARCHIVED
}
type User {
role: Role!
}
type Post {
status: PostStatus!
}Enum-Werte
Enum-Werte werden in Queries als unquoted Identifier geschrieben (color: RED), aber als Strings in JSON-Variablen und Antworten serialisiert. Konventionell UPPER_SNAKE_CASE benennen. Der Server validiert jeden Wert gegen die deklarierte Menge.
enum Color {
RED
GREEN
BLUE
}
# In a query, enum values are unquoted identifiers
query {
products(color: RED) { name }
}
# In variables JSON, they're sent as strings
{ "color": "RED" }Enums in Queries
Enums wirken als Feldtypen wie als Argument-Typen. Als Argument übergibt der Client einen der deklarierten Werte. Ungültige Enum-Werte scheitern an der Validierung, bevor der Resolver läuft, mit klarer Fehlermeldung.
type Query {
posts(status: PostStatus!): [Post!]!
}
query {
posts(status: PUBLISHED) { title }
}
query($status: PostStatus!) {
posts(status: $status) { title }
}
# { "status": "DRAFT" }Enum-Resolver
Standardmäßig mappt ein Enum-Wert auf sich selbst. Ein Enum-Resolver mappt zwischen dem öffentlichen API-Namen (ADMIN) und einer internen Repräsentation (ein String "admin" oder ein numerischer Rollencode). So entkoppelt das Schema von Storage-Details.
# Map internal values <-> API values
enum Role {
ADMIN
USER
}
const resolvers = {
Role: {
ADMIN: "admin", // internal DB value
USER: "user",
},
};
# Internally the resolver sees "admin"; the client sees ADMIN.
# Useful when DB values differ from the public API.Enum-Best-Practices
Für feste Optionsmengen immer Enums statt freier Strings — sie validieren Inputs, dokumentieren die API und bessern Tooling. Um einen Enum-Wert zu entfernen, ohne Clients zu brechen, ihn zuerst deprecaten. Ein noch von Clients gesendeter Wert zu entfernen ist ein Breaking Change.
# Prefer enums over strings for fixed option sets
type User {
role: Role! # GOOD - validated, self-documenting
roleStr: String # AVOID - no validation, magic strings
}
# Deprecate values instead of removing them
enum Status {
ACTIVE
INACTIVE @deprecated(reason: "Use ARCHIVED")
ARCHIVED
}Interfaces
Interfaces definieren
Ein Interface ist ein abstrakter Typ, der eine Feldmenge deklariert, die implementierende Typen liefern müssen. Er definiert einen Vertrag. Interfaces sind nützlich für gemeinsame Abstraktionen wie Node (Relay-artige globale IDs) oder Character über verwandte Typen hinweg.
interface Node {
id: ID!
}
interface Character {
name: String!
}
type User implements Node & Character {
id: ID!
name: String!
email: String!
}Interfaces implementieren
Ein Typ erklärt mit dem implements-Schlüsselwort, dass er ein Interface implementiert. Er muss jedes Interface-Feld mit kompatiblen Typen definieren. Ein Typ kann mehrere Interfaces implementieren (mit & getrennt). Das Schema validiert das beim Build.
interface Node {
id: ID!
}
type User implements Node {
id: ID! # required by Node
name: String!
}
type Post implements Node {
id: ID! # required by Node
title: String!
}
# A type must implement every field of the interface.Interfaces abfragen
Gibt ein Feld ein Interface zurück, lassen sich die geteilten Felder des Interfaces direkt wählen. Für typspezifische Felder Inline-Fragments (... on User) verwenden. Der Laufzeittyp jedes Ergebnisses entscheidet, welche Inline-Fragments gelten.
interface Node { id: ID! }
type Query {
node(id: ID!): Node
}
query {
node(id: "1") {
id # interface field - always selectable
... on User { name }
... on Post { title }
}
}Interface-Resolver
Ein Interface braucht eine __resolveType-Funktion, die für einen gegebenen Laufzeitwert den konkreten Typnamen (oder das Typ-Objekt) zurückgibt. So weiß GraphQL, welche Inline-Fragments gelten. Ohne sie kann GraphQL den konkreten Typ zur Laufzeit nicht bestimmen.
interface Character { name: String! }
type Human implements Character {
name: String!
starships: [String!]!
}
type Droid implements Character {
name: String!
primaryFunction: String
}
const resolvers = {
Character: {
// tell GraphQL which concrete type a value is
__resolveType(obj) {
return obj.primaryFunction ? "Droid" : "Human";
},
},
};Mehrere Interfaces
Ein Typ kann mit & getrennt mehrere Interfaces implementieren. Das komponiert Fähigkeiten — etwa ein Article, das Node, Timestamped und SoftDeletable ist. Die Abfrage gibt den Interface-Typ zurück, und Clients nutzen Inline-Fragments für konkrete Felder.
interface Node { id: ID! }
interface Timestamped { createdAt: String! }
interface SoftDeletable { deletedAt: String }
type Article implements Node & Timestamped & SoftDeletable {
id: ID!
createdAt: String!
deletedAt: String
title: String!
}
# Use & to list multiple implemented interfaces.Unions
Unions definieren
Eine Union ist ein abstrakter Typ, der einer von mehreren konkreten Typen sein kann, ohne geteilte Felder zu verlangen (anders als Interfaces). Definition mit union Name = TypeA | TypeB. Unions sind ideal, wenn Ergebnisse heterogen, aber konzeptionell verwandt sind.
union SearchResult = User | Post | Comment
type User { id: ID! name: String! }
type Post { id: ID! title: String! }
type Comment { id: ID! body: String! }
type Query {
search(term: String!): [SearchResult!]!
}Union vs. Interface
Interface, wenn Mitglieder einen gemeinsamen Vertrag teilen (Felder, die jedes Mitglied hat). Union, wenn Mitglieder außer konzeptionell nichts verbindet — sie teilen keine Felder. Ein Typ kann in vielen Unions sein; Unions können keine anderen Unions direkt implementieren.
# INTERFACE - shared contract
interface Node { id: ID! }
type User implements Node { id: ID! name: String! }
type Post implements Node { id: ID! title: String! }
# All members share the "id" field.
# UNION - no shared contract
union SearchResult = User | Post
# Members share NO required fields.Unions abfragen
Unions exponieren keine eigenen Felder, also braucht man Inline-Fragments, um überhaupt etwas zu lesen. __typename ist immer verfügbar und sagt dem Client, welcher konkrete Typ jedes Element ist. Ein Feld direkt auf einer Union zu wählen (ohne Typbedingung) ist ein Validierungsfehler.
query {
search(term: "graphql") {
__typename # always available
... on User { name email }
... on Post { title }
... on Comment { body }
}
}
# You CANNOT select fields directly on a union
# (no shared fields) - only via inline fragments.Union-Resolver
Wie Interfaces brauchen Unions einen __resolveType-Resolver, der für einen Laufzeitwert den konkreten Typnamen zurückgibt. Ohne ihn kann GraphQL keine Inline-Fragments wählen. Den Typnamen als String oder das Typ-Objekt aus dem Schema zurückgeben.
union SearchResult = User | Post | Comment
const resolvers = {
SearchResult: {
__resolveType(obj) {
if (obj.email) return "User";
if (obj.title) return "Post";
if (obj.body) return "Comment";
return null;
},
},
};Häufige Muster
Unions modellieren Ergebnis-oder-Fehler-Ausgänge: eine Mutation gibt eine Union aus Erfolgstyp und Fehlertyp zurück und zwingt Clients, beide zu behandeln. Typsicherer als ein einzelner Payload mit optionalen Fehler-Feldern. (SDL verlangt union, keine Typ-Aliase.)
# Mutation result that may be success or error
type CreateUserSuccess { user: User! }
type CreateUserError { messages: [String!]! }
type CreateUserPayload = CreateUserSuccess | CreateUserError
# (note: a type alias like this isn't valid SDL; use union)
union CreateUserPayload = CreateUserSuccess | CreateUserError
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
}Input-Typen
Input-Objekttypen
Input-Typen sind Objekttypen für Argumente, deklariert mit input. Sie gruppieren verwandte Felder (ein Nutzer, ein Filter) in ein einziges Argument. Anders als Ausgabe-Objekttypen dürfen Input-Typen nur Input-Typen enthalten (Skalare, Enums, andere Input-Typen).
input CreateUserInput {
name: String!
email: String!
age: Int
}
type Mutation {
createUser(input: CreateUserInput!): User!
}
mutation($input: CreateUserInput!) {
createUser(input: $input) { id }
}
# { "input": { "name": "Alice", "email": "[email protected]" } }Input vs. Output
Ausgabetypen (type) haben Feldargumente und Resolver; Input-Typen (input) sind reine Daten-Träger ohne Resolver. Sie sind separate Namensräume — es kann einen User-Typ und einen UserInput-Input geben. Nicht für beides denselben nutzen; das bricht die Evolution.
# OUTPUT type - returned from resolvers, has resolvers
type User {
id: ID!
name: String!
posts: [Post!]! # can have field arguments and resolvers
}
# INPUT type - passed into operations, no resolvers
input UserInput {
name: String!
email: String!
# NO field arguments, NO resolvers, NO output object types
}
# A type cannot be used as both input and output.Verschachtelte Inputs
Input-Typen können andere Input-Typen und Listen referenzieren und modellieren so komplexe verschachtelte Payloads. Ideal für hierarchische Formulare oder verschachtelte Filter. Jede Ebene wird gegen das Schema validiert und liefert klare Fehler bei malformed Input.
input AddressInput {
street: String!
city: String!
zip: String!
}
input CreateUserInput {
name: String!
email: String!
address: AddressInput # nested input type
tags: [String!] # list input
}
type Mutation {
createUser(input: CreateUserInput!): User!
}Input-Defaults
Input-Felder und Argumente können Default-Werte haben. Lässt der Client ein Feld weg, greift der Default. Defaults machen Inputs optional, ohne dass Clients ganze Objekte senden müssen. Hinweis: Defaults sind statische Literale, nicht pro Anfrage berechnet.
input PaginationInput {
limit: Int = 20
offset: Int = 0
sort: SortOrder = DESC
}
enum SortOrder { ASC DESC }
type Query {
posts(page: PaginationInput = { limit: 20, offset: 0 }): [Post!]!
}
# Defaults apply per-field when omitted by the client.Input-Validierung
GraphQL validiert Typen und Non-Nullität, aber keine semantischen Regeln (E-Mail-Format, Altersbereich, String-Länge). Diese im Resolver implementieren und für schlechte Daten UserInputError werfen. Manche Server ergänzen Validierungs-Directives (@constraint) für deklarative Regeln.
input CreateUserInput {
name: String! # required, non-null
email: String! # format check needs custom code
age: Int # range check needs custom code
}
# GraphQL validates structure; you validate semantics
function createUser(_, { input }) {
if (!input.email.includes("@")) {
throw new UserInputError("Invalid email");
}
if (input.age < 0 || input.age > 150) {
throw new UserInputError("Invalid age");
}
// ...
}Resolver
Resolver-Funktionen
Ein Resolver ist eine Funktion, die den Wert eines Feldes liefert. Die Resolver-Map spiegelt das Schema: resolvers.Query.user behandelt das user-Feld. Fehlt ein Resolver, nutzt GraphQL einen Default, der die passende Eigenschaft vom Parent liest.
const resolvers = {
Query: {
user: (parent, args, context, info) => {
return context.db.user.findById(args.id);
},
users: () => db.users.findAll(),
},
Mutation: {
createUser: (_, { input }, { db }) =>
db.user.create(input),
},
};Resolver-Argumente
Jeder Resolver bekommt vier Argumente: parent (der aufgelöste Wert des Eltern-Felds), args (die Argumente dieses Felds), context (ein geteiltes Objekt pro Anfrage) und info (AST- und Ausführungs-Metadaten). Die ersten zwei sind am häufigsten; info für fortgeschrittene Fälle wie Sub-Auswahl-Inspektion.
// (parent, args, context, info)
const resolvers = {
Query: {
user: (parent, args, context, info) => {
// parent - value returned by the parent field (root for Query)
// args - arguments passed to this field
// context - shared per-request object (db, user, loaders)
// info - AST + execution info (rarely needed)
return context.db.user.findById(args.id);
},
},
};Resolver-Kette
Resolver laufen in einer Tiefen-Kette: der Resolver des Eltern-Felds erzeugt ein Objekt, dann läuft der Resolver jedes Kind-Felds mit diesem Objekt als parent. Dieser Top-Down-Fluss lässt jedes Feld unabhängig auflösen — der Graph setzt sich Feld für Feld zusammen.
# query { user(id: "1") { name posts { title } } }
const resolvers = {
Query: {
user: () => ({ id: "1", name: "Alice" }), // runs first
},
User: {
posts: (user, args, ctx) => { // runs after user
return ctx.db.posts.findByAuthor(user.id);
},
},
Post: {
title: (post) => post.title, // runs after posts
},
};Async-Resolver
Resolver können Promises zurückgeben; GraphQL awaited sie, bevor Kind-Felder laufen. So ruft man Datenbanken und APIs auf. async/await für Lesbarkeit. Resolver auf derselben Ebene laufen parallel (bei Queries), also batcht sich unabhängige async-Arbeit von selbst.
const resolvers = {
Query: {
// return a Promise - GraphQL awaits it
user: async (_, { id }, { db }) => {
const user = await db.user.findById(id);
if (!user) throw new Error("User not found");
return user;
},
},
User: {
posts: async (user, _, { db }) =>
db.posts.findByAuthor(user.id),
},
};Default-Resolver
Hat ein Feld keinen Resolver, liest GraphQL die gleichnamige Eigenschaft vom Parent-Objekt (null, wenn undefined). Resolver schreibt man nur für Felder mit Logik oder Abruf. Das Default-Verhalten greift, wenn die Parent-Objekte schon die richtige Form haben.
# If you don't define a resolver, GraphQL reads from the parent
const resolvers = {
User: {
// name resolver missing - default behavior:
// (parent) => parent.name
posts: (user) => fetchPosts(user.id), // only this is custom
},
};
// Equivalent explicit default:
User: {
name: (user) => (user.name === undefined ? null : user.name),
}Resolver-Best-Practices
Resolver schlank halten: Abruf an Datenquellen-Klassen auf dem context delegieren. Das zentralisiert Datenzugriff (testbar, mockbar) und lässt Datenquellen batchen und cachen. Resolver sollen orchestrieren, nicht direkt SQL oder Fetch-Logik enthalten.
# Keep resolvers thin - delegate to data sources
const resolvers = {
Query: {
user: (_, { id }, { dataSources }) =>
dataSources.userAPI.getUser(id),
},
User: {
posts: (user, _, { dataSources }) =>
dataSources.postAPI.byAuthor(user.id),
},
};
// dataSources live on context, are injected per request,
// and can batch/cache calls internally.Context & DataLoader
Context-Objekt
Der context ist ein Objekt pro Anfrage, das alle Resolver einer Operation teilen. Geteilte Dependencies hier ablegen: Datenbank-Clients, der authentifizierte Nutzer, Data Loaders und Logger. Die context-Funktion läuft einmal pro Anfrage, ihr Rückgabewert geht an jeden Resolver.
const server = new ApolloServer({
typeDefs,
resolvers,
context: ({ req }) => ({
db: new PrismaClient(),
user: getUserFromToken(req.headers.authorization),
loaders: buildLoaders(),
}),
});
// Inside any resolver, the third argument is context:
(parent, args, context) => context.db.user.findById(args.id);Context pro Anfrage
Frische DataLoader-Instanzen innerhalb der context-Funktion erzeugen, damit ihre Caches auf eine Anfrage begrenzt sind. Ein Loader über Anfragen hinweg würde gecachte Daten zwischen Nutzern durchsickern lassen. Der context selbst entsteht einmal pro Anfrage, also gehört per-request-Setup hierher.
const context = async ({ req }) => {
const token = req.headers.authorization || "";
const user = await verifyToken(token); // may be null
return {
user,
db,
// a FRESH DataLoader instance per request
// so caches don't leak across requests
userLoader: new DataLoader((ids) => batchGetUsers(ids)),
};
};Das N+1-Problem
Das N+1-Problem: eine Liste von N Elementen laden, dann pro Element eine Extra-Query, um eine Relation nachzuladen. GraphQLs parallele Feld-Auflösung macht das leicht zu treffen — ein User.posts-Resolver läuft einmal pro User. Das Ergebnis ist eine Flut redundanter Queries.
# query { users { id name posts { title } } }
// BAD: 1 query for users, then N queries for each user's posts
const resolvers = {
User: {
posts: (user, _, { db }) =>
db.posts.findByAuthor(user.id), // runs once per user!
},
};
// If there are 100 users, that's 101 DB queries.
// This is the classic N+1 problem.DataLoader-Grundlagen
DataLoader verschmilzt viele einzelne Loads zu einer gebatchten Anfrage. Man gibt ihm eine batch-Funktion, die ein Array von Keys nimmt und ein Array von Ergebnissen in derselben Reihenfolge zurückgibt. DataLoader sammelt alle Loads innerhalb eines Ticks und ruft die batch-Funktion einmal auf.
import DataLoader from "dataloader";
// A batch function receives an array of keys, returns
// an array of values IN THE SAME ORDER as the keys.
const userLoader = new DataLoader(async (userIds) => {
const users = await db.users.findMany({ where: { id: { in: userIds } } });
// reorder to match the input keys
return userIds.map((id) =>
users.find((u) => u.id === id) ?? null
);
});DataLoader in Resolvern
In Resolvern loader.load(key) statt direkter DB-Aufrufe. Innerhalb eines Ticks werden alle Loads desselben Loaders zu einer Query gebatcht, und Ergebnisse sind für die Dauer der Anfrage gecacht. Das killt N+1s und hält Resolver simpel.
const resolvers = {
User: {
posts: (user, _, { loaders }) =>
loaders.postLoader.load(user.id),
},
Post: {
author: (post, _, { loaders }) =>
loaders.userLoader.load(post.authorId),
},
};
// 100 users -> ONE batched query for all their posts,
// instead of 100 separate queries.Batching und Caching
DataLoader macht zwei Dinge: Batching (viele Loads in einem Event-Loop-Tick werden zu einem batch-Aufruf) und per-Key-Caching (wiederholte Loads desselben Keys geben dasselbe Promise zurück). Der Cache ist pro Loader-Instanz — deshalb pro Anfrage einen frischen Loader erzeugen.
// Batching: many .load() calls in one tick -> one batch fn call
await Promise.all([loader.load(1), loader.load(2), loader.load(3)]);
// -> batchGetUsers([1, 2, 3]) called ONCE
// Caching: repeated .load(sameKey) returns the cached Promise
loader.load(1); loader.load(1); loader.load(1);
// -> batchGetUsers([1]) called ONCE; later calls hit cache
// .clear(key) invalidates; .clearAll() resets everything.Fehlerbehandlung
Fehler-Antwortformat
Fehler kommen in einem top-level errors-Array neben data zurück. Jeder Fehler hat eine message, eine Stelle in der Query, den Pfad zum fehlgeschlagenen Feld und extensions für maschinenlesbare Codes. Ein Feldfehler nullt dieses Feld (oder bubbelt hoch, wenn non-null), während data die erfolgreichen Teile weiterliefert.
# Errors appear in a top-level "errors" array
{
"errors": [
{
"message": "User not found",
"locations": [{ "line": 2, "column": 3 }],
"path": ["user"],
"extensions": {
"code": "NOT_FOUND",
"exception": { "stacktrace": ["..."] }
}
}
],
"data": { "user": null }
}Fehler werfen
Die einfachste Fehlerbehandlung: ein Error werfen. GraphQL fängt ihn, nullt das Feld und ergänzt einen Eintrag im errors-Array. Für mehr Struktur spezialisierte Fehler-Klassen (ApolloError, UserInputError), die einen Fehlercode in extensions tragen.
const resolvers = {
Query: {
user: async (_, { id }, { db }) => {
const user = await db.user.findById(id);
if (!user) {
throw new Error("User not found");
}
return user;
},
},
};
# Thrown errors become entries in the "errors" array.Eigene Fehler
Typisierte Fehlerklassen transportieren Absicht: UserInputError für schlechten Client-Input (4xx), AuthenticationError für fehlende Auth, ForbiddenError für fehlende Berechtigung, und ApolloError mit einem code für eigene Fälle. Der code in extensions lässt Clients zuverlässig auf Fehler verzweigen.
import { ApolloError, UserInputError } from "apollo-server-errors";
const resolvers = {
Mutation: {
createUser: (_, { input }) => {
if (!isValidEmail(input.email)) {
throw new UserInputError("Invalid email", {
field: "email",
});
}
if (emailTaken(input.email)) {
throw new ApolloError("Email taken", "EMAIL_TAKEN", {
email: input.email,
});
}
// ...
},
},
};Error-Extensions
extensions trägt maschinenlesbare Daten: einen stabilen code-String, Retry-Hinweise, Validierungs-Feldpfade usw. Clients sollten auf extensions.code verzweigen statt die menschliche message zu parsen, die sich ändern kann. Stacktraces aus Produktions-Antworten heraushalten.
# Structured, machine-readable error data
throw new ApolloError("Rate limited", "RATE_LIMITED", {
code: "RATE_LIMITED",
retryAfter: 60,
limit: 100,
});
# Clients check extensions.code to handle errors
if (err.extensions.code === "RATE_LIMITED") {
wait(err.extensions.retryAfter);
}Teilergebnisse
GraphQL gibt Teilergebnisse zurück: erfolgreiche Felder kommen in data, fehlgeschlagene sind null (oder bubbeln hoch, wenn non-null) und stehen in errors. Nullable Felder bevorzugen, damit ein Fehler nicht die ganze Antwort nullt. Non-null ist ein harter Vertrag — bewusst einsetzen.
# A non-null field error nulls the parent; nullable just nulls the field
type Query {
user(id: ID!): User # nullable - error nulls only "user"
me: User! # non-null - error bubbles up to null "me"
}
# Query selecting multiple fields:
query { me { name } user(id: "bad") { name } }
# If "user" errors but "me" succeeds:
{
"data": { "me": { "name": "Alice" }, "user": null },
"errors": [{ "path": ["user"], "message": "..." }]
}Apollo Server & Integration
Apollo Server-Setup
Apollo Server ist der populärste Node.js-GraphQL-Server. typeDefs (SDL) und resolvers übergeben, um ihn zu konstruieren, dann mit dem standalone server für schnelle Dev-Zyklen starten. In Produktion an ein bestehendes HTTP-Framework (Express, Fastify, Next.js) anbinden statt standalone.
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
const typeDefs = `#graphql
type Query { hello: String }
`;
const resolvers = {
Query: { hello: () => "Hello, world!" },
};
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
listen: { port: 4000 },
});
console.log(`Server ready at ${url}`);Express-Integration
Für Express expressMiddleware aus @apollo/server/express4 verwenden. Den Server vor dem Montieren der Middleware starten. Die context-Funktion erhält Express req/res und kann Header, Sessions lesen oder Auth anhängen. So komponiert sich GraphQL in eine bestehende Express-App.
import { ApolloServer } from "@apollo/server";
import { expressMiddleware } from "@apollo/server/express4";
import express from "express";
import cors from "cors";
import bodyParser from "body-parser";
const app = express();
const server = new ApolloServer({ typeDefs, resolvers });
await server.start();
app.use("/graphql", cors(), bodyParser.json(),
expressMiddleware(server, {
context: async ({ req }) => ({ user: getUser(req) }),
})
);
app.listen(4000);Schema-Build
makeExecutableSchema (aus @graphql-tools/schema) baut ein Schema aus typeDefs und resolvers und gibt ein GraphQLSchema-Objekt zurück, das an ApolloServer geht. Diese Indirektion ermöglicht Schema-Transforms, das Mergen mehrerer Module und eigene Directives — nützlich in größeren Codebasen.
import { makeExecutableSchema } from "@graphql-tools/schema";
const schema = makeExecutableSchema({
typeDefs,
resolvers,
});
const server = new ApolloServer({ schema });
// makeExecutableSchema lets you apply schema transforms,
// directive visitors, and merge modules before serving.Context-Funktion
Die context-Funktion läuft einmal pro Anfrage, ihr Rückgabewert wird von allen Resolvern geteilt. Hier Auth-Header lesen und den authentifizierten Nutzer, DB-Clients und frische DataLoaders anhängen. Innerhalb des context werfen lehnt eine Anfrage ab, bevor irgendein Resolver läuft (z. B. schlechte Auth).
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, {
context: async ({ req }) => {
const token = req.headers.authorization || "";
const user = await verifyToken(token);
return { user, db, loaders: makeLoaders() };
},
listen: { port: 4000 },
});Apollo Studio / Sandbox
Apollo Sandbox (im Browser unter deiner Server-URL) erlaubt das Erkunden des Schemas und das Ausführen von Operationen während der Entwicklung. Apollo Studio ist das Cloud-Gegenstück für Schema-Historie, Metriken und Tracing. In Produktion Introspection abschalten, wenn das Schema vor Außenstehenden verborgen bleiben soll.
# Apollo Sandbox is a dev IDE in the browser
# Visit the server URL in a browser to open it.
const server = new ApolloServer({
typeDefs,
resolvers,
// Apollo Studio reports go through this key (optional)
// apollo: { graphRef: "my-graph@current" },
});
# For introspection in production, enable it explicitly:
# new ApolloServer({ introspection: true });Request-Lebenszyklus
Apollo Server durchläuft pro Anfrage einen Lebenszyklus: context bauen, Query parsen, gegen das Schema validieren, Resolver ausführen, Antwort formatieren. formatError passt die Fehlerform an; Plugins haken in Phasen wie didResolveOperation, willSendResponse ein — ideal für Logging, Caching und Metriken.
# Order: HTTP request -> context -> parse -> validate ->
# execute (resolvers) -> format response -> HTTP response
const server = new ApolloServer({
typeDefs,
resolvers,
formatError: (formatted, error) => ({
message: error.message,
code: formatted.extensions?.code,
}),
plugins: [loggingPlugin, cachePlugin],
});
# plugins hook into every lifecycle phase.Verwandte GraphQL-Snippets
Copy-paste ready code for common tasks.
Schema and Types
Define types, enums, and scalars.
Queries
Read data with selection sets.
Mutations
Write data and return the result.
Subscriptions
Receive pushed updates over a stream.
Fragments
Reusable selection sets.
Variables
Parameterize operations dynamically.
Directives
Conditionally include or skip fields.
Resolvers
Functions that fulfill each field.
Was this helpful?