Skip to content

GraphQL Spickzettel

Abfragesprache und Runtime für APIs.

01

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.

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

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

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

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

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

graphql
# 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 } }
    }
  }
}
02

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.

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

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

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

graphql
"""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.

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

graphql
# 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" });
  },
});
03

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.

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

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

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

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

graphql
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),
  },
};
04

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.

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

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

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

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

graphql
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
}
05

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.

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

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

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

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

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

graphql
# 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
  }
}
06

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.

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

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

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

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

graphql
# 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 duplicate
07

Subscriptions

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.

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

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

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

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

WebSocket-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.

graphql
# 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"),
  }
);
08

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.

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

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

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

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

graphql
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"] }
09

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.

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

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

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

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

graphql
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 included
10

Fragments

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.

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

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

graphql
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).

graphql
// 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.

graphql
# 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).
11

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.

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

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

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

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

graphql
# 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.
12

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.

graphql
# @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.

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

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

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

graphql
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
}
13

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.

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

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

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

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

graphql
# 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
}
14

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.

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

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

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

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

graphql
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.
15

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.

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

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

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

graphql
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.)

graphql
# 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!
}
16

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

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

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

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

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

graphql
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");
  }
  // ...
}
17

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.

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

graphql
// (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.

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

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

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

graphql
# 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.
18

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.

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

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

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

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

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

graphql
// 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.
19

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.

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

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

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

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

graphql
# 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": "..." }]
}
20

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.

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

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

graphql
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).

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

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

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

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.