Ciao, e benvenuto nella quarta puntata della quarantaquattresima stagione. Nelle scorse puntate abbiamo visto che il cliente chiede la forma che vuole, percorrendo un grafo. Ma sorge subito una domanda: se il cliente può chiedere qualunque cosa, come fa a sapere cosa c'è? Quali cose esistono, quali campi hanno, come sono collegate? La risposta è una delle parti più belle di GraphQL: lo schema. Oggi capiamo lo schema e i tipi, la mappa di tutto, che è insieme un menù e una garanzia.
Partiamo dal bisogno, perché è concreto. Se ti do la penna per chiedere qualunque forma di dati, ti serve una mappa di cosa è disponibile. Non puoi chiedere alla cieca: devi sapere che esistono gli utenti, che un utente ha un nome e un'email, che è collegato ai suoi articoli, e così via. Senza una mappa, brancoleresti, tentando a caso. GraphQL risolve questo con lo schema: una descrizione formale, esplicita e completa dell'intero grafo. Ogni tipo di cosa che esiste, ogni suo campo, ogni suo collegamento, tutto scritto nero su bianco, in un unico posto.
Voglio aggiungere l'idea dei tipi, perché rende lo schema preciso. Lo schema non dice solo quali cose e campi esistono: dice anche di che tipo è ciascuno. Questo campo è un testo, quello è un numero, quest'altro è una data; un utente ha molti articoli; un articolo ha un solo autore. Ogni pezzo del grafo è etichettato con la sua natura. Questa tipizzazione, questa precisione, fa una differenza enorme, perché rende lo schema esatto e non ambiguo. Non c'è da indovinare: lo schema ti dice con certezza che forma ha ogni cosa, e che forma avrà ogni risposta.
Voglio farti vedere che lo schema è due cose in una, perché è la sua magia. Lo schema è, allo stesso tempo, un menù e una garanzia. È un menù, perché elenca tutto ciò che puoi chiedere: guardandolo, sai esattamente quali domande sono possibili. Ed è una garanzia, perché ti promette la forma e il tipo esatti di ciò che riceverai: se chiedi un campo che lo schema dice essere un numero, riceverai un numero. Menù e contratto insieme: da un lato ti mostra le possibilità, dall'altro ti assicura cosa otterrai. Sai in anticipo sia cosa puoi chiedere, sia cosa ti tornerà.
Voglio darti la proprietà più affascinante, perché è quasi magica. Lo schema, in GraphQL, descrive sé stesso. Il servizio è capace di raccontarti il proprio schema: puoi chiedergli quali cose esistono, quali campi hanno, come si collegano, e lui te lo dice. È auto-descrittivo. E questo apre possibilità bellissime: gli strumenti di sviluppo possono suggerirti i campi mentre scrivi la richiesta, completandola per te; possono controllare la tua richiesta e segnalarti un errore prima ancora che tu la invii; possono generare la documentazione da soli, sempre aggiornata. Un servizio che sa descriversi non ha bisogno di un manuale a parte: è il manuale di sé stesso.
Voglio farti apprezzare perché questo valga tanto, perché tocca temi che abbiamo amato. Pensa a cosa significa avere un contratto formale, condiviso e verificabile. Da un lato il cliente, dall'altro il servizio, si incontrano su un unico punto d'accordo: lo schema. Il frontend e il backend, come dicemmo tempo fa, si danno appuntamento lì. E poiché è tipizzato, tutta una categoria di errori viene colta subito: se chiedi un campo che non esiste, la richiesta viene rifiutata immediatamente, con chiarezza, non fallisce misteriosamente più tardi. Un accordo esplicito e verificabile trasforma un sistema da qualcosa che sondi a tentoni a qualcosa su cui puoi ragionare con sicurezza.
Voglio darti l'immagine che rende chiara questa idea, e la lezione. Pensa al catalogo di un grande magazzino, ma un catalogo perfetto: non solo l'elenco dei prodotti, ma per ciascuno le sue caratteristiche esatte, e come si collega agli altri, così preciso che puoi compilare un ordine impeccabile e sapere in anticipo esattamente cosa arriverà. E per di più, un catalogo che descrive sé stesso, così non ti serve mai un manuale separato. La lezione è questa: un contratto formale, condiviso e auto-descrittivo, uno schema, trasforma un sistema da qualcosa da esplorare per tentativi a qualcosa su cui ragionare con fiducia. Rendere l'accordo esplicito e preciso è un regalo a chiunque ci costruisca sopra.
Per oggi ci fermiamo qui. Se il cliente può chiedere qualunque forma, gli serve una mappa: ed è lo schema, la descrizione formale e completa dell'intero grafo, con ogni cosa, ogni campo, ogni collegamento. Tipizzato, cioè preciso: ogni pezzo etichettato con la sua natura, testo, numero, data. Lo schema è due cose in una, un menù di ciò che puoi chiedere e una garanzia di ciò che riceverai. E per di più descrive sé stesso, così gli strumenti possono suggerire, controllare, documentare da soli. La lezione: un contratto formale, condiviso e auto-descrittivo trasforma un sistema in qualcosa su cui ragionare con fiducia. Nella prossima puntata vediamo una sola porta: l'endpoint unico. Nelle note trovi qualche spunto. Se ti è utile, condividila. Grazie per l'ascolto, e ci sentiamo alla prossima.