Utilizzo delle Variabili in GraphQL: Guida Completa

Codegrind Team•Sep 05 2024

Le variabili in GraphQL permettono di rendere le query e le mutazioni più dinamiche e riutilizzabili, separando la logica dell’operazione dai dati che vengono passati al momento dell’esecuzione. Utilizzare le variabili rende le operazioni più flessibili e sicure, poiché evita la necessità di concatenare manualmente i parametri all’interno delle query. In questo articolo esploreremo come dichiarare, passare e utilizzare le variabili in GraphQL per ottimizzare le operazioni su dati dinamici.

Cos’è una Variabile in GraphQL?

Le variabili in GraphQL sono valori dinamici che vengono passati a una query o mutazione al momento della sua esecuzione. Invece di hardcodare i valori direttamente nella query, puoi dichiarare delle variabili e passare i valori esternamente, riducendo così la duplicazione di codice e migliorando la manutenibilità.

Vantaggi dell’Uso delle Variabili:

Sicurezza: Evita l’inserimento manuale di valori che potrebbero introdurre rischi di sicurezza, come l’injection di codice.
Riutilizzo: Le query e mutazioni possono essere scritte una volta e riutilizzate con dati diversi.
Flessibilità: Permette di passare valori dinamici in base alle condizioni dell’applicazione.

Dichiarare e Utilizzare Variabili in GraphQL

Una query o mutazione con variabili ha due componenti principali:

Dichiarazione delle Variabili: Specifica i tipi di variabili e i loro nomi direttamente nella query o mutazione.
Valori delle Variabili: I valori effettivi vengono passati come input separati durante l’esecuzione della query o mutazione.

Sintassi della Dichiarazione delle Variabili

Le variabili vengono dichiarate nella parte iniziale di una query o mutazione, all’interno di parentesi tonde. Ogni variabile ha un nome preceduto dal simbolo $ e un tipo associato.

Esempio di Query con Variabili

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

In questo esempio:

$id è una variabile di tipo ID!, che viene utilizzata per passare un identificativo utente dinamico alla query getUser.
La query user(id: $id) utilizza la variabile $id per recuperare i dati dell’utente specifico.

Passare i Valori delle Variabili

Durante l’esecuzione della query, i valori delle variabili vengono passati separatamente. Ad esempio, se esegui una query tramite GraphQL Playground o un client come Apollo Client o URQL, puoi specificare i valori delle variabili in un oggetto separato.

Esempio di Esecuzione con Valori delle Variabili

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

Con le seguenti variabili:

{
  "id": "1"
}

Il client GraphQL utilizza il valore "1" per la variabile $id e restituirà i dati dell’utente corrispondente.

Esempio di Mutazione con Variabili

Le variabili possono essere utilizzate anche nelle mutazioni, consentendo di inviare dati dinamici per creare, aggiornare o eliminare risorse.

mutation createUser($name: String!, $email: String!) {
  createUser(name: $name, email: $email) {
    id
    name
    email
  }
}

Con le seguenti variabili:

{
  "name": "Alice",
  "email": "alice@example.com"
}

In questo esempio:

La mutazione createUser crea un nuovo utente utilizzando i valori delle variabili $name e $email.

Esecuzione della Mutazione

Quando esegui questa mutazione, i valori delle variabili vengono passati dall’esterno:

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

Restituirà un nuovo oggetto utente con i campi id, name, e email.

Tipi di Variabili in GraphQL

Le variabili devono avere un tipo associato, che può essere uno dei tipi scalari predefiniti di GraphQL o un tipo personalizzato. Puoi utilizzare gli stessi tipi che usi per definire i campi nei tuoi schemi GraphQL.

Tipi Scalari per le Variabili

String: Per valori testuali.
Int: Per numeri interi.
Float: Per numeri decimali.
Boolean: Per valori vero/falso.
ID: Per identificatori univoci.

Esempio di Variabili con Diversi Tipi

query getProduct($id: ID!, $available: Boolean) {
  product(id: $id, available: $available) {
    id
    name
    price
    available
  }
}

In questo esempio, $id è una variabile obbligatoria di tipo ID!, mentre $available è una variabile opzionale di tipo Boolean.

Tipi Input Personalizzati per le Variabili

Le variabili possono anche essere di tipo input, che permette di passare oggetti più complessi come argomenti.

Esempio di Tipo Input con Variabili

input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

mutation createUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    name
    email
  }
}

In questo esempio, la variabile $input utilizza il tipo personalizzato CreateUserInput, che consente di passare i dettagli dell’utente come un oggetto complesso.

Le variabili passate alla mutazione saranno simili a questo:

{
  "input": {
    "name": "Bob",
    "email": "bob@example.com",
    "age": 30
  }
}

Default Values per le Variabili

Puoi anche specificare valori predefiniti per le variabili in una query o mutazione. Se il client non passa un valore per una variabile, il valore predefinito verrà utilizzato.

Esempio con Valori Predefiniti

query getUsers($limit: Int = 10) {
  users(limit: $limit) {
    id
    name
  }
}

In questo esempio:

Se il client non fornisce un valore per la variabile $limit, verrà utilizzato il valore predefinito 10.
Se viene fornito un valore, sovrascriverà il valore predefinito.

Utilizzare Variabili con URQL e Apollo Client

Le librerie client GraphQL come URQL e Apollo Client rendono facile utilizzare variabili nelle query e nelle mutazioni.

Esempio con URQL

import { useQuery } from "urql";

const UsersQuery = `
  query ($limit: Int) {
    users(limit: $limit) {
      id
      name
    }
  }
`;

const UsersList = () => {
  const [result] = useQuery({
    query: UsersQuery,
    variables: { limit: 5 },
  });

  if (result.fetching) return <p>Loading...</p>;
  if (result.error) return <p>Oh no... {result.error.message}</p>;

  return (
    <ul>
      {result.data.users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

In questo esempio, la variabile limit viene passata all’oggetto useQuery per limitare il numero di utenti recuperati.

Esempio con Apollo Client

import { useQuery, gql } from "@apollo/client";

const GET_USERS = gql`
  query GetUsers($limit: Int) {
    users(limit: $limit) {
      id
      name
    }
  }
`;

const UsersList = () => {
  const { loading, error, data } = useQuery(GET_USERS, {
    variables: { limit: 5 },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data.users.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

In questo esempio, la variabile limit viene passata a useQuery di Apollo Client per limitare il numero di utenti.

Best Practices

per l’Uso delle Variabili

Utilizza Variabili per Evitare Hardcoding: Evita di inserire direttamente valori dinamici nelle query. Usa variabili per migliorare la leggibilità e la sicurezza.
Definisci Tipi Chiari per le Variabili: Assicurati che le variabili abbiano tipi ben definiti per garantire che i valori passati siano corretti.
Imposta Valori Predefiniti: Usa i valori predefiniti per rendere opzionali alcune variabili, senza dover passare ogni volta un valore dal client.
Riutilizza Query e Mutazioni: Utilizzare le variabili ti permette di riutilizzare la stessa query o mutazione con diversi set di dati.

Conclusione

Le variabili in GraphQL sono uno strumento potente per rendere le query e mutazioni più dinamiche e flessibili. Separando i dati dalla logica dell’operazione, puoi creare query e mutazioni più riutilizzabili, migliorare la sicurezza e semplificare il codice. Sia che tu stia utilizzando URQL, Apollo Client o un altro client GraphQL, le variabili ti permettono di passare input dinamici in modo semplice ed efficace.