Mutations GraphQL : syntaxe, variables et types input | We.Inc
Écrivez des mutations GraphQL qui créent, modifient et suppriment des données : syntaxe de l'opération, $variables, types input, quoi renvoyer, et à quoi ressemblent les erreurs et le succès partiel.
Une mutation GraphQL est l'opération que vous envoyez pour modifier des données. Elle commence par le mot-clé mutation, appelle un champ du type Mutation du schéma, transmet des arguments, généralement un seul objet input placé dans une $variable, et sélectionne les champs du résultat à renvoyer. Les champs de mutation de premier niveau s'exécutent l'un après l'autre, jamais en parallèle.
La syntaxe d'une mutation, partie par partie
Partie
Exemple
Rôle
Mot-clé et nom
mutation AddTask
Marque l'opération comme une écriture et la nomme pour les logs
Définitions de variables
($input: TaskInput!)
Déclare des valeurs typées envoyées à part en JSON
Champ racine
addTask(input: $input)
Un champ défini sur le type Mutation
Ensemble de sélection
{ id title done }
Les champs du résultat à renvoyer
JSON des variables
{"input": {...}}
Les valeurs réelles, gardées hors de la chaîne de requête
Utilisez le générateur ci-dessous pour voir une mutation complète pour une petite liste de tâches : l'opération, le JSON des variables que votre code enverrait avec, et une réponse type. Saisissez un titre de tâche et regardez les variables se mettre à jour, pour copier une requête prête à être exécutée sur un schéma correspondant.
Choisissez créer, modifier ou supprimer.
Saisissez un titre pour la tâche ; le JSON des variables se met à jour pendant la saisie.
Copiez la mutation et les variables, puis envoyez-les comme clés query et variables d'un seul POST.
Comparez la réponse de votre serveur avec l'exemple de réponse affiché en dessous.
Envoyez les valeurs via des variables plutôt que de les coller dans la chaîne de requête. Cela évite les bugs d'échappement et permet aux serveurs de mettre en cache le document analysé.
Renvoyez l'objet modifié, avec son id, pour que les caches côté client mettent l'écran à jour sans seconde requête.
Nommez chaque opération. Les mutations nommées sont bien plus faciles à retrouver dans les logs serveur et les rapports d'erreur.
Traitez plusieurs champs racine dans une même mutation comme des étapes séparées, pas comme une transaction : un champ précédent reste appliqué quand un champ suivant échoue.
Questions fréquentes
Quelle est la différence entre une query et une mutation ?
Les deux utilisent la même syntaxe et peuvent toutes deux renvoyer des données. Par convention, les queries ne font que lire et les mutations écrivent. La règle d'exécution diffère aussi : les champs d'une query peuvent être résolus en parallèle, alors que les champs de mutation de premier niveau s'exécutent en série.
Pourquoi utiliser un type input plutôt que de simples arguments ?
Un objet input regroupe des valeurs liées en un seul argument typé : la signature de la mutation reste courte et vous pouvez ajouter plus tard des champs optionnels sans modifier chaque appelant.
Puis-je envoyer une mutation avec une requête GET ?
Non. Les recommandations GraphQL over HTTP autorisent les serveurs à accepter GET uniquement pour les opérations query. Les mutations passent en POST, ce qui tient aussi les écritures à l'écart des caches du navigateur et du CDN.
Une mutation avec plusieurs champs est-elle atomique ?
Non. graphql.org précise que l'exécution en série n'est pas une transaction de base de données. Si le second champ échoue, la modification du premier reste, et la réponse contient des données pour l'un et une erreur pour l'autre.
Que doit renvoyer une mutation de suppression ?
La spécification vous laisse le choix, mais le champ a quand même besoin d'un type de sortie. Les choix courants sont l'id de l'objet supprimé, l'objet supprimé lui-même, ou un type payload avec l'id et un indicateur de succès.
Anatomie d'une mutation
Côté serveur, le schéma déclare un type Mutation dont les champs sont les écritures que les clients peuvent appeler, chacune avec des arguments et un type de retour. Côté client, l'opération nomme un ou plusieurs de ces champs, transmet des arguments et choisit les champs du résultat à récupérer.
Si le champ renvoie un type objet, un ensemble de sélection est obligatoire, exactement comme dans une query. Demander le nouvel id et les champs affichés à l'écran permet au client de mettre sa vue à jour directement depuis la réponse.
Variables et objets input
Les variables se déclarent après le nom de l'opération avec un signe dollar et un type, par exemple $input: TaskInput!. Le point d'exclamation rend la variable obligatoire. Les valeurs voyagent dans un objet variables séparé dans le corps de la requête.
Un type objet input se déclare avec le mot-clé input au lieu de type. Ses champs ne peuvent être que des scalaires, des enums, des listes ou d'autres types input, ce qui garde la forme des données envoyées par les clients simple à valider.
Les erreurs lors d'une écriture
Si le document est invalide, par exemple un champ mal orthographié ou une variable obligatoire manquante, le serveur répond avec des erreurs et sans données, et rien n'est écrit.
Si l'écriture elle-même échoue pendant l'exécution, le champ revient à null et une entrée errors contient un message et un chemin. Beaucoup de schémas renvoient aussi les problèmes attendus, comme un titre trop long, sous forme de champs d'un type payload pour que le client puisse les afficher à côté du formulaire.
Le schéma derrière les exemples
Type Mutation et types input
Les types input utilisent le mot-clé input. TaskPatch n'a aucun champ obligatoire, donc une modification peut n'envoyer que ce qui change.
L'envoyer depuis JavaScript
Envoyer la mutation en POST avec fetch
Le document et les variables voyagent comme deux clés d'un même corps JSON. Vérifiez errors même quand le statut est 200.
Deux écritures dans une seule opération
Les alias permettent d'exécuter deux fois le même champ. Le second ne s'exécute qu'après la fin du premier, mais un échec du second n'annule pas le premier.
Créer
Le type input regroupe les champs de la nouvelle tâche. L'ensemble de sélection demande l'id attribué par le serveur.
Modifier
L'id indique quelle tâche modifier et l'input ne contient que les champs qui changent.
Supprimer
Il n'y a plus rien à sélectionner sur une tâche supprimée, donc ce schéma renvoie l'id supprimé sous forme de simple scalaire ID.
Générateur de mutation
Choisir une mutation
Titre de la tâche
Mutation
Variables (JSON)
Exemple de réponse
Copier la mutation
Copier les variables
La suppression n'a besoin que de l'id, donc le titre n'est pas envoyé.