Claude Code GraphQL: Schema, Resolver und Queries effizient entwickeln

GraphQL verspricht das Gegenteil von REST: statt vieler spezialisierter Endpunkte ein einziger, über den der Client exakt die Daten abfragt, die er braucht. In der Praxis bedeutet das aber auch: Schema entwerfen, Resolver implementieren, das N+1-Problem lösen, Typen sauber halten. Claude Code GraphQL-Workflows machen genau diese Arbeit schneller — besonders dann, wenn du von einer bestehenden REST-API migrierst oder ein Schema von Grund auf entwirfst.

Dieser Artikel zeigt, wie GraphQL funktioniert, wie du mit Node.js und Apollo Server ein vollständiges Schema aufsetzt, und wo Claude Code den größten Hebel hat — von der Typ-Ableitung bis zur Resolver-Diagnose.

1. Was ist GraphQL?

GraphQL ist eine Query Language für APIs, ursprünglich von Facebook entwickelt und 2015 veröffentlicht. Anders als REST, das Ressourcen auf feste URLs abbildet, hat GraphQL einen einzigen Endpunkt — typischerweise /graphql — und der Client schickt dort strukturierte Abfragen, die beschreiben, welche Felder er benötigt.

Das Kernprinzip: Schema-first. Bevor eine Zeile Resolver-Code geschrieben wird, definiert man das Schema: welche Typen es gibt, welche Felder jeder Typ hat, welche Queries und Mutations möglich sind. Das Schema ist gleichzeitig Dokumentation, Vertrag zwischen Frontend und Backend, und Basis für die automatische Typprüfung.

Drei Operationstypen gibt es in GraphQL:

• Query — Daten lesen (äquivalent zu GET in REST)
• Mutation — Daten schreiben oder verändern (äquivalent zu POST/PUT/DELETE)
• Subscription — Echtzeit-Updates über WebSockets empfangen

Ein Resolver ist die Funktion, die ein bestimmtes Feld im Schema mit tatsächlichen Daten befüllt. Jedes Feld kann einen eigenen Resolver haben — oder den Default-Resolver erbt, der einfach den gleichnamigen Wert aus dem übergeordneten Objekt zurückgibt.

2. Schema definieren: Types, Queries, Mutations, Subscriptions

Das GraphQL Schema Definition Language (SDL) ist bewusst einfach gehalten. Ein vollständiges Beispiel für eine Blog-Anwendung:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
  createdAt: String!
}

type Query {
  user(id: ID!): User
  users: [User!]!
  post(id: ID!): Post
  posts(authorId: ID): [Post!]!
}

type Mutation {
  createPost(title: String!, body: String!, authorId: ID!): Post!
  updatePost(id: ID!, title: String, body: String): Post!
  deletePost(id: ID!): Boolean!
}

type Subscription {
  postCreated: Post!
}

Das Ausrufezeichen (!) steht für Non-Nullable: dieses Feld kann nicht null sein. Eckige Klammern kennzeichnen Arrays. ID ist ein skalarer Typ für eindeutige Bezeichner.

3. Resolver implementieren mit Node.js und Apollo Server

Apollo Server ist der verbreitetste GraphQL-Server für Node.js. Die Grundstruktur ist überschaubar:

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

const typeDefs = `
  type User {
    id: ID!
    name: String!
    posts: [Post!]!
  }

  type Post {
    id: ID!
    title: String!
    author: User!
  }

  type Query {
    users: [User!]!
    post(id: ID!): Post
  }
`;

const resolvers = {
  Query: {
    users: async (_, __, { db }) => {
      return db.user.findMany();
    },
    post: async (_, { id }, { db }) => {
      return db.post.findUnique({ where: { id } });
    },
  },
  Post: {
    author: async (post, _, { db }) => {
      return db.user.findUnique({ where: { id: post.authorId } });
    },
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({ db }),
  listen: { port: 4000 },
});

console.log(`Server läuft auf ${url}`);

Jeder Resolver erhält drei Argumente: das übergeordnete Objekt (parent oder hier post), die Argumente des Feldes (args) und den Context (ctx). Der Context ist der Ort für geteilte Ressourcen wie Datenbankverbindungen, Auth-Token oder DataLoader-Instanzen.

4. Queries und Mutations schreiben: Felder auswählen, Variablen, Fragments

Auf der Client-Seite sieht eine GraphQL-Query so aus:

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    posts {
      id
      title
      createdAt
    }
  }
}

Der Client bekommt exakt diese Felder zurück — keine mehr, keine weniger. Variablen ($id) werden separat übergeben, nie in den Query-String eingebettet. Das verhindert Injection-Angriffe und ermöglicht Query-Caching.

Fragments vermeiden Wiederholung, wenn dieselben Felder in mehreren Queries auftauchen:

fragment PostFields on Post {
  id
  title
  createdAt
}

query GetPosts {
  posts {
    ...PostFields
    author {
      name
    }
  }
}

query GetPost($id: ID!) {
  post(id: $id) {
    ...PostFields
    body
    author {
      name
      email
    }
  }
}

Eine Mutation sieht strukturell genauso aus, mit dem Schlüsselwort mutation statt query:

mutation CreatePost($title: String!, $body: String!, $authorId: ID!) {
  createPost(title: $title, body: $body, authorId: $authorId) {
    id
    title
    author {
      name
    }
  }
}

5. Das N+1-Problem und DataLoader für Batching

Das klassische Performance-Problem in GraphQL: Wenn du eine Liste von Posts abfragst und für jeden Post den Autor haben willst, führt der naive Resolver für jeden Post einen separaten Datenbankaufruf aus. Bei 100 Posts sind das 101 Queries — eine für die Posts, 100 für die Autoren.

// Das N+1-Problem: jeder Post-Resolver ruft die DB einzeln auf
Post: {
  author: async (post, _, { db }) => {
    // Wird für JEDEN Post aufgerufen — 100 Posts = 100 DB-Queries!
    return db.user.findUnique({ where: { id: post.authorId } });
  },
}

Die Lösung ist DataLoader, eine Facebook-Bibliothek, die einzelne Requests bündelt und als einen einzigen Batch an die Datenbank schickt:

import DataLoader from 'dataloader';

// DataLoader-Instanz: sammelt IDs und macht einen einzigen DB-Call
const userLoader = new DataLoader(async (ids) => {
  const users = await db.user.findMany({
    where: { id: { in: ids } },
  });
  // Reihenfolge muss mit ids übereinstimmen
  return ids.map(id => users.find(u => u.id === id) ?? null);
});

// Im Resolver: loader statt direkter DB-Call
Post: {
  author: (post, _, { loaders }) => {
    return loaders.user.load(post.authorId);
  },
}

// Im Context: pro Request neue Instanz erstellen
context: async () => ({
  db,
  loaders: {
    user: new DataLoader(async (ids) => { /* ... */ }),
  },
})

Mit DataLoader werden die 100 einzelnen Aufrufe zu einem einzigen SELECT * FROM users WHERE id IN (...). Das ist der Unterschied zwischen einer trägen API und einer schnellen.

6. Claude Code GraphQL: Praxistipps

Schema aus einer bestehenden REST-API generieren

Wer von REST auf GraphQL migriert, hat oft Dutzende von Endpunkten mit unterschiedlichen Response-Strukturen. Claude Code kann aus OpenAPI-Specs, bestehenden Controller-Dateien oder einfachen Beispiel-Responses ein vollständiges GraphQL-Schema ableiten:

claude "Analysiere diese Express-Router-Dateien und generiere ein
GraphQL-Schema, das alle Endpunkte abdeckt. Nutze sinnvolle Typ-Namen
und markiere nicht-nullable Felder korrekt." routes/users.js routes/posts.js

Claude Code liest die Routen, erkennt die Datenstrukturen aus den Response-Objekten und Query-Parametern, und generiert ein Schema, das direkt als Ausgangspunkt dienen kann — inklusive sinnvoller Benennung von Types und Feldern.

Resolver debuggen

GraphQL-Fehler sind oft schwer zu lokalisieren, weil der Server immer HTTP 200 zurückgibt und Fehler im errors-Array verpackt — nicht als HTTP-Statuscode. Claude Code hilft dabei, den Ausführungspfad nachzuvollziehen:

claude "Dieser GraphQL-Resolver gibt null zurück, obwohl die Daten
in der DB vorhanden sind. Finde das Problem:

Fehler: { errors: [{ message: 'Cannot return null for non-nullable field Post.author' }] }

Resolver:" src/resolvers/post.resolver.ts

Claude Code liest den Resolver, verfolgt den Datenfluss, prüft ob der DataLoader korrekt konfiguriert ist, und gibt eine konkrete Diagnose — meistens mit einem Fix, der nicht nur das Symptom behebt, sondern die eigentliche Ursache.

Typen ableiten und TypeScript-Integration

GraphQL und TypeScript ergänzen sich gut: Das Schema definiert die Typen, TypeScript erzwingt sie im Code. Mit Tools wie graphql-codegen werden aus dem Schema automatisch TypeScript-Interfaces generiert. Claude Code kann diesen Schritt beschleunigen:

claude "Generiere TypeScript-Typen für dieses GraphQL-Schema und zeige,
wie ich graphql-codegen konfiguriere, um sie bei Schemaänderungen
automatisch neu zu generieren." schema.graphql

Das Ergebnis: ein codegen.yml, fertige TypeScript-Interfaces, und ein npm-Script, das bei jedem Schema-Update die Typen neu generiert. Manuelles Tippen von Interfaces entfällt vollständig.

Zwei verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code Debugging — wie du Fehler in Resolvern und APIs systematisch findest
• Claude Code für Unternehmen — Deployment, Zugriffskontrolle und Team-Workflows auf Unternehmensebene