GraphQL: tootmises saadud õppetunnid

See on 2020. Teie meeskond kaldub üha enam ühe lehekülje rakenduste ehitamise poole või vähemalt sisaldab rikkalikke komponente tavaliste mitme lehekülje rakenduste sees. [GraphQL](https://graphql.org/) on nüüdseks [üle kahe aasta vana](https://en.wikipedia.org/wiki/GraphQL), mis poolt JavaScript ökosüsteemi standardeid võib pidada küpseks. Me olime veidi seiklushimulised, nii et loobusime tavapärastest JSON APIdest ja sukeldusime otse sisse - siin on see, mida me õppisime.

Teil on vaja GraphQL-serverit

Enamikus raamistikes, mida kasutatakse veebiarendus, on vahendid JSON API loomiseks juba olemas. Saate luua marsruudi struktuuri ja lihtsalt vastu võtta mõned GET- ja POST-saated, seejärel väljastada JSON-vastuse. Ruby on Rails-l on isegi spetsiaalne projekt seadistamise lüliti, mis loobub tavalisest HTML-redigeerimisest ja paneb selle asemele kindla aluse APIdele. Sellest järeldub, et oskuslik arendaja, kes kasutab kaasaegseid vahendeid, saab backend'i üles keerata sõna otseses mõttes minutitega.

Mitte nii GraphQLi puhul. Kuigi on olemas serverite raamatukogud paljud keeled, siis tuleb teil ikkagi kohe algusest peale kiirustasu maksta - lihtsalt sellepärast, et te peate välja selgitama, mis on teie ökosüsteemi jaoks õige. Isiklikumalt öeldes ei meeldi mulle ka mõiste "server", mida kasutatakse projektile kasutusele võetava raamatukogu kirjeldamiseks.

On ainult üks lõpp-punkt

Aastate jooksul oleme harjunud konkreetse viisiga, kuidas API struktuurist mõelda. Kõige elementaarsemal tasemel järgisime lihtsalt REST-tavasid. See tähendas, et meie rakenduses loodi mitu lõpp-punkti iga loogilise mudeli kohta. See on struktuur, mida on lihtne mõista nii API autorite kui ka tarbijate jaoks. Samuti tekitab see hästi piiritletud meetodeid backendis, mis teeb arutluse üle kood sama lihtne kui API enda kohta. Seda struktuuri on ka lihtne nimetada, nt. API versioonimine.

GraphQL kasutab ainult ühte lõpp-punkti, tavaliselt /graphql. Iga teie API-le esitatav taotlus saabub POST-päringuna sellesse lõpp-punkti ja sealt edasi on GraphQL-serveri ülesanne välja selgitada, mida klient soovib, ja vastata sellele asjakohaselt.

Esmapilgul tundub see kohmakas: kujutage ette, et proovite teha kõike JSON API-d ühe lõpp-punktiga! Siiski hakkab see varsti mõttekaks muutuma, kui teie API küpseb ja mõned asjad asenduvad teistega. Deprecation klassikalistes API-des toimub tavaliselt nimeruumi tasandil, liikudes alates v1 aadressile v2. GraphQL võimaldab palju rohkem kontrolli, kuni ühe välja kaotamiseni. Kujutage ette, et saate REST API tarbijale öelda, et te ei soovi, et nad kasutaksid nimi valdkonnas ja kasutada fancy_name selle asemel! Selgub, et see, mis alguses tundus kohmakana, on tegelikult üks parimaid omadusi.

Kõik on trükitud

JSONis ei ole tegelikult palju tüübistamise võimalusi. Seal on stringid, numbrid, massiivid ja objektid. Peale selle ei ole teil õnne. Seevastu GraphQLis algab ja lõpeb kõik tüüpidega, sest isegi juur Query ja Mutation on just seda - tüübid. GraphQL DSL sunnib tüübikontrolli nii serveris kui ka kliendis, vältides igasuguseid ebameeldivaid üllatusi.

See on väga oluline, eriti kuna erihalduspiirkondi kontrollitakse üha sagedamini ise, kas siis TypeScript või alternatiivide, nagu Flow, abil. GraphQL muudab keeruliste ja liitetüüpide kasutuselevõtu vaikeväärtuste peal lihtsaks ning see muutub arendajatele nii backendis kui ka frontendis kiiresti teiseks.

Loe edasi: JavaScript testimine... koos Ruby'ga?!

Dokumendid on sisseehitatud

Klassikalise JSON API puhul võib dokumentatsioon olla tagantjärele. Ja isegi kui see ei ole, on palju meetodeid, mille vahel valida. Kas me kasutame mõnda skeemi nagu OpenAPI? Kas me siis teisendame selle inimesele loetavaks tööriistadega nagu Swagger? Või visandame lihtsalt terve hunniku Markdown-faile kuhugi? Kuigi see probleem on mitu korda lahendatud, nõuab see ikkagi meeskonnalt teadlikku mõtlemist ja pingutust - kõigepealt dokumentide koostamiseks, seejärel nende ajakohastamiseks ja levitamiseks. See on veelgi keerulisem probleem, kui API-l on mitu jaotist, millele on juurdepääs ainult nt teatud kasutajarollidel.

GraphQLis on dokumentatsioon esimese klassi kodanik, kuna enamik servereid võimaldab oma tüüpide ja taotluste dokumenteerimist kohapeal. Alates 2018. aasta algusest on GraphQL Schema Definition Language tehtud ametliku spetsifikatsiooni osaks, nii et GraphQL API dokumenteerimiseks on täpselt üks viis. Samuti kuna GraphQL võimaldab defineerida graafi teatud osade nähtavust, siis need kasutajad, kes ei tohiks, ei näe automaatselt doktorit selle kohta, millele nad ei pääse ligi. Selle otsuse eest hoolitsemine ja selged suunised on olnud meeskonnale suur õnnistus.

On ainult kahte liiki meetmeid

Erinevalt HTTP GET, POST, PUT, PATCH ja DELETE on GraphQLis ainult kahte tüüpi tegevusi: Päringud ja mutatsioonid. Peamine erinevus seisneb selles, et Mutations võib muuta süsteemi olekut ja muudab seda, Queries aga ainult passiivselt andmeid välja loeb.

Ma tunnistan, et olen selle kohta ikka veel ebalevalt meelestatud. Mulle meeldib, et HTTP-s on hulgaliselt verbe, mis võimaldavad ressurssidega suhelda ja kasutada täpselt õiget tööriista. GraphQL lihtsustab nende karvaste juhtumite lahendamist, kus mõni HTTP-verbidest ei sobinud täpselt, kuid toob kaasa karistuse, et tuleb mõelda, mida konkreetne mutatsioon tegelikult mõjutab. Samuti võib märkida, et kuna puudub tegelikult sisseehitatud standardne nimetamiskonventsioon, peate koostama sisemised stiilijuhendid või riskima ebajärjekindla segaduse loomisega.

Sa pead üsna palju klienti

REST API-dega suhtlemine üle HTTP on vanilla JavaScripts väga lihtne, veelgi enam, kui kasutada kaasaegset Tooge API. Seevastu GraphQLi puhul soovite kasutada kliendikirjastikku, kui soovite tõesti korralikku jõudlust. GraphQL APIga ei ole võimatu suhelda, kasutades lihtsalt vanilla JavaScript - tegemist on ju lihtsalt POST päringutega. Kuid lihtsalt pikaajaliste veebitehnoloogiate, nagu päringute vahemälu kasutamine tavaliste API-kutsete puhul ei toimi, kuna POST-päringud ei ole üldiselt vahemällu salvestatud.

Iga mõistlik GraphQL-klient rakendab kliendipoolset tulemuste vahemälumehhanismi ja palju muid funktsioone. Tänu kõigile nendele valikutele on GraphQL-kliendi konfiguratsiooni käsitsi keeramine algtasemel täiesti uimastav ülesanne. GraphQL-iga alustades soovitan ma eriti pilk peale visata Apollo-Boost kuna see on varustatud väga mõistlike vaikimisi seadistustega.

Klient valib andmed

Me kõik oleme olnud selles olukorras: me tõmbame API-st välja andmete nimekirja ja sellest puudub mõni oluline väli seotud mudeli kohta. Seejärel rakendame N+1 päringut hõlmava häkkimise, samal ajal nurisedes backend-arendajate üle, kes kiirelt selle lisavad. Hästi rakendatud GraphQL API puhul see tavaliselt nii ei ole, sest me saame lihtsalt süveneda andmetesse nii sügavale, kui me tahame. Kas on vaja näha kliendi aadressi tellimuse kohta selles partiis? Pole probleem - vähemalt teoreetiliselt, mis viib meid kenasti edasi...

Keerukust on raskem ette näha

GraphQL-i kujundamisel back-end'i poolelt võib olla raske mõelda, kui sügavale klient saab graafi süveneda. Graafi kasutamise instrumenteerimiseks ja jälgimiseks on palju võimalusi ning pärast seda, kui olete lasknud oma front-end kolleegidel mõnda aega mängida, võite hakata nägema, et teie andmepoes tehakse üsna fantaasiarikkaid päringuid. REST API puhul on seda lihtsam kontrollida, kuna saate hõlpsasti öelda, millises ulatuses andmeid ühe päringuga vaadatakse. Tihtipeale võib see vahelejäänud keerukus teid kõvasti hammustada, kui te toodangule vabastate. Paljudel juhtudel ei ole ka ilmne, kuidas sellest enda jaoks kaevatud august pääseda.

Nummerdatud leheküljed on tõesti raske

See on tegelikult keelega seotud nurinat. Kindlasti on tunda, et GraphQL on loodud Facebooki juures ja Facebooki jaoks, kui vaadata, kuidas selle ette nähtud lehekülgede loomise mehhanism töötab. Niinimetatud ühendused on põhimõtteliselt lõputud graafi servade voogud, millel navigeerimine toimub klassikaliste lehekülgede asemel kursorite abil. Kuigi on lihtne mõista, kuidas see sobib Facebooki stiilis lõputu postituste vooguga, on teil palju raskem, kui soovite korralikult liigendatud nimekirja, kus on võimalik minna näiteks leheküljele 42. Loomulikult on võimalusi selle vältimiseks, kuid see ongi see, mida nad on - vältimisvõimalused.

Kas me teeksime seda uuesti?

Kõigi eespool loetletud gripes ja erinevuste puhul arvate ilmselt, et me käsitleme GraphQL-i kui hapuks muutunud eksperimenti ja läksime otse tagasi REST API-de juurde. See ei ole tõsi. Kui üldse, siis me töötame selle nimel, et GraphQLi laialdasemalt kogu organisatsiooni projektides kasutada. See on suurepärane tehnoloogia, mis on muutnud meie töö lihtsamaks ja paremaks. Me investeerisime siiski esialgu GraphQL-i, ilma et oleksime täielikult aru saanud, milliseid kasvuvalu me läbi elame.

Kui te arvate, et GraphQL võib olla teie jaoks õige, siis julgustan teid seda tegema. Andke endale piisavalt aega ja ruumi ohutuks ebaõnnestumiseks, ja te saate kasu juba varsti!

Loe ka:

– Kuidas tõhusalt juhtida kaugarendajaid? Juhend CTO-le

– Python vs. Ruby? Millist tehnoloogiat peaksite tootearenduses kasutama?

– Kiire juhend oma turu loomiseks ja arendamiseks. Mida tasub teada?