Che cos'è GraphQL?

GraphQL è un linguaggio di query per le API e un runtime lato server che restituisce esattamente i campi richiesti da ogni client in una sola richiesta. La dualità conta: il linguaggio è una specifica che qualsiasi client può parlare; il runtime esegue quelle query contro un sistema di tipi definito sopra i dati già esistenti – qualsiasi database, qualsiasi servizio. Non è un database, e non sostituisce né l’archiviazione né, necessariamente, l’API REST.

Punti chiave

La demo caratteristica: query e risposta

La demo verso cui converge ogni spiegazione, perché è l’idea – la risposta è la query, compilata:

# Richiesta                            # Risposta
{                                      {
  post(id: "8fk2") {                     "data": {
    title                                  "post": {
    author {                                 "title": "Hello GraphQL",
      username                               "author": {
    }                                          "username": "ada"
    comments(first: 2) {                     },
      text                                   "comments": [
    }                                          { "text": "Nice." },
  }                                            { "text": "Ship it." }
}                                            ]
                                           }
                                         }
                                       }

Una sola richiesta, tre risorse collegate, zero campi non richiesti – la coppia overfetching e underfetching mandata in pensione in un colpo solo. Chiamarla da client reali è HTTP ordinario:

// JavaScript / Node.js — query Back4app's auto-generated GraphQL API
const res = await fetch('https://parseapi.back4app.com/graphql', {
  method: 'POST',
  headers: {
    'X-Parse-Application-Id': APP_ID,
    'X-Parse-Client-Key': CLIENT_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: '{ posts(first: 20) { edges { node { title author { username } } } } }',
  }),
});
const { data } = await res.json(); // shaped exactly like the query

// Flutter / Dart — query Back4app's auto-generated GraphQL API
final res = await http.post(
  Uri.parse('https://parseapi.back4app.com/graphql'),
  headers: {
    'X-Parse-Application-Id': appId,
    'X-Parse-Client-Key': clientKey,
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'query': '{ posts(first: 20) { edges { node { title author { username } } } } }',
  }),
);
final data = jsonDecode(res.body)['data']; // shaped exactly like the query

// iOS / Swift — query Back4app's auto-generated GraphQL API
var request = URLRequest(url: URL(string: "https://parseapi.back4app.com/graphql")!)
request.httpMethod = "POST"
request.setValue(appId, forHTTPHeaderField: "X-Parse-Application-Id")
request.setValue(clientKey, forHTTPHeaderField: "X-Parse-Client-Key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let query = "{ posts(first: 20) { edges { node { title author { username } } } } }"
request.httpBody = try JSONEncoder().encode(["query": query])
let (data, _) = try await URLSession.shared.data(for: request)
// data is shaped exactly like the query

// Android / Kotlin — query Back4app's auto-generated GraphQL API
val body = """{ "query": "{ posts(first: 20) { edges { node { title author { username } } } } }" }"""
val request = Request.Builder()
    .url("https://parseapi.back4app.com/graphql")
    .addHeader("X-Parse-Application-Id", APP_ID)
    .addHeader("X-Parse-Client-Key", CLIENT_KEY)
    .post(body.toRequestBody("application/json".toMediaType()))
    .build()
val data = client.newCall(request).execute().body?.string() // shaped like the query

Schema, query, resolver: il trio che fa il lavoro

Le spiegazioni mostrano la query; quasi nessuna mostra il meccanismo che le sta dietro come un quadro coerente. Lo schema è il contratto tipizzato, scritto in SDL:

type Post {
  title: String!          # ! = non nullo
  author: User!
  comments(first: Int): [Comment!]
}

type Query {              # i punti di ingresso in lettura
  post(id: ID!): Post
}

type Mutation {           # i punti di ingresso in scrittura
  createPost(title: String!): Post!
}

I resolver sono l’altra metà del runtime – una funzione per campo, ognuna libera di recuperare i dati da qualsiasi parte:

const resolvers = {
  Query: {
    post: (_, { id }) => db.posts.findById(id),
  },
  Post: {
    author: (post) => db.users.findById(post.authorId),   // chiamata per ogni post!
  },
};

L’esecuzione è una pipeline: analizzare la query, validarla contro lo schema (le operazioni non valide muoiono prima di toccare i dati), poi percorrere il selection set chiamando i resolver e assemblare il JSON speculare. Quella chiamata di resolver per ogni campo è anche il cartellino del prezzo della flessibilità – si noti il // chiamata per ogni post!, che più sotto diventa il problema N+1. Il nome, che nessuno spiega: i dati formano un grafo di oggetti tipizzati, e le query lo attraversano partendo dai campi radice – ma solo lungo i percorsi esposti dallo schema, non con attraversamenti arbitrari come in un vero linguaggio di query su grafi.

Provenienza, in breve: creato in Facebook (oggi Meta) nel 2012 per le sue app mobile, rilasciato open source nel 2015, governato dal 2018 dalla GraphQL Foundation sotto la Linux Foundation, edizione attuale della spec di ottobre 2021, con una bozza GraphQL over HTTP che standardizza le convenzioni di trasporto.

Query, mutation, subscription

Le query leggono. Le mutation scrivono – e selezionano campi sul risultato, così il client riceve lo stato post-scrittura nello stesso giro di andata e ritorno. Le subscription tengono aperta una connessione (in pratica WebSocket) e spingono gli eventi appena si verificano; sono il capitolo tempo reale di GraphQL, con l’avvertenza che ogni subscription attiva è stato tenuto dal server. Tutte e tre condividono lo schema, il sistema di tipi e gli strumenti – un contratto, tre tempi verbali.

GraphQL vs. REST

L’argomento completo – incluso quando REST è semplicemente la scelta migliore – vive nella voce dedicata GraphQL vs. API REST.

GraphQL in produzione: i costi onesti

La sezione che le spiegazioni commerciali addolciscono. Cache: un solo endpoint POST rinuncia alla cache HTTP e CDN indicizzata per URL; il rimpiazzo sono cache normalizzate lato client indicizzate su id più __typename, e le persisted query (operazioni pre-approvate e sottoposte ad hash, inviate come GET) per recuperare una parte della cache di trasporto. N+1: resolver ingenui trasformano una lista di 20 post in 1 + 20 letture sul database – lo stesso problema che i client REST hanno su HTTP, trasferito nel livello dei resolver e corretto lì con loader di batching come DataLoader. Errori: GraphQL restituisce 200 OK con un array errors – il monitoring basato sui codici di stato diventa cieco se non viene rieducato. Rate limiting: le richieste non si equivalgono quando una sola può annidare dieci relazioni; le API mature misurano il costo della query (analisi di profondità e complessità), non il numero di richieste. Sicurezza: conviene disattivare l’ispezione in produzione, imporre limiti di profondità e complessità e tenere l’autorizzazione nel livello di business sotto i resolver – l’endpoint unico accieca anche le regole WAF basate sull’URL, quindi la validazione si sposta dentro il livello GraphQL stesso.

Casi d’uso tipici

• App mobile su reti limitate – il caso d’uso fondativo: campi esatti, byte minimi, meno andate e ritorni.
• Prodotti multi-client – app per orologio, app per telefono, dashboard web, ognuna che modella le proprie risposte contro un unico schema.
• Aggregazione backend-for-frontend – un livello GraphQL che compone diversi servizi interni per il consumo da parte delle UI.
• Frontend che evolvono rapidamente – schermate nuove selezionano campi nuovi senza attendere endpoint nuovi.
• Contratti tipizzati da un capo all’altro – l’ispezione dello schema genera client tipizzati, tenendo API e UI onesti già in compilazione.

Conviene usare GraphQL? Matrice decisionale

Limiti e trade-off

• La flessibilità la paga il server. Query arbitrarie dal client impongono che il server sia sicuro sotto qualsiasi forma – batching, limiti di costo e guardrail di profondità sono prerequisiti, non rifiniture.
• La cache diventa un progetto a sé. Quello che HTTP regalava a REST, i team GraphQL lo reimplementano in cache lato client e persisted query.
• L’osservabilità va reimparata. Un solo endpoint, risposte sempre a 200 e tempi per campo richiedono strumenti che capiscano GraphQL.
• Upload di file e dati binari sono scomodi – di solito delegati a endpoint di upload separati, accanto al grafo.
• La governance dello schema è organizzativa. Un contratto condiviso fra team ha bisogno di regole di proprietà; la federazione (comporre subgraph posseduti dai singoli team in un supergraph) è la risposta alla scala, e una disciplina a sé.

GraphQL su Back4app

Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. La parte distintiva è da dove arriva lo schema: si definisce un modello di dati e la piattaforma genera l’API GraphQL – tipi di oggetto tipizzati, campi di query e mutation, connection che attraversano le relazioni come nell’esempio posts → author qui sopra – senza resolver da scrivere, perché Back4app li implementa contro il database con i permessi applicati a ogni richiesta. Le schede di codice mostrano tutta la storia lato client: un POST verso /graphql con le chiavi dell’app. Una console GraphQL integrata copre l’esplorazione, REST resta disponibile sugli stessi dati per letture compatibili con la cache, e la logica su misura entra nello schema sotto forma di funzioni Cloud Code – la sezione dei costi onesti qui sopra diventa in gran parte la fattura della piattaforma, non quella di chi sviluppa.