GraphQL: Linguaggio di Query per API

GraphQL: Linguaggio di Query per API

GraphQL è un linguaggio di query e runtime per API che permette ai client di richiedere esattamente i dati di cui hanno bisogno. Sviluppato da Facebook (2012), open-sourced (2015).

Concetti Fondamentali

Schema: Contratto fortemente tipizzato (SDL - Schema Definition Language). Tipi: Scalar (String, Int, Float, Boolean, ID), Object, Interface, Union, Enum, Input. Query: Operazioni lettura. Mutation: Operazioni scrittura. Subscription: Aggiornamenti real-time. Resolver: Funzione che recupera dati per un campo.

Design Schema

Progetta per client, non per database. Usa interfacce per polimorfismo. Connections per paginazione (spec Relay: edges, nodes, pageInfo). Identificazione oggetto globale (interfaccia Node). Nullability: Sii esplicito, evita campi nullable dove possibile. Deprecazione: Direttiva @deprecated con motivo.

Resolver e Data Loading

Firma resolver: (parent, args, context, info). Problema N+1: Usa DataLoader (batching + caching). Context: Request-scoped (auth, DB, loaders). Resolver modulari: Split per dominio. Direttive: @auth, @rateLimit, @cacheControl.

GraphQL Federation

Componi più servizi GraphQL in un supergraph unificato. Entities: Tipi condivisi across subgraph (@key). Gateway: Inoltra query ai subgraph (Apollo Router, Cosmo Router, GraphQL Mesh). Subgraph: Servizio indipendente con proprio schema. Vantaggi: Autonomia team, deployment indipendente, polyglot.

Subscription e Real-time

Basato su WebSocket (protocollo graphql-ws). Server push aggiornamenti. Casi d'uso: Notifiche, dashboard live, editing collaborativo. Scaling: Redis pub/sub, sticky sessions. Filtraggio: Invia solo aggiornamenti rilevanti.

Strategie Caching

Cache normalizzata (Apollo Client, urql, Relay): Memorizza per __typename + ID. HTTP caching: Non nativo (richieste POST), usa GET per query (Persisted Queries). CDN: Automatic Persisted Queries (APQ) + CDN. Direttive cache: @cacheControl(maxAge, scope).

Sicurezza

Limitazione profondità: Previeni query profondamente annidate. Analisi costo: Assegna costo a campi, limita totale. Rate limiting: Per client, per operazione. Introspezione: Disabilita in produzione. Auth a livello campo: Direttiva @auth. Query allowlist: Permetti solo query pre-approvate (Persisted Queries).

GraphQL vs REST

GraphQL: Singolo endpoint, client-driven, niente over/under-fetching, strong typing, introspezione, federation. REST: Endpoint multipli, server-driven, caching nativo, più semplice, tooling più ampio. Scegli GraphQL per: Relazioni complesse, client multipli, iterazione rapida. Scegli REST per: Risorse semplici, API pubbliche, caching critico, familiarità team.

Ecosistema Tooling

Server: Apollo Server, Yoga, GraphQL.js, Mercurius (Fastify), Strawberry (Python), gqlgen (Go). Client: Apollo Client, urql, Relay, TanStack Query (GraphQL). Codegen: GraphQL Code Generator. Testing: GraphQL Voyager, Postman, Insomnia. Monitoring: Apollo Studio, Grafana.