Tipi di Base in GraphQL: Guida Completa

In GraphQL, i tipi di base (o scalari) sono fondamentali per la definizione dello schema, poiché descrivono la forma dei dati che possono essere richiesti o modificati attraverso le query, le mutazioni e le subscriptions. Utilizzare i tipi corretti garantisce la coerenza dei dati e migliora la chiarezza e la manutenibilità dello schema. In questo articolo esploreremo i tipi di base in GraphQL, come utilizzarli e le loro applicazioni pratiche.

Tipi di Base in GraphQL

I tipi di base o scalari in GraphQL rappresentano singoli valori. Questi tipi sono analoghi ai tipi primitivi in altri linguaggi di programmazione e sono utilizzati per definire i campi che non sono relazioni tra tipi complessi.

1. Int

Int rappresenta un numero intero a 32 bit con segno. Può essere utilizzato per rappresentare valori numerici senza decimali come contatori, indici o ID numerici.

Esempio di utilizzo di Int

type User {
  id: Int!
  age: Int
}

In questo esempio:

• Il campo id è un intero obbligatorio (Int!), mentre age è opzionale.

2. Float

Float rappresenta un numero in virgola mobile a precisione doppia, utile per valori numerici con decimali come prezzi o misure.

Esempio di utilizzo di Float

type Product {
  id: ID!
  price: Float!
}

In questo esempio, price è un campo obbligatorio di tipo Float che rappresenta il prezzo di un prodotto.

3. String

String rappresenta una sequenza di caratteri testuali. È utilizzato per campi come nomi, descrizioni, email e altri dati testuali.

Esempio di utilizzo di String

type User {
  id: ID!
  name: String!
  email: String!
}

In questo esempio, name e email sono campi di tipo String che rappresentano rispettivamente il nome e l’email di un utente.

4. Boolean

Boolean rappresenta un valore di tipo vero/falso (true o false). È utile per rappresentare campi che indicano lo stato, come se un elemento è attivo o meno.

Esempio di utilizzo di Boolean

type Task {
  id: ID!
  description: String!
  completed: Boolean!
}

In questo esempio, il campo completed indica se un’attività è stata completata o meno.

5. ID

ID rappresenta un identificatore univoco e viene generalmente utilizzato per campi che devono identificare in modo univoco un oggetto, come ID di utenti, prodotti o post. È rappresentato come una String, ma semanticamente è utilizzato per rappresentare identificatori.

Esempio di utilizzo di ID

type User {
  id: ID!
  username: String!
}

In questo esempio, id è un identificatore univoco di tipo ID per l’utente.

6. Enum (Enum Types)

Gli enum sono tipi che definiscono un insieme ristretto e predefinito di valori possibili. Sono utili quando un campo può assumere solo un insieme di valori limitato.

Esempio di utilizzo di un Enum

enum UserRole {
  ADMIN
  USER
  GUEST
}

type User {
  id: ID!
  role: UserRole!
}

In questo esempio:

• Il tipo UserRole definisce un insieme di ruoli (ADMIN, USER, GUEST).
• Il campo role di un utente può avere solo uno di questi valori.

Creare Tipi Personalizzati con i Tipi Base

Oltre ai tipi di base, GraphQL consente di creare tipi personalizzati, combinando i tipi scalari per definire oggetti complessi.

Esempio di Tipo Complesso

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  views: Int
}

In questo esempio, il tipo Post combina diversi tipi scalari (ID, String, Int) e un tipo complesso (User) per descrivere un post su un blog.

Nullabilità nei Tipi di Base

In GraphQL, i campi possono essere nullabili o non nullabili. Un campo non nullabile è indicato con il simbolo ! e significa che quel campo deve sempre avere un valore. Se non è presente il !, il campo può restituire null.

Esempio di Campo Non Nullabile

type User {
  id: ID!
  name: String!
  email: String
}

In questo esempio:

• id e name sono campi non nullabili, quindi devono sempre essere presenti.
• email può essere opzionale e restituire null.

Tipi di Collezioni: Liste e Array

Oltre ai tipi scalari, GraphQL supporta liste di elementi. Una lista è una collezione di valori di un determinato tipo e viene rappresentata con le parentesi quadre [].

Esempio di Lista

type Query {
  users: [User!]!
}

In questo esempio:

• Il campo users restituisce una lista di oggetti di tipo User.
• [User!]! significa che la lista stessa non può essere null, e nessun elemento della lista può essere null.

Esempio di Lista di Tipi Base

type Query {
  numbers: [Int!]!
}

In questo esempio:

• numbers restituisce una lista di numeri interi, e ogni numero nella lista non può essere null.

Usare le Variabili nei Tipi Base

Le variabili nelle query e mutazioni GraphQL permettono di fornire input dinamici ai campi che utilizzano tipi scalari. Le variabili sono particolarmente utili nelle mutazioni e nelle query che richiedono filtri o parametri.

Esempio di Query con Variabili

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

Esempio di Mutazione con Variabili

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

Best Practices per l’Utilizzo dei Tipi Base

1. Usare i Tipi Più Restrittivi Possibili: Definire i campi come non nullabili quando possibile, in modo da garantire che il client riceva sempre dati completi e coerenti.
2. Usare Enum per Valori Fissi: Quando un campo può assumere solo un insieme ristretto di valori, utilizza un enum per garantire che vengano forniti solo valori validi.
3. Liste di Oggetti Non Nullabili: Quando utilizzi liste, specifica se gli elementi della lista possono essere null o meno, per evitare ambiguità nel comportamento.
4. Validazione degli Input: Verifica sempre i valori passati ai campi durante le mutazioni, soprattutto quando accettano input di tipo String o Int.

Conclusione

I tipi di base in GraphQL sono la fondazione su cui costruire uno schema solido e ben strutturato. Usare correttamente tipi scalari come Int, Float, String, Boolean, e ID, insieme agli enum, garantisce che i dati siano chiari, coerenti e facili da gestire. Inoltre, combinando questi tipi di base con tipi complessi personalizzati, puoi modellare dati flessibili e potenti per la tua API.