Formattatore GraphQL

Perché formattare GraphQL

Le query GraphQL vengono spesso costruite nel codice, registrate nei log su una sola riga o copiate dalle richieste di rete nel browser. In quella forma, una query con qualche livello di annidamento è quasi illeggibile: non capisci quali campi appartengono a quale oggetto, né dove finisce un fragment.

Un formattatore GraphQL mette ogni campo su una riga propria e indenta ogni selection set di un livello rispetto al genitore. La struttura della query rispecchia così quella della risposta che ricevi, e controllarla diventa facile.

Questo strumento usa Prettier 3 con il suo plugin GraphQL, direttamente nel tuo browser.

Come si usa

1. Incolla una query, una mutation o uno schema nel riquadro a sinistra. Viene formattato subito dopo averlo incollato.
2. In alternativa premi Apri file per caricare un file .graphql, oppure Esempio per un esempio.
3. Scegli il Rientro: 2 spazi, 4 spazi o tabulazioni.
4. Scegli la Larghezza riga. Argomenti ed elenchi di variabili che non ci stanno vengono divisi su più righe.
5. Premi Formatta o Ctrl+Invio.
6. Premi Copia, oppure Scarica per salvare un file .graphql.

Dopo la prima formattazione, il risultato segue quello che scrivi. Se c’è un errore di sintassi, il messaggio indica riga e colonna, e Mostra nell’input ti porta lì.

Prima e dopo

Una query su una sola riga:

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

Dopo Formatta con 2 spazi:

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

Le variabili ricevono uno spazio dopo i due punti, il valore predefinito 5 riceve spazi intorno a = e ogni selection set annidato è indentato. Ora vedi che title è un campo di node, dentro edges, dentro posts.

Mutation e input object

Gli input object che rientrano nella larghezza della riga restano su una sola riga:

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

Quando non ci stanno, gli argomenti vengono divisi. Ecco la stessa mutation con una larghezza riga di 40:

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

Nota che negli oggetti su più righe le virgole tra i campi di input spariscono. In GraphQL le virgole sono facoltative e valgono come spazi.

Fragment

Fragment e spread restano nell’ordine in cui li hai scritti:

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

File di schema

Lo schema definition language viene formattato con le stesse regole. Un campo per riga, e ogni valore di un enum su una riga a sé:

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

Con il Rientro impostato su 4 spazi, query{viewer{login}} diventa:

query {
    viewer {
        login
    }
}

Errori di sintassi

Il parser GraphQL è rigoroso e i suoi messaggi sono brevi (e in inglese). Due dei più comuni:

• Una parentesi graffa di chiusura mancante alla fine dà Riga 4, colonna 1: Syntax Error: Expected Name, found <EOF>. Il parser è arrivato alla fine dell’input mentre si trovava ancora dentro un selection set.
• Un argomento senza valore, come in user(id: ), dà Riga 2, colonna 12: Syntax Error: Unexpected ")".

Conta le parentesi graffe a partire dalla posizione indicata. Il formattatore è anche un modo rapido per trovare una graffa mancante in una query lunga: incollala, e se l’errore punta alla fine dell’input significa che un selection set non è mai stato chiuso.

Limiti

• Viene controllata solo la sintassi. Nomi dei campi, tipi degli argomenti e variabili obbligatorie non vengono convalidati rispetto a nessuno schema.
• Il formattatore non riordina i campi, non ordina i tipi e non rimuove i fragment inutilizzati.
• Per le query dentro template string gql in JavaScript o TypeScript, incolla qui solo il testo della query e poi rimetti il risultato al suo posto. Il formattatore JavaScript e il formattatore TypeScript formattano il codice intorno ma lasciano la template string com’è.
• Le variabili vengono inviate come JSON, non come GraphQL. Per formattare un oggetto di variabili usa il formattatore JSON.

Altri modi per formattare GraphQL

• VS Code: con l’estensione Prettier, Format Document (Maiusc+Alt+F su Windows, Maiusc+Opzione+F su macOS) formatta i file .graphql e .gql con le stesse regole di questa pagina.
• Riga di comando: npx prettier --write schema.graphql.
• IDE per GraphQL come GraphiQL hanno un pulsante Prettify che formatta la query nell’editor. È comodo mentre fai i test, mentre questa pagina è utile quando hai solo il testo e nessun IDE a portata di mano.