GraphQL : leçons apprises en production

Nous sommes en 2020. Votre équipe s'oriente de plus en plus vers la construction d'applications à page unique ou, du moins, vers l'inclusion de composants riches dans des applications multi-pages ordinaires. [GraphQL](https://graphql.org/) a [plus de deux ans](https://en.wikipedia.org/wiki/GraphQL) maintenant, ce qui par JavaScript Les normes de l'écosystème peuvent être considérées comme matures. Comme nous nous sentions un peu aventureux, nous avons renoncé aux API JSON habituelles et nous nous sommes lancés dans l'aventure - voici ce que nous avons appris.

Vous avez besoin d'un serveur GraphQL

Dans la plupart des cadres utilisés pour les développement webLes outils pour construire une API JSON sont déjà là. Vous pouvez construire une structure de route et facilement accepter quelques GET et POST, puis produire une réponse JSON. Ruby on Rails dispose même d'une fonction spéciale projet qui se passe des fonctionnalités habituelles de rendu HTML et met à la place une base solide pour les API. Il s'ensuit qu'un développeur compétent utilisant des outils modernes peut créer un backend en quelques minutes.

Ce n'est pas le cas avec GraphQL. Bien qu'il existe des bibliothèques de serveurs pour de nombreuses languesMais si l'on utilise le terme "serveur", on subit tout de même une pénalité de vitesse dès le départ - simplement parce qu'il faut trouver ce qui convient à son écosystème. D'un point de vue plus personnel, je n'aime pas non plus le terme "serveur" utilisé pour décrire une bibliothèque qui peut être introduite dans un projet.

Il n'y a qu'un seul point d'arrivée

Au fil des ans, nous nous sommes habitués à une façon particulière de concevoir la structure des API. Au niveau le plus élémentaire, nous suivions simplement les pratiques REST. Cela signifie que nous avons créé plusieurs points d'extrémité par modèle logique dans notre application. Cette structure est facile à comprendre pour les auteurs et les consommateurs d'API. Elle produit également des méthodes bien ciblées dans le backend, ce qui permet de raisonner sur la structure de l'API. code que sur l'API elle-même. Cette structure est également facile à nommer, par exemple pour les besoins de l'application Version de l'API.

GraphQL n'utilise qu'un seul point de terminaison, communément appelé /graphql. Chaque demande adressée à votre API arrivera sous la forme d'une requête POST à ce point d'extrémité, et à partir de là, il incombe au serveur GraphQL de déterminer ce que veut le client et d'y répondre de manière appropriée.

À première vue, cela semble difficile à gérer : imaginez que vous essayez de faire tout ce qu'il y a dans une API JSON avec un seul point de terminaison ! Cependant, elle commence rapidement à prendre tout son sens à mesure que votre API mûrit et que certaines choses sont remplacées par d'autres. La dépréciation dans les API classiques se fait généralement au niveau de l'espace de noms, en passant de v1 à v2. GraphQL offre beaucoup plus de contrôle, jusqu'à la dépréciation d'un seul champ. Imaginez que vous puissiez dire à un consommateur d'API REST que vous ne voulez pas qu'il utilise le champ nom et d'utiliser le champ nom_fantaisie au lieu de cela ! Il s'avère que ce qui semblait peu pratique au départ est en fait l'une des meilleures fonctionnalités.

Tout est dactylographié

JSON n'offre pas vraiment de possibilités de typage. Il y a des chaînes de caractères, des nombres, des tableaux et des objets. Au-delà, vous n'avez pas de chance. En revanche, dans GraphQL, tout commence et se termine par des types, puisque même les racines Query et Mutation sont justement des types. Le DSL GraphQL applique la vérification des types à la fois sur le serveur et sur le client, ce qui permet d'éviter toutes sortes de mauvaises surprises.

Ceci est très important, d'autant plus que les SPA sont de plus en plus souvent soumis à des contrôles de type, que ce soit en utilisant TypeScript ou d'autres solutions comme Flow. GraphQL permet d'introduire facilement des types complexes et composés en plus des valeurs par défaut et devient rapidement une seconde nature pour les développeurs, tant au niveau du backend que du frontend.

En savoir plus : Test du JavaScript...avec Ruby !

Les documents sont intégrés

Dans une API JSON classique, la documentation peut être une réflexion après coup. Et même si ce n'est pas le cas, il y a beaucoup de méthodes à choisir. Devons-nous utiliser une méthode comme OpenAPI? Devons-nous ensuite le convertir en un format lisible par l'homme avec des outils tels que Swagger ? Ou bien nous contentons-nous de déverser tout un tas de fichiers Markdown quelque part ? Même si ce problème a été résolu à plusieurs reprises, il nécessite toujours une réflexion et des efforts de la part de l'équipe - d'abord pour construire les documents, puis pour les mettre à jour et les diffuser. Le problème est encore plus complexe lorsque l'API comporte plusieurs sections qui ne sont accessibles que par certains rôles d'utilisateurs, par exemple.

Dans GraphQL, la documentation est un citoyen de première classe, car la plupart des serveurs permettent de documenter vos types et vos demandes en place. Depuis le début de l'année 2018, le langage de définition de schéma GraphQL a été intégré à la spécification officielle, de sorte qu'il n'existe précisément qu'une seule façon de documenter une API GraphQL. De plus, puisque GraphQL permet de définir la visibilité de certaines parties du graphe, les utilisateurs qui ne devraient pas le faire sont automatiquement empêchés de voir les docs pour ce à quoi ils ne peuvent pas accéder. Le fait d'avoir pris la décision et d'avoir des lignes directrices claires a été une véritable bénédiction pour l'équipe.

Il n'y a que deux types d'actions

Contrairement aux actions HTTP GET, POST, PUT, PATCH et DELETE, il n'y a que deux types d'actions dans GraphQL : les requêtes et les mutations. La principale différence réside dans le fait que les mutations peuvent modifier l'état du système et qu'elles le feront, tandis que les requêtes ne font que lire passivement des données.

Je dois admettre que je ne suis pas encore tout à fait d'accord sur ce point. J'apprécie la pléthore de verbes HTTP pour interagir avec les ressources et être en mesure d'utiliser le bon outil pour le travail. GraphQL facilite la prise en charge des cas où l'un des verbes HTTP n'est pas exactement adapté, mais il est pénalisé par le fait qu'il faut réfléchir à ce qu'une mutation particulière va réellement affecter. On peut également faire remarquer que, puisqu'il n'existe pas vraiment de convention de dénomination standard intégrée, vous devrez élaborer des guides de style internes ou risquer de créer un désordre incohérent.

Vous avez besoin d'un client

Interagir avec les API REST via HTTP est très facile dans la version vanille de JavaScript, et encore plus en utilisant la version moderne de chercher API. En revanche, pour GraphQL, vous devez utiliser une bibliothèque client si vous souhaitez obtenir des performances décentes. Il n'est pas impossible d'interagir avec une API GraphQL en utilisant simplement JavaScript vanille - il ne s'agit que de requêtes POST après tout. Toutefois, l'utilisation de technologies Web de longue date telles que la mise en cache des requêtes pour les appels d'API courants ne fonctionnera pas, car les requêtes POST ne sont généralement pas mises en cache.

Tout client GraphQL raisonnable implémente un mécanisme de mise en cache des résultats côté client, et bien d'autres fonctionnalités encore. Grâce à tous ces choix, la configuration d'un client GraphQL d'entrée de gamme est une tâche tout à fait stupéfiante. Lorsque l'on débute avec GraphQL, je recommande tout particulièrement de jeter un coup d'œil à Apollo-Boost puisqu'il est livré avec des valeurs par défaut très raisonnables.

Le client choisit les données

Nous sommes tous passés par là : nous extrayons une liste de données de l'API et il manque un champ crucial concernant un modèle connexe. Nous mettons alors en œuvre un hack impliquant N+1 requêtes tout en râlant contre les développeurs du backend qui s'empressent de l'ajouter rapidement. Ce n'est généralement pas le cas avec une API GraphQL bien implémentée, puisque nous pouvons plonger dans les données aussi profondément que nous le souhaitons. Vous avez besoin de connaître l'adresse d'un client pour une commande dans ce lot ? Ce n'est pas un problème, du moins en théorie, ce qui nous amène à...

La complexité est plus difficile à prévoir

Lorsque l'on conçoit GraphQL du côté du back-end, il peut être difficile de penser à toute la profondeur qu'un client peut atteindre dans le graphe. Il existe de nombreuses façons d'instrumenter et d'observer l'utilisation de votre graphe, et après avoir laissé vos collègues du front-end s'amuser pendant un certain temps, vous pouvez commencer à voir de longues requêtes effectuer des lectures plutôt imaginatives sur votre magasin de données. Dans une API REST, cela est plus facile à contrôler puisque vous pouvez facilement déterminer l'étendue des données qui seront accédées en une seule requête. Souvent, cette complexité manquée peut vous coûter cher une fois que vous passez en production. La plupart du temps, il n'est pas évident de sortir du trou que vous vous êtes creusé.

Les pages numérotées sont vraiment difficiles

Il s'agit là d'un reproche qui n'a rien d'ironique. On sent bien que GraphQL a été conçu par et pour Facebook en observant le fonctionnement de son mécanisme de pagination. Les "Connections" sont en fait des flux sans fin d'arêtes de graphe, sur lesquelles on navigue à l'aide de curseurs plutôt que par le biais de pages plus classiques. S'il est facile de comprendre comment cela s'intègre dans un flux continu de posts à la Facebook, si vous voulez une liste bien paginée avec la possibilité d'aller, disons, à la page 42, vous allez avoir beaucoup plus de mal. Il existe bien sûr des moyens de contourner ce problème, mais c'est ce qu'ils sont - des moyens de contournement.

Le referions-nous ?

Avec tous les griefs et les différences énumérés ci-dessus, vous pensez probablement que nous considérons GraphQL comme une expérience qui a tourné court et que nous sommes revenus directement aux API REST. Ce n'est pas le cas. Au contraire, nous nous efforçons de généraliser l'utilisation de GraphQL dans les projets de l'ensemble de l'organisation. C'est une technologie formidable qui a facilité et amélioré notre travail. Toutefois, nous avons initialement investi dans GraphQL sans nous rendre compte des difficultés de croissance que nous allions rencontrer.

Si vous pensez que GraphQL pourrait vous convenir, je vous encourage à vous lancer. Donnez-vous suffisamment de temps et d'espace pour échouer en toute sécurité, et vous récolterez les fruits de votre travail en peu de temps !

Lire aussi :

– Comment gérer efficacement les développeurs à distance ? Le guide pour les CTO

– Python ou Ruby ? Quelle technologie utiliser pour le développement de produits ?

– Un guide rapide pour créer et développer votre propre place de marché. Que faut-il savoir ?