Formater une requête GraphQL

Comment ça marche

Une requête GraphQL copiée depuis l'onglet réseau du navigateur, un journal d'erreurs ou du code JavaScript tient souvent sur une seule longue ligne, et on ne voit pas quel champ se trouve dans quel autre. Collez la requête dans la zone de gauche. À droite, chaque champ passe sur sa propre ligne, les sélections imbriquées sont décalées de 2 espaces et les arguments (premiers: $nombre, statut: LIVREE) reçoivent une espace après chaque deux-points et chaque virgule. Par exemple, {user(id:1){name}} devient une requête lisible de cinq lignes. Les fragments, les définitions de variables ($client: ID!), les directives (@include) et les définitions de schéma (type, input, enum) suivent le même style standard. Avec Une ligne, on fait l'inverse : les espaces inutiles disparaissent mais le texte entre guillemets reste intact, et la requête peut aller dans une URL ou dans du code. En cas d'erreur de syntaxe, sa ligne et sa colonne sont indiquées. Les commentaires écrits avec # ne sont pas conservés par l'imprimeur standard ; la ligne de résultat indique combien ont été retirés.

Cet outil est aussi connu sous le nom de formater graphql, graphql formatter, graphql beautifier, indenter graphql en ligne.

Qu'est-ce que GraphQL ?

GraphQL est un langage de requête dans lequel le client décrit exactement quelles données il veut obtenir d'une API. En REST, chaque adresse renvoie une réponse fixe ; en GraphQL, une requête envoyée à une seule adresse liste les champs voulus entre accolades imbriquées, et la réponse revient exactement sous cette forme. Il a été créé chez Facebook, et GitHub, Shopify et de nombreuses API d'applications l'utilisent. Requêtes, mutations (modifications) et fragments (groupes de champs réutilisables) en sont les briques principales.

Qu'est-ce que Fragment ?

En GraphQL, un fragment est un groupe de champs nommé qui revient dans plusieurs requêtes : fragment Adresse on Commande { rue ville } est défini une fois, puis ajouté là où il faut avec ...Adresse. Il n'est plus nécessaire de réécrire la même liste de champs dans chaque requête, et l'ajout d'un champ ne change qu'un seul endroit. Le formateur écrit la définition du fragment comme un bloc à part et l'endroit où il est utilisé comme une ligne ...Adresse.

Quelle différence entre une requête GraphQL et un schéma GraphQL ?

Une requête (query, mutation) dit ce que le client veut de l'API : quels champs, avec quels arguments. Un schéma (SDL) définit ce que le serveur propose : des types comme type Commande { id: ID! montant: Float }, leurs champs et le type de ces champs. Les requêtes sont validées par rapport au schéma ; demander un champ absent du schéma renvoie une erreur du serveur. Cet outil met en forme les deux, mais ne valide pas une requête par rapport à un schéma ; il vérifie seulement la syntaxe.

La mise en forme change-t-elle le résultat de la requête ?

Non. En GraphQL, les espaces, les retours à la ligne et les virgules n'ont pas de sens ; le serveur répond de la même façon à la requête mise en forme et à la requête sur une ligne. L'outil lit la requête avec l'analyseur de graphql-js et réécrit le même arbre dans le style standard ; l'ordre des champs, les alias, les valeurs des arguments et les chaînes sont conservés.

La seule différence concerne les commentaires : les lignes commençant par # ne font pas partie de l'arbre syntaxique, l'imprimeur standard les laisse donc de côté. Si vos commentaires comptent, gardez le texte d'origine ; la ligne de résultat indique combien de lignes de commentaire ont été retirées. Les descriptions ("""...""") font partie du schéma et sont conservées.

Que vérifie cet outil, et que ne peut-il pas vérifier ?

L'outil vérifie la syntaxe : une accolade non fermée, un deux-points manquant, une virgule ou un guillemet mal placé apparaît avec sa ligne et sa colonne. Cela suffit pour savoir si une requête est cassée avant qu'elle n'atteigne le serveur.

Il ne valide pas par rapport à un schéma : il ne peut pas savoir si le champ demandé existe ni si un argument a le bon type, car il ne dispose pas du schéma de l'API. Pour cela, utilisez l'écran GraphiQL ou Apollo Studio de l'API.

• Lire une requête sur une ligne tirée des journaux → Lisible
• Mettre la requête dans un paramètre d'URL ou dans du code → Une ligne
• Le champ existe-t-il, le type est-il bon → GraphiQL de l'API

Questions fréquentes

Comment rendre lisible une requête GraphQL sur une ligne ?

Collez la requête dans la zone de gauche de cette page. Chaque champ passe sur sa propre ligne et les sélections imbriquées sont indentées de 2 espaces. Copiez le résultat ou téléchargez-le en fichier .graphql.

Les définitions de schéma (type, input, enum) sont-elles mises en forme ?

Oui. En plus du langage de requête, l'outil lit le langage de définition de schéma (SDL) : les définitions type, interface, input, enum, union et scalar suivent le même style standard, et les descriptions sont conservées.

Pourquoi mes commentaires ont-ils disparu ?

L'imprimeur officiel de GraphQL ne reprend pas les commentaires #, car ils ne font pas partie de l'arbre syntaxique de la requête. La ligne de résultat indique combien de lignes de commentaire ont été retirées ; gardez le texte d'origine si vous en avez besoin.

Ma requête est-elle envoyée à un serveur ?

Non. La mise en forme se fait entièrement dans votre navigateur ; la requête, avec les identifiants ou valeurs qu'elle contient, ne quitte pas cette page et n'est envoyée à aucune API.