Sådan fungerer GraphQL

Grundlæggende principper for GraphQL

Den centrale styrke i GraphQL ligger i dens forespørgselsbaserede arkitektur, der fundamentalt adskiller sig fra traditionelle API-løsninger. I klassiske REST-arkitekturer definerer serveren både datastrukturen og adgangspunkterne, hvilket ofte resulterer i enten for meget eller for lidt data i forhold til klientens behov. GraphQL vender dette forhold om ved at lade klienten specificere præcis hvilke data den har brug for.

Forespørgselsbaseret arkitektur

I GraphQL starter enhver datahentning med en forespørgsel, der præcist beskriver de ønskede data. Denne deklarative tilgang minder om den måde, vi naturligt tænker på data. Når en udvikler skal hente information om en bruger, kan forespørgslen direkte afspejle det mentale billede af hvilke brugerdata der er relevante for den aktuelle situation.

GraphQLs forespørgselssprog bruger en intuitiv syntaks, der ligner den måde dataen senere vil blive brugt i applikationen. Dette reducerer den kognitive belastning ved at oversætte mellem forskellige datarepræsentationer. En forespørgsel efter en brugers navn og e-mail adresse kunne se således ud:

{
  bruger(id: "123") {
    navn
    emailadresse
  }
}

Den resulterende data matcher nøjagtigt strukturen i forespørgslen, hvilket eliminerer behovet for kompleks datatransformation på klientsiden. Serveren returnerer kun de specificerede felter, hvilket optimerer både båndbreddeforbrug og behandlingstid.

Denne arkitektur muliggør også sammensat datahentning, hvor relaterede data kan hentes i samme forespørgsel. Dette løser det klassiske N+1 problem, hvor traditionelle API’er ofte kræver multiple separate kald for at samle relaterede data.

Typesystem og skema

GraphQLs typesystem danner fundamentet for pålidelig datakommunikation mellem klient og server. Gennem et veldesignet skema defineres ikke bare hvilke datatyper der er tilgængelige, men også hvordan disse typer relaterer til hinanden. Dette skaber en klar kontrakt mellem klient og server, der sikrer forudsigelighed og reducerer risikoen for fejl.

Et GraphQL-skema bruger en deklarativ syntaks til at definere typer og deres felter. For hver type specificeres nøjagtigt hvilke felter der er tilgængelige, samt deres datatype. Dette kunne eksempelvis være en brugertype med tilhørende felter:

type Bruger {
  id: ID!
  navn: String!
  emailadresse: String!
  oprettet: DateTime
  ordrer: [Ordre!]
}

Udråbstegnet efter typeangivelsen markerer at feltet er påkrævet, hvilket giver klienten garantier om datastrukturen. Dette stærke typesystem fungerer som en form for kontrakt mellem klient og server.

Resolver-funktioner

Hvor skemaet definerer datastrukturen, er det resolver-funktionerne der implementerer logikken for hvordan disse data faktisk hentes. En resolver er en funktion der ved præcis hvordan et specifikt felt skal resolves, uanset om data kommer fra en database, ekstern service eller beregning.

Resolver-funktioner implementeres på serversiden og følger en specifik signatur der matcher skemadefinitionen. En resolver modtager kontekst om forespørgslen og eventuelle argumenter, og returnerer de ønskede data. Dette muliggør kompleks datasammensætning uden at eksponere implementationsdetaljerne til klienten:

const resolvers = {
  Bruger: {
    ordrer: async (parent, args, context) => {
      // Resolver-funktion der henter brugerens ordrer
      return await context.database.findOrdrer(parent.id)
    }
  }
}

Resolver-kæden følger naturligt den nøstede struktur i forespørgslen, hvor hver resolver kun er ansvarlig for at levere data for sit specifikke felt. Dette skaber en modulær arkitektur der er nem at vedligeholde og udvide.

Arkitektoniske fordele ved GraphQL

GraphQLs arkitektur tilbyder markante forbedringer i måden hvorpå moderne applikationer håndterer datakommunikation. Disse fordele bliver særligt tydelige når vi ser på hvordan GraphQL elegant løser klassiske udfordringer med dataafhængigheder.

Håndtering af dataafhængigheder

I traditionelle REST-arkitekturer støder udviklere ofte på udfordringer når relaterede data skal hentes. Forestil dig en e-handelsplatform hvor vi skal vise en ordrehistorik. For hver ordre skal vi måske hente produktdetaljer, leveringsstatus og kundeinformation. I en REST-arkitektur ville dette typisk kræve multiple separate kald til forskellige endepunkter.

GraphQL transformerer denne proces ved at tillade klienten at specificere hele datahierarkiet i én enkelt forespørgsel. Dette eliminerer behovet for vandfaldsforespørgsler, hvor hvert datasæt skal vente på det foregående. En forespørgsel kunne se således ud:

{
  ordre(id: "789") {
    ordrenummer
    kunde {
      navn
      leveringsadresse
    }
    produkter {
      navn
      pris
      lagerStatus
    }
    leveringsstatus {
      estimeret_levering
      nuværende_lokation
    }
  }
}

Denne tilgang giver ikke bare bedre ydeevne gennem reducerede netværkskald, men skaber også mere vedligeholdelsesvenlig kode. Udviklere kan tydeligt se sammenhængen mellem relaterede data direkte i forespørgselsstrukturen, hvilket gør koden mere selvdokumenterende og lettere at debugge.

Versionering og evolution

GraphQL tilbyder en unik tilgang til API-evolution, der adskiller sig markant fra traditionel versionering. Hvor REST-baserede API’er ofte kræver eksplicitte versioner som v1, v2, osv., arbejder GraphQL med en mere flydende tilgang til ændringer. Dette opnås gennem et princip om additive ændringer, hvor nye felter kan tilføjes uden at påvirke eksisterende klienter.

Når et GraphQL-skema skal udvides, kan nye felter tilføjes ved siden af eksisterende felter. Klienter der ikke kender til de nye felter fortsætter med at fungere uforstyrret, da de kun modtager de felter de eksplicit beder om. Dette muliggør en gradvis evolution af API’et uden at introducere breaking changes.

Ydeevne og optimering

GraphQLs fleksibilitet i datahentning åbner for avancerede optimeringsmuligheder. En central udfordring i GraphQL er N+1 problemet, hvor en forespørgsel efter en liste af elementer potentielt kan udløse et separat databasekald for hvert element. Dette håndteres gennem dataindlæsning (dataloading), der samler multiple forespørgsler til færre optimerede databasekald.

Implementeringen af effektiv dataindlæsning sker gennem en datalader (DataLoader), der fungerer som et intelligent mellemlag mellem GraphQL-resolvere og datakilden. Dataloaderen grupperer individuelle forespørgsler i batches og cacher resultaterne:

const brugerLoader = new DataLoader(async brugerIds => {
  // Henter multiple brugere i én database-forespørgsel
  const brugere = await database.findBrugere(brugerIds)
  return brugerIds.map(id => brugere.find(b => b.id === id))
})

Denne optimeringsteknik reducerer markant antallet af databasekald og forbedrer dermed både svartider og serverbelastning. GraphQLs introspektive natur gør det også muligt at implementere intelligent feltniveau-caching, hvor ofte forespurgte data kan caches effektivt.

Implementation af GraphQL

Etableringen af en GraphQL-server kræver omhyggelig planlægning og strukturering for at sikre en robust og vedligeholdelsesvenlig løsning. Den grundlæggende implementering involverer flere nøglekomponenter der tilsammen danner fundamentet for GraphQL-servicen.

Opsætning af GraphQL-server

En GraphQL-server bygges typisk på et etableret framework der håndterer de grundlæggende GraphQL-operationer. Apollo Server er blevet industristandard grundet dens robuste funktionalitet og aktive udviklerfællesskab. Implementeringen starter med definition af serverkonfigurationen:

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'

const typeDefs = `
  type Bruger {
    id: ID!
    navn: String!
    email: String!
  }

  type Query {
    brugere: [Bruger!]!
    bruger(id: ID!): Bruger
  }
`

const resolvers = {
  Query: {
    brugere: async (parent, args, context) => {
      return await context.dataSources.brugere.findAlle()
    },
    bruger: async (parent, args, context) => {
      return await context.dataSources.brugere.findMedId(args.id)
    }
  }
}

const server = new ApolloServer({
  typeDefs,
  resolvers
})

Serveropsætningen indeholder to hovedkomponenter: typedefinitioner der beskriver datamodellen, og resolvere der implementerer logikken for datahentning. Denne adskillelse af ansvar skaber en klar struktur der er nem at vedligeholde og udvide.

For at sikre pålidelig datahåndtering implementeres datakilder som separate klasser. Dette skaber et abstraktionslag mellem GraphQL-laget og den underliggende database eller eksterne services:

class BrugerDataKilde {
  constructor(database) {
    this.database = database
  }

  async findAlle() {
    return await this.database.query('SELECT * FROM brugere')
  }

  async findMedId(id) {
    return await this.database.query('SELECT * FROM brugere WHERE id = ?', [id])
  }
}

Denne modulære tilgang gør det muligt at ændre implementationsdetaljer uden at påvirke GraphQL-skemaet eller klientapplikationerne. Det forenkler også testning og fejlfinding, da hver komponent har et veldefineret ansvarsområde.

Klientside integration

På klientsiden handler GraphQL-integration om at etablere en pålidelig kommunikation med serveren og effektivt håndtere de modtagne data. Apollo Client har udviklet sig til industristandard grundet dens sofistikerede håndtering af forespørgsler, caching og tilstandsstyring.

Integrationen starter med opsætning af en Apollo Client-instans der konfigureres til at kommunikere med GraphQL-serveren. Klienten håndterer automatisk komplekse aspekter som forespørgselscaching, optimistiske opdateringer og fejlhåndtering:

import { ApolloClient, InMemoryCache } from '@apollo/client'

const klient = new ApolloClient({
  uri: 'https://api.eksempel.dk/graphql',
  cache: new InMemoryCache(),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network'
    }
  }
})

Sikkerhed og validering

Sikkerhed i GraphQL-applikationer kræver opmærksomhed på flere niveauer. På serversiden implementeres validering af indkommende forespørgsler for at beskytte mod overbelastning og ondsindede forespørgsler. Dette omfatter begrænsning af forespørgselskompleksitet og dybde:

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [
    depthLimit(5),
    createComplexityLimit({
      maksimalKompleksitet: 1000,
      skalarKompleksitet: 1,
      objektKompleksitet: 10
    })
  ]
})

Autentificering og autorisering implementeres gennem et middleware-lag der validerer hver forespørgsel. Dette sikrer at brugere kun får adgang til data de har rettigheder til:

const beskyttetResolver = async (parent, args, context) => {
  if (!context.bruger) {
    throw new Error('Ingen adgang')
  }

  const bruger = await context.dataSources.brugere.hentMedId(args.id)

  if (bruger.organisationId !== context.bruger.organisationId) {
    throw new Error('Utilstrækkelige rettigheder')
  }

  return bruger
}

Denne lagdelte sikkerhedstilgang kombinerer robuste valideringsregler med granulær adgangskontrol på resolverniveau.

Best practices og designmønstre

Udviklingen af et velfungerende GraphQL-API kræver omhyggelig planlægning og overholdelse af etablerede designprincipper. Disse principper sikrer at API’et forbliver vedligeholdelsesvenligt og skalerbart over tid.

Skemadesign

Et veldesignet GraphQL-skema fungerer som et fundament for hele API’et. Det afspejler ikke bare datastrukturen, men også domænelogikken i applikationen. Ved udformning af skemaet bør man fokusere på at skabe en intuitiv og konsistent datamodel der afspejler forretningsdomænet.

Navngivning af typer og felter kræver særlig omtanke, da disse navne bliver en del af API’ets offentlige kontrakt. Navne skal være selvbeskrivende og følge konsekvente konventioner. I stedet for generiske navne som hentData eller opdaterElement bør man bruge domænespecifikke termer som hentOrdre eller opdaterProfil.

Interfaces og unions spiller en vigtig rolle i at skabe fleksible og genbrugelige strukturer. Et interface kan eksempelvis definere fælles egenskaber for forskellige brugertyper:

interface Person {
  id: ID!
  navn: String!
  email: String!
}

type Kunde implements Person {
  id: ID!
  navn: String!
  email: String!
  ordrer: [Ordre!]!
}

type Medarbejder implements Person {
  id: ID!
  navn: String!
  email: String!
  afdeling: String!
}

Denne tilgang skaber en balanceret struktur der er både fleksibel og stringent. Den tillader udvidelser og specialiseringer, samtidig med at den bevarer en klar og forståelig datamodel.

Fejlhåndtering

Robust fejlhåndtering i GraphQL adskiller sig markant fra traditionelle REST-baserede systemer. I stedet for at bruge HTTP-statuskoder kommunikerer GraphQL fejl gennem en dedikeret fejlstruktur i svaret. Dette giver mulighed for mere nuanceret fejlhåndtering og bedre fejlinformation til klienten.

En central del af fejlhåndteringen ligger i at definere forskellige fejltyper der matcher applikationens domæne. Ved at implementere specifikke fejlklasser kan vi give præcis information om hvad der gik galt:

class ForretningsfejlBase extends Error {
  constructor(besked, kode) {
    super(besked)
    this.kode = kode
    this.name = this.constructor.name
  }
}

class ValideringsFejl extends ForretningsfejlBase {
  constructor(besked) {
    super(besked, 'VALIDERING_FEJLET')
  }
}

Teststrategi

En omfattende teststrategi for GraphQL-applikationer bygger på flere testlag der tilsammen sikrer systemets pålidelighed. Enhedstest fokuserer på individuelle resolvere og deres logik, mens integrationstests verificerer samspillet mellem forskellige komponenter.

Resolver-test bør validere både succesfulde operationer og fejlscenarier. Dette sikrer at fejlhåndteringen fungerer som forventet:

describe('BrugerResolver', () => {
  test('hentBruger returnerer bruger ved gyldigt id', async () => {
    const resultat = await resolvers.Query.bruger(null, { id: '123' }, context)
    expect(resultat).toMatchObject({
      id: '123',
      navn: 'Test Bruger'
    })
  })

  test('hentBruger kaster fejl ved ugyldigt id', async () => {
    await expect(
      resolvers.Query.bruger(null, { id: 'ugyldigt' }, context)
    ).rejects.toThrow(ValideringsFejl)
  })
})

Skematest verificerer at typedefinitioner og resolvere er korrekt implementeret og matcher hinanden. Dette forhindrer subtile fejl der kunne opstå ved ændringer i skemaet eller implementationen.