Entrée

Sortie

Qu'est-ce que le Formateur de Requêtes GraphQL ?

Chaque requête GraphQL écrite à la main commence par un mur d'accolades sur une seule ligne. La coller dans une revue de code sans la formater d'abord est le meilleur moyen de récupérer "merci de reformater" en premier commentaire. Pareil pour les requêtes que crache un build frontend, qui sont loguées par un serveur, ou qui atterrissent dans un fil Slack quand un coéquipier demande "pourquoi ça renvoie null ?". Cette page prend une requête, mutation, subscription ou fragment et l'embellit : indentation à deux espaces, un champ par ligne, arguments en ligne quand ils tiennent, variables remises au propre, et la grammaire des opérations de la spec GraphQL respectée de bout en bout.

Notez que cette page est le pendant côté opérations de GraphQL Formatter. Cet outil-là formate le langage de définition de schéma — vos type Order, interface Node, enum Status. Cet outil-ci formate ce que votre client envoie et ce que votre serveur reçoit : query OrderDetails($id: ID!) { order(id: $id) { ... } }, mutations, subscriptions et définitions de fragments. Les deux grammaires partagent des tokens mais les règles structurelles sont différentes — selection sets, alias, fragment spreads, inline fragments et applications de directives sont propres aux opérations. Si vous avez collé du SDL par erreur, allez plutôt sur le formateur de schéma.

Le formatage est codé à la main en TypeScript — aucun bundle graphql-js n'est chargé sur la page, donc le premier rendu reste léger. La sortie correspond à ce que produit Prettier avec son plugin GraphQL pour les cas courants, donc coller la requête formatée dans une base de code qui utilise déjà Prettier ne devrait pas créer de diff. Tout tourne en local — votre requête ne quitte jamais le navigateur.

Comment Utiliser le Formateur de Requêtes GraphQL

Trois étapes. Pas de bouton Convertir — le formatage se déclenche automatiquement un instant après que vous arrêtiez de taper.

Collez, Téléversez ou Chargez un Exemple

Collez une opération GraphQL dans le panneau Entrée à gauche. Cliquez sur Téléverser pour un fichier .graphql ou .gql, ou sur Exemple pour une requête e-commerce OrderDetails réaliste accompagnée d'un petit fragment. Un collage typiquement en vrac ressemble à :

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

Le formateur gère toutes les constructions d'opération qui apparaissent dans le code client réel : définitions de variables avec valeurs par défaut, valeurs par défaut de type liste, directives @include / @skip / personnalisées, alias, fragment spreads (...Money), et inline fragments (... on PaidOrder { ... }). Plusieurs opérations ou fragments dans un même document sont gardés séparés, avec une ligne vide entre chacun — c'est ainsi qu'Apollo Client et la plupart des outils GraphQL s'attendent à ce que les documents soient présentés.

Lisez la Sortie Embellie

Le panneau Sortie à droite affiche l'opération formatée. Chaque champ est sur sa propre ligne. Les arguments restent en ligne quand le champ tient sur 80 caractères et passent sur des lignes séparées sinon — même règle que le plugin GraphQL de Prettier. Les définitions de variables suivent la même règle dans l'en-tête d'opération. Les alias gardent un seul espace après les deux-points (aliasedAs: fieldName). Les commentaires (# ...) sont préservés à l'indentation de la ligne à laquelle ils étaient attachés. Si l'entrée est mal formée — accolades non appariées, $ orphelin, : manquant — le formateur écrit un message d'erreur sympathique en ligne plutôt que de planter.

Copier ou Télécharger

Cliquez sur Copier pour récupérer la requête formatée pour une PR, un doc ou un message de chat. Cliquez sur Télécharger pour sauvegarder en tant que query.graphql. Effacer réinitialise l'entrée. Toute la chaîne est côté client — pratique quand vous déboguez une requête contre une API interne et préférez ne pas la coller dans un outil tiers.

Quand l'Utiliser Vraiment

Revue de Code et Hygiène de PR

Une PR frontend ajoute une nouvelle mutation. La chaîne de requête a été émise par une étape de build qui a viré le whitespace, et le diff est désormais un mur de 400 caractères. Passez la mutation au formateur, mettez la version embellie dans la description de la PR, et le relecteur peut enfin voir quels champs vous lisez. Le même truc marche pour graphql-react, urql, Relay, et tout autre client où les requêtes sont inlinées en template literals.

Déboguer une Requête en Production

Une requête en production renvoie null pour un champ que vous attendiez. Vous récupérez le corps de la requête depuis l'onglet réseau, vous le collez ici, et vous voyez maintenant les valeurs de variables, quels champs utilisent @include, et où atterrissent les fragment spreads. Mieux que de plisser les yeux sur une longue ligne. Combinez avec le guide officiel sur servir GraphQL via HTTP quand vous devez reproduire la requête manuellement avec curl ou Postman.

Apprentissage et Onboarding

Nouveau dans les opérations GraphQL ? Collez une requête trouvée dans un tuto, formatez-la, et la structure devient évidente — en-tête d'opération, selection set, selection sets imbriqués, définitions de fragments en bas. La sortie reflète la mise en page que vous verrez dans le guide des requêtes de graphql.org, donc facile de revenir à la doc en cours d'apprentissage.

Pre-commit et Garde-fous CI

Comme le formateur est déterministe — les requêtes déjà embellies ressortent inchangées — vous pouvez utiliser cette page comme un rapide "ma requête est-elle déjà jolie ?" avant de commit. Pour un pipeline totalement automatisé, faites passer la même source par Prettier avec son plugin GraphQL et faites échouer le build sur un diff non nul. Même idée, à plus grande échelle.

Questions Fréquentes

En quoi est-ce différent de la page GraphQL Formatter ?

La page GraphQL Formatter formate le langage de définition de schéma — vos déclarations type, interface, enum, union, scalar et directive. Cette page formate les opérations : query, mutation, subscription et fragment. Les deux grammaires partagent des tokens mais des règles structurelles très différentes, donc essayer de formater une opération sur la page de schéma (ou inversement) donne une sortie confuse. Choisissez le bon outil selon ce que vous avez collé.

Valide-t-il ma requête contre un schéma ?

Non. Le formateur vérifie l'équilibre des accolades, parenthèses et crochets juste assez pour pretty-printer, mais il ne connaît pas votre schéma, donc il ne peut pas vous dire que order attend id: ID! et non id: Int!. Pour une vraie validation, faites passer votre opération par les vérifications au démarrage de votre serveur, ou par le validateur de référence graphql-js via le lien GitHub plus haut.

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

Non. Le formatage est du JavaScript pur côté client — rien n'est uploadé, rien n'est logué. Sûr pour des requêtes internes, des requêtes contenant des valeurs de variables sensibles, ou des requêtes contre des APIs privées.

Va-t-il toucher à mes valeurs de variables ou arguments ?

Non. Les valeurs d'arguments, valeurs par défaut et valeurs par défaut de type liste sont émises exactement comme écrites, juste avec un espacement cohérent autour de :, = et ,. Le formateur n'invente, ne supprime ni ne réordonne jamais champs, arguments ou variables — ce que vous avez collé est ce qui ressort, juste mis en forme proprement.

Gère-t-il inline fragments et fragment spreads ?

Oui. Les inline fragments (... on PaidOrder { ... }) reçoivent le traitement standard du selection set avec indentation à deux espaces. Les fragment spreads (...Money) tiennent sur une seule ligne à l'indentation du champ, avec toute directive maintenue sur la même ligne. Plusieurs définitions de fragments dans un document sont conservées comme définitions distinctes de premier niveau avec une ligne vide entre elles.

Et les requêtes anonymes — <code>{ field }</code> — les développe-t-il en <code>query { field }</code> ?

Non. La forme raccourcie fait partie de la spec et le formateur la préserve telle quelle. Si vous voulez une requête nommée, nommez-la vous-même — le formateur ne réécrit pas silencieusement les opérations.

Autres Outils GraphQL

Un formateur de requêtes n'est qu'une partie du travail avec GraphQL. Les autres outils GraphQL du site :