Hopp til innhold

Genererte API‑kontrakten med databasen som kilde

Genererte API‑kontrakten fra databasen og utover — OpenAPI, en typet TypeScript‑klient på 44 076 linjer, 61 mock‑handlere og grensene brukergrensesnittet håndhever — med en kontroll i hvert ledd som feiler ved avvik.

44,076 linjer typet klientkode, generert fra databasen

Situasjon. Frontend og backend utvikler seg i hvert sitt tempo, og antakelsene deres om innholdet i en forespørsel kan gli fra hverandre uten at noen merker det. Som regel oppdager man det gjennom en 422 i nettleseren — etter at avviket allerede er levert, som er det dyreste tidspunktet å få vite om det på. Å skrive begge sidene for hånd ut fra samme dokument løser det ikke; det flytter bare avviket over til den som glemte å lese dokumentet på nytt.

Oppgave. De to sidene måtte genereres fra én kilde i stedet for å avtales mellom to, og hvert trinn i genereringen måtte kontrolleres i stedet for å tas på tro.

Handling. Kjeden starter i databasen og går utover. Skjemaet og funksjonene i det definerer datastrukturene; Go‑typene definerer API‑et; Huma lager OpenAPI‑beskrivelsen ut fra dem; en typet TypeScript‑klient — 44 076 linjer i alt — genereres fra den beskrivelsen; 61 mock‑handlere genereres ved siden av, slik at frontendens egne tester kjører mot den virkelige kontrakten og ikke mot håndskrevne testdata; og grensene brukergrensesnittet håndhever i et webskjema, kommer fra samme sted i stedet for å bli skrevet inn på nytt i en validator. Hvert ledd har en vakt. En kontraktskontroll i CI sammenligner det frontenden sender, med det API‑et forventer, og får bygget til å feile ved avvik, med en skjemaprobe under som kontrollerer de faktiske datastrukturene i stedet for en beskrivelse av dem. Den dekker med vilje stedene der avvik gjerne gjemmer seg: valgfrie felt i forespørselskroppen, der «mangler» og «null» blandes sammen, og enumer i spørringsparametere, der de to sidene i det stille kan være uenige om de tillatte verdiene.

Resultat. Et felt kan ikke endres på bare én side — det feiler i det første leddet som merker det, i et bygg, minutter etter endringen. Det fjernet en tilbakevendende og virkelig irriterende klasse feil, den typen som er usynlig i kodegjennomgang og bare viser seg under kjøring. Prisen er et genereringstrinn midt i alt sammen: å generere på nytt er et ork, og kjeden er bare så pålitelig som sitt dårligst bevoktede ledd, og derfor fikk hvert ledd sin vakt.

  • Løs puslespillbrikke ved en åpning
    Foto: 422737 / Pixabay
  • Flerfargede puslespillbrikker
    Foto: rkit / Pixabay

Bruk erfaringen i prosjektet deres

Bruk «Genererte API‑kontrakten med databasen som kilde» som utgangspunkt for en lignende utfordring i organisasjonen deres. Tjenestene bak arbeidet er tilgjengelige for prosjektet deres. Testet, utgitt og mulig å reversere, slik at endringer når kundene en tirsdag ettermiddag i stedet for sent en fredagskveld.

Se tjenestene våre Ta kontakt

Se bak resultatet

Les om situasjonen, beslutningene og resultatet i eksemplet. Vi kan drøfte hva som passer deres rammer, og hva som krever en annen tilnærming. Genererte API‑kontrakten med databasen som kilde — 44,076 linjer typet klientkode, generert fra databasen

Se tjenestene våre Ta kontakt

Ett stykke av en lengre oversikt — og den ligger i sin helhet her.

Hver oppføring er skrevet på samme måte: situasjonen, oppgaven, hva vi gjorde, og hva som endret seg.

Se hele oversikten

Definer forbedringen dere trenger

Ta med utrullingsløpet, driftsrisikoene og dem som har vakt. Vi kan avgrense en endring med kontroller, en vei tilbake og tydelig ansvar.

Se hva det koster Ta kontakt

Glir frontend og backend fra hverandre?

Spør om beslutningene bak «Genererte API‑kontrakten med databasen som kilde». Dere snakker med folk som kan forklare arbeidet og vurdere deres eget prosjekt.

Se tjenestene våre
welcome@engineer.company +45 50 10 61 84 København, Danmark
QR-kode for Genererte API‑kontrakten fra databasen og utover — OpenAPI, en typet TypeScript‑klient på 44 076 linjer, 61 mock‑handlere og grensene brukergrensesnittet håndhever — med en kontroll i hvert ledd som feiler ved avvik.
Ta med deg denne sidenhttps://platform.engineer.company/nb/portfolio/generated-the-api-contract-from-the-database-out/