Skip to content
/ ekorre Public

🐿 E-hemsidans backend i node skriven med Typescript, GraphQL via Apollo och Prisma

License

Notifications You must be signed in to change notification settings

esek/ekorre

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Ekorre

Mascot logo

Ekorre Àr sektionens nya backend driven av Node och GraphQL och skriven i TypeScript.

Förhoppningsvis har nÄgon hÄllit denna README:n uppdaterad...

Hur startar jag?

Börja med att installera alla node modules med š

npm install .

Kopiera .env.example till .env och fyll i miljövariablerna. .env-filen innehÄller konfigurationsvariabler till servern

ekorre anvÀnder docker compose för att fÄ upp en fungerande en databas, dvs.

docker compose up

(förutsatt att du installerat docker).

För att generera en PrismaClient (som anvÀnds för att kommunicera med databasen) och fylla databasen med rÀtt schemas anvÀnds

npm run prisma:reset

vilket Àven brukar lösa dryga problem. Detta seedar Àven databasen med lite testdata. Sedan körs projektet med

npm run dev

Hur utvecklar jag?

LĂ€s semver

TL;DR

npm run generate # Generera typescript frÄn gql och en Prisma client
npm run dev # Kompilera kontiuerligt och öppna för debugger
npm run prettier-format # Formatera kod, finns IDE intergration oftast

Struktur

För att separera kod och underlÀtta utveckling sÄ finns det en struktur. För den som ska utöka funktionaliteten i programmet finns det fyra mappar som Àr viktiga:

src
├── api
│   └── <modul>.api.ts
├── resolvers
│   ├── index.ts
│   └── <modul>.resolver.ts
├── reducers
│   └── <modul>.reducer.ts
└── schema
    └── <modul>.graphql

dÀr schemas och resolvers Àr viktigast. För att hÄlla en konsekvent och stabil struktur bör alla databasfrÄgor skötas frÄn en klass i api och sql Àr dedikerad till att skapa de tabeller som behövs för din funktion. Det finns mer djupgÄende README:s i undermapparna.

Förutom dessa finns Àven prisma/, som Àr vÄr ORM (isch). Detta Àr delen som sköter databasstruktur och vÄra queries till databasen (Postgres).

Verktyg

Det Àr rekomenderat att du bekantar dig lite med de verktyg som anvÀnds:

*kursivt

graphql-codegen

För att underlÀtta utveckling sÄ anvÀnds graphql-codegen. Detta gör att en typescript fil vid namn 'graphql.ts' i mappen src/models/generated generas som innehÄller typdefintioner för graphql frÄgor. AnvÀnd denna!

För att generera:

npm run graphql:generate

Det kan hÀnda att VScode eller annan IDE gnÀller pÄ dina typer Àven om du genererat nya. DÄ bör du i VScode köra Ctrl+Shift+P följt av Reload Window.

Kodstil

Eslint och prettier Àr konfigurerat och det rekomenderas att du följer de regler som Àr givna.

npm run lint // Testa kodfel, brukar göras av IDE
npm run prettier-format // Formatera all kod

Det hÀnder att prettier och eslint brÄkar, frÀmst vid lÄnga typdeklarationer som i src/models/mappers.d.ts. DÄ Àr det praktiskt att prega in en

// prettier-ignore

ovanför typen.

SEMVER

Versionshantering följer semantic versioning specificationen. Detta Àr viktigt eftersom releases ska taggas med semver för att kunna automatiskt deployas.

CHANGELOG

Parallellt med SEMVER (som ska uppdateras i package.json) skrivs Àven förÀndringar ner i CHANGELOG.MD. Detta för att hÄlla reda pÄ vad som förÀndrats, och för att ha en lÀttlÀst historik över projektet (vilket Àr kul!). git-historik Àr inte en ersÀttning till en bra CHANGELOG! Kolla in Keep a Changelog för mer info.

Typiskt arbetsflöde

NÀr du utvecklar en modul ser det troligen ut pÄ följande sÀtt.

  1. Du har en idé om vad man ska kunna göra och ungefÀr hur det ska fungera
  2. Du skapar en ny typ i prisma/schema.prisma och lÀgger till testdata i prisma/data/. Prisma sköter sjÀlv att skapa databasen nÀr man kör npm run prisma:push, sÄ du behöver inte skapa SQL-schemas sjÀlv!
  3. Du skapar ett nytt GraphQL-schema i src/schemas
  4. Du skapar en ny API i src/api/, som bara har i uppgift att prata med din nya SQL
  5. Du inser att du inte kan fÄ all information ur SQL och skapar en mapper-typ i src/models/mappers.d.ts, t.ex. AmazingFeatureResponse
  6. Du skapar en reducer som omvandlar DatabaseAmazingFeature till AmazingFeatureResponse
  7. Du skapar en resolver i src/resolvers/. Funktionerna dÀr anvÀnder din API och returnerar t.ex. AmazingFeatureResponse
  8. Du lÀgger till resolver-metoder för att omvandla AmazingFeatureResponse till AmazingFeature, t.ex. om AmazingFeature innehÄller User-objekt. AmazingFeatureAPI kan inte sjÀlv lösa dessa, sÄ resolvern anvÀnder ctx.userDataLoader för att omvandla AmazingFeatureResponses halvfÀrdiga User-objekt till fullvÀrdiga (detta görs automatiskt om resolvern har rÀtt fÀlt/metoder!)
  9. Du kan behöva skapa en ny DataLoader för att undvika n + 1-problemet.
  10. Du skriver enhetstester i src/test/unit/ för din nya API och reducer, och integrationstester i test/integration för din resolver
  11. Du uppdaterar CHANGELOG.MD med din nya uppdatering, och Àndrar samtidigt versionsnummret i package.json!
  12. Du ber om code review i GitHub pÄ din nya PR!

Glöm inte att köra npm run generate nÀr du pillat med GraphQL eller Prisma!

Detta kan tyckas vara mÄnga steg, men det finns gott om fÀrdiga exempel. Dessutom finns det gott om hjÀlpfunktioner, och mÄnga problem man kan tÀnkas finns lösta nÄnstans! Försök att följa de konventioner som finns, i design, namngiving och förvÀntade returvÀrden. API:n Àr mycket enklare att anvÀnda om man Àr konsekvent!

Testning

För att dels garantera att det som utvecklas gör det vi vill, och dessutom att koden fungerar som den ska, anvÀnder ekorre automatisk testning. Testerna hittas i test/ och baseras pÄ testningsramverket jest. Genom lite lek med GitLab CI trackas code coverage (alltsÄ hur stor del av koden som körs i tester) pÄ GitLab. Högt coverage garanterar inte att saker fungerar som de ska, men utan nÄgot coverage famlar man helt i blinda. Det Àr nÀstan krav att ny kod Àven kommer med tester. Hur ska du annars kunna bevisa att din kod gör det du sÀger?

Docker

Det finns en pipeline som kommer bygga docker bilder med hjÀlp av Dockerfile. Dessa publiceras sedan till en registry som tillhör detta projekt. Dessa bilder Àr i huvudsak designade för servern (som i skrivande stund Àr extrovert).

Referera till ddgwiki för mer information.