Fondamenti di GraphQL per sviluppatori React

REST espone endpoint con struttura fissa: GET /users/:id restituisce l'intero oggetto utente, indipendentemente dai dati necessari al client. GraphQL consente ai client di specificare esattamente i campi desiderati, eliminando l'over-fetching (troppi dati) e l'under-fetching (dati insufficienti, che richiedono più richieste).

Una singola query GraphQL può recuperare un utente, i suoi post e l'autore di ogni post in un unico round-trip.

Ogni API GraphQL è definita da uno schema scritto in Schema Definition Language (SDL). Lo schema dichiara i tipi, i relativi campi e i tipi radice Query, Mutation e Subscription su cui i client possono operare.

Lo schema è il contratto tra client e server. I team frontend e backend possono lavorare in parallelo una volta concordato lo schema.

Una query GraphQL seleziona i campi: { user(id: "1") { name email posts { title } } }. I campi annidati attraversano le relazioni in un'unica richiesta. Gli alias rinominano i campi: { me: user(id: "1") { name } }. I fragment riutilizzano le selezioni dei campi in più query.

Le variabili rendono riutilizzabili le query: query GetUser($id: ID!) { user(id: $id) { name } } con variables: { id: "1" }.

Ogni campo nello schema GraphQL ha una funzione resolver sul server. Quando un client interroga user.name, il resolver user recupera l'oggetto utente e il resolver name, oppure il resolver predefinito, restituisce il campo name.

Questa risoluzione a livello di campo consente a GraphQL di recuperare con precisione solo i dati richiesti.

Se si interroga un elenco di 100 post e ogni post include il relativo autore, un'implementazione ingenua esegue 100 query separate al database per recuperare gli autori. Questo problema N+1 rende lente le API GraphQL se non viene ottimizzato.

DataLoader risolve il problema N+1 raggruppando tutte le richieste degli autori in un'unica query al database, usando una cache per richiesta e una funzione di batching.

Apollo Studio e GraphQL Playground sono interfacce utente accessibili dal browser per esplorare interattivamente un'API GraphQL. Completano automaticamente i campi in base allo schema, mostrano i risultati delle query e visualizzano la documentazione dei tipi direttamente nell'interfaccia.

Utilizzare il playground è il modo più rapido per comprendere un'API GraphQL sconosciuta prima di scrivere il codice client.

Le API GraphQL espongono il proprio schema tramite una query di introspezione: { __schema { types { name } } }. I client possono interrogare lo schema stesso per scoprire i tipi, i campi e gli argomenti disponibili.

Gli strumenti di generazione del codice come graphql-codegen usano l'introspezione per generare automaticamente tipi TypeScript corrispondenti allo schema dell'API.

Le mutation GraphQL modificano i dati: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Le subscription stabiliscono una connessione persistente, in genere WebSocket, e inviano gli aggiornamenti: subscription { postAdded { id title } }.

Tutti e tre i tipi radice (Query, Mutation, Subscription) usano la stessa sintassi per la selezione dei campi.

GraphQL è particolarmente adatto alle applicazioni con requisiti di dati complessi e annidati, a più tipi di client (mobile, web, TV) che necessitano di sottoinsiemi di campi diversi o ad API in rapida evoluzione, nelle quali la deprecazione dei campi è preferibile alla gestione delle versioni degli endpoint.

REST è più semplice per le API CRUD con forme delle risorse prevedibili e piatte e ottime caratteristiche di caching HTTP grazie a ETag e intestazioni di cache.

Apollo Client è il client GraphQL più completo: cache normalizzata, gestione dello stato locale, subscription e link per la gestione degli errori. URQL è più leggero, con una document cache e un'API più semplice. React Query con graphql-request è l'approccio più semplice per query+mutation di base senza funzionalità avanzate di caching.

Scelga in base ai requisiti di caching: una cache normalizzata per le entità condivise tra più query (Apollo), oppure una document cache più semplice per query indipendenti (URQL o React Query).

Un SDL semplice: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. I punti esclamativi indicano i campi non null.

Questo schema indica al client esattamente quali campi esistono per ogni tipo e quali query sono disponibili, consentendo la generazione di codice con controllo dei tipi.

Che cosa significa "over-fetching" nel contesto del confronto tra REST e GraphQL?

GraphQL consente ai client di richiedere esattamente i campi necessari, senza over-fetching o under-fetching, usando un linguaggio di query definito dallo schema. I resolver rispondono per ogni campo; DataLoader risolve il problema N+1. L'introspezione consente di generare tipi TypeScript. Apollo Client, URQL e React Query sono i principali client GraphQL compatibili con React.

Scelga GraphQL per requisiti di dati complessi, annidati e destinati a più client; scelga REST per operazioni CRUD semplici con forme prevedibili.