Skip to content

GraphQL Aide-mémoire

Langage de requête et runtime pour les API.

01

Démarrage

Requête de base

GraphQL permet aux clients de spécifier exactement les données dont ils ont besoin. Une query récupère des données, et la réponse reflète la forme de la requête. Cela évite le sur-fetching et le sous-fetching courants des API REST.

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

Requête avec variables

Les variables paramètrent les requêtes pour que la même opération se réutilise avec des entrées différentes. Elles se déclarent dans l'en-tête de l'opération avec $name: Type. La chaîne de requête reste statique, seul le JSON des variables change à chaque appel.

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
}

Bases des mutations

Les mutations modifient des données et renvoient un ensemble de sélection comme les queries. Par convention, elles devraient être suivies d'une lecture des données modifiées. GraphQL exécute les mutations en série (l'une après l'autre), tandis que les champs de query tournent en parallèle.

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"
    }
  }
}

Champs et ensembles de sélection

Un ensemble de sélection est la liste des champs entre accolades. Les scalaires et enums renvoient des valeurs feuilles ; les types objets exigent un ensemble de sélection imbriqué. Oublier une sous-sélection sur un type objet est une erreur de validation fréquente.

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 expose de nombreux endpoints à forme fixe ; GraphQL expose un seul endpoint où le client définit la forme. Cela réduit les allers-retours et prévient sur/sous-fetching. Le compromis : un serveur plus complexe et un cache 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

L'introspection permet aux clients de découvrir le schéma à l'exécution. Des outils comme GraphiQL, Apollo Studio et les générateurs de code s'y appuient. Les champs racines __schema et __type sont les points d'entrée. Les serveurs de production peuvent désactiver l'introspection pour masquer leurs entrailles.

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

Schéma et système de types

Déclaration de schéma

Le bloc schema relie les types d'opérations racines. Si vos types racines s'appellent Query, Mutation et Subscription, Apollo/GraphQL.js infère le schéma automatiquement et vous pouvez omettre cette déclaration.

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.

Types racines

Query, Mutation et Subscription sont les points d'entrée d'un schéma. Query est le seul type racine requis. Chaque champ racine devient une opération que les clients peuvent lancer. Les nommer en verbes (createUser) pour les mutations et en noms pour les queries est la convention.

graphql
type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
}

type Subscription {
  postAdded: Post!
}

Définitions de types

Les types se définissent avec le mot-clé type suivi de champs. Chaque champ a un nom et un type de retour. Le suffixe ! signifie non-null ; [Type!] une liste d'éléments non null ; [Type!]! une liste non null d'éléments non null.

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!
}

Ajouter des descriptions

Les chaînes entre triples guillemets (ou les chaînes d'une ligne avant une définition) font partie du schéma comme descriptions. Elles apparaissent dans la doc GraphiQL et l'introspection. Les simples commentaires # ne servent qu'au dev et sont retirés, utilisez donc les triples guillemets pour la doc visible.

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
}

Schéma avec extensions

extend type ajoute des champs à un type déclaré ailleurs. C'est ainsi qu'on découpe un grand schéma en fichiers ou qu'on ajoute des champs propres à un module. Un type peut être déclaré une fois et étendu plusieurs fois, mais chaque champ ne se définit qu'une fois.

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.

Schéma d'abord vs code d'abord

Schema-first écrit le SDL à la main et attache les résolveurs (l'approche classique d'Apollo). Code-first construit le schéma par programme avec des décorateurs/builders TypeScript (Nexus, TypeGraphQL, Pothos), gagnant une sûreté de type entre schéma et résolveurs. Les deux produisent le même schéma d'exécution.

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

Types scalaires

Scalaires intégrés

GraphQL livre cinq scalaires intégrés : Int, Float, String, Boolean et ID. ID se sérialise en chaîne mais désigne sémantiquement un identifiant — les clients doivent le traiter comme opaque. Pas de Date ni DateTime intégrés ; vous les définissez vous-mêmes.

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
}

Scalaires personnalisés

Les scalaires personnalisés permettent de représenter des primitives du domaine. Après les avoir déclarés, vous devez fournir un résolveur qui sérialise (vers JSON), parse (depuis les variables) et éventuellement parse les littéraux (depuis l'AST inline). Sinon la valeur passe telle quelle.

graphql
# Declare a custom scalar in SDL
scalar DateTime
scalar URL
scalar JSON

type Event {
  id: ID!
  at: DateTime!
  link: URL
  metadata: JSON
}

Résolveurs de scalaires

Un résolveur de scalaire a trois méthodes optionnelles. serialize convertit une valeur interne vers la sortie JSON. parseValue convertit une entrée de variable vers la forme interne. parseLiteral convertit un littéral inline de l'AST de requête vers la forme interne. Définissez les trois pour un scalaire pleinement typé.

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;
    },
  },
};

Scalaire Date/DateTime

Le package graphql-scalars livre des scalaires éprouvés : DateTime, Date, Time, EmailAddress, URL, UUID, BigInt, JSON, etc. Préférez-le à une implémentation maison, surtout pour le parsing de dates ISO 8601 où les cas limites abondent.

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!
}

Scalaire JSON

Les scalaires JSON laissent passer des données arbitraires, utiles pour une config dynamique ou des métadonnées. Le compromis : perte de sûreté de type et de validation au niveau champ, et les clients ne peuvent sélectionner des sous-champs. À employer avec parcimonie — un type objet typé est presque toujours meilleur.

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

Types objets

Définir des types objets

Un type objet est une collection de champs nommés avec types de retour. Les types objets forment le graphe — ils se référencent pour bâtir les relations (User a des Posts, Post a un Author). Les types objets sont des types de sortie ; utilisez des types d'entrée pour les entrées.

graphql
type User {
  id: ID!
  name: String!
  email: String
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
}

Champs et types de champs

Chaque champ déclare un type de retour. Nullable par défaut ; ! le rend non null. Les listes s'enveloppent de []. La position de ! compte : [String] peut être null et contenir des null ; [String!] peut être null mais pas ses éléments ; [String!]! ne peut jamais être null ni contenir de null.

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 et listes

Le placement de ! contrôle la nullabilité à chaque niveau. Non-null est puissant mais risqué : si un résolveur renvoie null sur un champ non null, l'erreur remonte et annule aussi le champ parent. Partez de nullable et optez pour non-null quand une valeur est vraiment garantie.

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
}

Objets imbriqués

Les types objets se référencent pour former le graphe, permettant des requêtes qui traversent les relations (user -> posts -> author -> profile). Les références circulaires entre types sont permises et courantes. Le graphe est ce qui fait de GraphQL un graphe, pas un arbre d'endpoints.

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
}

Arguments de champs sur objets

N'importe quel champ — pas seulement les champs racines — peut prendre des arguments. Cela permet à un seul type d'exposer des vues filtrées/paginées des données liées (ex. user.posts(limit: 10)). Les arguments avec valeur par défaut deviennent optionnels dans les requêtes.

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

Type Query

Le type Query est le point d'entrée de toutes les lectures. Chaque champ ici est une opération de premier niveau que les clients peuvent demander. Gardez-le centré sur les lectures ; placez les écritures dans Mutation. Nommer les champs en noms (users, user, search) est la convention.

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

Plusieurs champs

Une query peut sélectionner plusieurs champs racines en une requête. GraphQL les exécute en parallèle (sauf dans les mutations). Cela regroupe des fetches liés en un seul aller-retour, un gain d'efficacité clé face à 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" }, ... ]
  }
}

Alias

Les alias renomment les champs dans la réponse. Ils sont requis quand on sélectionne le même champ avec des arguments différents — les clés d'un objet JSON doivent être uniques. Les alias servent aussi à des clés de réponse plus courtes ou plus parlantes.

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" }
  }
}

Requêtes imbriquées

Traverser les relations est le super-pouvoir de GraphQL. Le client marche dans le graphe (user -> posts -> comments -> author) en une seule requête. Le serveur résout chaque champ via son résolveur ; l'imbrication profonde est permise mais surveillez les requêtes N+1 côté backend.

graphql
query {
  user(id: "1") {
    name
    posts {            # traverse relationship
      title
      comments {        # and another level
        author {
          name
        }
      }
    }
  }
}

Requête avec arguments

Les arguments peuvent être des littéraux inline ou des variables. Les littéraux inline conviennent aux valeurs statiques ; utilisez des variables dès qu'une valeur vient d'une entrée utilisateur ou change à chaque appel. Les variables gardent la requête cachable et évitent la concaténation de chaînes.

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

Nom d'opération

Nommer les opérations (query GetUserProfile) est optionnel mais fortement recommandé. Les opérations nommées se déboguent plus facilement, apparaissent dans les logs et Apollo Studio, et sont requises quand on envoie plusieurs opérations dans un document ou pour des requêtes persistées.

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

Mutations

Type Mutation

Le type Mutation est le point d'entrée des écritures. Par convention, nommez les champs de mutation en verbes (createUser, updatePost). Les mutations s'exécutent en série dans l'ordre écrit, les effets de bord dépendant de l'ordre sont donc sûrs entre plusieurs champs de mutation d'une requête.

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 avec input

Utilisez des types input pour les arguments de mutation. Ils regroupent les champs liés, rendent la signature propre et évoluent sûrement (ajouter des champs optionnels sans casser). Passez toujours les charges de mutation par variables, jamais en littéraux inline.

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

Renvoyer des payloads

Un pattern courant est un objet payload enveloppant le résultat avec des erreurs, un flag de succès ou un ID de mutation client. Plus flexible que lever : on peut renvoyer un succès partiel et des erreurs de validation structurées à côté de l'entité.

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!
}

Plusieurs mutations

Contrairement aux queries (parallèles), les mutations d'une même opération s'exécutent en série dans l'ordre déclaré. Cela garantit que la seconde mutation voit les effets de la première. Si un champ de mutation erre, les suivants tournent quand même — validez les entrées et utilisez des transactions au besoin.

graphql
# Multiple mutations run SERIALLY in declared order
mutation {
  createPost(input: { title: "A" }) {
    id
  }
  publishPost(id: "1") {
    publishedAt
  }
}

Idempotence

Les reprises réseau peuvent dupliquer les écritures. Une clé d'idempotence permet au serveur de reconnaître une reprise et de renvoyer le résultat d'origine au lieu de créer un doublon. Essentiel pour les paiements, commandes et toute action irréversible.

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

Type Subscription

Les subscriptions poussent des données du serveur vers le client quand des événements surviennent, typiquement par WebSocket. Ce sont des opérations de longue durée. Gardez des charges petites — les clients récupèrent généralement les données détaillées par une query de suivi plutôt que de diffuser de gros objets.

graphql
type Subscription {
  postAdded: Post!
  userJoined(roomId: ID!): User!
  messageReceived(userId: ID!): Message!
}

# Client subscribes (usually over WebSocket)
subscription {
  postAdded {
    id
    title
    author { name }
  }
}

S'abonner aux événements

Un résolveur de subscription expose une fonction subscribe renvoyant un AsyncIterator. Les mutations (ou tout code serveur) publient des événements sur le même topic via pubsub. La fonction resolve optionnelle transforme la charge publiée en forme du champ.

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

Le PubSub de graphql-subscriptions convient à une instance de serveur unique. Pour plusieurs instances derrière un load balancer, il faut un broker partagé — redis-pubsub, MQTT, ou un pubsub adossé à Kafka — pour que les événements atteignent les clients connectés à n'importe quelle instance.

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 avec filtres

withFilter permet à chaque client connecté de ne recevoir que les événements pertinents — ex. les messages qui lui sont adressés. La fonction de filtre reçoit la charge publiée et les variables de la subscription. Gardez des filtres légers ; ils s'exécutent pour chaque événement publié par client connecté.

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

Transport WebSocket

Les subscriptions utilisent le protocole graphql-ws (ou l'ancien subscriptions-transport-ws) par WebSocket. Le protocole graphql-ws plus récent est recommandé. connectionParams transporte les tokens d'auth. Le serveur doit installer le handler WS à côté de l'endpoint HTTP.

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

Arguments

Arguments de champs

Les arguments sont nommés, jamais positionnels. Ils peuvent apparaître sur tout champ, pas seulement les champs racines. Des arguments nommés rendent les requêtes auto-documentées et indépendantes de l'ordre. Utilisez des variables plutôt que des littéraux inline quand les valeurs sont dynamiques.

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

Valeurs par défaut

Les arguments avec valeur par défaut deviennent optionnels — les clients peuvent les omettre. Les défauts s'évaluent à chaque requête. Pour un argument non null, pas de défaut ; le client doit fournir une valeur. Les défauts gardent les requêtes concises tout en restant explicites au besoin.

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

Types d'arguments

Les arguments peuvent être des scalaires, enums, listes ou types objets input — jamais des types objets ordinaires (réservés à la sortie). Les objets input sont la façon idiomatique de passer des arguments complexes et structurés, surtout pour les filtres et la 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!]!
}

Requis vs optionnel

Le suffixe ! sur un argument le rend requis. Omettre un argument requis échoue à la validation avant que le résolveur tourne, avec une erreur claire. Préférez requis pour les entrées vraiment nécessaires et optionnel-avec-défaut pour les comportements ajustables.

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.

Arguments en liste

Les arguments en liste utilisent des crochets. [ID!]! signifie une liste non null d'IDs non null — le client doit passer une liste et chaque élément doit être non null. Passez les listes par variables plutôt qu'en littéraux inline, pour la propreté et pour éviter les problèmes d'échappement.

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

Variables

Définition de variable

Les variables paramètrent les opérations. Déclarez-les comme $name: Type dans l'en-tête de l'opération, référencez-les comme $name dans le corps, et envoyez les valeurs dans un champ JSON variables séparé. Cela sépare la requête statique des données dynamiques.

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"
}

Types de variables

Les types de variables doivent correspondre aux types d'arguments du schéma. Les variables peuvent être nullables, non null, listes ou objets input. Le type d'une variable doit être un type d'entrée (scalaire, enum ou objet input) — jamais un type objet de sortie.

graphql
query Search(
  $term: String!
  $limit: Int = 10
  $filters: PostFilter
  $tags: [String!]
) {
  search(term: $term, limit: $limit, filters: $filters, tags: $tags) {
    title
  }
}

Valeurs par défaut

Les défauts de variables s'appliquent quand le client omet la variable. Ils ne sont légaux que sur les variables nullables — une variable non null signifie que le client DOIT fournir une valeur. Les défauts permettent aux clients d'envoyer des jeux de variables minimaux pendant que le serveur reste flexible.

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.

Variables requises

Une variable non null (!) est requise — l'omettre échoue à la validation avant que le résolveur tourne. C'est le moyen le plus sûr de garantir qu'une entrée existe. Les variables non null ne peuvent pas avoir de défaut ; si vous voulez un défaut, rendez la 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.

Variables avec directives

Les variables peuvent piloter des directives comme @include et @skip, permettant aux clients de basculer des champs dynamiquement. Parfait pour les feature flags, tests A/B ou sections conditionnelles — le tout avec un seul document de requête mis en cache.

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

Fragments nommés

Les fragments sont des ensembles de sélection réutilisables liés à un type précis (fragment Name on Type). Dépliez-les avec ...Name partout où ce type apparaît. Ils gardent les requêtes DRY et permettent de partager des sélections de champs entre opérations.

graphql
# Define a reusable fragment
fragment UserFields on User {
  id
  name
  email
}

# Spread it into queries
query {
  user(id: "1") {
    ...UserFields
  }
  users {
    ...UserFields
  }
}

Composition de fragments

Les fragments peuvent déplier d'autres fragments, construisant des sélections composées. Cela module les choix de champs (profil basique vs complet) et laisse chaque composant UI déclarer ses besoins de données, puis les composer en une requête.

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.

Variables de fragment

Les variables de fragment à la Relay permettent à un fragment d'accepter des paramètres (comme une limite) que les appelants passent via @arguments. Cela rend les fragments vraiment réutilisables avec des réglages différents. Apollo le gère via la directive @arguments de ses directives client.

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.

Fragments réutilisables

Placer les fragments à côté des composants qui les rendent est un pattern puissant : chaque composant déclare ses besoins de données, et le parent les compose en une requête. Cela fait monter en charge le fetch de données dans les grandes apps (Relay et Apollo le gèrent tous deux).

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

Pièges des fragments

Un fragment déclaré sur Post ne peut se déplier que là où un Post est attendu — le déplier sur un User est une erreur de validation. Utilisez des fragments inline avec conditions de type pour déplier conditionnellement sur des unions/interfaces. Évitez aussi les dépliages circulaires de fragments.

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

Fragments inline

Bases du fragment inline

Un fragment inline est un ensemble de sélection sans nom préfixé de ... on Type. Il n'applique ses champs que quand l'objet d'exécution correspond à la condition de type. C'est ainsi qu'on accède aux champs spécifiques à un type sur les interfaces et unions.

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.

Conditions de type

La syntaxe ... on Type est une condition de type. Plusieurs fragments inline dans une même sélection permettent de traiter séparément chaque type possible d'une union/interface. Les champs partagés par tous les types se sélectionnent directement hors des fragments.

graphql
query Search($term: String!) {
  search(term: $term) {
    ... on User { name email }
    ... on Post { title author { name } }
    ... on Comment { body }
  }
}

Accès aux unions

Les unions n'ont pas de champs partagés au-delà de __typename ; pour lire des données spécifiques à un type, il faut des fragments inline. __typename est toujours sélectionnable et indique au client le type concret de chaque élément — indispensable pour rendre les résultats d'union.

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

Accès aux interfaces

Les interfaces déclarent des champs partagés. Ces champs partagés se sélectionnent directement sur l'interface ; les champs spécifiques à un type exigent des fragments inline. Contrairement aux unions, les interfaces garantissent un ensemble commun de champs que tout type implémentant doit fournir.

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

Fragment nommé avec condition de type

Les fragments nommés portent leur propre condition de type ; on peut donc les déplier sur un résultat d'union/interface et chacun ne s'applique qu'à son type correspondant. Cela combine réutilisabilité et sélection conditionnelle — dépliez plusieurs fragments nommés pour couvrir tous les membres de l'union.

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

Directives intégrées

GraphQL livre deux directives client intégrées : @skip(if: Boolean!) omet le champ quand vrai, @include(if: Boolean!) ne l'inclut que quand vrai. Elles s'excluent mutuellement et s'appliquent aux champs, dépliages de fragments et fragments inline.

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 et @include

@skip et @include permettent à une requête de servir plusieurs formes. Elles prennent une variable booléenne, donc la même requête persistée peut rendre un résumé ou une vue détaillée selon les variables — inutile de maintenir deux chaînes de requête.

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 }

Directives personnalisées

Les directives personnalisées commencent par une déclaration directive précisant arguments et emplacements autorisés. La sémantique d'exécution n'est pas intégrée — on l'implémente avec des transforms de schéma (Apollo) ou des visiteurs de directives (graphql-tools). Usages courants : @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).

Emplacements des directives

Chaque directive déclare où elle est légale — sur des opérations, champs, fragments ou définitions de schéma (FIELD_DEFINITION, OBJECT, etc.). Les directives client (appliquées dans les requêtes) et les directives de schéma (appliquées dans le SDL) utilisent des ensembles d'emplacements différents. Validez à la construction du schéma.

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.

Arguments de directive

Les directives peuvent prendre des arguments typés avec défauts. La directive intégrée @deprecated(reason:) marque champs et valeurs d'enum comme obsolètes ; les outils avertissent les clients qui les emploient. Les directives personnalisées avec arguments pilotent des comportements comme des TTL de cache ou des rôles requis.

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

Définir des enums

Un enum est un ensemble fini de valeurs nommées. Les enums sont des types scalaires — des valeurs feuilles sans sous-sélection. Employez-les pour tout champ à ensemble fixe d'options (status, role, kind) plutôt que des chaînes magiques, gagnant validation et auto-documentation.

graphql
enum Role {
  ADMIN
  USER
  GUEST
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type User {
  role: Role!
}

type Post {
  status: PostStatus!
}

Valeurs d'enum

Les valeurs d'enum s'écrivent comme identifiants sans guillemets dans les requêtes (color: RED), mais se sérialisent en chaînes dans les variables et réponses JSON. La convention de nommage est UPPER_SNAKE_CASE. Le serveur valide toute valeur contre l'ensemble déclaré.

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 dans les requêtes

Les enums servent à la fois de types de champs et de types d'arguments. En tant qu'argument, le client passe une des valeurs déclarées. Les valeurs d'enum invalides échouent à la validation avant que le résolveur tourne, avec des erreurs claires.

graphql
type Query {
  posts(status: PostStatus!): [Post!]!
}

query {
  posts(status: PUBLISHED) { title }
}

query($status: PostStatus!) {
  posts(status: $status) { title }
}
# { "status": "DRAFT" }

Résolveurs d'enum

Par défaut, une valeur d'enum se mappe à elle-même. Un résolveur d'enum permet de mapper entre le nom public d'API (ADMIN) et une représentation interne (une chaîne "admin" ou un code de rôle numérique). Cela découple le schéma des détails de stockage.

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.

Bonnes pratiques des enums

Préférez toujours les enums aux chaînes libres pour les ensembles fixes d'options — ils valident les entrées, documentent l'API et offrent de meilleurs outils. Pour retirer une valeur d'enum sans casser les clients, dépréciez-la d'abord. Retirer une valeur que les clients envoient encore est un changement cassant.

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

Définir des interfaces

Une interface est un type abstrait déclarant un ensemble de champs que les types implémentant doivent fournir. Elle définit un contrat. Les interfaces servent aux abstractions partagées comme Node (IDs globaux à la Relay) ou Character entre types liés.

graphql
interface Node {
  id: ID!
}

interface Character {
  name: String!
}

type User implements Node & Character {
  id: ID!
  name: String!
  email: String!
}

Implémenter des interfaces

Un type déclare implémenter une interface avec le mot-clé implements. Il doit définir chaque champ de l'interface, avec des types compatibles. Un type peut implémenter plusieurs interfaces (séparées par &). Le schéma valide cela à la construction.

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.

Requêter des interfaces

Quand un champ renvoie une interface, on peut sélectionner directement les champs partagés de l'interface. Pour accéder aux champs spécifiques à un type, utilisez des fragments inline (... on User). Le type d'exécution de chaque résultat détermine quels fragments inline s'appliquent.

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

Résolveurs d'interface

Une interface exige une fonction __resolveType qui renvoie le nom du type concret (ou l'objet type) pour une valeur d'exécution donnée. Cela permet à GraphQL de savoir quels fragments inline appliquer. Sans elle, GraphQL ne peut déterminer le type concret à l'exécution.

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";
    },
  },
};

Interfaces multiples

Un type peut implémenter plusieurs interfaces avec le séparateur &. Cela compose les capacités — ex. un Article qui est à la fois Node, Timestamped et SoftDeletable. La requête renvoie le type interface, et les clients utilisent des fragments inline pour les champs concrets.

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

Définir des unions

Une union est un type abstrait pouvant être l'un de plusieurs types concrets, sans exiger de champs partagés (contrairement aux interfaces). Définissez-la avec union Name = TypeA | TypeB. Les unions conviennent quand les résultats sont hétérogènes mais conceptuellement liés.

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

Utilisez une interface quand les membres partagent un contrat commun (des champs que tous ont). Utilisez une union quand les membres n'ont de lien que conceptuel — ils ne partagent aucun champ. Un type peut figurer dans plusieurs unions ; les unions ne peuvent pas directement implémenter d'autres unions.

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.

Requêter des unions

Les unions n'exposent aucun champ propre, il faut donc des fragments inline pour lire quoi que ce soit. __typename est toujours disponible et indique au client le type concret de chaque élément. Sélectionner un champ directement sur une union (sans condition de type) est une erreur de validation.

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.

Résolveurs d'union

Comme les interfaces, les unions exigent un résolveur __resolveType renvoyant le nom du type concret pour une valeur d'exécution. Sans lui, GraphQL ne peut choisir les fragments inline. Renvoyez le nom du type en chaîne ou l'objet type du schéma.

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;
    },
  },
};

Patterns courants

Les unions modélisent les issues résultat-ou-erreur : une mutation renvoie une union d'un type succès et d'un type erreur, forçant les clients à gérer les deux. Plus type-safe qu'un payload unique avec champs d'erreur optionnels. (Le SDL exige union, pas d'alias de type.)

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

Types d'entrée

Types objets input

Les types input sont des types objets utilisés pour les arguments, déclarés avec input. Ils regroupent des champs liés (un utilisateur, un filtre) en un seul argument. Contrairement aux types objets de sortie, les types input ne peuvent contenir que des types input (scalaires, enums, autres types input).

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

Les types de sortie (type) peuvent avoir des arguments de champ et des résolveurs ; les types d'entrée (input) sont de simples porteurs de données sans résolveurs. Ce sont des namespaces séparés — on peut avoir un type User et un input UserInput. Ne réutilisez pas l'un pour l'autre ; cela casse l'évolution.

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.

Inputs imbriqués

Les types input peuvent référencer d'autres types input et des listes, modélisant des charges imbriquées complexes. Idéal pour des formulaires hiérarchiques ou des filtres imbriqués. Chaque niveau est validé contre le schéma, donnant des erreurs claires en cas d'entrée malformée.

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!
}

Défauts d'input

Les champs et arguments input peuvent avoir des valeurs par défaut. Quand le client omet un champ, le défaut s'applique. Les défauts rendent les inputs optionnels sans forcer les clients à envoyer des objets complets. Notez que les défauts sont des littéraux statiques, non calculés par requête.

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.

Validation d'input

GraphQL valide les types et la non-nullité, mais pas les règles sémantiques (format email, plage d'âge, longueur de chaîne). Implémentez-les dans le résolveur, en levant UserInputError pour les mauvaises données. Certains serveurs ajoutent des directives de validation (@constraint) pour des règles déclaratives.

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

Résolveurs

Fonctions résolveur

Un résolveur est une fonction qui produit la valeur d'un champ. La map de résolveurs reflète le schéma : resolvers.Query.user traite le champ user. Si un résolveur manque, GraphQL emploie un défaut qui lit la propriété correspondante sur le parent.

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

Arguments des résolveurs

Chaque résolveur reçoit quatre arguments : parent (la valeur résolue du champ parent), args (les arguments de ce champ), context (un objet partagé par requête) et info (AST et métadonnées d'exécution). Les deux premiers sont les plus courants ; info sert aux cas avancés comme l'inspection des sous-sélections.

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

Chaîne de résolveurs

Les résolveurs tournent en une chaîne profondeur d'abord : le résolveur du champ parent produit un objet, puis le résolveur de chaque champ enfant tourne avec cet objet comme parent. Ce flux descendant laisse chaque champ se résoudre indépendamment — le graphe s'assemble champ par champ.

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
  },
};

Résolveurs asynchrones

Les résolveurs peuvent renvoyer des Promises ; GraphQL les attend avant de continuer vers les champs enfants. C'est ainsi qu'on interroge bases et API. Utilisez async/await pour la lisibilité. Les résolveurs du même niveau tournent en parallèle (pour les queries), donc le travail asynchrone indépendant se regroupe naturellement.

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

Résolveurs par défaut

Si un champ n'a pas de résolveur, GraphQL lit la propriété de même nom sur l'objet parent (renvoyant null si undefined). On n'écrit des résolveurs que pour les champs nécessitant logique ou fetch. Le comportement par défaut fonctionne quand vos objets parents ont déjà la bonne forme.

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),
}

Bonnes pratiques des résolveurs

Gardez les résolveurs fins : déléguez le fetch à des classes de sources de données sur le contexte. Cela centralise l'accès aux données (testable, mockable) et laisse les sources de données regrouper et mettre en cache. Les résolveurs doivent orchestrer, pas contenir directement du SQL ou de la logique de fetch.

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

Contexte et DataLoader

Objet contexte

Le contexte est un objet par requête partagé par tous les résolveurs d'une opération. Placez-y les dépendances partagées : clients de base, utilisateur authentifié, data loaders, loggers. La fonction de contexte tourne une fois par requête et sa valeur de retour passe à chaque résolveur.

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

Contexte par requête

Créez des instances de DataLoader fraîches dans la fonction de contexte pour que leurs caches se limitent à une requête. Réutiliser un loader entre requêtes ferait fuiter des données en cache entre utilisateurs. Le contexte lui-même se construit une fois par requête, la configuration par requête se fait donc ici.

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

Le problème N+1

Le problème N+1 : récupérer une liste de N éléments, puis faire une requête supplémentaire par élément pour charger une relation. La résolution parallèle des champs de GraphQL rend ce piège facile — un résolveur User.posts tourne une fois par utilisateur. Résultat : une avalanche de requêtes redondantes.

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.

Bases de DataLoader

DataLoader fusionne de nombreux chargements individuels en une requête groupée. Vous lui donnez une fonction de batch qui prend un tableau de clés et renvoie un tableau de résultats dans le même ordre. DataLoader collecte alors tous les chargements d'un tick et appelle votre fonction de batch une fois.

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 dans les résolveurs

Utilisez loader.load(key) dans les résolveurs au lieu d'appels DB directs. Dans un même tick, tous les chargements du même loader se regroupent en une requête, et les résultats se mettent en cache pour la durée de la requête. Cela tue les N+1 tout en gardant les résolveurs simples.

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 et caching

DataLoader fait deux choses : le batching (plusieurs chargements d'un même tick de boucle d'événements deviennent un appel de batch) et le cache par clé (des chargements répétés de la même clé renvoient la même Promise). Le cache est par instance de loader — d'où un loader frais par requête.

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

Gestion des erreurs

Format de réponse d'erreur

Les erreurs reviennent dans un tableau errors de premier niveau à côté de data. Chaque erreur porte un message, un emplacement dans la requête, un chemin vers le champ fautif et des extensions pour les codes lisibles par machine. Une erreur de champ annule ce champ (ou remonte s'il est non null) pendant que data renvoie les parties réussies.

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

Lever des erreurs

La gestion d'erreur la plus simple : lever une Error. GraphQL l'attrape, annule le champ et ajoute une entrée au tableau errors. Pour plus de structure, utilisez des classes d'erreurs spécialisées (ApolloError, UserInputError) qui portent un code d'erreur dans extensions.

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.

Erreurs personnalisées

Utilisez des classes d'erreurs typées pour exprimer l'intention : UserInputError pour une entrée client fautive (4xx), AuthenticationError pour une auth absente, ForbiddenError pour un manque de permission, et ApolloError avec un code pour les cas personnalisés. Le code dans extensions permet aux clients de brancher de façon fiable sur les erreurs.

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,
        });
      }
      // ...
    },
  },
};

Extensions d'erreur

extensions transporte des données lisibles par machine : une chaîne de code stable, des indications de reprise, des chemins de champs de validation, etc. Les clients doivent brancher sur extensions.code plutôt que parser le message humain, qui peut changer. Gardez les piles d'erreurs hors des réponses de production.

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);
}

Résultats partiels

GraphQL renvoie des résultats partiels : les champs réussis reviennent dans data tandis que les champs fautifs sont null (ou remontent s'ils sont non null) et listés dans errors. Préférez des champs nullables pour qu'un échec n'annule pas toute la réponse. Non-null est un contrat fort — employez-le à dessein.

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 et intégration

Configuration d'Apollo Server

Apollo Server est le serveur GraphQL Node.js le plus populaire. Passez typeDefs (SDL) et resolvers pour le construire, puis démarrez avec le serveur standalone pour un dev rapide. En production, intégrez-le à un framework HTTP existant (Express, Fastify, Next.js) plutôt qu'en 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}`);

Intégration Express

Pour Express, utilisez expressMiddleware de @apollo/server/express4. Démarrez le serveur avant de monter le middleware. La fonction de contexte reçoit req/res Express, permettant de lire en-têtes, sessions ou attacher l'auth. Cela compose GraphQL dans une app Express existante.

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

Construction du schéma

makeExecutableSchema (de @graphql-tools/schema) construit un schéma depuis typeDefs et resolvers, renvoyant un objet GraphQLSchema à passer à ApolloServer. Cette indirection permet les transforms de schéma, la fusion de plusieurs modules et l'application de directives personnalisées — utile dans les grandes bases de code.

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.

Fonction de contexte

La fonction de contexte tourne une fois par requête et sa valeur de retour est partagée par tous les résolveurs. Lisez-y les en-têtes d'auth et attachez l'utilisateur authentifié, les clients de base et des DataLoader frais. Lever dans le contexte rejette une requête avant que tout résolveur tourne (ex. auth fautive).

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 (dans le navigateur, à l'URL de votre serveur) permet d'explorer le schéma et de lancer des opérations pendant le développement. Apollo Studio est l'équivalent cloud pour l'historique du schéma, les métriques et le tracing. Désactivez l'introspection en production si vous voulez masquer votre schéma aux étrangers.

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 });

Cycle de vie d'une requête

Apollo Server exécute un cycle par requête : construire le contexte, parser la requête, valider contre le schéma, exécuter les résolveurs, puis formater la réponse. formatError personnalise la forme des erreurs ; les plugins s'accrochent à des phases comme didResolveOperation, willSendResponse — parfait pour logging, cache et métriques.

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.