GraphQL ja Golang: Syvä sukellus perusteista edistyneisiin

GraphQL: stä on tullut muotisana viime vuosina, kun Facebook on tehnyt siitä avoimen lähdekoodin. Olen kokeillut GraphQL: ää Node.js: n kanssa ja olen samaa mieltä kaikesta GraphQL: n eduista ja yksinkertaisuudesta.

Joten mikä on GraphQL? Tämän sanoo virallinen GraphQL-määritelmä:

GraphQL on sovellusliittymien ja ajonaikaisen kyselykieli näiden kyselyjen täyttämiseksi olemassa olevilla tiedoilla. GraphQL tarjoaa täydellisen ja ymmärrettävän kuvauksen sovellusliittymän tiedoista, antaa asiakkaille voiman kysyä juuri sitä, mitä he tarvitsevat, eikä mitään muuta, helpottaa sovellusliittymien kehittämistä ajan myötä ja mahdollistaa tehokkaat kehittäjien työkalut.

Vaihdoin äskettäin Golangiin uuden projektin parissa, jota työskentelen (Node.js: ltä) ja päätin kokeilla GraphQL: ää sen kanssa. Golangilla ei ole paljon kirjastovaihtoehtoja, mutta olen kokeillut sitä Thunderin, graphql: n, graphql-go: n ja gqlgenin kanssa. Ja minun on sanottava, että gqlgen on voittanut kaikkien kokeilemieni kirjastojen joukossa.

gqlgen on edelleen beetaversiossa viimeisimmän version 0.7.2 kanssa tämän artikkelin kirjoittamisen aikaan, ja se kehittyy nopeasti. Löydät heidän tiekartansa täältä. Ja nyt 99designs sponsoroi niitä virallisesti, joten näemme vielä paremman kehityksen nopeuden tälle mahtavalle avoimen lähdekoodin projektille. vektah ja neelance ovat tärkeimpiä tekijöitä, ja neelance kirjoitti myös graphql-go.

Joten sukelkaamme kirjaston semantiikkaan olettaen, että sinulla on perustiedot GraphQL: stä.

Kohokohdat

Kuten heidän otsikkonsa sanoo,

Tämä on kirjasto tiukasti kirjoitettujen GraphQL-palvelimien nopeaan luomiseen Golangissa.

Mielestäni tämä on lupaavin asia kirjastossa: et näe koskaan map[string]interface{}täällä, koska se käyttää tiukasti kirjoitettua lähestymistapaa.

Sen lisäksi se käyttää Schema first Approach -ohjelmaa : joten määrität sovellusliittymän käyttämällä graphql-skeeman määrittelykieliä. Tällä on omat tehokkaat koodinmuodostustyökalut, jotka tuottavat kaikki GraphQL-koodisi automaattisesti, ja sinun tarvitsee vain toteuttaa kyseisen käyttöliittymämenetelmän ydinlogiikka.

Olen jakanut tämän artikkelin kahteen vaiheeseen:

  • Perustiedot: Kokoonpano, Mutaatiot, Kyselyt ja Tilaus
  • Edistyneet: Authentication, Dataloaders ja Query Complexity

Vaihe 1: Perusteet - kokoonpano, muunnokset, kyselyt ja tilaukset

Käytämme videoiden julkaisusivustoa esimerkkinä, jossa käyttäjä voi julkaista videon, lisätä kuvakaappauksia, lisätä arvostelun ja saada videoita ja niihin liittyviä videoita.

mkdir -p $GOPATH/src/github.com/ridhamtarpara/go-graphql-demo/

Luo seuraava kaava projektin juuressa:

Tässä olemme määrittäneet perusmallimme ja yhden mutaation uusien videoiden julkaisemiseksi ja yhden kyselyn kaikkien videoiden saamiseksi. Voit lukea lisää graphql-skeemasta täältä. Olemme myös määrittäneet yhden mukautetun tyypin (skalaari), koska grafql: llä on oletusarvoisesti vain 5 skalaarityyppiä, jotka sisältävät Int, Float, String, Boolean ja ID.

Joten jos haluat käyttää mukautettua tyyppiä, voit määrittää mukautetun skalaarin schema.graphql(kuten olemme määrittäneet Timestamp) ja antaa sen määritelmän koodina. Vuonna gqlgen, sinun täytyy antaa marsalkka ja unmarshal menetelmiä kaikki muokatut skalaarien ja kartta heitä gqlgen.yml.

Toinen merkittävä muutos gqlgenissä viimeisessä versiossa on, että ne ovat poistaneet riippuvuuden käännetyistä binääreistä. Joten lisää seuraava tiedosto projektiisi kohdassa scripts / gqlgen.go.

ja alusta dep:

dep init

Nyt on aika hyödyntää kirjaston koodegen-ominaisuutta, joka tuottaa kaiken tylsä ​​(mutta muutamille mielenkiintoinen) luurankokoodi.

go run scripts/gqlgen.go init

joka luo seuraavat tiedostot:

gqlgen.yml - Määritä tiedosto ohjaamaan koodin luomista.

generated.go - Luodtu koodi, jota et halua nähdä.

models_gen.go - Kaikki syötetyn mallin mallit.

resolver.go - Sinun on kirjoitettava toteutuksesi.

server / server.go - aloituskohta, jossa on http.Handler Käynnistä GraphQL-palvelin.

Katsotaanpa yksi Videotyypin luomista malleista :

Kuten näette, ID määritetään merkkijonoksi ja CreatedAt on myös merkkijono. Muut aiheeseen liittyvät mallit kartoitetaan vastaavasti, mutta todellisessa maailmassa et halua tätä - jos käytät mitä tahansa SQL-tietotyyppiä, haluat ID-kentän int tai int64 tietokannastasi riippuen.

Esimerkiksi käytän PostgreSQL: tä demona, joten tietysti haluan tunnuksen int-muodossa ja CreatedAt-ajan . Joten meidän on määriteltävä oma mallimme ja ohjeistettava gqlgen käyttämään malliamme uuden luomisen sijaan.

ja päivitä gqlgen käyttääksesi näitä malleja näin:

Joten keskipiste on ID: n ja aikaleiman mukautetut määritelmät marsalkka- ja unmarsaalisilla menetelmillä ja niiden kartoitus gqlgen.yml-tiedostossa. Nyt kun käyttäjä antaa merkkijonon tunnukseksi, UnmarshalID muuntaa merkkijonon int: ksi. Lähetettäessä vastausta MarshalID muuntaa int merkkijonoksi. Sama koskee Aikaleimaa tai muuta määrittelemääsi mukautettua skalaaria.

Nyt on aika toteuttaa todellinen logiikka. Avaa resolver.goja anna määritelmä mutaatiolle ja kyselyille. Tankot on jo luotu automaattisesti, kun paniikkilausetta ei ole toteutettu, joten ohitetaan se.

ja osui mutaatioon:

Ohh se toimi ... .. mutta odota, miksi käyttäjäni on tyhjä? Joten tässä on samanlainen käsite kuin laiska ja innokas lataus. Koska graphQL on laajennettavissa, sinun on määriteltävä, mitkä kentät haluat täyttää innokkaasti ja mitkä laiskasti.

I have created this golden rule for my organization team working with gqlgen:

Don’t include the fields in a model which you want to load only when requested by the client.

For our use-case, I want to load Related Videos (and even users) only if a client asks for those fields. But as we have included those fields in the models, gqlgen will assume that you will provide those values while resolving video — so currently we are getting an empty struct.

Sometimes you need a certain type of data every time, so you don’t want to load it with another query. Rather you can use something like SQL joins to improve performance. For one use-case (not included in the article), I needed video metadata every time with the video which is stored in a different place. So if I loaded it when requested, I would need another query. But as I knew my requirements (that I need it everywhere on the client side), I preferred it to load eagerly to improve the performance.

So let’s rewrite the model and regenerate the gqlgen code. For the sake of simplicity, we will only define methods for the user.

So we have added UserID and removed User struct and regenerated the code:

go run scripts/gqlgen.go -v

This will generate the following interface methods to resolve the undefined structs and you need to define those in your resolver:

And here is our definition:

Now the result should look something like this:

So this covers the very basics of graphql and should get you started. Try a few things with graphql and the power of Golang! But before that, let’s have a look at subscription which should be included in the scope of this article.

Subscriptions

Graphql provides subscription as an operation type which allows you to subscribe to real tile data in GraphQL. gqlgen provides web socket-based real-time subscription events.

You need to define your subscription in the schema.graphql file. Here we are subscribing to the video publishing event.

Regenerate the code by running: go run scripts/gqlgen.go -v.

As explained earlier, it will make one interface in generated.go which you need to implement in your resolver. In our case, it looks like this:

Now, you need to emit events when a new video is created. As you can see on line 23 we have done that.

And it’s time to test the subscription:

GraphQL comes with certain advantages, but everything that glitters is not gold. You need to take care of a few things like authorizations, query complexity, caching, N+1 query problem, rate limiting, and a few more issues — otherwise it will put you in performance jeopardy.

Phase 2: The advanced - Authentication, Dataloaders, and Query Complexity

Every time I read a tutorial like this, I feel like I know everything I need to know and can get my all problems solved.

But when I start working on things on my own, I usually end up getting an internal server error or never-ending requests or dead ends and I have to dig deep into that to carve my way out. Hopefully we can help prevent that here.

Let’s take a look at a few advanced concepts starting with basic authentication.

Authentication

In a REST API, you have a sort of authentication system and some out of the box authorizations on particular endpoints. But in GraphQL, only one endpoint is exposed so you can achieve this with schema directives.

You need to edit your schema.graphql as follows:

We have created an isAuthenticated directive and now we have applied that directive to createVideo subscription. After you regenerate code you need to give a definition of the directive. Currently, directives are implemented as struct methods instead of the interface so we have to give a definition.

I have updated the generated code of server.go and created a method to return graphql config for server.go as follows:

We have read the userId from the context. Looks strange right? How was userId inserted in the context and why in context? Ok, so gqlgen only provides you the request contexts at the implementation level, so you can not read any of the HTTP request data like headers or cookies in graphql resolvers or directives. Therefore, you need to add your middleware and fetch those data and put the data in your context.

So we need to define auth middleware to fetch auth data from the request and validate.

I haven’t defined any logic there, but instead I passed the userId as authorization for demo purposes. Then chain this middleware in server.go along with the new config loading method.

Now, the directive definition makes sense. Don’t handle unauthorized users in your middleware as it will be handled by your directive.

Demo time:

You can even pass arguments in the schema directives like this:

directive @hasRole(role: Role!) on FIELD_DEFINITIONenum Role { ADMIN USER }

Dataloaders

This all looks fancy, doesn’t it? You are loading data when needed. Clients have control of the data, there is no under-fetching and no over-fetching. But everything comes with a cost.

So what’s the cost here? Let’s take a look at the logs while fetching all the videos. We have 8 video entries and there are 5 users.

query{ Videos(limit: 10){ name user{ name } }}
Query: Videos : SELECT id, name, description, url, created_at, user_id FROM videos ORDER BY created_at desc limit $1 offset $2Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1Resolver: User : SELECT id, name, email FROM users where id = $1

Why 9 queries (1 videos table and 8 users table)? It looks horrible. I was just about to have a heart attack when I thought about replacing our current REST API servers with this…but dataloaders came as a complete cure for it!

This is known as the N+1 problem, There will be one query to get all the data and for each data (N) there will be another database query.

This is a very serious issue in terms of performance and resources: although these queries are parallel, they will use your resources up.

We will use the dataloaden library from the author of gqlgen. It is a Go- generated library. We will generate the dataloader for the user first.

go get github.com/vektah/dataloadendataloaden github.com/ridhamtarpara/go-graphql-demo/api.User

This will generate a file userloader_gen.go which has methods like Fetch, LoadAll, and Prime.

Now, we need to define the Fetch method to get the result in bulk.

Here, we are waiting for 1ms for a user to load queries and we have kept a maximum batch of 100 queries. So now, instead of firing a query for each user, dataloader will wait for either 1 millisecond for 100 users before hitting the database. We need to change our user resolver logic to use dataloader instead of the previous query logic.

After this, my logs look like this for similar data:

Query: Videos : SELECT id, name, description, url, created_at, user_id FROM videos ORDER BY created_at desc limit $1 offset $2Dataloader: User : SELECT id, name, email from users WHERE id IN ($1, $2, $3, $4, $5)

Now only two queries are fired, so everyone is happy. The interesting thing is that only five user keys are given to query even though 8 videos are there. So dataloader removed duplicate entries.

Query Complexity

In GraphQL you are giving a powerful way for the client to fetch whatever they need, but this exposes you to the risk of denial of service attacks.

Let’s understand this through an example which we’ve been referring to for this whole article.

Now we have a related field in video type which returns related videos. And each related video is of the graphql video type so they all have related videos too…and this goes on.

Consider the following query to understand the severity of the situation:

{ Videos(limit: 10, offset: 0){ name url related(limit: 10, offset: 0){ name url related(limit: 10, offset: 0){ name url related(limit: 100, offset: 0){ name url } } } }}

If I add one more subobject or increase the limit to 100, then it will be millions of videos loading in one call. Perhaps (or rather definitely) this will make your database and service unresponsive.

gqlgen provides a way to define the maximum query complexity allowed in one call. You just need to add one line (Line 5 in the following snippet) in your graphql handler and define the maximum complexity (300 in our case).

gqlgen assigns fix complexity weight for each field so it will consider struct, array, and string all as equals. So for this query, complexity will be 12. But we know that nested fields weigh too much, so we need to tell gqlgen to calculate accordingly (in simple terms, use multiplication instead of just sum).

Just like directives, complexity is also defined as struct, so we have changed our config method accordingly.

En ole määrittänyt siihen liittyvää menetelmälogiikkaa ja palautin vain tyhjän taulukon. Joten liittyvä on tyhjä tulosteessa, mutta tämän pitäisi antaa sinulle selkeä käsitys kyselyn monimutkaisuuden käytöstä.

Viimeiset huomautukset

Tämä koodi on Githubissa. Voit leikkiä sen kanssa, ja jos sinulla on kysyttävää tai huolenaiheita, ilmoita siitä minulle kommenttiosassa.

Kiitos lukemisesta! Muutama (toivottavasti 50) taputus? ovat aina arvostettuja. Olen kirjoittaa JavaScript, Go kieli, DevOps ja Computer Science. Seuraa minua ja jaa tämä artikkeli, jos pidät siitä.

Ota yhteyttä minuun osoitteessa @Twitter @Linkedin. Lisätietoja on osoitteessa www.ridham.me.