Una guida per principianti a GraphQL

Uno dei termini più comunemente discussi oggi è l'API. Molte persone non sanno esattamente cos'è un'API. Fondamentalmente, API sta per Application Programming Interface. È, come dice il nome, un'interfaccia con cui le persone - sviluppatori, utenti, consumatori - possono interagire con i dati.

Puoi pensare a un'API come a un barista. Chiedi al barista un drink e ti danno quello che volevi. Semplice. Allora perché è un problema?

Dall'inizio del web moderno, la creazione di API non è stata così difficile come sembra. Ma l'apprendimento e la comprensione delle API lo erano. Gli sviluppatori formano la maggior parte delle persone che useranno la tua API per creare qualcosa o semplicemente consumare dati. Quindi la tua API dovrebbe essere il più pulita e intuitiva possibile. Un'API ben progettata è molto facile da usare e da imparare. È anche intuitivo, un buon punto da tenere a mente quando inizi a progettare la tua API.

Usiamo REST per creare API da molto tempo. Insieme a ciò arrivano alcuni problemi. Quando crei un'API usando il design REST, dovrai affrontare alcuni problemi come:

1) avrai molti endpoint

2) sarà molto più difficile per gli sviluppatori apprendere e comprendere la tua API

3) c'è un recupero eccessivo e insufficiente di informazioni

Per risolvere questi problemi, Facebook ha creato GraphQL. Oggi, penso che GraphQL sia il modo migliore per creare API. Questo articolo ti dirà perché dovresti iniziare a impararlo oggi.

In questo articolo imparerai come funziona GraphQL. Ti mostrerò come creare un'API molto ben progettata, efficiente e potente utilizzando GraphQL.

Probabilmente hai già sentito parlare di GraphQL, poiché molte persone e aziende lo usano. Poiché GraphQL è open-source, la sua community è cresciuta enormemente.

Ora è tempo che inizi a imparare in pratica come funziona GraphQL e tutto sulla sua magia.

Che cos'è GraphQL?

GraphQL è un linguaggio di query open source sviluppato da Facebook. Ci fornisce un modo più efficiente di progettare, creare e utilizzare le nostre API. Fondamentalmente, è il sostituto di REST.

GraphQL ha molte funzionalità, come:

  1. Scrivi i dati che desideri e ottieni esattamente i dati che desideri. Niente più recupero eccessivo di informazioni come siamo abituati con REST.
  2. Ci fornisce un singolo endpoint, non più versione 2 o versione 3 per la stessa API.
  3. GraphQL è fortemente tipizzato e con ciò è possibile convalidare una query all'interno del sistema di tipi GraphQL prima dell'esecuzione. Ci aiuta a creare API più potenti.

Questa è un'introduzione di base a GraphQL: perché è così potente e perché sta guadagnando molta popolarità in questi giorni. Se vuoi saperne di più, ti consiglio di visitare il sito Web GraphQL e verificarlo.

Iniziare

L'obiettivo principale di questo articolo non è imparare come configurare un server GraphQL, quindi per ora non ci stiamo approfondendo. L'obiettivo è imparare come funziona GraphQL nella pratica, quindi utilizzeremo un server GraphQL a configurazione zero chiamato Graphpack.

Per iniziare il nostro progetto, creeremo una nuova cartella e puoi nominarla come preferisci. Lo chiamerò graphql-server:

Apri il tuo terminale e digita:

mkdir graphql-server

Ora, dovresti avere npm o filo installati nella tua macchina. Se non sai cosa siano, npm e thread sono gestori di pacchetti per il linguaggio di programmazione JavaScript. Per Node.js, il gestore pacchetti predefinito è npm.

All'interno della cartella creata digitare il comando seguente:

npm init -y

O se usi il filato:

filato init

npm creerà un file package.json per te e tutte le dipendenze che hai installato e i tuoi comandi saranno lì.

Quindi ora installeremo l'unica dipendenza che useremo.

RaGraphpack ti consente di creare un server GraphQL con configurazione zero. Dato che stiamo iniziando con GraphQL, questo ci aiuterà molto ad andare avanti e ad imparare di più senza preoccuparci della configurazione del server.

Nel tuo terminale, all'interno della cartella principale, installalo in questo modo:

npm install --save-dev graphpack

Oppure, se usi il filato, dovresti andare così:

filato aggiungere --dev graphpack

Dopo aver installato Graphpack, vai ai nostri script nel file package.json e inserisci il seguente codice:

Creeremo una cartella chiamata src e sarà l'unica cartella in tutto il nostro server.

Crea una cartella chiamata src, dopodiché, all'interno della nostra cartella, creeremo solo tre file.

All'interno della nostra cartella src creare un file chiamato schema.graphql. All'interno di questo primo file, inserisci il seguente codice:

In questo file schema.graphql sarà il nostro intero schema GraphQL. Se non sai di cosa si tratta, ti spiegherò più avanti - non preoccuparti.

Ora, all'interno della nostra cartella src, crea un secondo file. Chiamalo resolvers.js e, all'interno di questo secondo file, inserisci il seguente codice:

Questo file resolvers.js sarà il modo in cui forniamo le istruzioni per trasformare un'operazione GraphQL in dati.

E infine, all'interno della tua cartella src, crea un terzo file. Chiama questo db.js e, all'interno di questo terzo file, inserisci il seguente codice:

In questo tutorial non stiamo utilizzando un database reale. Quindi questo file db.js simulerà un database, solo a scopo di apprendimento.

Ora la nostra cartella src dovrebbe apparire così:

src
  | --db.js
  | --resolvers.js
  | --schema.graphql

Ora, se esegui il comando npm run dev o, se stai usando filato, filato dev, dovresti vedere questo output nel tuo terminale:

Ora puoi andare su localhost: 4000. Ciò significa che siamo pronti per iniziare e iniziare a scrivere le nostre prime query, mutazioni e abbonamenti in GraphQL.

Vedi GraphQL Playground, un potente IDE GraphQL per flussi di lavoro di sviluppo migliori. Se vuoi saperne di più su GraphQL Playground, clicca qui.

Schema

GraphQL ha il suo tipo di linguaggio utilizzato per scrivere schemi. Questa è una sintassi dello schema leggibile dall'uomo chiamata Schema Definition Language (SDL). L'SDL sarà lo stesso, indipendentemente dalla tecnologia che stai utilizzando: puoi utilizzarlo con qualsiasi lingua o framework tu voglia.

Questo linguaggio di schema è molto utile perché è semplice capire quali tipi avrà la tua API. Puoi capirlo solo guardandolo bene.

tipi

I tipi sono una delle caratteristiche più importanti di GraphQL. I tipi sono oggetti personalizzati che rappresentano l'aspetto dell'API. Ad esempio, se stai creando un'applicazione per social media, la tua API dovrebbe avere tipi come Post, Utenti, Mi piace, Gruppi.

I tipi hanno campi e questi campi restituiscono un tipo specifico di dati. Ad esempio, creeremo un tipo di utente, dovremmo avere alcuni campi relativi a nome, email ed età. I campi di tipo possono essere qualsiasi cosa e restituiscono sempre un tipo di dati come Int, Float, String, Boolean, ID, un elenco di tipi di oggetto o tipi di oggetti personalizzati.

Quindi ora per scrivere il nostro primo tipo, vai al tuo file schema.graphql e sostituisci il tipo Query che è già lì con il seguente:

Ogni utente avrà un ID, quindi gli abbiamo assegnato un tipo di ID. L'utente avrà anche un nome e un'e-mail, quindi gli abbiamo dato un tipo String e un'età, a cui abbiamo dato un tipo Int. Abbastanza semplice, vero?

Ma che dire di quelli! alla fine di ogni riga? Il punto esclamativo indica che i campi sono non annullabili, il che significa che ogni campo deve restituire alcuni dati in ogni query. L'unico campo nullable che avremo nel nostro tipo di utente sarà l'età.

In GraphQL, tratterai tre concetti principali:

  1. query: il modo in cui otterrai i dati dal server.
  2. mutazioni: il modo in cui modificherai i dati sul server e recupererai i dati aggiornati (crea, aggiorna, elimina).
  3. abbonamenti: il modo in cui manterrai una connessione in tempo reale con il server.

Te li spiegherò tutti. Cominciamo con le query.

Interrogazioni

Per spiegarlo in modo semplice, le query in GraphQL sono come ottenere i dati. Una delle cose più belle delle query in GraphQL è che otterrai i dati esatti che desideri. Ne più ne meno. Questo ha un enorme impatto positivo nella nostra API: non più informazioni di recupero eccessivo o insufficiente come abbiamo avuto con le API REST.

Creeremo la nostra prima query di tipo in GraphQL. Tutte le nostre domande finiranno all'interno di questo tipo. Quindi, per iniziare, andremo nel nostro schema.graphql e scriveremo un nuovo tipo chiamato Query:

È molto semplice: la query degli utenti ci restituirà una matrice di uno o più utenti. Non restituirà null, perché inseriamo il! , il che significa che è una query non annullabile. Dovrebbe sempre restituire qualcosa.

Ma potremmo anche restituire un utente specifico. Per questo creeremo una nuova query chiamata user. All'interno del nostro tipo di query, inserisci il seguente codice:

Ora il nostro tipo di query dovrebbe apparire così:

Come vedi, con le query in GraphQL possiamo anche passare argomenti. In questo caso, per richiedere un utente specifico, passeremo il suo ID.

Ma ti starai chiedendo: come fa GraphQL a sapere dove ottenere i dati? Ecco perché dovremmo avere un file resolvers.js. Quel file dice a GraphQL come e dove sta andando a recuperare i dati.

Innanzitutto, vai al nostro file resolvers.js e importa il file db.js che abbiamo appena creato qualche istante fa. Il file resolvers.js dovrebbe assomigliare a questo:

Ora creeremo la nostra prima query. Vai al tuo file resolvers.js e sostituisci la funzione ciao. Ora il tipo di query dovrebbe essere simile al seguente:

Ora, per spiegare come funzionerà:

Ogni risolutore di query ha quattro argomenti. Nella funzione utente, passeremo id come argomento, quindi restituiamo l'utente specifico che corrisponde all'ID passato. Abbastanza semplice.

Nella funzione utenti, restituiremo l'array di utenti già esistente. Restituirà sempre a noi tutti i nostri utenti.

Ora testeremo se le nostre query funzionano correttamente. Vai a localhost: 4000 e inserisci il seguente codice:

Dovrebbe restituirti tutti i nostri utenti.

Oppure, se si desidera restituire un utente specifico:

Ora inizieremo a conoscere le mutazioni, una delle caratteristiche più importanti di GraphQL.

mutazioni

In GraphQL, le mutazioni sono il modo in cui modificherai i dati sul server e recupererai i dati aggiornati. Puoi pensare come il CUD (Crea, Aggiorna, Elimina) di REST.

Creeremo la nostra prima mutazione di tipo in GraphQL e tutte le nostre mutazioni finiranno all'interno di questo tipo. Quindi, per iniziare, vai sul nostro schema.graphql e scrivi un nuovo tipo chiamato mutazione:

Come puoi vedere, avremo tre mutazioni:

createUser: dovremmo trasmettere un ID, nome, e-mail ed età. Dovrebbe restituirci un nuovo utente.

updateUser: dovremmo passare un ID e un nuovo nome, e-mail o età. Dovrebbe restituirci un nuovo utente.

deleteUser: dovremmo passare un ID. Dovrebbe restituirci un nuovo utente.

Ora, vai al nostro file resolvers.js e sotto l'oggetto Query, crea un nuovo oggetto mutazione come questo:

Ora, il nostro file resolvers.js dovrebbe assomigliare a questo:

Ora testeremo se le nostre mutazioni funzionano bene. Vai a localhost: 4000 e inserisci il seguente codice:

Dovrebbe restituirti un nuovo utente. Se vuoi provare a creare nuove mutazioni, ti consiglio di provare tu stesso! Prova a eliminare lo stesso utente che hai creato per vedere se funziona correttamente.

Infine, inizieremo a conoscere gli abbonamenti e perché sono così potenti.

Sottoscrizioni

Come ho detto prima, gli abbonamenti sono il modo in cui manterrai una connessione in tempo reale con un server. Ciò significa che ogni volta che si verifica un evento nel server e ogni volta che viene chiamato quell'evento, il server invierà i dati corrispondenti al client.

Lavorando con gli abbonamenti, puoi mantenere la tua app aggiornata alle ultime modifiche tra diversi utenti.

Un abbonamento di base è così:

Dirai che è molto simile a una query, e sì lo è. Ma funziona diversamente.

Quando qualcosa viene aggiornato nel server, il server eseguirà la query GraphQL specificata nella sottoscrizione e invierà un risultato appena aggiornato al client.

Non lavoreremo con gli abbonamenti in questo articolo specifico, ma se vuoi saperne di più clicca su di essi.

Conclusione

Come hai visto, GraphQL è una nuova tecnologia davvero potente. Ci dà il vero potere di creare API migliori e ben progettate. Ecco perché ti consiglio di iniziare a impararlo ora. Per me, alla fine sostituirà REST.

Grazie per aver letto l'articolo, per favore fai un commento qui sotto!

Seguimi su Twitter!
Seguimi su GitHub!

Sto cercando un'opportunità remota, quindi se ne ho qualcuno che mi piacerebbe sentirne parlare, quindi per favore contattami sul mio Twitter!