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.
# 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.
# 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.
# 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.
# 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.
# 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.
# 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 } }
}
}
}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.
# 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.
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.
# 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.
"""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.
# 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.
# 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" });
},
});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.
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.
# 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é.
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.
# 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.
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),
},
};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.
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.
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.
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.
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.
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
}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.
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.
# 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.
# 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.
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.
# 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.
# 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
}
}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.
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.
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é.
# 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.
# 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.
# 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 duplicateSubscriptions
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.
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.
# 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.
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é.
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 clientTransport 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.
# 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"),
}
);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.
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.
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.
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.
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.
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"] }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.
# 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.
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.
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.
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.
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 includedFragments
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.
# 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.
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.
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).
// 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.
# 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).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.
# 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.
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.
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.
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.
# 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.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.
# @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.
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.
# 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.
# 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.
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
}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.
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é.
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.
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.
# 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.
# 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
}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.
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.
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.
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.
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.
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.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.
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.
# 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.
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.
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.)
# 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!
}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).
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.
# 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.
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.
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.
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");
}
// ...
}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.
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.
// (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.
# 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.
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.
# 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.
# 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.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.
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.
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.
# 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.
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.
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.
// 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.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.
# 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.
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.
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.
# 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.
# 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": "..." }]
}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.
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.
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.
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).
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.
# 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.
# 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.Snippets GraphQL associés
Copy-paste ready code for common tasks.
Schema and Types
Define types, enums, and scalars.
Queries
Read data with selection sets.
Mutations
Write data and return the result.
Subscriptions
Receive pushed updates over a stream.
Fragments
Reusable selection sets.
Variables
Parameterize operations dynamically.
Directives
Conditionally include or skip fields.
Resolvers
Functions that fulfill each field.
Was this helpful?