Fondamentaux de GraphQL pour les développeurs React

REST expose des points de terminaison à forme fixe : GET /users/:id renvoie l’objet utilisateur entier, quels que soient les besoins du client. GraphQL permet aux clients de spécifier exactement les champs souhaités, ce qui élimine la récupération excessive (trop de données) et la récupération insuffisante (pas assez de données, nécessitant plusieurs requêtes).

Une seule requête GraphQL peut récupérer un utilisateur, ses articles et l’auteur de chaque article en un seul aller-retour.

Chaque API GraphQL est définie par un schéma écrit en langage de définition de schéma (SDL). Le schéma déclare les types, leurs champs et les types racine Query, Mutation et Subscription sur lesquels les clients peuvent agir.

Le schéma constitue le contrat entre le client et le serveur. Les équipes frontend et backend peuvent travailler en parallèle une fois le schéma accepté.

Une requête GraphQL sélectionne des champs : { user(id: "1") { name email posts { title } } }. Les champs imbriqués parcourent les relations en une seule requête. Les alias renomment les champs : { me: user(id: "1") { name } }. Les fragments réutilisent des sélections de champs dans plusieurs requêtes.

Les variables rendent les requêtes réutilisables : query GetUser($id: ID!) { user(id: $id) { name } } avec les variables suivantes : { id: "1" }.

Chaque champ du schéma GraphQL possède une fonction de résolution sur le serveur. Lorsqu’un client demande user.name, le résolveur user récupère l’objet utilisateur et le résolveur name (ou le résolveur par défaut) renvoie le champ name.

Cette résolution au niveau des champs permet à GraphQL de récupérer précisément les seules données demandées.

Si vous demandez une liste de 100 articles et que chaque article inclut son auteur, l’implémentation naïve lance 100 requêtes distinctes vers la base de données pour récupérer les auteurs. Ce problème N+1 ralentit les API GraphQL s’il n’est pas optimisé.

DataLoader résout le problème N+1 en regroupant toutes les recherches d’auteurs dans une seule requête vers la base de données, à l’aide d’un cache par requête et d’une fonction de regroupement.

Apollo Studio et GraphQL Playground sont des interfaces utilisateur accessibles depuis un navigateur permettant d'explorer interactivement une API GraphQL. Ils complètent automatiquement les champs à partir du schéma, affichent les résultats des requêtes et présentent la documentation des types directement dans l'interface.

Utiliser l'interface d'exploration est le moyen le plus rapide de comprendre une API GraphQL inconnue avant d'écrire le code client.

Les API GraphQL exposent leur propre schéma au moyen d'une requête d'introspection : { __schema { types { name } } }. Les clients peuvent interroger le schéma lui-même pour découvrir les types, champs et arguments disponibles.

Les outils de génération de code comme graphql-codegen utilisent l'introspection pour générer automatiquement des types TypeScript correspondant au schéma de l'API.

Les mutations GraphQL modifient les données : mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Les abonnements établissent une connexion persistante (généralement WebSocket) et transmettent les mises à jour : subscription { postAdded { id title } }.

Les trois types racine (Query, Mutation, Subscription) utilisent la même syntaxe de sélection des champs.

GraphQL est particulièrement adapté aux applications ayant des besoins complexes en données imbriquées, à plusieurs types de clients (mobile, web, TV) nécessitant des sous-ensembles de champs différents, ou à des API qui évoluent rapidement, lorsque la dépréciation des champs est préférable au versionnement des points de terminaison.

REST est plus simple pour les API CRUD offrant des structures de ressources plates et prévisibles, ainsi que d'excellentes possibilités de mise en cache HTTP grâce aux ETags et aux en-têtes de cache.

Apollo Client est le client GraphQL le plus riche en fonctionnalités : cache normalisé, gestion de l'état local, abonnements et liens de gestion des erreurs. URQL est plus léger, avec un cache de documents et une API plus simple. React Query avec graphql-request est l'approche la plus simple pour les requêtes et mutations de base, sans mécanisme de cache avancé.

Choisissez en fonction de vos exigences de mise en cache : un cache normalisé pour les entités partagées entre plusieurs requêtes (Apollo), ou un cache de documents plus simple pour les requêtes indépendantes (URQL ou React Query).

Voici un SDL simple : type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Les points d'exclamation indiquent les champs non nuls.

Ce schéma indique précisément au client quels champs existent pour chaque type et quelles requêtes sont disponibles, ce qui permet de générer du code sûr du point de vue des types.

Que signifie la « sur-récupération » dans le contexte de REST et de GraphQL ?

GraphQL permet aux clients de demander exactement les champs dont ils ont besoin (sans sur- ni sous-récupération) au moyen d'un langage de requête défini par un schéma. Les résolveurs répondent pour chaque champ ; DataLoader résout le problème N+1. L'introspection permet de générer du code pour les types TypeScript. Apollo Client, URQL et React Query sont les principaux clients GraphQL compatibles avec React.

Choisissez GraphQL pour les besoins complexes, imbriqués et adaptés à plusieurs clients ; REST pour les opérations CRUD simples avec des structures prévisibles.