GraphQL.js für JavaScript (Node.js): Das vollständige Handbuch

1. Was ist GraphQL.js und warum wird es benötigt?

GraphQL.js ist die Referenzimplementierung der GraphQL-Spezifikation in JavaScript. Sie bietet ein komplettes Toolkit zum Erstellen, Ausführen und Validieren von GraphQL-Abfragen auf der Serverseite (Node.js) und im Browser. Im Gegensatz zu REST-APIs, bei denen jeder Endpunkt eine feste Datenstruktur zurückgibt, ermöglicht GraphQL dem Client, genau die Daten anzufordern, die er benötigt – und nichts Überflüssiges. Dies löst die Probleme des Over-Fetching (Abruf überflüssiger Daten) und Under-Fetching (unzureichende Daten), was für die Leistung mobiler Apps und komplexer Web-Oberflächen entscheidend ist.

Die Bibliothek GraphQL.js bildet die Grundlage für alle gängigen GraphQL-Frameworks im JavaScript-Ökosystem, wie Apollo Server, Express-GraphQL, Yoga und andere. Sie übernimmt die schwere Arbeit des Parsens von Abfragen, deren Validierung, der Ausführung von Resolvern und der Erstellung von Antworten in strikter Übereinstimmung mit der Spezifikation. Wenn Sie GraphQL.js direkt verwenden, haben Sie maximale Kontrolle über den Abfrageverarbeitungsprozess – besonders wichtig für die Erstellung benutzerdefinierter Middleware, Testtools oder die Integration mit ungewöhnlichen Datenquellen.

Zu den Hauptvorteilen der Verwendung von GraphQL.js gehören: strenge Schematypisierung, automatische Dokumentationsgenerierung (über Introspection Query), die Möglichkeit, Daten aus mehreren Quellen (Datenbanken, REST-APIs, Microservices) effizient in einer einzigen Abfrage zu kombinieren, sowie integrierte Mechanismen zur Fehlerbehandlung und Paginierung. Dies macht die Bibliothek unverzichtbar für den Aufbau moderner, skalierbarer und flexibler APIs.

2. Installation

Die Installation der Bibliothek erfolgt über den Paketmanager npm (Node Package Manager). Stellen Sie sicher, dass Node.js Version 12 oder höher installiert ist.

npm install graphql

Für die Verwendung in einem Projekt mit ES-Modul-Unterstützung (type: "module" in package.json) importieren Sie die Funktionen wie folgt:

import { graphql, buildSchema } from 'graphql';

Für CommonJS (Standardansatz in Node.js):

const { graphql, buildSchema } = require('graphql');

3. Schnellstart – Minimales funktionierendes Beispiel

Nachfolgend sehen Sie einen einfachen Server, der eine GraphQL-Abfrage annimmt und eine Begrüßung zurückgibt. Dieses Beispiel zeigt den Kern der Bibliothek: Schemadefinition, Resolver und Abfrageausführung.

const { graphql, buildSchema } = require('graphql');

// 1. Schema definieren (Schema Definition Language - SDL)
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// 2. Root-Resolver definieren
const rootValue = {
  hello: () => {
    return 'Hallo, GraphQL.js!';
  },
};

// 3. Abfrage ausführen
const query = '{ hello }';

graphql({
  schema,
  source: query,
  rootValue,
}).then((response) => {
  console.log(JSON.stringify(response, null, 2));
  // Ausgabe: { "data": { "hello": "Hallo, GraphQL.js!" } }
});

4. Wichtige Methoden/Funktionen/Klassen

4.1. buildSchema(schemaString: string): GraphQLSchema

Funktion: Parst einen String, der in der GraphQL-Schema-Definitionssprache (SDL) geschrieben ist, und erstellt ein GraphQLSchema-Objekt. Dies ist der schnellste Weg, ein Schema ohne programmatischen Konstruktor zu definieren.

const { buildSchema } = require('graphql');

const schema = buildSchema(`
  type Query {
    user(id: ID!): User
  }
  type User {
    id: ID
    name: String
  }
`);

4.2. graphql(args: GraphQLArgs): Promise<GraphQLResult>

Funktion: Die Hauptfunktion zur Ausführung einer GraphQL-Abfrage. Sie nimmt ein Objekt mit Parametern entgegen (Schema, Abfrage-String, Root-Wert,