GraphQL — Cheat Sheet

Tag: graphql, api, query, mutation, schema, resolver, apollo, backend

Livello: intermedio

TL;DR: Linguaggio di query per API che permette al client di richiedere esattamente e solo i dati necessari, eliminando over-fetching e under-fetching tramite un singolo endpoint.

Concetti chiave

Schema fortemente tipizzato (SDL) che funge da contratto rigoroso tra client e server.

Query utilizzate per la lettura dei dati (operazioni read-only).

Mutation utilizzate per la scrittura, modifica o cancellazione dei dati.

Subscription per ricevere aggiornamenti in tempo reale, solitamente implementate via WebSocket.

Resolver: funzioni lato server incaricate di recuperare i dati reali per uno specifico campo dello schema.

Singolo endpoint (solitamente /graphql) rispetto alla pletora di URL specifici per risorsa in REST.

Previene l'over-fetching (scaricare dati inutili) e l'under-fetching (dover fare più chiamate in cascata).

Domande tipiche e risposte pronte

Q: Qual è la differenza principale di architettura tra REST e GraphQL?R: REST si basa su endpoint multipli, uno per ogni risorsa. In GraphQL espongo un singolo endpoint e il client descrive la forma esatta del JSON di risposta che desidera.

Q: Come risolvi il famigerato problema N+1 in GraphQL?R: Uso strumenti come DataLoader. Mi permette di fare batching e caching delle richieste al database a livello di singola request, accorpando le chiavi richieste dai vari resolver.

Q: Come gestisci l'autenticazione in GraphQL?R: La gestisco a livello di contesto (context). Passo il token o l'utente decodificato nell'oggetto context condiviso tra tutti i resolver, verificando lì i permessi.

Insidie e errori comuni

Ignorare il problema N+1: query a cascata nei resolver annidati che moltiplicano esponenzialmente le query al database.

Mancanza di controlli sulla profondità (depth limiting) o complessità della query, esponendo il server ad attacchi DoS.

Difficoltà nel caching HTTP standard (es. CDN) perché le richieste GraphQL sono quasi sempre chiamate POST sullo stesso URL.

Snippet e comandi

# Esempio di Schema Definition Language (SDL)
type User {
  id: ID!
  name: String!
  email: String
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
}

type Query {
  getUser(id: ID!): User
}

type Mutation {
  createUser(name: String!, email: String): User
}

Da ripassare

[ ] Implementazione pratica di DataLoader con batching delle query SQL

[ ] Gestione del caching con Apollo Client (fetch policies)

[ ] Direttive GraphQL personalizzate per il controllo degli accessi

[x] Sintassi base per definire type, input, enum e interface