GraphQL.js pour JavaScript (Node.js) : Guide complet

1. Qu'est-ce que GraphQL.js et pourquoi l'utiliser ?

GraphQL.js est l'implémentation de référence de la spécification GraphQL en JavaScript. Elle fournit un ensemble complet d'outils pour créer, exécuter et valider des requêtes GraphQL côté serveur (Node.js) et dans le navigateur. Contrairement à une API REST, où chaque endpoint renvoie une structure de données fixe, GraphQL permet au client de demander précisément les données dont il a besoin, sans rien de superflu. Cela résout les problèmes de sur-récupération (over-fetching) et de sous-récupération (under-fetching) des données, ce qui est crucial pour les performances des applications mobiles et des interfaces web complexes.

La bibliothèque GraphQL.js est le fondement de tous les frameworks GraphQL populaires dans l'écosystème JavaScript, tels qu'Apollo Server, Express-GraphQL, Yoga et autres. Elle prend en charge le travail lourd d'analyse des requêtes, de leur validation, d'exécution des résolveurs et de génération de la réponse en stricte conformité avec la spécification. En utilisant GraphQL.js directement, vous obtenez un contrôle maximal sur le processus de traitement des requêtes, ce qui est particulièrement important lors de la création de middleware personnalisé, d'outils de test ou d'intégration avec des sources de données non standard.

Les principaux avantages de l'utilisation de GraphQL.js incluent : un typage strict du schéma, la génération automatique de documentation (via Introspection Query), la possibilité de combiner efficacement des données provenant de plusieurs sources (bases de données, API REST, microservices) en une seule requête, ainsi que des mécanismes intégrés pour la gestion des erreurs et la pagination. Cela rend la bibliothèque indispensable pour la construction d'API modernes, évolutives et flexibles.

2. Installation

L'installation de la bibliothèque se fait via le gestionnaire de paquets npm (Node Package Manager). Assurez-vous d'avoir Node.js version 12 ou supérieure installé.

npm install graphql

Pour une utilisation dans un projet avec support des modules ES (type: "module" dans package.json), importez les fonctions comme suit :

import { graphql, buildSchema } from 'graphql';

Pour CommonJS (approche standard dans Node.js) :

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

3. Démarrage rapide — exemple minimal fonctionnel

Voici un serveur très simple qui reçoit une requête GraphQL et renvoie un message de bienvenue. Cet exemple illustre le cœur de la bibliothèque : définition du schéma, résolveurs et exécution de la requête.

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

// 1. Définir le schéma (Schema Definition Language - SDL)
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// 2. Définir le résolveur racine (root resolver)
const rootValue = {
  hello: () => {
    return 'Bonjour, GraphQL.js !';
  },
};

// 3. Exécuter la requête
const query = '{ hello }';

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

4. Méthodes / fonctions / classes principales

4.1. buildSchema(schemaString: string): GraphQLSchema

Rôle : Analyse une chaîne écrite en langage de schéma GraphQL (SDL) et crée un objet GraphQLSchema. C'est le moyen le plus rapide de définir un schéma sans utiliser de constructeur programmatique.

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>

Rôle : Fonction principale pour exécuter une requête GraphQL. Elle accepte un objet avec des paramètres (schéma, chaîne de requête, valeur racine,