1.1.0-next.0 • Published 4 years ago

diva-backend-commons v1.1.0-next.0

Weekly downloads
-
License
COMMERCIAL
Repository
-
Last release
4 years ago

Diva Backend Commons

Diese Library sollte für alle Diva Services verwendet werden. Sie enthält viel Boilerplate code und erlaubt es sehr schnell einen neuen Service aufzusetzen.

Verwendung

Unter '/api' befindet sich eine Beispiel implementierung die zeigt wie die Library verwendet wird.

Router

Das Haubtmodule bildet der Router. Die Klasse bildet einen Wrapper für den Express Server und kann mittels wenigen Options konfiguriert werden.

Die Options für die Router Klasse:

  • allRoutes: Ein Array aller Controller für die Routen dieses Services
  • authProvider: Optional kann der Authorizationprovider überschrieben werden
  • openApiSpecPath: Optional kann ein Pfad zu einer OpenAPI Spezifikation angegeben werden die OpenAPI Funktionalitäten aktiviert
  • processPayload: Ein Optionales Array von Funktionene die es erlauben den Payload von jeder Response noch einmal zu bearbeiten
  • middleware: Ein Optionales Array von zusätzlichen RequestHandlern zum Express Server hinzugefügt werden sollen

Mit der Funktion router.startup() wird der Expressserver gestartet. Die Environmentvariable PORT legt den Port für den Server fest, der Defaultwert ist 8080.

RouteController

Der Routecontroller bildet das Interface das implementiert wird um einen bestimmten Endpoint zu definieren.

Folgende Felder müssen implementiert werden:

  • route: Die Route des Endpoints (z.B. '/users')
  • method: Die Http Request Methode (z.B. GET)
  • authRequired: Legt fest ob ein Nutzer authentifiziert sein muss um diesen Endpoint zu nutzen
  • permissions (optional): Ein Array von Rechten die für diesen Endpoint relevant sind
  • handler: Eine Funktion die die effektive Controllerlogik implementiert. Diese Funktion bekommt zwei Paramter übergeben. Das Data Objekt, ist vom Type der der im Typeparameter des Controllers definert wird und enthält alle query und body daten. Das Authorization Objekt enthält die Daten des eingeloggten Users und funktionen zur Rechteverwaltung.

Authorization Provider

Dieser Provider kann durch die Implementierung des entsprechenden Interfaces überschrieben werden. Normalerweise ist die Defaultimplementierung aber ausreichent.

Der Provider überprüft ob der Authentication Header im Request vorhanden ist, falls das im RouteController festgelegt wurde. Außerdem erstellt er das Obejekt Authorization, dass in der Handler Funktion des RouteControllers verfügtbar ist.

Vom Authorization Objekt kann mit auth.getUserData() die Daten des eingeloggten Users abgefragt werden, und mit auth.checkPermission() überprüft werden ob der User eine der im RouteController angegeben permissions besitzt.

OpenApi

Durch das angeben einer OpenApi Spezifikation, werden alle Request auf daraufhin überprüft, ob sie der Spezifikation folgen. Dadurch müssen nur mehr semantische Validierungen händisch ausprogrammiert werden.

Zusätzlich werden zwei API Endpoints erstellt, die auch bereits mit der Berechtigung api:read geschützt sind.

Unter /api-docs ist ein Webinterface verfügtbar, das es erlaubt direkt mit der API zu interagieren. Unter /api wird die OpenAPI Specification als JSON zurück geliefert, was für maschinelle Verarbeitungen genutzt werden kann.

Error Handling

Alle Errors im Service werden abgefangen und eine Fehlermeldung mit Status Code 500 über die API ausgegeben. Mit dem typ ApplicationError kann eine bestimmte Error Message und ein Http Status Code festgelegt werden, der Default Status Code für diese Errors ist 400.

Development

Voraussetzungen

  • NodeJS und NPM müssen installiert sein
    • Getestet wurde mit Version 12.13.1, also sollten alle Versionen >= 12 verwendet werden können

VS Code Konfiguration

Es sind bereits Konfigurationsdateien für VS Code enthalten, sowohl für auto-formatting als auch für debugging.

Damit sie funktionieren müssen folgende Plugins installiert sein:

  • Prettier - Code fromatter

Installationsprozess

Schritt 1: Alle Dependencies installieren

Dazu folgenden Command ausführen (PowerShell, CMD oder Bash)

npm i

Schritt 2: .env Datei erstellen

Im Basisverzeichnis des Projektes eine Datei namens '.env' erstellen. Zu beginn kann eine Kopie von '.env.example' erstellt werden. Für Details dazu siehe Abschnitt "Environment Variablen".

Aufbau/Überblick

API Test Server (/api)

Commands

Entwicklung starten

Um die Entwicklung der API zu starten, folgenden Command ausführen:

npm run server:dev

Auf welchem Port der Server gestartet wurde, kann aus der Konsole entnommen werden.

Library Component (/components)

Hier befindet sich der effektive Code der library.

Kompilieren

Ein Produktions build der Library kann mit folgendem Befehl erstellt werden:

    npm component:build

Releasen

Der Releaseprozess ist durch die CI Pipeline realisiert. Wenn keine Buildfehler auftretten und alle Tests mit einer Coverage von mindestens 50% erfolgreich sind, wird eine neue Version auf NPM released.

Tests

Mit folgendem Befehl können die Unit Tests ausgeführt werden:

npm run test:unit

Technologien

  • Webpack
  • Webpack Bundle Analyzer
  • Babel
  • TypeScript
  • Jest + TS-Jest (Testing)
  • Nodemon
  • ExpressJS
    • Wird dazu verwendet, die Domain-Logik als REST-API zur Verfügung zu stellen
  • OpenAPI / Swagger

Environment Variablen

Environment Variablen, welche für das Projekt benötigt werden, können in der '.env' Datei definiert werden. Außerdem sollten neue Environment Variabeln unter components/src/utils/index.ts, dem Objekt 'environment', mit einen eventuellen default Wert, hinzugefügt werden. Über dieses Objekt kann dann auf die Environment Variabeln zugegriffen werden.

Im Projekt eingecheckt befindet sich die Datei '.env.example'. Hier sollten alle benötigten Environment Variablen vordefiniert werden. Falls ihr in halt nicht geheim ist, z.B. ein Port, kann auch gleich ein default Wert vergeben werden. So gibt es eine gute Übersicht, über welche Environment Varialben benötigt werden.