GraphQL: lezioni apprese in produzione

È il 2020. Il vostro squadra si orienta sempre più verso la costruzione di applicazioni a pagina singola, o almeno verso l'inclusione di componenti ricchi all'interno di normali applicazioni a più pagine. [GraphQL](https://graphql.org/) ha ormai [più di due anni](https://en.wikipedia.org/wiki/GraphQL), il che per JavaScript Gli standard dell'ecosistema possono essere considerati maturi. Ci sentivamo un po' avventurosi, quindi abbiamo rinunciato alle solite API JSON e ci siamo tuffati a capofitto: ecco cosa abbiamo imparato.

È necessario un server GraphQL

Nella maggior parte dei framework utilizzati per sviluppo webGli strumenti per costruire un'API JSON ci sono già. È possibile costruire una struttura di rotte e accettare facilmente alcuni GET e POST, quindi produrre una risposta JSON. Ruby on Rails ha persino uno speciale progetto che fa a meno delle solite chicche di rendering HTML e mette al suo posto una solida base per le API. Ne consegue che uno sviluppatore esperto che utilizza strumenti moderni può creare un backend in pochi minuti.

Non è così con GraphQL. Mentre esistono librerie server per molte lingueMa si incorre comunque in una penalizzazione in termini di velocità fin dall'inizio, semplicemente dovendo capire cosa è giusto per il proprio ecosistema. A titolo personale, non mi piace che il termine "server" venga usato per descrivere una libreria che può essere introdotta in un progetto.

C'è solo un punto finale

Nel corso degli anni ci siamo abituati a un modo particolare di pensare alla struttura delle API. Al livello più elementare, abbiamo semplicemente seguito le pratiche REST. Ciò significava creare diversi endpoint per ogni modello logico della nostra applicazione. È una struttura facile da comprendere sia per gli autori che per i consumatori delle API. Inoltre, produce metodi ben distribuiti nel backend, rendendo più semplice il ragionamento sulle API. codice come semplice come l'API stessa. Questa struttura è anche facile da spazializzare, ad esempio per gli scopi di Versione dell'API.

GraphQL impiega solo un singolo endpoint, comunemente /graphql. Ogni richiesta all'API arriverà come richiesta POST a quell'endpoint e da lì sarà responsabilità del server GraphQL capire cosa vuole il cliente e rispondere in modo appropriato.

A prima vista sembra ingombrante: immaginate di provare a fare tutto quello che c'è in un'API JSON con un singolo endpoint! Tuttavia, la deprecazione inizia presto ad avere senso quando l'API matura e alcune cose vengono sostituite da altre. La deprecazione nelle API classiche viene solitamente effettuata a livello di spazio dei nomi, passando da v1 a v2. GraphQL consente un controllo molto maggiore, fino alla deprecazione di un singolo campo. Immaginate di poter dire a un utente di API REST che non volete che usi il campo nome e di utilizzare il campo nome_di_fantasia invece! È emerso che ciò che all'inizio sembrava ingombrante è in realtà una delle caratteristiche migliori.

Tutto è digitato

JSON non ha molto in termini di tipizzazione. Ci sono stringhe, numeri, array e oggetti. Al di là di questo, si è sfortunati. Al contrario, in GraphQL, tutto inizia e finisce con i tipi, poiché anche le query e le mutazioni sono solo questo: tipi. Il DSL GraphQL impone il controllo dei tipi sia sul server che sul client, evitando ogni sorta di spiacevole sorpresa.

Si tratta di un aspetto molto importante, soprattutto perché le SPA vengono sempre più spesso sottoposte a controlli di tipo, sia con l'uso di TypeScript che di alternative come Flow. GraphQL facilita l'introduzione di tipi complessi e composti in aggiunta ai valori predefiniti e diventa rapidamente una seconda natura per gli sviluppatori sia del backend che del frontend.

Per saperne di più: Prova dell'JavaScript... con Ruby?!

I documenti sono integrati

In una classica API JSON, la documentazione può essere un ripensamento. E anche se non lo è, ci sono molti metodi tra cui scegliere. Usiamo uno schema come OpenAPI? Dobbiamo poi convertirlo in forma leggibile dall'uomo con strumenti come Swagger? O semplicemente scarichiamo un mucchio di file Markdown da qualche parte? Anche se questo problema è stato risolto più volte, richiede ancora una riflessione e uno sforzo consapevole da parte del team: prima per costruire i documenti, poi per mantenerli aggiornati e diffonderli. È un problema ancora più complesso quando l'API ha diverse sezioni che sono accessibili solo, ad esempio, da determinati ruoli utente.

In GraphQL la documentazione è un cittadino di prima classe, poiché la maggior parte dei server consente di documentare i tipi e le richieste in loco. Dall'inizio del 2018 il GraphQL Schema Definition Language è stato reso parte delle specifiche ufficiali, quindi c'è esattamente un modo per documentare un'API GraphQL. Inoltre, dal momento che GraphQL consente di definire la visibilità di alcune parti del grafico, gli utenti che non dovrebbero vederla sono automaticamente impossibilitati a vedere i documenti relativi a ciò a cui non possono accedere. Avere la decisione presa e linee guida chiare è stato un grande vantaggio per il team.

Esistono solo due tipi di azione

A differenza di GET, POST, PUT, PATCH e DELETE di HTTP, in GraphQL esistono solo due tipi di azione: Query e Mutazioni. La differenza principale è che le Mutazioni possono modificare lo stato del sistema, mentre le Query si limitano a leggere passivamente i dati.

Ammetto di essere ancora indeciso su questo punto. Mi piace la pletora di verbi HTTP per interagire con le risorse e poter usare lo strumento giusto per il lavoro. GraphQL rende più facile occuparsi di quei casi difficili in cui uno qualsiasi dei verbi HTTP non si adatta esattamente, ma comporta la penalizzazione di dover pensare a cosa influirà effettivamente una particolare mutazione. Si può anche affermare che, non essendoci una convenzione di denominazione standard incorporata, si dovranno redigere guide di stile interne o si rischierà di creare un pasticcio incoerente.

Avete praticamente bisogno di un cliente

Interagire con le API REST su HTTP è facilissimo con la versione vanilla dell'JavaScript, ma lo è ancora di più utilizzando la moderna interfaccia recuperare API. Al contrario, per GraphQL è necessario utilizzare una libreria client se si vogliono prestazioni davvero decenti. Non è impossibile interagire con un'API GraphQL usando solo JavaScript vanilla: dopo tutto si tratta solo di richieste POST. Tuttavia, l'uso di tecnologie Web di vecchia data, come la cache delle richieste per le chiamate API comuni, non funzionerà, poiché le richieste POST non sono generalmente memorizzate nella cache.

Ogni client GraphQL ragionevole implementa un meccanismo di caching dei risultati lato client e molte altre caratteristiche. Grazie a tutte queste scelte, creare a mano una configurazione per un client GraphQL di livello base è un compito del tutto stupefacente. Quando si inizia a lavorare con GraphQL, consiglio in particolare di dare un'occhiata a Apollo-Boost poiché viene fornito con valori predefiniti molto ragionevoli.

Il cliente sceglie i dati

Ci siamo passati tutti: abbiamo estratto un elenco di dati dall'API e manca un campo cruciale su un modello correlato. Allora implementiamo un hack che comporta N+1 richieste e brontoliamo con gli sviluppatori del backend che si affrettano ad aggiungerlo. Questo di solito non accade con un'API GraphQL ben implementata, perché possiamo scavare nei dati a piacimento. Avete bisogno di vedere l'indirizzo di un cliente in un ordine di questo lotto? Non è un problema, almeno in teoria, e questo ci porta a...

La complessità è più difficile da prevedere

Quando si progetta GraphQL dal lato back-end, può essere difficile pensare a tutte le profondità che un cliente può scavare nel grafo. Ci sono molti modi per strumentare e osservare l'uso del grafico e, dopo aver lasciato che i colleghi del front-end ci giochino per un po', si possono iniziare a vedere alcune lunghe query che eseguono letture piuttosto fantasiose sul vostro archivio dati. In un'API REST questo è più facile da controllare, poiché si può facilmente definire l'ambito dei dati a cui si accede in una singola richiesta. Spesso questa complessità mancante può essere un duro colpo quando si passa alla produzione. Molte volte non è nemmeno ovvio come uscire dalla buca che vi siete scavati.

Le pagine numerate sono davvero difficili

Si tratta di una lamentela che non ha peli sulla lingua. Il fatto che GraphQL sia stato progettato da e per Facebook si può percepire chiaramente osservando il modo in cui funziona il meccanismo di paginazione previsto. Le cosiddette Connessioni sono fondamentalmente flussi infiniti di bordi del grafo, la cui navigazione avviene tramite cursori invece che con le più classiche pagine. Sebbene sia facile capire come ciò si adatti a un feed infinito di post in stile Facebook, se si desidera un elenco ordinato di pagine con la possibilità di andare, ad esempio, a pagina 42, sarà molto più difficile. Naturalmente ci sono modi per aggirare il problema, ma è proprio questo che sono: aggiustamenti.

Lo rifaremmo?

Con tutte le lamentele e le differenze elencate sopra, probabilmente penserete che stiamo trattando GraphQL come un esperimento finito male e che siamo tornati direttamente alle API REST. Non è così. Semmai, stiamo lavorando per utilizzare GraphQL in modo più diffuso nei progetti di tutta l'organizzazione. È un'ottima tecnologia che ha reso il nostro lavoro più semplice e migliore. Tuttavia, inizialmente abbiamo investito in GraphQL senza renderci conto del tipo di difficoltà di crescita che avremmo dovuto affrontare.

Se pensate che GraphQL possa fare al caso vostro, vi incoraggio a fare il grande passo. Datevi tutto il tempo e lo spazio per fallire in sicurezza, e ne raccoglierete i frutti in breve tempo!

Leggi anche:

– Come gestire efficacemente gli sviluppatori remoti? La guida per gli CTO

– Python vs. Ruby? Quale tecnologia utilizzare per lo sviluppo dei prodotti?

– Una guida rapida alla costruzione e allo sviluppo del proprio mercato. Cosa vale la pena di sapere?