GraphQL:n perusteet React-kehittäjille

REST tarjoaa kiinteän rakenteen päätepisteitä: GET /users/:id palauttaa koko käyttäjäolion riippumatta siitä, mitä asiakas tarvitsee. GraphQLin avulla asiakas voi määrittää täsmälleen haluamansa kentät, mikä poistaa ylihaun (liikaa tietoa) ja alihakemisen (liian vähän tietoa, mikä edellyttää useita pyyntöjä).

Yhdellä GraphQL-kyselyllä voidaan hakea käyttäjä, hänen julkaisunsa ja jokaisen julkaisun tekijä yhdellä edestakaisella pyynnöllä.

Jokainen GraphQL-rajapinta määritellään Schema Definition Language (SDL) -kielellä kirjoitetulla skeemalla. Skeema ilmoittaa tyypit ja niiden kentät sekä juurityypit Query, Mutation ja Subscription, joita asiakkaat voivat käyttää.

Skeema on asiakkaan ja palvelimen välinen sopimus. Käyttöliittymä- ja taustajärjestelmätiimit voivat työskennellä rinnakkain, kun skeemasta on sovittu.

GraphQL-kysely valitsee kenttiä: { user(id: "1") { name email posts { title } } }. Sisäkkäiset kentät kulkevat suhteita pitkin yhden pyynnön aikana. Aliakset nimeävät kenttiä uudelleen: { me: user(id: "1") { name } }. Fragmenttien avulla kenttävalintoja voidaan käyttää uudelleen useissa kyselyissä.

Muuttujat tekevät kyselyistä uudelleenkäytettäviä: query GetUser($id: ID!) { user(id: $id) { name } } muuttujilla: { id: "1" }.

Jokaisella GraphQL-skeeman kentällä on palvelimella resolver-funktio. Kun asiakas kysyy user.name-kenttää, user-resolver hakee käyttäjäolion ja name-resolver (tai oletusresolver) palauttaa name-kentän.

Tämä kenttätason ratkaisu mahdollistaa sen, että GraphQL hakee täsmälleen vain pyydetyt tiedot.

Jos kysely hakee 100 julkaisun luettelon ja jokainen julkaisu sisältää tekijänsä, naiivi toteutus tekee tekijöistä 100 erillistä tietokantakyselyä. Tämä N+1-ongelma hidastaa GraphQL-rajapintoja ilman optimointia.

DataLoader ratkaisee N+1-ongelman niputtamalla kaikki tekijöiden haut yhdeksi tietokantakyselyksi käyttämällä pyyntökohtaista välimuistia ja niputusfunktiota.

Apollo Studio ja GraphQL Playground ovat selainpohjaisia käyttöliittymiä GraphQL-rajapinnan interaktiiviseen tutkimiseen. Ne täydentävät kentät automaattisesti skeeman perusteella, näyttävät kyselyjen tulokset ja esittävät tyyppien dokumentaation suoraan käyttöliittymässä.

Playgroundin käyttäminen on nopein tapa ymmärtää ennestään tuntematon GraphQL-rajapinta ennen asiakaskoodin kirjoittamista.

GraphQL-rajapinnat tarjoavat oman skeemansa introspektiokyselyn kautta: { __schema { types { name } } }. Asiakkaat voivat kysellä itse skeemaa selvittääkseen käytettävissä olevat tyypit, kentät ja argumentit.

graphql-codegenin kaltaiset koodigeneraattorityökalut käyttävät introspektiota luodakseen automaattisesti API-skeemaa vastaavat TypeScript-tyypit.

GraphQL-mutaatiot muokkaavat tietoja: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Tilaukset muodostavat pysyvän yhteyden (yleensä WebSocket-yhteyden) ja välittävät päivityksiä: subscription { postAdded { id title } }.

Kaikki kolme juurityyppiä (Query, Mutation, Subscription) käyttävät samaa kenttien valinnan syntaksia.

GraphQL soveltuu erinomaisesti sovelluksiin, joissa on monimutkaisia ja sisäkkäisiä tietotarpeita, useita asiakastyyppejä (mobiili, verkko, TV), jotka tarvitsevat eri osajoukkoja kentistä, tai nopeasti kehittyviä rajapintoja, joissa kenttien käytöstä poistaminen on endpointien versiointia suositeltavampaa.

REST on yksinkertaisempi CRUD-rajapinnoille, joiden resurssirakenteet ovat ennakoitavia ja tasaisia ja jotka hyödyntävät HTTP-välimuistia tehokkaasti ETag-tunnisteiden ja välimuistiotsakkeiden avulla.

Apollo Client on monipuolisin GraphQL-asiakas: se tarjoaa normalisoidun välimuistin, paikallisen tilan hallinnan, tilaukset ja virheenkäsittelylinkit. URQL on kevyempi, ja siinä on dokumenttivälimuisti sekä yksinkertaisempi rajapinta. graphql-requestin kanssa käytetty React Query on yksinkertaisin vaihtoehto peruskyselyihin ja -mutaatioihin ilman kehittynyttä välimuistinhallintaa.

Valitkaa ratkaisu välimuistivaatimusten perusteella: käyttäkää normalisoitua välimuistia useissa kyselyissä jaettaville entiteeteille (Apollo) ja yksinkertaisempaa dokumenttivälimuistia toisistaan riippumattomille kyselyille (URQL tai React Query).

Yksinkertainen SDL-esimerkki: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Huutomerkit ilmaisevat, että kentät eivät voi olla null-arvoja.

Tämä skeema kertoo asiakkaalle täsmälleen, mitä kenttiä kullakin tyypillä on ja mitä kyselyjä on käytettävissä, mikä mahdollistaa tyyppiturvallisen koodin generoinnin.

GraphQLin avulla asiakkaat voivat pyytää täsmälleen tarvitsemansa kentät ilman liika- tai vajaanoutoa käyttämällä skeeman määrittämää kyselykieltä. Resolverit vastaavat kustakin kentästä, ja DataLoader ratkaisee N+1-ongelman. Introspektio mahdollistaa TypeScript-tyyppien generoinnin. Apollo Client, URQL ja React Query ovat tärkeimmät React-yhteensopivat GraphQL-asiakkaat.

Valitkaa GraphQL monimutkaisiin, sisäkkäisiin ja useiden asiakkaiden tietotarpeisiin ja REST yksinkertaiseen CRUD-käyttöön, jossa resurssirakenteet ovat ennakoitavia.