Struttura di una Query in GraphQL: Guida Completa

Una query in GraphQL permette ai client di richiedere dati da un server in modo flessibile ed efficiente. La potenza di GraphQL risiede nella capacità di definire esattamente i dati richiesti, evitando sia overfetching (richiedere troppi dati) che underfetching (richiedere troppo poco). In questo articolo esploreremo la struttura di una query in GraphQL, comprendendo le diverse parti che la compongono e come costruire query efficaci e performanti.

Struttura di Base di una Query in GraphQL

Una query GraphQL ha una struttura semplice e leggibile, che include:

1. Tipo di Operazione: query, mutation, o subscription.
2. Nome della Query (opzionale): Un nome per identificare la query (utile soprattutto per debugging o logging).
3. Campi Richiesti: La lista di campi che si desidera ottenere dal server.
4. Argomenti (opzionali): Parametri passati alla query per filtrare o modificare i dati restituiti.
5. Alias (opzionale): Rinomina i campi restituiti dalla query.
6. Frammenti (opzionale): Parti riutilizzabili della query che possono essere usate in più campi o query.

Esempio di Query di Base

query {
  user(id: "1") {
    id
    name
    email
  }
}

In questo esempio:

• La query recupera un utente con un determinato id.
• I campi richiesti sono id, name e email.

Tipi di Operazioni in GraphQL

Le operazioni in GraphQL possono essere di tre tipi principali:

1. Query: Per ottenere dati.

query {
  users {
    id
    name
  }
}

2. Mutation: Per modificare o creare dati.

mutation {
  createUser(name: "Alice", email: "alice@example.com") {
    id
    name
    email
  }
}

3. Subscription: Per ricevere aggiornamenti in tempo reale.

subscription {
  messageAdded {
    id
    content
  }
}

1. Campi Richiesti in una Query

In GraphQL, devi sempre specificare i campi che desideri recuperare per ciascun tipo di dato. Questo ti permette di ottenere solo le informazioni necessarie, evitando overfetching.

Esempio di Query con Campi Richiesti

query {
  user(id: "1") {
    id
    name
    email
    posts {
      title
      content
    }
  }
}

In questo esempio:

• La query recupera un utente specifico e i suoi post.
• Per ogni post, vengono restituiti title e content.

2. Argomenti nelle Query

Gli argomenti permettono di personalizzare le query in base ai parametri forniti dal client. Gli argomenti vengono spesso utilizzati per filtrare, ordinare o paginare i risultati.

Esempio di Query con Argomenti

query {
  user(id: "1") {
    id
    name
    posts(limit: 5, offset: 10) {
      title
    }
  }
}

In questo esempio:

• La query richiede un utente con un determinato id.
• Per i post dell’utente, vengono applicati i parametri di paginazione: limit e offset, per recuperare solo 5 post a partire dal decimo.

3. Alias: Rinomina i Campi

Gli alias permettono di rinominare i campi restituiti da una query. Questo è particolarmente utile quando si eseguono query su più campi dello stesso tipo con parametri diversi.

Esempio di Alias

query {
  firstUser: user(id: "1") {
    id
    name
  }
  secondUser: user(id: "2") {
    id
    name
  }
}

In questo esempio:

• Vengono richiesti due utenti con id diversi.
• Gli alias firstUser e secondUser consentono di rinominare i risultati per evitare conflitti di nomi.

Risultato della Query con Alias

{
  "data": {
    "firstUser": {
      "id": "1",
      "name": "Alice"
    },
    "secondUser": {
      "id": "2",
      "name": "Bob"
    }
  }
}

4. Frammenti: Riutilizzo di Parti della Query

I frammenti permettono di definire un insieme di campi riutilizzabile in più parti di una query o in più query. Questo è utile per evitare la duplicazione del codice e migliorare la leggibilità.

Esempio di Frammento

fragment userFields on User {
  id
  name
  email
}

query {
  user1: user(id: "1") {
    ...userFields
  }
  user2: user(id: "2") {
    ...userFields
  }
}

In questo esempio:

• Il frammento userFields definisce i campi comuni id, name e email.
• Questo frammento viene utilizzato per recuperare le stesse informazioni su due utenti diversi, evitando la duplicazione.

Risultato della Query con Frammento

{
  "data": {
    "user1": {
      "id": "1",
      "name": "Alice",
      "email": "alice@example.com"
    },
    "user2": {
      "id": "2",
      "name": "Bob",
      "email": "bob@example.com"
    }
  }
}

5. Variabili nelle Query

Le variabili permettono di rendere una query più flessibile e riutilizzabile, passando parametri esterni invece di codificarli direttamente nella query.

Esempio di Query con Variabili

query getUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}

In questo esempio, la query getUser accetta una variabile $userId, che può essere fornita dal client.

Passaggio delle Variabili

Le variabili vengono passate separatamente dalla query:

{
  "userId": "1"
}

Risultato della Query

{
  "data": {
    "user": {
      "id": "1",
      "name": "Alice"
    }
  }
}

Esecuzione di Query Multiple

In GraphQL, è possibile eseguire più query all’interno della stessa richiesta, riducendo il numero di round trip tra client e server.

Esempio di Query Multiple

query {
  user(id: "1") {
    id
    name
  }
  posts {
    id
    title
  }
}

In questo esempio:

• La query richiede contemporaneamente i dettagli di un utente e un elenco di post, tutto in un’unica richiesta.

Direttive nelle Query

Le direttive in GraphQL permettono di eseguire query condizionali o di modificare il comportamento della query stessa. Una delle direttive più comuni è @include o @skip.

Esempio con Direttiva @include

query getUser($includeEmail: Boolean!) {
  user(id: "1") {
    id
    name
    email @include(if: $includeEmail)
  }
}

In questo esempio:

• La query include il campo email solo se la variabile $includeEmail è true.

Risultato con @include

Passando includeEmail: false, il campo email non verrà restituito.

{
  "data": {
    "user": {
      "id": "1",
      "name": "Alice"
    }
  }
}

Best Practices per la Scrittura di Query

1. Richiedere Solo i Dati Necessari: Evita di richiedere campi non necessari per ridurre il carico sul server e migliorare le prestazioni.
2. Usare Frammenti: Utilizza frammenti per evitare la duplicazione del codice, soprattutto quando richiami gli stessi campi in più parti della query.
3. Implementare la Paginazione: Quando si recuperano liste di dati, utilizza argomenti come limit e offset per paginare i risultati e migliorare l’efficienza.
4. Usare Variabili: Usa le variabili per rendere le query riutilizzabili e più sicure, evitando di

hardcodare parametri. 5. Controllare la Complessità delle Query: Limita la profondità e la complessità delle query per evitare il sovraccarico del server.

Conclusione

La struttura di una query in GraphQL è semplice ma estremamente potente, consentendo ai client di richiedere esattamente i dati di cui hanno bisogno. Usando campi, argomenti, alias, frammenti e variabili, puoi creare query altamente flessibili, riutilizzabili e ottimizzate. Seguendo le best practices, puoi garantire che le tue query siano efficienti, riducendo il carico sul server e migliorando le prestazioni complessive dell’applicazione.