Détails GraphQL: quoi, comment et pourquoi

GraphQL est maintenant, sans exagération, c'est le dernier coup d'oeil du mode informatique. Et si vous ne savez pas encore de quel type de technologie il s'agit, comment l'utiliser et pourquoi elle peut vous être utile, l'article que nous publions aujourd'hui est écrit pour vous. Nous allons ici passer en revue les bases de GraphQL en utilisant un exemple d'implémentation d'un schéma de données pour l'API d'une entreprise de pop-corn. Parlons en particulier des types de données, des requêtes et des mutations.

Qu'est-ce que GraphQL?

GraphQL est un langage de requête utilisé par les applications clientes pour travailler avec les données. GraphQL est associé à un concept tel que «schéma» - c'est ce qui vous permet d'organiser la création, la lecture, la mise à jour et la suppression de données dans votre application (c'est-à-dire que nous avons quatre fonctions de base utilisées lorsque nous travaillons avec des entrepôts de données, qui sont généralement désignés par l'acronyme CRUD - créer, lire, mettre à jour, supprimer).

Il a été dit plus haut que GraphQL est utilisé pour travailler avec des données dans «votre application», et non «dans votre base de données». Le fait est que GraphQL est un système indépendant des sources de données, c'est-à-dire qu'il importe peu où il est organisé pour organiser son travail.

Si vous regardez, sans rien savoir de GraphQL, sur le nom de cette technologie, il peut sembler que nous sommes confrontés à quelque chose de très compliqué et déroutant. Le nom de la technologie a le mot «graphique». Est-ce à dire que pour le maîtriser, il faut apprendre à travailler avec des bases de données graphiques? Et le fait que le nom contienne «QL» (qui peut signifier «langage de requête», c'est-à-dire «langage de requête»), cela signifie-t-il que ceux qui veulent utiliser GraphQL devront apprendre un tout nouveau langage de programmation?

Ces craintes ne sont pas entièrement justifiées. Afin de vous rassurer - c'est la cruelle vérité sur cette technologie: il s'agit simplement d'embellir des requêtes GET ou POST . Alors que GraphQL, en général, introduit de nouveaux concepts liés à l'organisation des données et à leur interaction, les mécanismes internes de cette technologie reposent sur les bonnes vieilles requêtes HTTP.

Repenser la technologie REST

La flexibilité est ce qui distingue la technologie GraphQL de la technologie REST bien connue. Lorsque vous utilisez REST, si tout est fait correctement, les noeuds finaux sont généralement créés en tenant compte des caractéristiques d'un certain type de données de ressource ou d'application.

Par exemple, lors de l'exécution d'une demande GET vers le point de terminaison /api/v1/flavors il est prévu qu'il envoie une réponse qui ressemble à ceci:

 [ {  "id": 1,   "name": "The Lazy Person's Movie Theater",   "description": "That elusive flavor that you begrudgingly carted yourself to the theater for, now in the comfort of your own home, you slob!" }, {   "id": 2,   "name": "What's Wrong With You Caramel",   "description": "You're a crazy person that likes sweet popcorn. Congratulations." }, {   "id": 3,   "name": "Gnarly Chili Lime",   "description": "The kind of popcorn you make when you need a good smack in the face."} ] 

Il n'y a rien de catastrophique dans cette réponse, mais réfléchissons à l'interface utilisateur, ou plutôt à la façon dont nous avons l'intention de consommer ces données.

Si nous voulons afficher une simple liste dans l'interface qui ne contient que les noms des types de pop-corn disponibles (et rien d'autre), cette liste peut ressembler à celle illustrée ci-dessous.


Liste des types de pop-corn

On peut voir que nous sommes ici dans une situation difficile. Nous pouvons bien décider de ne pas utiliser le champ de description , mais allons-nous nous asseoir et prétendre que nous n'avons pas envoyé ce champ au client? Que pouvons-nous faire d'autre? Et quand, au bout de quelques mois, ils nous demanderont pourquoi l'application est si lente pour les utilisateurs, il suffit de laisser le gars et de ne plus rencontrer la direction de l'entreprise pour laquelle nous avons fait cette application.

En fait, le fait que le serveur envoie des données inutiles en réponse à une demande client n'est pas entièrement de notre faute. REST est un mécanisme d'acquisition de données qui peut être comparé à un restaurant dans lequel le serveur demande au visiteur: "Qu'est-ce que tu veux?" .

Si nous mettons de côté les blagues, dans les applications réelles, cela peut conduire à des situations problématiques. Par exemple, nous pouvons afficher diverses informations supplémentaires sur chaque type de pop-corn, telles que des informations sur les prix, des informations sur le fabricant ou des informations nutritionnelles («Popcorn végétalien!»). Dans le même temps, les points de terminaison REST rigides rendent très difficile l'obtention de données spécifiques sur des types spécifiques de pop-corn, ce qui conduit à une charge déraisonnablement élevée sur les systèmes et au fait que les solutions qui en résultent sont loin de celles dont les développeurs pourraient être fiers.

Comment la technologie GraphQL améliore l'utilisation de la technologie REST

Une analyse superficielle de la situation décrite ci-dessus peut sembler que nous ne sommes qu'un problème mineur. "Quel est le problème avec l'envoi au client de données inutiles?" Afin de comprendre dans quelle mesure les «données inutiles» peuvent être un gros problème, n'oubliez pas que GraphQL a été développé par Facebook. Cette entreprise doit répondre à des millions de demandes par seconde.

Qu'est-ce que cela signifie? Et le fait qu'avec de tels volumes, chaque petite chose compte.

GraphQL, si nous continuons l'analogie avec un restaurant, au lieu de «porter» au visiteur «ce qui est», apporte exactement ce que le visiteur commande.

Nous pouvons obtenir une réponse de GraphQL qui se concentre sur le contexte dans lequel les données sont utilisées. Dans ce cas, nous n'avons pas besoin d'ajouter des points d'accès «uniques» au système, d'effectuer de nombreuses demandes ou d'écrire des structures conditionnelles à plusieurs étages.

Comment fonctionne GraphQL?

Comme nous l'avons déjà dit, GraphQL s'appuie sur de simples requêtes GET ou POST pour transmettre des données au client et les recevoir de lui. Si nous considérons cette idée plus en détail, il s'avère qu'il existe deux types de requêtes dans GraphQL. Le premier type comprend les demandes de lecture de données, qui dans la terminologie GraphQL sont simplement appelées requêtes et font référence à la lettre R (lecture, lecture) de l'acronyme CRUD. Les requêtes du deuxième type sont des demandes de modification de données, appelées mutations dans GraphQL. Ils concernent les boîtes d'essieux C, U et D de l'acronyme CRUD, c'est-à-dire qu'ils les utilisent pour créer, créer, mettre à jour et supprimer des enregistrements.

Toutes ces requêtes et mutations sont envoyées à l'URL du serveur GraphQL, qui peut par exemple ressembler à https://myapp.com/graphql , sous forme de requêtes GET ou POST . Nous en parlerons plus loin ci-dessous.

Requêtes GraphQL

Les requêtes GraphQL sont des entités représentant une demande au serveur de recevoir certaines données. Par exemple, nous avons une certaine interface utilisateur que nous voulons remplir de données. Pour ces données, nous nous tournons vers le serveur, exécutant la demande. Lorsque vous utilisez des API REST traditionnelles, notre demande prend la forme d'une demande GET. Lorsque vous travaillez avec GraphQL, une nouvelle syntaxe de requête est utilisée:

 { flavors {   name } } 

Est-ce JSON? Ou un objet JavaScript? Ni l'un ni l'autre. Comme nous l'avons déjà dit, au nom de la technologie GraphQL, les deux dernières lettres, QL, signifient «langage de requête», c'est-à-dire le langage de requête. C'est, littéralement, un nouveau langage pour écrire des demandes de données. Tout cela ressemble à une description de quelque chose de plutôt compliqué, mais en fait il n'y a rien de compliqué ici. Analysons la requête ci-dessus:

 { //    ,   . } 

Toutes les demandes commencent par une «demande racine» et ce que vous devez obtenir lors de l'exécution de la demande s'appelle un champ. Afin de vous éviter la confusion, il est préférable d'appeler ces entités «champs de requête dans le schéma». Si un tel nom vous semble incompréhensible - attendez un peu - ci-dessous, nous parlerons davantage du schéma. Ici, dans la requête racine, nous demandons le champ des flavors .

 { flavors {   //  ,        flavor. } } 

Lors de la demande d'un certain champ, nous devons également indiquer les champs imbriqués qui doivent être reçus pour chaque objet qui vient en réponse à la demande (même s'il est prévu qu'un seul objet viendra en réponse à la demande).

 { flavors {   name } } 

Quel sera le résultat? Après avoir envoyé une telle demande au serveur GraphQL, nous obtiendrons une réponse nette et bien formée, comme la suivante:

 { "data": {   "flavors": [     { "name": "The Lazy Person's Movie Theater" },     { "name": "What's Wrong With You Caramel" },     { "name": "Gnarly Chili Lime" }   ] } } 

Veuillez noter qu'il n'y a rien de superflu. Afin de le rendre plus clair, voici une autre requête qui est exécutée pour obtenir des données sur une autre page de l'application:

 { flavors {   id   name   description } } 

En réponse à cette demande, nous obtenons ce qui suit:

 { "data": {   "flavors": [     { "id": 1, "name": "The Lazy Person's Movie Theater", description: "That elusive flavor that you begrudgingly carted yourself to the theater for, now in the comfort of your own home, you slob!" },     { "id": 2, "name": "What's Wrong With You Caramel", description: "You're a crazy person that likes sweet popcorn. Congratulations." },     { "id": 3, "name": "Gnarly Chili Lime", description: "A friend told me this would taste good. It didn't. It burned my kernels. I haven't had the heart to tell him." }   ] } } 

Comme vous pouvez le voir, GraphQL est une technologie très puissante. Nous nous tournons vers le même point de terminaison, et les réponses aux demandes correspondent exactement à ce qui est nécessaire pour remplir la page à partir de laquelle ces demandes sont exécutées.

Si nous devons obtenir un seul objet de flavor , nous pouvons profiter du fait que GraphQL peut fonctionner avec des arguments:

 { flavors(id: "1") {   id   name   description } } 

Ici, nous définissons de manière rigide l'identifiant spécifique ( id ) de l'objet dans le code, les informations dont nous avons besoin, mais dans de tels cas, nous pouvons utiliser des identifiants dynamiques:

 query getFlavor($id: ID) { flavors(id: $id) {   id   name   description } } 

Ici, dans la première ligne, nous donnons un nom à la demande (le nom est choisi arbitrairement, getFlavor peut être remplacé par quelque chose comme pizza , et la demande restera opérationnelle) et déclarons les variables que la demande attend. Dans ce cas, on suppose que l'identifiant ( id ) de l' ID type scalaire sera transmis à la requête (nous parlerons des types ci-dessous).

Peu importe si un id statique ou dynamique id utilisé lors de l'exécution d'une demande, voici à quoi ressemblera la réponse à une demande similaire:

 { "data": {   "flavors": [     { "id": 1, "name": "The Lazy Person's Movie Theater", description: "That elusive flavor that you begrudgingly carted yourself to the theater for, now in the comfort of your own home, you slob!" }   ] } } 

Comme vous pouvez le voir, tout est arrangé de manière très pratique. Vous commencez probablement à penser à utiliser GraphQL dans votre propre projet. Et, bien que ce dont nous avons déjà parlé soit magnifique, la beauté de GraphQL se manifeste vraiment là où il fonctionne avec des champs imbriqués. Supposons que dans notre schéma, il existe un autre domaine appelé nutrition qui contient des informations sur la valeur nutritionnelle de différents types de pop-corn:

 { flavors {   id   name   nutrition {     calories     fat     sodium   } } } 

Il peut sembler que dans notre entrepôt de données, chaque objet de flavor contiendra un objet nutrition imbriqué. Mais ce n'est pas tout à fait vrai. À l'aide de GraphQL, vous pouvez combiner des appels à des sources de données indépendantes mais liées dans une seule requête, ce qui vous permet de recevoir des réponses qui offrent la commodité de travailler avec des données incorporées sans avoir besoin de dénormaliser la base de données:

 { "data": {   "flavors": [     {       "id": 1,       "name": "The Lazy Person's Movie Theater",       "nutrition": {         "calories": 500,         "fat": 12,         "sodium": 1000       }     },     ...   ] } } 

Cela peut augmenter considérablement la productivité du programmeur et la vitesse du système.

Jusqu'à présent, nous avons parlé des demandes de lecture. Qu'en est-il des demandes de mise à jour des données? Les utiliser nous donne-t-il la même commodité?

Mutations GraphQL

Tandis que les requêtes GraphQL chargent des données, les mutations sont responsables d'apporter des modifications aux données. Les mutations peuvent être utilisées sous la forme du mécanisme de base RPC (Remote Procedure Call) pour résoudre diverses tâches, telles que l'envoi de données utilisateur à une API tierce.

Lors de la description des mutations, une syntaxe similaire à celle utilisée lors de la génération des requêtes est utilisée:

 mutation updateFlavor($id: ID!, $name: String, $description: String) { updateFlavor(id: $id, name: $name, description: $description) {   id   name   description } } 

Ici, nous déclarons la mutation updateFlavor , en spécifiant certaines variables - id , name et description . En agissant selon le même schéma que celui utilisé pour décrire les requêtes, nous «établissons» des champs de variables (mutation racine) à l'aide du mot-clé mutation , suivis d'un nom décrivant la mutation et d'un ensemble de variables nécessaires pour former la demande de changement de données correspondante.

Ces variables incluent ce que nous essayons de changer ou quelle mutation nous voulons provoquer. Veuillez également noter qu'après la mutation, nous pouvons demander le retour de certains champs.

Dans ce cas, nous devons obtenir, après avoir modifié l'enregistrement, les champs id , name et description . Cela peut être utile lors du développement de quelque chose comme des interfaces optimistes, éliminant ainsi la nécessité de répondre à une demande de réception de données modifiées après les avoir modifiées.

Concevoir un schéma et le connecter à un serveur GraphQL

Jusqu'à présent, nous avons parlé du fonctionnement de GraphQL sur le client et de la façon dont ils exécutent les requêtes. Voyons maintenant comment répondre à ces demandes.

Server Serveur GraphQL

Pour exécuter une requête GraphQL, vous avez besoin d'un serveur GraphQL auquel vous pouvez envoyer une telle requête. Un serveur GraphQL est un serveur HTTP standard (si vous écrivez en JavaScript, il peut s'agir d'un serveur créé en utilisant Express ou Hapi), auquel un diagramme GraphQL est attaché.

 import express from 'express' import graphqlHTTP from 'express-graphql' import schema from './schema' const app = express() app.use('/graphql', graphqlHTTP({ schema: schema, graphiql: true })) app.listen(4000) 

Par «rejoindre» un schéma, nous entendons un mécanisme qui transmet les demandes reçues du client via le schéma et y renvoie des réponses. C'est comme un filtre à air à travers lequel l'air pénètre dans la pièce.

Le processus de "filtrage" est associé aux requêtes ou mutations envoyées par le client au serveur. Les requêtes et les mutations sont résolues à l'aide de fonctions liées aux champs définis dans la requête racine ou dans la mutation racine du schéma.

Ce qui précède est un exemple d'infrastructure de serveur HTTP créé à l'aide de la bibliothèque JavaScript Express. En utilisant la fonction express-graphql de Facebook, nous «attachons» le schéma (on suppose qu'il est décrit dans un fichier séparé) et exécutons le serveur sur le port 4000. Autrement dit, les clients, parlant de l'utilisation locale de ce serveur, pourront envoyer des requêtes via adresse http://localhost:4000/graphql .

▍ Types de données et résolveurs

Afin d'assurer le fonctionnement du serveur GraphQL, vous devez préparer le schéma et le joindre à celui-ci.

Rappelons que nous avons parlé de déclarer des champs dans une requête racine ou dans une mutation racine ci-dessus.

 import gql from 'graphql-tag' import mongodb from '/path/to/mongodb' //  -  . ,  `mongodb`     MongoDB. const schema = { typeDefs: gql`   type Nutrition {     flavorId: ID     calories: Int     fat: Int     sodium: Int   }   type Flavor {     id: ID     name: String     description: String     nutrition: Nutrition   }   type Query {     flavors(id: ID): [Flavor]   }   type Mutation {     updateFlavor(id: ID!, name: String, description: String): Flavor   } `, resolvers: {   Query: {     flavors: (parent, args) => {       // ,  args  ,  { id: '1' }       return mongodb.collection('flavors').find(args).toArray()     },   },   Mutation: {     updateFlavor: (parent, args) => {       // ,  args    { id: '1', name: 'Movie Theater Clone', description: 'Bring the movie theater taste home!' }       //  .       mongodb.collection('flavors').update(args)       //  flavor  .       return mongodb.collection('flavors').findOne(args.id)     },   },   Flavor: {     nutrition: (parent) => {       return mongodb.collection('nutrition').findOne({         flavorId: parent.id,       })     }   }, }, } export default schema 

La définition des champs dans un schéma GraphQL se compose de deux parties - à partir des déclarations de type ( typeDefs ) et des resolver . L' typeDefs contient des déclarations de type pour les données utilisées dans l'application. Par exemple, plus tôt, nous avons parlé d'une demande pour obtenir une liste d'objets de flavor du serveur. Afin de faire une demande similaire à notre serveur, vous devez effectuer les trois étapes suivantes:

1. Indiquez au schéma à quoi ressemblent les données de l'objet de flavor (dans l'exemple ci-dessus, elles ressemblent à une annonce de type Flavor ).
2. Déclarez le champ dans le champ racine de type Query (il s'agit de la propriété flavors de la valeur de type Query ).
3. Déclarez une fonction de reconnaissance d'objet resolvers.Query écrite conformément aux champs déclarés dans le champ racine de type Query .

typeDefs maintenant attention à typeDefs . Ici, nous donnons les informations de schéma sur la forme de nos données. En d'autres termes, nous informons GraphQL des différentes propriétés qui peuvent être contenues dans des entités du type correspondant.

 type Flavor { id: ID name: String description: String nutrition: Nutrition } 

Une déclaration de type Flavor indique qu'un objet type Flavor peut contenir un champ id de type ID , un champ de name de type String , un champ de description de type String et un champ de nutrition de type Nutrition .

Dans le cas de la nutrition nous utilisons ici le nom d'un type différent déclaré dans typeDefs . Ici, le type Nutrition construction type Nutrition décrit la forme de données nutritionnelles du pop-corn.

Faites attention au fait qu'ici, comme au tout début de ce document, nous parlons d'une «application» et non d'une «base de données». Dans l'exemple ci-dessus, on suppose que nous avons une base de données, mais les données de l'application peuvent provenir de n'importe quelle source. Il peut même s'agir d'une API tierce ou d'un fichier statique.

Tout comme nous l'avons fait dans la déclaration de type Flavor , nous indiquons ici les noms des champs qui seront contenus dans les objets de nutrition , en utilisant, comme types de données de ces champs (propriétés), ce qui dans GraphQL est appelé types de données scalaires. Au moment d'écrire ces lignes, GraphQL supportait 5 types de données scalaires intégrés :

• Int : entier 32 bits signé.
• Float : un nombre à virgule flottante double précision avec un signe.
• String : une séquence de caractères encodés en UTF-8.
• Boolean : Boolean true or false .
• ID : identifiant unique souvent utilisé pour charger à plusieurs reprises des objets ou comme clé dans le cache. Les valeurs de type ID sérialisées de la même manière que les chaînes, cependant, une indication qu'un type d' ID a une valeur est soulignée par le fait que cette valeur n'est pas destinée à être affichée aux gens, mais à être utilisée dans des programmes.

En plus de ces types scalaires, nous pouvons également attribuer des propriétés aux types que nous définissons nous-mêmes. C'est exactement ce que nous avons fait en attribuant la propriété nutrition décrite dans le type Flavor , type Nutrition .

 type Query { flavors(id: ID): [Flavor] } 

Dans la construction de type Query , qui décrit le type racine de Query (la «requête racine» dont nous avons parlé plus tôt), nous déclarons le nom du champ qui peut être demandé. En déclarant ce champ, nous spécifions, en plus du type de données que nous attendons, les arguments qui peuvent venir dans la demande.

Dans cet exemple, nous attendons une réception possible de l'argument id d'un ID type scalaire. En réponse à une telle demande, un tableau d'objets est attendu dont le périphérique ressemble à un périphérique de type Flavor .

▍Connexion du module de reconnaissance des requêtes

, type Query field , , -.

— , GraphQL, , «». resolvers , Query , , flavors , . flavors , type Query .

 typeDefs: gql`…`, resolvers: { Query: {   flavors: (parent, args) => {     // ,  args    { id: '1' }     return mongodb.collection('flavors').find(args).toArray()   }, }, … }, 

- . parent — , , args , . context , . «» ( — , ).

, , . GraphQL « » . , , .

GraphQL , , . JSON-, JSON-, ( GraphQL ).

- flavors MongoDB, args ( ) .find() , , .

▍

-, GraphQL, , , , nutrition . , , Nutrition , , , , flavor . , / .

GraphQL , type Flavor nutrition type Nutrition , . , , flavor .

 typeDefs: gql`   type Nutrition {     flavorId: ID     calories: Int     fat: Int     sodium: Int   }   type Flavor {     […]     nutrition: Nutrition   }   type Query {…}   type Mutation {…} `, resolvers: {   Query: {     flavors: (parent, args) => {…},   },   Mutation: {…},   Flavor: {     nutrition: (parent) => {       return mongodb.collection('nutrition').findOne({         flavorId: parent.id,       })     }   }, }, 

resolvers , , Query , Mutation Flavor . , typeDefs .

Flavors , , nutrition -. , Flavor . , : « , nutrition , type Flavor ».

MongoDB, , parent , -. , parent , , , flavors . , flavor , :

 { flavors {   id   name   nutrition {     calories   } } } 

flavor , flavors , nutrition , parent . , , , MongoDB, parent.id , id flavor , .

parent.id , nutrition flavorId , flavor .

▍

, , . , . type Mutation , , updateFlavor , , .

 type Mutation { updateFlavor(id: ID!, name: String, description: String): Flavor } 

: « , updateFlavor id ID ( , ! , GraphQL , ), name String description String ». , , Flavor ( — , id , name , description , , , nutrition ).

 { typeDefs: gql`…`, resolvers: {   Mutation: {     updateFlavor: (parent, args) => {       // ,  args    { id: '1', name: 'Movie Theater Clone', description: 'Bring the movie theater taste home!' }       //  .       mongodb.collection('flavors').update(         { id: args.id },         {           $set: {             ...args,           },         },       )       //  flavor  .       return mongodb.collection('flavors').findOne(args.id)     },   }, }, } 

- updateFlavor , : , , — , flavor .

, , flavor . ?

, , . , flavor , .

args ? , . , , , 100% , . , , , , , .

GraphQL?

, , , , , GraphQL-API.

, GraphQL , . , . , . , , , GraphQL REST . , , , GraphQL.

▍ ,

, HTTP-, , , , — . GraphQL , , , , ( ).

, , ( — ), GraphQL .

▍ , ,

, , « ». , , , . . GraphQL .

▍ ,

REST API, : , . , -, iOS Android, API . , , , , « » .

, , , HTTP, API (, , ).

▍ GraphQL — ? REST API GraphQL?

, . . , , GraphQL . GraphQL, . , , , . , , .

, GraphQL , , , . GraphQL , Apollo Relay, .

GraphQL — , , . graphql ( express-graphql , ) — . , GraphQL - . , -, , , , .

Résumé

, GraphQL , . GraphQL , , , . , , , , GraphQL.

, : GraphQL . GraphQL . , GraphQL, , , , , , , .

— , GraphQL — , , . GraphQL , . , GraphQL — , , , . . , , , , , , GraphQL.

Chers lecteurs! GraphQL — , .