GraphQL avec du style : le langage secret des requêtes et schémas bien rangés

En une phrase

Le formatage GraphQL, c'est l'art d'appliquer des règles de style cohérentes aux requêtes, mutations et schémas, transformant un enchevêtrement d'accolades et de champs en un chef-d'œuvre lisible et maintenable.

Le problème que ça résout

À l'époque, si vous vouliez récupérer des données d'un serveur pour votre nouvelle appli web super cool, vous utilisiez probablement une API REST. Vous demandiez à un endpoint comme /users/123 les données d'un utilisateur, et à /users/123/posts ses articles. Le problème ? Vous pouviez recevoir bien plus de données que nécessaire (over-fetching), ou alors vous deviez faire plusieurs allers-retours pour obtenir toutes les données dont vous aviez vraiment besoin (under-fetching).

C'est là qu'intervient GraphQL, un langage de requête pour les API développé par Facebook. Ça a complètement changé la donne. Au lieu que le serveur décide quelles données envoyer, c'est le client qui demande exactement ce dont il a besoin, en une seule requête. C'est comme commander à la carte au lieu d'avoir un menu fixe.

# Donne-moi juste le nom de l'utilisateur 42 et les titres de ses 3 premiers articles
query GetUserNameAndPosts {
  user(id: "42") {
    name
    posts(first: 3) {
      title
    }
  }
}

C'était une révolution. Mais ça a introduit un nouveau problème, à plus petite échelle. Les requêtes GraphQL, avec leurs accolades imbriquées, peuvent devenir complexes. Très complexes. Sans aucune règle, une requête écrite par un développeur peut ressembler à une seule ligne de texte illisible. Un autre développeur pourrait écrire la même requête avec un style d'indentation complètement différent.

Quand vous essayez de déboguer un problème à 2 heures du matin ou qu'un nouveau membre de l'équipe tente de comprendre la structure de votre API, ce manque de cohérence est un cauchemar. Le code, c'est de la communication, et du GraphQL non formaté, c'est comme essayer de lire un livre sans paragraphes, sans ponctuation et avec une police de caractères qui change tout le temps. Le formatage impose une grammaire commune, rendant l'intention du code instantanément plus claire pour tout humain qui le lit.

Comment ça marche sous le capot

Un formateur GraphQL ne se contente pas d'un simple chercher-remplacer des familles. C'est un processus sophistiqué qui implique de comprendre la structure du code, d'appliquer un ensemble de règles, puis de reconstruire le code de zéro de manière élégante et prévisible.

Parsing : du texte à l'arbre

D'abord, le formateur doit lire la chaîne de caractères brute du code GraphQL et comprendre ce que c'est. Il ne peut pas se contenter de chercher une { et d'ajouter un saut de ligne. Il doit savoir si cette accolade ouvre une requête, une définition de type, ou un objet d'entrée.

Ce processus s'appelle le parsing. Le formateur découpe l'entrée en tokens (des morceaux qui ont du sens comme query, user, (, id, :, "42", )) puis construit un Arbre de Syntaxe Abstraite (AST). L'AST est une structure de données en forme d'arbre qui représente la structure grammaticale du code.

Pour une requête simple :

query { user { name } }

L'AST pourrait ressembler à quelque chose comme ça (de manière conceptuelle et simplifiée) :

- Document
  - Definition (OperationDefinition, type: query)
    - SelectionSet
      - Selection (Field)
        - name: "user"
        - SelectionSet
          - Selection (Field)
            - name: "name"

Le texte n'est plus juste du texte ; c'est un objet structuré que le programme peut manipuler intelligemment.

Les règles du style

Une fois que le formateur a l'AST, il peut parcourir l'arbre et appliquer ses règles de style. Ces règles sont le cœur du formatage et sont souvent le sujet de débats de développeurs (généralement futiles). Les règles communes incluent :

• Indentation : Combien d'espaces (ou de tabulations, si vous êtes un psychopathe) utiliser pour chaque niveau d'imbrication. Le standard quasi-universel est de 2 espaces.
• Sauts de ligne : Quand mettre les choses sur une nouvelle ligne. Est-ce que l'accolade ouvrante { doit être sur la même ligne que le nom du champ ou sur une nouvelle ligne ? (La plupart des formateurs la mettent sur la même ligne.)
• Espacement : Assurer un espacement cohérent autour des opérateurs comme les deux-points et à l'intérieur des parenthèses.
• Tri des champs : Pour les gros schémas, certains formateurs peuvent même trier les champs par ordre alphabétique pour les retrouver plus facilement.

Des outils comme Prettier sont devenus célèbres pour être « opinionated » (avec des choix bien tranchés) — ils font ces choix pour vous, comme ça vous n'avez pas à en débattre. Le but n'est pas de trouver le style « parfait », mais d'en choisir un et de l'appliquer sans relâche.

Pretty-Printing : de l'arbre au texte

Après avoir appliqué les règles, la dernière tâche du formateur est de prendre l'AST modifié et de le retransformer en une chaîne de texte. Ce processus s'appelle le pretty-printing. Le formateur traverse l'arbre, et à chaque nœud (comme Field ou SelectionSet), il imprime le texte correspondant, en ajoutant l'indentation et les sauts de ligne corrects selon les règles.

Le résultat est une chaîne de caractères GraphQL magnifiquement formatée.

Un concept lié est la minification ou le compactage. C'est le contraire du pretty-printing. Il parse aussi le code en un AST, mais le réécrit ensuite en supprimant tous les espaces optionnels. Cela crée une chaîne de caractères compacte sur une seule ligne, illisible pour les humains mais parfaite pour être envoyée sur un réseau, car elle économise quelques précieux octets.

Histoires vécues

L'affaire de la session de débogage de minuit

Jasmine, une ingénieure backend, était d'astreinte. À 1h30 du matin, une alerte se déclenche : une mutation GraphQL critique plante en production. Le seul indice est une entrée de log contenant la requête exacte envoyée par le client — une unique ligne de charabia de 3000 caractères, copiée-collée depuis un bundle JavaScript minifié. Elle a fixé ce mur de texte, ...customer{address{..., en essayant de trouver la partie malformée. Son regard s'est perdu dans le vide. Frustrée, elle a balancé la chaîne de caractères complète dans un formateur GraphQL. Instantanément, la requête s'est épanouie en une structure de 70 lignes parfaitement indentée. Et là, c'était écrit noir sur blanc à la ligne 47 : une faute de frappe dans un nom de champ crucial, adress au lieu de address. La correction était triviale, mais elle n'aurait jamais pu voir le problème sans le formatage.

La leçon : La lisibilité est la première étape, et la plus importante, vers la facilité de débogage. Un formateur transforme un blob de texte impénétrable en quelque chose qu'un humain peut réellement analyser.

La pull request qui ne voulait pas être mergée

Une petite équipe développait un nouveau backend e-commerce avec GraphQL. Deux développeurs, Liam et Olivia, travaillaient sur une fonctionnalité. Liam avait configuré son éditeur pour utiliser une indentation de 4 espaces. Olivia, fan des 2 espaces, avait une configuration différente. Quand Liam a soumis sa pull request, Olivia l'a relue, a fait quelques changements logiques, et a pushé son commit. Le « diff » résultant était un océan de rouge et de vert. Presque chaque ligne était marquée comme modifiée, simplement parce que leurs éditeurs se battaient pour des espaces. Les vrais changements de fond étaient complètement noyés dans le bruit. Le tech lead a dû passer une heure à démêler ce bazar. Le lendemain, il a ajouté un formateur GraphQL automatique à leur hook de pré-commit. Maintenant, tout le code est formaté selon le même standard avant même d'être commité.

La leçon : Le formatage automatique élimine les débats de style et garde l'historique du contrôle de version propre, en concentrant les relectures de code sur ce qui compte : la logique.

Le schéma qui ressemblait à un plat de spaghettis

Le schéma GraphQL d'une startup avait grandi de manière organique pendant trois ans. Les types étaient ajoutés un peu n'importe où, les champs n'avaient aucun ordre particulier, et les commentaires étaient sporadiques. Pour une nouvelle recrue, essayer de comprendre le modèle de données de l'API, c'était comme essayer de démêler un tiroir plein de vieux câbles. Ils ont décidé de tenter une expérience : ils ont passé le fichier schema.graphql entier dans un formateur. L'outil a non seulement tout indenté correctement, mais il a aussi trié tous les champs de chaque type par ordre alphabétique. Soudain, id était toujours le premier champ. Les champs dépréciés étaient groupés ensemble. Toute la structure est devenue limpide. Ce n'était pas juste plus joli ; c'était devenu un élément de documentation utile.

La leçon : Un schéma bien formaté agit comme une documentation vivante. Il révèle la structure et l'intention de votre API, la rendant plus accessible pour tout le monde.

Erreurs et pièges courants

• Se disputer sur le style. Le plus grand piège est de perdre des heures à débattre sur les tabulations contre les espaces, ou sur où placer l'accolade. La valeur du formatage, c'est la cohérence. Choisissez un outil populaire et « opinionated » comme Prettier, mettez-vous d'accord pour l'utiliser, et passez à autre chose.
• Oublier de formater avant de commiter. Si le formatage est un processus manuel, les gens oublieront. Cela mène aux diffs brouillons que vous essayiez d'éviter. Intégrez le formatage dans un hook de pré-commit (avec des outils comme Husky et lint-staged) pour le rendre automatique et transparent.
• Confondre formatage et linting. Un formateur rend votre code visuellement cohérent. Un linter (comme eslint-plugin-graphql) vérifie votre code à la recherche de bugs potentiels ou de mauvaises pratiques, comme l'utilisation d'un champ déprécié ou l'écriture d'une requête inefficace. Vous avez besoin des deux. Un formateur nettoie la cuisine ; un linter vérifie si vous avez laissé le gaz allumé.
• Formater du code généré. Certains workflows génèrent des fichiers de schéma ou des requêtes GraphQL à partir d'une autre source (comme un schéma de base de données ou un autre langage de programmation). Formater le code en sortie est souvent une perte de temps, car vos modifications seront écrasées à la prochaine génération de code. Formatez plutôt la source.
• Envoyer des requêtes formatées en production. Bien qu'une belle indentation soit géniale pour le développement, ce sont des octets gaspillés sur le réseau. Votre processus de build devrait minifier les requêtes GraphQL avant qu'elles ne soient envoyées de votre application client au serveur.

Pourquoi c'est un sujet à garder sur votre radar

Vous devriez commencer à penser au formatage GraphQL dès qu'un projet implique plus d'une personne, ou dès que vos requêtes deviennent plus complexes qu'un seul champ imbriqué.

C'est un outil fondamental du développement logiciel professionnel qui s'applique parfaitement à GraphQL. Le but n'est pas de rendre les choses « jolies » pour le plaisir. Il s'agit de :

• Clarté : Rendre le code plus facile à lire et à comprendre.
• Maintenabilité : Rendre le code plus facile à modifier et à déboguer.
• Collaboration : Réduire les frictions entre les membres de l'équipe en automatisant les choix stylistiques.

Si jamais vous vous surprenez à fixer une requête GraphQL minifiée dans un fichier de log, ou à vous disputer avec un collègue sur l'indentation, c'est le signe que vous avez besoin d'un formateur automatique dans votre vie.

Pour aller plus loin

• GraphQL Specification - La source officielle et canonique pour le langage GraphQL lui-même.
• Prettier: GraphQL - La documentation du formateur de code le plus populaire pour son support de GraphQL.
• Exploring GraphQL APIs with Abstract Syntax Trees - Un excellent article d'Apollo sur la puissance de l'AST.
• GraphQL on Wikipedia - Pour une vue d'ensemble et un historique.
• ESLint Plugin for GraphQL - Une plongée en profondeur dans le linting, le puissant compagnon du formatage.