Comment utiliser les fragments GraphQL

Cet article accompagne une vidéo de la chaîne YouTube ShopifyDevs. Chuck Kosman, ingénieur de lancement chez Shopify Plus, y présente certaines des principales fonctionnalités de GraphQL qui permettent de créer plus facilement des applications à grande échelle. Cet article est le troisième d'une série de 5 tutoriels de formation conçus pour améliorer votre compréhension des avantages de GraphQL.

Dans ce tutoriel, Chuck présente les fragments GraphQL, qui sont une manière de réutiliser des champs. Il explique comment les définir et les utiliser.

Créer plusieurs champs avec GraphQL

Dans la troisième partie de ce tutoriel sur les fonctionnalités du langage GraphQL, nous allons nous pencher sur les fragments, qui sont une manière de réutiliser des champs. Dans la partie précédente, Comment utiliser les alias GraphQL, nous avons vu ce que les alias permettaient de faire. Nous allons reprendre là où nous nous étions arrêtés. Vous pouvez également revenir au premier article, Débuter avec GraphQL, pour mieux connaître le langage lui-même et savoir comment débuter.

Si vous n’avez pas suivi le tutoriel sur les alias, notez que nous avons ici une requête sans nom d’opération, où nous utilisons des alias pour différencier deux champs product avec des identifiants différents.

Vous voyez immédiatement que ce code est redondant. Nous voulons récupérer les mêmes informations pour ces deux produits, product1 et product2, mais nous avons dû écrire deux fois title et description.

Cela serait pratique de pouvoir réutiliser ces champs dans une définition unique, afin de pouvoir faire référence à cette définition et de ne pas avoir à ressaisir title et description, en particulier si nous travaillons à grande échelle et que nous devons récupérer ces champs plusieurs fois.

Nous ne voulons pas avoir à mettre à jour les champs à différents endroits, nous voulons les définir une seule fois.

C’est là que les fragments viennent nous aider, car c'est exactement ce qu'ils permettent de faire.

Syntaxe : écrire des fragments avec GraphQL

Voici à quoi ressemble la syntaxe des fragments :

Juste au-dessous de la requête, nous allons utiliser le mot-clé fragment. Nommons notre fragment TitleAndDescription. Nous devons également spécifier le type auquel ce fragment peut s’appliquer. La syntaxe ici est d'utiliser le mot-clé on, puis de spécifier le type. Nous savons que lorsque nous faisons une requête pour les champs de produits, le type retourné est product.

Si nous ne le savons pas, nous pouvons dans GraphiQL passer notre souris ici, ce qui nous indique que le type retourné est Product, avec un P majuscule. Saisissons donc Product (la saisie semi-automatique nous le suggère d'ailleurs).

Ouvrons des accolades et indiquons les champs, comme nous le faisons pour récupérer des champs pour un type Product. Nous écrivons donc title et description.

En haut, dans notre requête, nous allons indiquer que nous voulons utiliser ce fragment pour récupérer des champs en entrant des points de suspension (...), puis nous allons indiquer le nom du fragment lui-même. Nous saisissons donc ...TitleAndDescription, aux deux endroits.

Nous nous attendons à récupérer les mêmes informations qu’auparavant lorsque nous allons exécuter cette requête, c’est-à-dire les données title et description pour l’alias product1 comme pour l’alias product2. C’est bien le cas, la requête fonctionne.

Les fragments sont vraiment très utiles à grande échelle si nous voulons ajouter un autre champ. Regardons dans la documentation quel champ nous pouvons ajouter pour le type Product.

Disons que nous voulons l’image vedette, featuredImage, et son identifiant, id. Nous n’avons besoin de les définir qu'une seule fois, nous n’avons pas à les répéter à chaque fois.

Exécutons cette requête et récupérons les identifiants que nous voulons. Dans cette syntaxe, nous avons défini le fragment avec le mot-clé fragment, puis remplacé les champs par le fragment dans la requête.

Fragments en ligne : définition et utilité

Nous pouvons également utiliser des fragments en ligne. Ils peuvent être très pratiques si le schéma avec lequel vous travaillez implémente des interfaces ou des unions. Dans un schéma, une union signifie qu’un champ pourrait renvoyer plusieurs types différents. Disons que dans le schéma Shopify, nous nous attendons à récupérer à un endroit non seulement un type Product, mais aussi un type Collection ou un type Customer. Les interfaces sont assez similaires, et elles sont utilisées dans les schémas GraphQL lorsque plusieurs types différents ont les mêmes champs.

Nous pouvons dire que dans le schéma Shopify, il existe un « type abstrait » comme l’appelle GraphQL, appelé node, et de nombreux autres types implémentant l'interface node.

Regardons pour mieux comprendre la documentation Shopify du type node dans l’API administrateur. node y est défini comme une interface. Le seul champ que cette interface utilise est id.

Mais plusieurs types différents implémentent node, plusieurs types d’entités sur Shopify doivent avoir un champ id associé. Cela inclut notamment les commandes, les produits et les clients, et bien d’autres choses encore.

Passons à une autre section de la documentation Shopify pour voir où les fragments en ligne peuvent se révéler particulièrement utiles lorsque l’on travaille avec des interfaces.

Examinons la documentation de la mutation appelée tagsAdd.

Exemple : utiliser tagsAdd

Notons plusieurs choses sur cet exemple interactif d’utilisation de tagsAdd.

tagsAdd est une mutation qui vous permet d’ajouter des balises à un objet les acceptant.

Comment ?

Elle vous permet de spécifier l’identifiant de l’entité à laquelle vous souhaitez ajouter ces balises, et elle renvoie ensuite un nœud node. Le seul champ dans node est l’identifiant id. Que se passe-t-il si vous savez que vous ajoutez des balises à un produit et que vous voulez récupérer les détails de ce produit autres que son identifiant lorsque vous avez terminé cette opération ?

Pour simplifier notre démonstration, nous allons copier-coller cet exemple. Il nous donne tout ce dont nous avons besoin. Copions donc ce contenu et collons-le dans notre boutique après avoir complètement supprimé la requête existante.

Copions aussi les variables en dessous.

Cet identifiant ne va pas fonctionner ici, nous allons le remplacer par l’identifiant d’un produit existant sur notre boutique de test. Disons que nous voulons ajouter la balise on-sale à ce produit. Nous pouvons ajouter cette balise à des fins de merchandising ou de reporting pour le reste de nos applications.

Nous n’allons pas encore exécuter cette requête.

Précisons d’abord certaines choses. Nous récupérons donc ce nœud, mais nous voulons aussi avoir la liste complète des balises (tags) associées à ce nœud ainsi que le titre (title) du produit. Nous constatons déjà que quelque chose ne va pas, car GraphQL ne nous suggère pas automatiquement « tags » ou « title » lorsque nous commençons notre saisie. Mais disons que nous avons tout de même écrit cela dans une application.

Un message d’erreur nous indique alors que le champ « title » n’existe pas dans le type Node. Nous savons que nous avons balisé un produit. Nous savons que l’identifiant que nous avons fourni est celui d'un produit. Et nous savons que les produits ont un champ title, et qu'ils ont une propriété appelée tags que nous pourrions voir si nous exportions le schéma.

Que se passe-t-il ?

Le type Product implémente node.

Clarifier la terminologie : définir les fragments en ligne

Nous devons préciser que, si un type Product est renvoyé, nous voulons obtenir les informations sur ces champs et produits spécifiques. Nous allons donc utiliser un fragment en ligne dans cette syntaxe pour voir la différence.

Comme pour un fragment classique, nous commençons par ... Nous indiquons ainsi ...on Product, nous ouvrons des accolades, puis nous déplaçons les champs title et tags dans ce fragment en ligne.

C’est presque comme un fragment anonyme que nous avons défini directement à l’intérieur des champs.

Maintenant, quand nous envoyons cette mutation pour tagsAdd, nous récupérons toutes les données que nous attendions.

La réponse indique que dans ce node, il y a un id et que cet id appartient à l’interface node. Ensuite, nous récupérons les données title et tags qui n’appartiennent pas à l’interface node car nous avons utilisé un fragment en ligne.

Pour récapituler, notre code indique que si le node renvoyé est un Product, alors les champs title et tags doivent aussi être récupérés.

Dans ce cas précis, la mutation tagsAdd peut opérer sur n’importe quel nœud. Donc, si nous ajoutons des balises à Customer et si nous ne savons pas avant d'utiliser cette mutation dans notre application si nous allons récupérer un type Product ou Customer, et/ou si nous voulons différents champs en fonction du type renvoyé, nous pourrons définir un autre fragment en ligne ...on Customer pour récupérer par exemple les données email ou addresses.

Pour résumer, cette syntaxe appelée fragment en ligne est très utile lorsque le schéma dans lequel vous travaillez utilise des unions ou des interfaces.

Merci d’avoir suivi la troisième partie de ce tutoriel sur les fonctionnalités du langage GraphQL. Dans la prochaine partie, nous verrons ensemble comment utiliser la pagination dans GraphQL.

---

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.