GraphQL: tuotannossa opittua

Nyt on vuosi 2020. Sinun joukkue suuntautuu yhä enemmän yhden sivun sovellusten rakentamiseen tai ainakin rikkaiden komponenttien sisällyttämiseen tavallisiin monisivuisiin sovelluksiin. [GraphQL](https://graphql.org/) on nyt [yli kaksi vuotta vanha](https://en.wikipedia.org/wiki/GraphQL), mikä on jo JavaScript ekosysteemistandardeja voidaan pitää kypsinä. Olimme hieman seikkailunhaluisia, joten hylkäsimme tavanomaiset JSON-API:t ja sukelsimme suoraan sisään - tässä on, mitä opimme.

Tarvitset GraphQL-palvelimen

Useimmissa kehyksissä, joita käytetään web-kehitys, työkalut JSON API:n rakentamiseen ovat jo olemassa. Voit rakentaa reittirakenteen ja hyväksyä helposti joitakin GET- ja POST-kutsuja ja antaa sitten JSON-vastauksen. Ruby on Rails:ssä on jopa erityinen projekti asennusvaihtoehto, joka luopuu tavanomaisista HTML-muokkauksen herkuista ja asettaa tilalle vankan perustan API:ille. Tästä seuraa, että taitava kehittäjä, joka käyttää nykyaikaisia työkaluja, voi luoda backendin kirjaimellisesti muutamassa minuutissa.

Toisin on GraphQL:n kanssa. Vaikka palvelinkirjastoja on olemassa monia kieliä, joudut silti kärsimään nopeussakkoa heti alussa - yksinkertaisesti siksi, että sinun on selvitettävä, mikä sopii ekosysteemillesi. Henkilökohtaisesti en myöskään pidä siitä, että termiä "palvelin" käytetään kuvaamaan kirjastoa, joka voidaan ottaa käyttöön projektissa.

On vain yksi päätepiste

Vuosien mittaan olemme tottuneet tiettyyn tapaan ajatella API-rakenteita. Yksinkertaisimmillaan noudatimme yksinkertaisesti REST-käytäntöjä. Se tarkoitti useiden päätepisteiden luomista sovelluksemme loogista mallia kohti. Se on rakenne, joka on helppo hahmottaa sekä API:n laatijoille että kuluttajille. Se tuottaa myös hyvin rajattuja metodeja backendiin, jolloin päättelyä voidaan tehdä koodi yhtä helppoa kuin itse API:sta. Tätä rakennetta on myös helppo käyttää nimiavaruudessa, esimerkiksi seuraavissa tarkoituksissa API-versionointi.

GraphQL käyttää vain yhtä päätepistettä, joka on yleensä /graphql. Jokainen API:n pyyntö saapuu POST-pyyntönä kyseiseen päätepisteeseen, ja GraphQL-palvelimen vastuulla on selvittää, mitä asiakas haluaa, ja vastata siihen asianmukaisesti.

Ensi silmäyksellä se tuntuu hankalalta: kuvittele, että yrität tehdä kaiken JSON API:ssa yhdellä päätepisteellä! Se alkaa kuitenkin pian olla järkevää, kun API kehittyy ja jotkin asiat korvataan toisilla. Poistaminen klassisissa API:issa tehdään yleensä nimiavaruuden tasolla, jolloin siirrytään nimestä v1 osoitteeseen v2. GraphQL tarjoaa paljon enemmän hallintaa, jopa yksittäisen kentän poistamiseen asti. Kuvittele, että voit kertoa REST API:n kuluttajalle, että et halua hänen käyttävän kenttää nimeltä nimi kenttää ja käyttää fancy_name sen sijaan! Kävi ilmi, että se, mikä aluksi tuntui hankalalta, on itse asiassa yksi parhaista ominaisuuksista.

Kaikki on kirjoitettu

JSONissa ei ole kovinkaan paljon tyypittelyä. On merkkijonoja, numeroita, matriiseja ja objekteja. Sen lisäksi sinulla ei ole onnea. Sen sijaan GraphQL:ssä kaikki alkaa ja päättyy tyyppeihin, sillä jopa juuret Query ja Mutation ovat juuri sitä - tyyppejä. GraphQL DSL pakottaa tyyppitarkistuksen sekä palvelimella että asiakkaalla, mikä estää kaikenlaisia ikäviä yllätyksiä.

Tämä on erittäin tärkeää erityisesti siksi, että SPA-yksiköt tekevät yhä useammin itse tyyppitarkastuksia, olipa kyse sitten TypeScript:stä tai Flow'n kaltaisista vaihtoehdoista. GraphQL:n avulla on helppo ottaa käyttöön monimutkaisia ja yhdistettyjä tyyppejä oletusarvojen päälle, ja siitä tulee nopeasti toinen luonto kehittäjille sekä backendissä että frontendissä.

Lue lisää: Testaan JavaScript:tä... Rubylla?!

Asiakirjat ovat sisäänrakennettuja

Klassisessa JSON-API:ssä dokumentaatio voi olla jälkiviisas. Ja vaikka se ei olisikaan, menetelmiä on paljon. Käytämmekö jotain järjestelmää, kuten OpenAPI? Muunnetaanko se sitten ihmisen luettavaan muotoon Swaggerin kaltaisilla työkaluilla? Vai heitämmekö vain koko joukon Markdown-tiedostoja jonnekin? Vaikka tämä ongelma on ratkaistu useita kertoja, se vaatii edelleen tiimiltä tietoista ajattelua ja ponnistelua - ensin asiakirjojen rakentaminen, sitten niiden päivittäminen ja levittäminen. Ongelma on vieläkin monimutkaisempi, kun API:ssa on useita osioita, joihin pääsevät käsiksi vain esimerkiksi tietyt käyttäjäroolit.

GraphQL:ssä dokumentointi on ensiluokkaista, sillä useimmat palvelimet mahdollistavat tyyppien ja pyyntöjen dokumentoinnin paikan päällä. Alkuvuodesta 2018 GraphQL Schema Definition Language on otettu osaksi virallista speksejä, joten GraphQL API:n dokumentointiin on olemassa nimenomaan yksi tapa. Koska GraphQL mahdollistaa myös graafin tiettyjen osien näkyvyyden määrittelyn, ne käyttäjät, joiden ei pitäisi, estetään automaattisesti näkemästä dokumentteja siitä, mihin he eivät pääse käsiksi. Se, että päätös on hoidettu ja selkeät ohjeet ovat olleet suuri siunaus tiimille.

Toimintatapoja on vain kahdenlaisia

Toisin kuin HTTP:n GET, POST, PUT, PATCH ja DELETE, GraphQL:ssä on vain kahdenlaisia toimintoja: Kyselyt ja muunnokset. Tärkein ero on se, että Mutations voi muuttaa ja muuttaa järjestelmän tilaa, kun taas Queries vain lukee passiivisesti tietoja.

Myönnän, että olen vielä epävarma tämän suhteen. Pidän HTTP:n lukuisista verbeistä, joilla voi olla vuorovaikutuksessa resurssien kanssa ja käyttää juuri oikeaa työkalua työhön. GraphQL helpottaa niiden karvaisten tapausten hoitamista, joissa jokin HTTP-verbeistä ei ole sopinut täsmälleen, mutta siitä seuraa rangaistus, että täytyy miettiä, mihin tietty mutaatio todella vaikuttaa. Voidaan myös huomauttaa, että koska ei ole olemassa sisäänrakennettua vakiomuotoista nimeämiskäytäntöä, sinun on laadittava sisäisiä tyylioppaita tai vaarana on, että rakennat epäjohdonmukaisen sotkun.

Tarvitset melko paljon asiakasta

Vuorovaikutus REST API:iden kanssa HTTP:n kautta on erittäin helppoa vanilja JavaScript:ssä, ja vielä helpompaa se on nykyaikaisen nouto API. Sen sijaan GraphQL:ssä kannattaa käyttää asiakaskirjastoa, jos haluat todella kunnon suorituskyvyn. Ei ole mahdotonta olla vuorovaikutuksessa GraphQL API:n kanssa käyttämällä pelkkää vanilla JavaScript:tä - onhan kyse vain POST-pyynnöistä. Pelkkien vanhojen Web-tekniikoiden, kuten pyyntöjen välimuistitallennuksen, käyttäminen tavallisiin API-kutsuihin ei kuitenkaan toimi, koska POST-pyyntöjä ei yleensä tallenneta välimuistiin.

Jokainen järkevä GraphQL-asiakas toteuttaa asiakaspuolen tulosten välimuistitallennusmekanismin ja monia muita ominaisuuksia. Kaikkien näiden valintojen ansiosta GraphQL-asiakkaan konfiguraation käsinkääntäminen lähtötasolla on täysin häkellyttävä tehtävä. GraphQL:n kanssa aloittaessasi suosittelen erityisesti tutustumaan seuraaviin asioihin Apollo-Boost koska siinä on hyvin kohtuulliset oletusarvot.

Asiakas valitsee tiedot

Olemme kaikki kokeneet tämän: olemme saaneet API:sta luettelon tiedoista, ja siitä puuttuu jokin tärkeä kenttä johonkin malliin liittyvästä tiedosta. Toteutamme sitten N+1 pyyntöä käsittävän hakkeroinnin ja murahdamme samalla backend-kehittäjille, jotka kiirehtivät lisäämään sen nopeasti. Näin ei yleensä ole hyvin toteutetun GraphQL API:n tapauksessa, koska voimme vain tutkia tietoja niin syvällisesti kuin haluamme. Haluatko nähdä erään asiakkaan osoitteen tässä erässä olevasta tilauksesta? Se ei ole ongelma - ainakaan teoriassa, mikä johtaa meidät mukavasti...

Monimutkaisuutta on vaikeampi ennakoida

Kun GraphQL:ää suunnitellaan back-end-puolelta käsin, voi olla vaikea ajatella, miten syvälle asiakas voi syventyä graafiin. On olemassa monia tapoja instrumentoida ja tarkkailla graafisi käyttöä, ja kun olet antanut front-end-kollegojesi leikkiä jonkin aikaa, voit alkaa nähdä pitkiä kyselyjä, jotka suorittavat varsin mielikuvituksellisia lukutoimintoja tietovarastossasi. REST-API:ssä tätä on helpompi hallita, koska voit helposti kertoa, kuinka paljon tietoja käytetään yhdellä pyynnöllä. Usein tämä hukkaan jäänyt monimutkaisuus voi purra sinua kovaa, kun julkaiset sen tuotantoon. Usein ei myöskään ole selvää, miten tästä itsellesi kaivetusta kuopasta pääsee pois.

Numeroidut sivut ovat todella vaikeita

Tämä on oikeastaan kieli poskessa oleva valituksen aihe. GraphQL:n suunnittelusta Facebookia varten ja Facebookissa voi selvästi päätellä, että se on suunniteltu Facebookille, kun katsoo, miten sen sivutusmekanismi toimii. Niin kutsutut Connectionsit ovat periaatteessa loputtomia graafin reunojen virtoja, joissa navigointi tapahtuu kursoreiden avulla klassisempien sivujen sijaan. Vaikka on helppo ymmärtää, miten tämä sopii Facebook-tyyliseen loputtomaan postausten syötteeseen, jos haluat siististi sivutetun luettelon, jossa on mahdollisuus siirtyä vaikkapa sivulle 42, sinulla on paljon vaikeampaa. On toki olemassa keinoja kiertää tämä, mutta sitä ne ovat - kiertoteitä.

Tekisimmekö sen uudelleen?

Kaikkien edellä lueteltujen epäkohtien ja erojen vuoksi luultavasti ajattelet, että pidämme GraphQL:ää kokeiluna, joka muuttui happamaksi, ja palasimme suoraan takaisin REST API:iin. Se ei ole totta. Jos jotain, pyrimme käyttämään GraphQL:ää laajemmin projekteissa koko organisaatiossa. Se on loistava teknologia, joka on tehnyt työstämme helpompaa ja parempaa. Investoimme kuitenkin aluksi GraphQL:ään ymmärtämättä täysin, millaisia kasvukipuja tulemme kokemaan.

Jos luulet, että GraphQL saattaisi sopia juuri sinulle, rohkaisen sinua tarttumaan toimeen. Anna itsellesi runsaasti aikaa ja tilaa epäonnistua turvallisesti, niin saat hyötyä ennen pitkää!

Lue myös:

– Miten hallita tehokkaasti etäkehittäjiä? Opas teknologiajohtajille

– Python vs. Ruby? Mitä teknologiaa kannattaa käyttää tuotekehityksessä?

– Nopea opas oman markkinapaikan rakentamiseen ja kehittämiseen. Mitä kannattaa tietää?