Comment utiliser les noms d’opérations et les variables GraphQL

Cet article accompagne une vidéo de la chaîne YouTube ShopifyDevs. Chuck Kosman, ingénieur de lancement chez Shopify Plus, vous y présente certaines des fonctionnalités de GraphQL qui permettent de créer plus facilement des applications à grande échelle. Cette vidéo est la première d’une série de 5 tutoriels de formation conçus pour vous aider à mieux comprendre les avantages de GraphQL.

Dans ce premier tutoriel, Chuck Kosman présente les noms d'opérations et les variables GraphQL.

Utiliser GraphQL pour créer une requête de base

Ici, nous utilisons l’IDE graphique. C’est une application installée sur une boutique de développement où nous avons déjà renseigné des produits, des clients et des commandes. Si ces deux premières phrases vous ont paru incompréhensibles, consultez notre article Débuter avec GraphQL.

Nous avons ici une requête qui récupère un produit grâce à son identifiant, via l'argument GraphQL id. Cliquons sur le bouton d'exécution pour récupérer les données.

Ce code marche comme prévu, mais ne sera pas réutilisable à grande échelle. Il faudrait passer cette requête quelque part lors d’une requête HTTP. Cela signifie que si nous souhaitions changer l’identifiant, il faudrait composer la requête séparément pour chaque identifiant, en utilisant l’interpolation de chaîne.

C’est possible, mais ce n’est pas idéal, et surtout cette méthode ne permet pas de profiter au mieux du système de types de GraphQL.

Définir un nom dans GraphQL

Nous pouvons ajouter certains éléments au début du corps de cette requête pour qu’elle soit plus facilement réutilisable. Il s’agit des noms d'opérations et des variables. Notez que notre code n’est pas explicitement une requête, car nous n’avons pas indiqué le mot-clé « query ». Nous allons cependant en avoir besoin pour les opérations suivantes et nous allons donc l’ajouter maintenant.

Nous pouvons donner le nom de notre choix à l’opération en saisissant un nom d’opération juste après le mot-clé « query ». Nous pourrions faire la même chose pour une mutation, en saisissant mutation puis un espace et enfin le nom choisi. La convention est d’écrire en PascalCase et de décrire le résultat obtenu.

Saisissons ProductTitleAndDescription. Relançons la requête et vous verrez que rien ne change. Nous pouvons librement ajouter un nom d’opération sans modifier la requête.

Définir une variable avec GraphQL

La suite concerne les variables. Voici à quoi ressemble la syntaxe des variables :

Ouvrons des parenthèses après le nom de l’opération et spécifions que nous allons fournir une variable id. Le symbole $ est utilisé pour indiquer qu’il s’agit d’une variable. Insérons un signe :, puis indiquons que cette variable est de type ID. Il est impératif de toujours spécifier le type des variables.

Nous allons légèrement modifier cette requête. Copions le contenu de l’identifiant dans le presse-papiers, et indiquons que l’identifiant fourni à ce champ de produit est la variable id.

Notez que nous n’avons pas indiqué de variable. Cliquons sur le bouton d’exécution et nous obtenons un message indiquant que nous aurions dû fournir une valeur de type ID pour cette variable id, mais que nous n’avons indiqué aucune valeur.

C’est à ce moment que nous devons utiliser le panneau « query variables » (variables de requête) dans les clients HTTP ou l’application graphique. La syntaxe pour indiquer la valeur des variables est la suivante :

Ouvrons des accolades et indiquons la valeur de l’identifiant. Notez que l’outil a compris que nous essayons de fournir une variable id de type ID, grâce à la façon dont nous avons configuré la requête auparavant.

Nous pouvons simplement copier-coller l’identifiant depuis le presse-papiers et exécuter cette requête. En arrière-plan, l’IDE remplace la variable id par la valeur que nous avons définie, sans qu’aucune interpolation de chaîne manuelle soit nécessaire.

Les fonctionnalités du langage GraphQL permettent de faire la substitution automatiquement. Ce n’est pas très clair ici, car nous travaillons dans un IDE, mais nous pouvons voir à quoi cela ressemble dans une application client très simple.

Nous allons donc passer à Visual Studio Code pour voir tous les avantages que cela offre à grande échelle.

Utiliser des noms et des variables dans une application

Dans Visual Studio Code, j’ai créé une application très simple à l’aide d’une bibliothèque client appelée graphql-request. C’est un moyen très facile de créer des requêtes GraphQL en utilisant Node.js. Les premières lignes surlignées ont simplement pour objectif de faire fonctionner l’application dans l’environnement Node.js plutôt que dans un environnement de navigateur.

Notez que j’utilise également dotenv afin d’éviter de vous dévoiler le mot de passe de mon application privée quand j’exécute cette requête pendant la démo. J’ai codé en dur l’URL que j’appelle. https://getting-starter-with-graphql.myshopify.com/admin/api/2020-20/graphql.json est l’adresse de ma boutique de test. J’instancie graphQLClient, puis j’indique les en-têtes requis, à savoir application/JSON, et le mot de passe de mon application privée, process.env.API_PASSWORD.

Lorsque vous travaillez avec GraphQL et des applications, les requêtes sont souvent définies de cette façon. Le client avec lequel vous travaillez a en général une fonction de littéral de gabarits, où vous passez une chaîne qui est votre opération, qu’il s’agisse d’une requête ou d’une mutation.

Vous voyez ici que j’utilise la syntaxe de variable. J’indique que je vais fournir un identifiant de type ID, que je fournirai ensuite à l’argument id.

Ensuite, ici en bas, je définis les variables que je vais passer. Tout comme dans le panneau « query variables » de GraphiQL, j’indique un objet de clé id puis la chaîne qui correspond à l’identifiant du produit. J’envoie cette requête conformément à la méthode définie dans le client GraphQL et je fournis les variables que j’ai définies en même temps que cette requête.

Je n’ai ainsi pas à faire moi-même l’interpolation des chaînes.

Enfin, j’enregistre le résultat dans la console. Exécutons ce script, et nous obtenons les données que nous attendions. C’est là que les variables deviennent très pratiques. Nous avons d’autres identifiants plus bas dans le code, pour un autre produit. Nous allons émettre cette requête exactement de la même façon, mais indiquer les autres variables (otherVariables) qui sont définies. Nous allons donc indiquer non pas le premier identifiant produit, mais le deuxième, et nous enregistrerons également cela dans la console. Exécutons cette requête.

Nous obtenons maintenant les deux résultats.

C’est le gros avantage des variables. Nous n’avons eu aucune interpolation de chaînes à faire, tout est déjà intégré dans GraphQL. Pour l’instant, cette requête n’a pas de nom d’opération. Commentons à nouveau les autres variables, pour ne plus exécuter qu’une seule requête. Disons que nous ayons fait une erreur de syntaxe, par exemple que nous ayons oublié une accolade. Enregistrons le script avec cette erreur et exécutons-le à nouveau : l’outil va me signaler que je n’ai pas fait les choses correctement.

Si nous avions essayé de parcourir la requête pour trouver l’erreur sans avoir nommé l’opération, cela aurait été très difficile.

Et pourtant c’est une application très simple qui effectue une seule requête. Imaginez ce que cela donnerait pour une application beaucoup plus grande. Vous voudriez quand même pouvoir déterminer quelle requête échoue, sans avoir à parcourir toute l’application pour trouver la requête avec ce type de structure. Les journaux devraient pouvoir déterminer cela automatiquement en fonction d’un nom d’opération.

Nommer les opérations GraphQL pour débugger à grande échelle

Nous pouvons arbitrairement introduire un nom d’opération. Disons ProductIdAndTitle, simplement car ce sont les informations que cette requête permet de récupérer. Sans corriger l’erreur de syntaxe, exécutons à nouveau la requête après avoir nettoyé le journal d’erreur.

Maintenant, quand le script échoue, les journaux indiquent au moins le nom de l’opération. C’est là toute l’utilité des noms d’opérations. Ils offrent le même avantage que les fonctions nommées par rapport aux fonctions anonymes.

Les fonctions anonymes n’ayant par définition pas de nom, il est très difficile de repérer exactement dans la trace de la pile d’où vient l’erreur. C’est pour cela qu’il est conseillé de nommer les fonctions : dans une trace de pile, cela permet de savoir quelle fonction échoue. C’est exactement la même chose ici: il n’est pas obligatoire de nommer les requêtes ou les mutations, mais c’est très utile pour débugger à grande échelle.

Publié par Maud Leuenberger. Maud est la rédactrice en chef du blog français de Shopify.

Texte original par Chuck Kosman. Traduction par Solenn Marchand.