Utilisation de données lors de la création d'une API basée sur GraphQL

Préambule

Tout d'abord, cet article est conçu pour les lecteurs qui connaissent déjà GraphQL et plus sur les subtilités et les nuances de son utilisation. J'espère néanmoins qu'il sera utile aux débutants.

GraphQL est un excellent outil. Je pense que beaucoup de gens connaissent et comprennent déjà ses avantages. Cependant, il y a quelques nuances à prendre en compte lors de la création de vos API basées sur GraphQL.

Par exemple, GraphQL vous permet de retourner au consommateur (utilisateur ou programme) en demandant les données uniquement la partie qui l'intéresse. Néanmoins, lors de la construction d'un serveur, il est assez facile de se tromper, ce qui conduit au fait qu'à l'intérieur du serveur (qui peut être, entre autres, distribué), les données s'exécuteront en bundles complets. Cela est principalement dû au fait que GraphQL lui-même ne fournit pas d'outils pratiques pour analyser une requête entrante et que les interfaces qui y sont posées ne sont pas bien documentées.

Source du problème

Regardons un exemple typique d'une implémentation non optimale (ouvrez l'image dans une fenêtre séparée si elle est mal lue):

Supposons que notre consommateur soit une certaine application ou composante du "répertoire téléphonique" qui ne demande à notre API que l'identifiant, le nom et le numéro de téléphone des utilisateurs stockés par nous. Dans le même temps, notre API est beaucoup plus étendue, elle permettra d'accéder à d'autres données, telles que l'adresse physique de la résidence et l'adresse e-mail des utilisateurs.

Au moment de l'échange de données entre le consommateur et l'API, GraphQL fait parfaitement tout le travail dont nous avons besoin - seules les données demandées seront envoyées en réponse à la demande. Le problème dans ce cas est au point d'échantillonnage des données de la base de données - c'est-à-dire dans l'implémentation interne de notre serveur, et cela consiste dans le fait que pour chaque requête entrante nous sélectionnons toutes les données utilisateur de la base de données, malgré le fait que nous n'en ayons pas besoin. Cela génère une charge excessive sur la base de données et conduit à la circulation d'un trafic excessif au sein du système. Avec un nombre important de requêtes, vous pouvez obtenir une optimisation significative en modifiant l'approche d'échantillonnage des données et en sélectionnant uniquement les champs qui ont été demandés. En même temps, peu importe quelle est notre source de données - une base de données relationnelle, la technologie NoSQL ou un autre service (interne ou externe). Tout comportement non optimal peut être affecté par n'importe quelle implémentation. MySQL dans ce cas est sélectionné simplement à titre d'exemple.

Solution

Il est possible d'optimiser ce comportement de serveur si nous analysons les arguments qui viennent à la fonction resolve() :

 async resolve(source, args, context, info) { // ... } 

C'est le dernier argument, info , qui nous intéresse particulièrement dans ce cas. Nous nous tournons vers la documentation et analysons en détail en quoi consistent la fonction resolve() et l'argument qui nous intéresse:

 type GraphQLFieldResolveFn = ( source?: any, args?: {[argName: string]: any}, context?: any, info?: GraphQLResolveInfo ) => any type GraphQLResolveInfo = { fieldName: string, fieldNodes: Array<Field>, returnType: GraphQLOutputType, parentType: GraphQLCompositeType, schema: GraphQLSchema, fragments: { [fragmentName: string]: FragmentDefinition }, rootValue: any, operation: OperationDefinition, variableValues: { [variableName: string]: any }, } 

Ainsi, les trois premiers arguments transmis au résolveur sont la source - les données transmises par le nœud parent dans l'arborescence GraphQL du schéma, args - les arguments de requête (qui proviennent de la requête) et le context - l'objet de contexte d'exécution défini par le développeur, souvent appelé pour transmettre des données globales dans les «résolveurs». Et enfin, le quatrième argument est la méta-information sur la demande.

Que pouvons-nous extraire de GraphQLResolveInfo pour résoudre notre problème?

Ses parties les plus intéressantes sont:

• fieldName est le nom de champ actuel de leur schéma GraphQL. C'est-à-dire il correspond au nom de champ spécifié dans le schéma pour ce résolveur. Si nous interceptons l'objet info sur le champ users , comme dans notre exemple ci-dessus, alors ce sont les "utilisateurs" qui seront contenus comme la valeur de fieldName
• fieldNodes - collection (tableau) de nœuds qui ont été DEMANDÉS dans la requête. Exactement ce qui est nécessaire!
• fragments - une collection de fragments de la demande (dans le cas où la demande a été fragmentée). Informations importantes également pour récupérer les champs de données finaux.

Donc, comme solution, nous devons analyser l'outil d' info et sélectionner la liste des champs qui nous sont venus de la requête, puis les transmettre à la requête SQL. Malheureusement, le package GraphQL de Facebook «prêt à l'emploi» ne nous donne rien pour simplifier cette tâche. Dans l'ensemble, comme la pratique l'a montré, cette tâche n'est pas si simple, étant donné que les demandes peuvent être fragmentées. Et d'ailleurs, une telle analyse a une solution universelle, qui est ensuite simplement copiée de projet en projet.

J'ai donc décidé de l'écrire en tant que bibliothèque open source sous licence ISC . Avec son aide, la solution pour analyser les champs de requête entrants est résolue tout simplement, par exemple, dans notre cas comme ceci:

 const { fieldsList } = require('graphql-fields-list'); // ... async resolve(source, args, context, info) { const requestedFields = fieldsList(info); return await database.query(`SELECT ${requestedFields.join(',')} FROM users`) } 

fieldsList(info) dans ce cas fait tout le travail pour nous et retourne un tableau "plat" de champs enfants pour ce résolveur, c'est-à-dire notre requête SQL finale ressemblera à ceci:

 SELECT id, name, phone FROM users; 

Si nous modifions la demande entrante en:

 query UserListQuery { users { id name phone email } } 

alors la requête SQL se transformera en:

 SELECT id, name, phone, email FROM users; 

Cependant, il n'est pas toujours possible de faire avec un défi aussi simple. Souvent, les applications réelles ont une structure beaucoup plus complexe. Dans certaines implémentations, nous pouvons avoir besoin de décrire le résolveur au niveau supérieur par rapport aux données dans le schéma GraphQL final. Par exemple, si nous décidons d'utiliser la bibliothèque Relay , nous aimerions utiliser un mécanisme prêt à l'emploi pour diviser les collections d'objets de données en pages, ce qui conduit au fait que notre schéma GraphQL sera construit selon certaines règles. Par exemple, nous retravaillons notre schéma de cette façon (TypeScript):

 import { GraphQLObjectType, GraphQLSchema, GraphQLString } from 'graphql'; import { connectionDefinitions, connectionArgs, nodeDefinitions, fromGlobalId, globalIdField, connectionFromArray, GraphQLResolveInfo, } from 'graphql-relay'; import { fieldsList } from 'graphql-fields-list'; export const { nodeInterface, nodeField } = nodeDefinitions(async (globalId: string) => { const { type, id } = fromGlobalId(globalId); let node: any = null; if (type === 'User') { node = await database.select(`SELECT id FROM user WHERE id="${id}"`); } return node; }); const User = new GraphQLObjectType({ name: 'User', interfaces: [nodeInterface], fields: { id: globalIdField('User', (user: any) => user.id), name: { type: GraphQLString }, email: { type: GraphQLString }, phone: { type: GraphQLString }, address: { type: GraphQLString }, } }); export const { connectionType: userConnection } = connectionDefinitions({ nodeType: User }); const Query = new GraphQLObjectType({ name: 'Query', fields: { node: nodeField, users: { type: userConnection, args: { ...connectionArgs }, async resolve( source: any, args: {[argName: string]: any}, context: any, info: GraphQLResolveInfo, ) { // TODO: implement }, }, }); export const schema = new GraphQLSchema({ query: Query }); 

Dans ce cas, connectionDefinition from Relay ajoutera des edges , des node , des informations de page et des nœuds de cursor au schéma, c'est-à-dire nous devrons maintenant reconstruire nos requêtes différemment (nous ne nous attarderons pas sur la pagination maintenant):

 query UserListQuery { users { edges { node { id name phone email } } } } 

Ainsi, resolve() fonction implémentée sur le nœud des users devra maintenant déterminer quels champs sont demandés non pas pour lui-même, mais pour son nœud de node enfant imbriqué, qui, comme nous le voyons, est relatif aux users long du chemin edges.node .

fieldsList de la graphql-fields-list aidera à résoudre ce problème, pour cela vous devez lui passer l'option de path correspondante. Par exemple, voici l'implémentation dans notre cas:

 async resolve( source: any, args: {[argName: string]: any}, context: any, info: GraphQLResolveInfo, ) { const fields = fieldsList(info, { path: 'edges.node' }); return connectionFromArray( await database.query(`SELECT ${fields.join(',')} FROM users`), args ); } 

Dans le monde réel, il se peut également que dans le schéma GraphQL nous ayons défini un seul nom de champ, et dans le schéma de base de données, d'autres noms de champ leur correspondent. Par exemple, supposons que la table utilisateur de la base de données ait été définie différemment:

 CREATE TABLE users ( id BIGINT PRIMARY KEY AUTO_INCREMENT, fullName VARCHAR(255), email VARCHAR(255), phoneNumber VARCHAR(15), address VARCHAR(255) ); 

Dans ce cas, les champs de la requête GraphQL doivent être renommés avant d'être incorporés dans la requête SQL. fieldsList y aidera si vous lui passez une mappe de traduction de nom dans l'option de transform correspondante:

 async resolve( source: any, args: {[argName: string]: any}, context: any, info: GraphQLResolveInfo, ) { const fields = fieldsList(info, { path: 'edges.node', transform: { phone: 'phoneNumber', name: 'fullName' }, }); return connectionFromArray( await database.query(`SELECT ${fields.join(',')} FROM users`), args ); } 

Et pourtant, parfois, la conversion en un tableau plat de champs n'est pas suffisante (par exemple, si la source de données renvoie une structure complexe avec imbrication). Dans ce cas, la fonction fieldsMap de la graphql-fields-list viendra à la rescousse, qui retourne l'arborescence entière des champs demandés en tant qu'objet:

 const { fieldsMap } = require(`graphql-fields-list`); // ... some resolver implementation on `users`: resolve(arc, args, ctx, info) { const map = fieldsMap(info); /* RESULT: { edges: { node: { id: false, name: false, phone: false, } } } */ } 

Si nous supposons que l'utilisateur est décrit par une structure complexe, nous aurons tout. Cette méthode peut également prendre l'argument de path facultatif, qui vous permet d'obtenir une carte de la branche nécessaire uniquement de l'arborescence entière, par exemple:

 const { fieldsMap } = require(`graphql-fields-list`); // ... some resolver implementation on `users`: resolve(arc, args, ctx, info) { const map = fieldsMap(info, 'edges.node'); /* RESULT: { id: false, name: false, phone: false, } */ } 

La transformation des noms sur les cartes n'est actuellement pas prise en charge et reste à la merci du développeur.

Fragmentation de la demande

GraphQL prend en charge la fragmentation des requêtes, par exemple, nous pouvons nous attendre à ce que le consommateur nous envoie une telle demande (ici, nous nous référons au schéma d'origine, un peu farfelu, mais syntaxiquement correct):

 query UsersFragmentedQuery { users { id ...NamesFramgment ...ContactsFragment } } fragment NamesFragment on User { name } fragment AddressFragment on User { address } fragment ContactsFragment on User { phone email ...AddressFragment } 

Ne vous inquiétez pas dans ce cas, et fieldsList(info) , et fieldsMap(info) dans ce cas fieldsMap(info) le résultat attendu, car ils prennent en compte la possibilité de fragmenter les demandes. Ainsi, fieldsList(info) renverra ['id', 'name', 'phone', 'email', 'address'] , et fieldsMap(info) , respectivement, renverra:

 { id: false, name: false, phone: false, email: false, address: false } 

PS

J'espère que cet article a aidé à faire la lumière sur certaines des nuances du travail avec GraphQL sur le serveur, et la bibliothèque graphql-fields-list peut vous aider à créer des solutions optimales à l'avenir.

UPD 1

La version 1.1.0 de la bibliothèque a été publiée - la prise en @include @skip et @include dans les requêtes a été ajoutée. Par défaut, l'option est activée, si nécessaire, désactivez-la comme ceci:

 fieldsList(info, { withDirectives: false }) fieldsMap(info, null, false);