Formateur GraphQL

Pourquoi formater du GraphQL

Les requêtes GraphQL sont souvent construites dans le code, journalisées sur une seule ligne ou copiées depuis l’inspecteur réseau du navigateur. Une requête à quelques niveaux d’imbrication devient presque illisible sous cette forme. On ne voit plus quels champs appartiennent à quel objet, ni où finit un fragment.

Un formateur GraphQL met chaque champ sur sa propre ligne et indente chaque ensemble de sélection d’un niveau de plus que son parent. La structure de la requête correspond alors à celle de la réponse reçue, ce qui la rend facile à vérifier.

Cet outil utilise Prettier 3 avec son plugin GraphQL, dans votre navigateur.

Mode d’emploi

1. Collez une requête, une mutation ou un schéma dans la zone de gauche. Il est formaté juste après le collage.
2. Ou appuyez sur Ouvrir un fichier pour charger un fichier .graphql, ou sur Exemple pour un exemple.
3. Choisissez l’Indentation : 2 espaces, 4 espaces ou tabulations.
4. Choisissez la Largeur de ligne. Les arguments et les listes de variables qui ne tiennent pas sont répartis sur plusieurs lignes.
5. Appuyez sur Formater ou Ctrl+Entrée.
6. Appuyez sur Copier, ou sur Télécharger pour enregistrer un fichier .graphql.

Après un premier formatage, le résultat suit votre frappe. En cas d’erreur de syntaxe, le message donne sa ligne et sa colonne, et Afficher dans l’entrée vous y amène.

Avant et après

Une requête sur une seule ligne :

query GetUser($id:ID!,$first:Int=5){user(id:$id){id name email posts(first:$first){edges{node{id title publishedAt}}}}}

Après Formater avec 2 espaces :

query GetUser($id: ID!, $first: Int = 5) {
  user(id: $id) {
    id
    name
    email
    posts(first: $first) {
      edges {
        node {
          id
          title
          publishedAt
        }
      }
    }
  }
}

Les variables reçoivent une espace après le deux-points, la valeur par défaut 5 des espaces autour de =, et chaque ensemble de sélection imbriqué est indenté. Vous voyez maintenant que title est un champ de node, dans edges, dans posts.

Mutations et objets d’entrée

Les objets d’entrée qui tiennent dans la largeur de ligne restent sur une ligne :

mutation {
  createPost(input: { title: "Hello", tags: ["news", "update"] }) {
    id
  }
}

Quand ils ne tiennent pas, les arguments sont répartis. Voici la même mutation avec une largeur de ligne de 40 :

mutation {
  createPost(
    input: {
      title: "Hello"
      tags: ["news", "update"]
    }
  ) {
    id
  }
}

Notez que les virgules entre les champs d’entrée disparaissent dans les objets sur plusieurs lignes. En GraphQL, les virgules sont facultatives et comptent comme des espaces.

Fragments

Les fragments et les spreads sont gardés dans l’ordre où vous les avez écrits :

fragment UserParts on User {
  id
  name
}
query {
  me {
    ...UserParts
  }
}

Fichiers de schéma

Le langage de définition de schéma est formaté selon les mêmes règles. Un champ par ligne, et chaque valeur d’enum sur sa propre ligne :

type User {
  id: ID!
  name: String!
  posts(first: Int): [Post!]!
}
enum Role {
  ADMIN
  EDITOR
}

Avec l’Indentation réglée sur 4 espaces, query{viewer{login}} devient :

query {
    viewer {
        login
    }
}

Erreurs de syntaxe

L’analyseur GraphQL est strict, et ses messages, en anglais, sont courts. Deux messages courants :

• Une accolade fermante manquante à la fin donne Ligne 4, colonne 1 : Syntax Error: Expected Name, found <EOF>. L’analyseur a atteint la fin de la saisie alors qu’il était encore dans un ensemble de sélection.
• Un argument sans valeur, comme dans user(id: ), donne Ligne 2, colonne 12 : Syntax Error: Unexpected ")".

Comptez vos accolades à partir de la position indiquée. Un formateur est aussi un moyen rapide de trouver une accolade manquante dans une longue requête : collez-la, et si l’erreur pointe la fin de la saisie, un ensemble de sélection n’a jamais été fermé.

Limites

• Seule la syntaxe est vérifiée. Les noms de champs, les types d’arguments et les variables obligatoires ne sont validés par rapport à aucun schéma.
• Le formateur ne réordonne pas les champs, ne trie pas les types et ne retire pas les fragments inutilisés.
• Pour une requête dans une chaîne de template gql en JavaScript ou en TypeScript, collez seulement le texte de la requête ici, puis remettez le résultat en place. Le formateur JavaScript et le formateur TypeScript formatent le code autour mais laissent la chaîne de template telle quelle.
• Les variables sont envoyées en JSON, pas en GraphQL. Formatez un objet de variables avec le formateur JSON.

Autres façons de formater du GraphQL

• VS Code : avec l’extension Prettier, Mettre en forme le document (Maj+Alt+F sous Windows, Maj+Option+F sous macOS) formate les fichiers .graphql et .gql avec les mêmes règles que cette page.
• Ligne de commande : npx prettier --write schema.graphql.
• Les IDE GraphQL comme GraphiQL ont un bouton Prettify qui formate la requête dans l’éditeur. C’est pratique pendant les tests, et cette page est utile quand vous n’avez que le texte, sans IDE sous la main.