Das könnte dich ebenfalls interessieren: Swagger zu Node Server hinzufügen

Schritt 1: NestJS auf Vercel hosten

Das Wichtigste zuerst: Die Grundeinstellungen für die Bereitstellung auf Vercel. Vercel ist großartig für Serverless, aber die Arbeit mit NestJS benötigt ein paar Anpassungen. Die Hauptsache ist, eine vercel.json-Konfigurationsdatei einzurichten, die Vercel genau sagt, wie die App zu behandeln ist.

Hier ist die Endkonfiguration:

{
  "version": 2,
  "builds": [
    {
      "src": "src/main.ts",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "src/main.ts",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "OPTIONS",
        "DELETE",
        "HEAD",
        "CONNECT",
        "TRACE"
      ]
    }
  ]
}

Ich habe daraufhin in Vercel folgende Fehlermeldung erhalten:

This Serverless Function has crashed. Your connection is working correctly. 
Vercel is working correctly. 500: INTERNAL_SERVER_ERROR 
Code: FUNCTION_INVOCATION_FAILED ID: bom1::sgk4v-1711014022883-1e9ed54f4c37

Bei einem Blick in die Logs stellte ich fest, dass die Datenbankverbindung ein Problem darstellte und außerdem die folgende Logmeldung angezeigt wurde:

No exports found in module "/var/task/app-name/src/main.js".
Did you forget to export a function or a server?

Es stellte sich heraus, dass ich den zweiten Teil der Fehlermeldung ignorieren und mich nur auf die Datenbankverbindung konzentrieren musste.

Schritt 2: Konfigurieren der Datenbank

Für meine Anwendung habe ich eine mysql-Datenbank mit mehreren Schemata verwendet. Ich habe mehrere kostenlose Angebote ausprobiert, aber sie waren nicht mit dem Ansatz mehrerer Schemata kompatibel. Daher habe ich mich für das Hosting bei Google Cloud entschieden. Ich habe es auf einen Preis von 0,01 $ pro Stunde heruntergeschraubt und das 300 $-Einsteigerangebot genutzt.

Um Vercel eine Verbindung zu ermöglichen, musste in der Konfiguration von Google Cloud die IP-Adresse auf 0.0.0.0/0 gesetzt werden, so dass die Datenbank von jeder IP-Adresse aus zugänglich war.

Schritt 3: Umgang mit CORS

Die CORS Fehler haben auch für einige Kopfschmerzen gesorgt. Stelle sicher, dass OPTIONS für CORS Preflight-Anfragen zugelassen wird, da Vercel eine explizite Erlaubnis für Cross-Origin-Anfragen benötigt. Am Ende musste ich eine Menge Header hinzufügen, um sicherzustellen, dass die Anfragen erlaubt waren:

app.enableCors({
    origin: 'domain-name',
    credentials: true,
    methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
    allowedHeaders: [
      'Origin',
      'X-Requested-With',
      'Content-Type',
      'Accept',
      'Authorization',
    ],
  });

Schritt 4: Umstellung auf express-session und Redis für die Sitzungsverwaltung

Einer der kniffligsten Teile war die Sessions zum Laufen zu bringen. Ich begann mit der cookie-session Bibliothek, aber Vercel ignoriert sie komplett. Nach einem Blick in die Dokumentation und einigem Ausprobieren wechselte ich zur express-session Bibliothek, da sie populärer ist und besser mit Vercels serverloser Umgebung funktioniert.

Aus irgendeinem Grund muss die Import-Syntax genau so aussehen:

import session = require('express-session');

Außerdem musste ich die Sitzungsmiddleware mit aktiviertem Vertrauensproxy konfigurieren, da Vercel Anfragen proxifiziert. So sieht die Einstellung aus:

const expressApp = app.getHttpAdapter().getInstance();
expressApp.set('trust proxy', true);

Auch die Einstellung secure: true und sameSite: ’none‘ war wichtig, um sicherzustellen, dass Cookies über HTTPS und verschiedene Domainanfragen funktionieren!

Beachten, dass mit Vercel mehrere serverlose Instanzen Anfragen bearbeiten können, was bei parallelen Anfragen leider zu Sitzungskonflikten führt. Um dies zu beheben, habe ich meinen Sitzungsspeicher mit einer Redis-Instanz verbunden. Glücklicherweise war das super einfach.

Redis hält die Sitzungsdaten konsistent und vermeidet Konflikte zwischen Anfragen, insbesondere unter Last. Hier der Code:

const expressApp = app.getHttpAdapter().getInstance();
expressApp.set('trust proxy', true);

const redisClient = createClient({
    password: process.env.REDIS_PASSWORD,
    socket: {
      host: process.env.REDIS_HOST,
      port: parseInt(process.env.REDIS_PORT, 10),
    },
  });

  redisClient
    .connect()
    .catch((err) =>
      console.log('Could not establish a connection with Redis: ' + err),
    );

  redisClient.on('error', (err) => console.log('Redis error: ' + err));
  redisClient.on('connect', () =>
    console.log('Connected to Redis successfully'),
  );

  app.use(
    session({
      store: new RedisStore({ client: redisClient }),
      secret: process.env.COOKIE_SECRET,
      cookie: {
        secure: process.env.NODE_ENV !== 'development',
        sameSite: process.env.NODE_ENV === 'development' ? 'lax' : 'none',
        maxAge: 86400000,
      },
    }),
  );

Schritt 5: Hinzufügen von withCredentials im Frontend

Dieser Schritt ist nur eine Randnotiz: Damit Session-Cookies zwischen Frontend und Backend funktionieren, muss withCredentials in den HTTP-Anfragen meines Frontends auf true gesetzt werden. Dies ermöglicht die Einbeziehung von Cookies in herkunftsübergreifende Anfragen, was wichtig ist, wenn das Frontend und das Backend getrennt gehostet werden. Ich musste sicherstellen, dass der HTTP-Client von Angular diese Einstellung aktiviert hat.

Schritt 6: Schriftart hinzufügen

Um Schriftdateien in Ihr NestJS-Projekt einzubinden, muss man die CompilerOptions in der nest-cli.json-Datei verwenden, um Assets für die Build-Ausgabe zu definieren, z. B. durch die Angabe von „include“: „**/*.ttf“ und ‚outDir‘: „dist/src“.

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "assets": [
      {
        "include": "**/*.ttf",
        "outDir": "dist/src"
      }
    ],
    "deleteOutDir": true
  }
}

Anschließend kann man nach dem Build die Schriftarten im Code mit path.resolve referenzieren, z. B. path.resolve(__dirname, ‚../fonts/Roboto-Regular.ttf‘). Auf diese Weise wird sichergestellt, dass die Schriftartendateien mit dem Build gebündelt werden und während der Laufzeit zugänglich sind.

Schlussgedanken zum Thema NestJS auf Vercel hosten

Das Deployment meiner NestJS-App auf Vercel war eine wahre Achterbahnfahrt. Manchmal hatte ich das Gefühl, dass ich kurz davor war, alles perfekt zum Laufen zu bringen, nur um dann mit neuen Fehlern konfrontiert zu werden, die mich zurück in den Fehlersuch-Modus schickten. Es gab Momente der Frustration – vor allem im Zusammenhang mit der Sessionverarbeitung und CORS-Problemen. Aber jede Lösung brachte ein neues Hoch, und jeder behobene Fehler fühlte sich wie ein kleiner Sieg an.

Jetzt, wo endlich alles reibungslos funktioniert, kann ich sagen, dass es ein großartiges Gefühl ist. Wenn ich sehe, dass meine Anwendung so funktioniert, wie ich es mir vorgestellt habe, ist das all die Kopfschmerzen wert. Es ist eine große Erleichterung, aber noch mehr freut es mich, zu wissen, dass ich jede Hürde überwunden habe und auf das, was ich gelernt habe, zurückblicken kann. Ich hoffe, dieser Leitfaden kann anderen einige dieser Schwierigkeiten ersparen und helfen, diesen „Es funktioniert einfach“-Moment etwas schneller zu erreichen!

The post Erfahrungen aus der Praxis: NestJS auf Vercel hosten appeared first on Nerd Corner.

Ich sehe leider sehr oft Blogartikel in denen der HTML Code in der Arduino Datei eingebettet wird. Sowas kann man für eine Mini Demonstration zwar machen, ist aber im Alltag völliger Schwachsinn. Es ist viel zu unübersichtlich und sobald das Projekt wächst nicht mehr nutzbar.

Die ordentliche Alternative ist einen Ordner namens „data“ einzurichten und in diesem die Webseiten als html Dateien abzulegen. Zusätzlich wird das Styling als CSS Datei gespeichert und es können sogar Funktionen per JavaScript Datei ausgeführt werden. Also alles 1:1 wie auf einem gewöhnlichem Webserver!

Das könnte dich auch interessieren: WeMos D1 R2 erste Schritte und Wlan Integration

Liste der Komponenten

• Arduino IDE (Entwicklungsumgebung)
• WeMos D1 R2

Das Einrichten des Dateisystems (offiziell SPIFFS) geschieht einmalig und ist kinderleicht:

(Zunächst sollte man die grundlegende Einrichtung aus dem ersten Teil abgeschlossen haben!)

1. Auf GitHub eine Kopie der Datei „ESP8266FS-0.2.0.zip“ herunterladen und entpacken
2. Die Datei esp8266fs.jar im Arduino-Tool-Verzeichnis ablegen. Der Pfad sieht etwa so aus: [home_dir]\Arduino\tools\ESP8266FS\tool\esp8266fs.jar (Siehe Bild) Ich musste den Pfadteil tools\ESP8266FS\tool\ im Arduino Ordner selbst erstellen.
3. Die Arduino IDE neustarten.

Das wars auch schon! Man kann jetzt in der Arduino DIE unter Tools den neuen Punkt „ESP8266 Sketch Data Upload“ sehen.

Wie kann man das neue Dateisystem jetzt nutzen?

1. Erstellen Sie in ihrem aktuellen WeMos Projekt Ordner einen zusätzlichen Ordner mit dem Namen „data“. So wie in dem nachfolgendem Bild

2. Legen Sie die Dateien, die Sie hochladen möchten, in das ‚data‘-Verzeichnis
3. Wählen Sie in der Arduino IDE im Menü ‚Tools‘ den WeMos aus und wählen Sie eine Größe bei ‚Flash Size‘
4. Das Dialogfeld für den seriellen Monitor schließen!
5. Wählen Sie aus dem Menü ‚Tools‘ die Option ‚ESP8266 Sketch Data Upload‘.

Sobald der Upload abgeschlossen ist zeigt das Nachrichtenfenster der Arduino IDE 100% Upload an.

WeMos Beispielprogramm zum Ein- und Ausschalten der OnBoard LED

Ähnlich wie im ersten Teil wird der Webserver die OnBoard LED steuern. Als Basis dient ebenfalls der Code aus dem ersten Teil. Der überarbeitete Code sieht so aus:

#include <ESP8266WiFi.h>
#include <ESP8266WebServer.h>
#include <ESP8266mDNS.h>

ESP8266WebServer server(80);

void setup() {
  Serial.begin(115200); //Baudrate
  Serial.println("ESP starts");

  WiFi.begin("NerdCornerWiFi","NerdCornerPassword");


  Serial.print("Connecting...");

  while(WiFi.status()!=WL_CONNECTED){ //Loop which makes a point every 500ms until the connection process has finished

    delay(500);
    Serial.print(".");
  }
  Serial.println();

  Serial.print("Connected! IP-Address: ");
  Serial.println(WiFi.localIP()); //Displaying the IP Address

  if (MDNS.begin("nerd-corner")) {
    Serial.println("DNS started, available with: ");
    Serial.println("http://nerd-corner.local/");
  }

  server.serveStatic("/", SPIFFS, "/", "max-age=86400");
  SPIFFS.begin();

  server.onNotFound([](){ 
    server.send(404, "text/plain", "Landing page not found! Don't forget to name your landing page 'index.html'!");  
  });
 
  server.on("/led", HTTP_POST, []() {    
     
    const String ledState = server.arg("ledstate");
    if(ledState=="on"){
      switchLedOn();
    }
    else if(ledState=="off"){
      switchLedOff();
    }
    server.send(200, "text/json", "{\"result\":\"ok\"}");
  });

  server.begin();
  // initialize digital pin LED_BUILTIN as an output.
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  server.handleClient();
  MDNS.update();

}

void switchLedOff(){ 
  digitalWrite(LED_BUILTIN, HIGH);   // turn the D1 LED off 
}

void switchLedOn(){ 
  digitalWrite(LED_BUILTIN, LOW);    // turn the LED on 
}

Auf ein paar Besonderheiten möchte ich dabei hinweisen. Wir haben beispielsweise folgendes hinzugefügt:

server.serveStatic("/", SPIFFS, "/", "max-age=86400"); 
SPIFFS.begin();

Ohne die beiden Zeilen wäre der Zugriff auf die Dateien im „data“ Ordner nicht möglich. Bitte beachten, dass der Name „index.html“ als default für die Landing Page eingestellt ist. Wenn man unbedingt möchte kann man das aber auch ändern.

server.on("/led", HTTP_POST, []() {    
     
    const String ledState = server.arg("ledstate");
    if(ledState=="on"){
      switchLedOn();
    }
    else if(ledState=="off"){
      switchLedOff();
      }
      server.send(200, "text/json", "{\"result\":\"ok\"}");
  });

Der „/led“ Endpoint empfängt die Befehle vom Webserver. Lautet der Befehl „on“ wird die LED eingeschaltet und bei „off“ wird die LED ausgeschaltet.

Wemos Webseite zum Ein- und Ausschalten der WeMos OnBoard LED

Die Beispielwebseite ist ganz einfach aufgebaut. Sie besteht in erster Linie aus 2 Buttons zum Ein- und Ausschalten der LED.

Die Ordnerstruktur der Webseite ist sehr übersichtlich gehalten. Es gibt eine Hauptseite mit dem Namen „index.html“ Dieser Name ist weltweit üblich für die Hauptseiten und wird auch automatisch vom WeMos entsprechend erkannt. Darüber hinaus einen „CSS“ Ordner fürs Styling und einen „JS“ Ordner für Funktionen.

Im Header Bereich der Webseite verlinken wir die Styles. Da wäre zum einen ein Standard Bootstrap, der alles automatisch bischen schöner macht und zusätzlich eine custom Styles Datei mit meinen eigenen Anpassungen. Außerdem werden im Header Bereich auch die Funktionen der Webseite verlinkt. Ich benutze den jQuery Standard um von der Webseite Requests an den WeMos zu senden. Meine eigenen custom Funktionen liegen in der „index.js“.

Bitte beachten, dass die jQuery Datei VOR der eigenen Datei eingebunden werden muss, sonst können keine jQuery Befehle im eigenen Code benutzt werden! Die eigenen Funktionen werden anschließend von den Buttons verwendet. Der HTML Code der Seite sieht insgesamt folgendermaßen aus:

<!DOCTYPE html>
<html lang="en"></html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1, shrink-to-fit=no"
    />
    <script type="text/javascript" src="js/jquery-3.5.1.min.js"></script>
    <script type="text/javascript" src="./js/index.js"></script>
    <link rel="stylesheet" href="css/bootstrap.min.css" />
    <link rel="stylesheet" href="css/custom-style.css" />
    <title>D1 Webserver</title>
  </head>
  <body>
    <h1>D1 Webserver with filesystem</h1>
    <p>
      This is an example for a WeMos Webserver with a filesystem. You can easily
      create webpages with html, css and js!
    </p>

    <h3>Example to turn on and off the built in LED</h3>
    <button class="button-style" onclick="changeLEDState('on')">Turn on</button>
    <button class="button-style" onclick="changeLEDState('off')">
      Turn off
    </button>

    <h3>Example to demo a JS function</h3>
    <button class="button-style" onclick="showAlert()">Show alert</button>
  </body>
</html>

Besonderes Augenmerk gilt der JavaScript Funktion „changeLEDState(value)“

function changeLEDState(value) {
  $.post("/led", { ledstate: value });
}

Dadurch, dass jQuery genutzt wird für die Kommunikation mit dem WeMos, reicht ein einfaches Dollarzeichen mit dem entsprechendem Request Befehl. Bei diesem POST Request wird ebenfalls ein Wert mit geschickt, welcher entweder „on“ oder „off“ ist zum ein- und ausschalten der LED.

Die Webseite kann nachfolgend als zip Datei heruntergeladen werden.

Dateien zum Herunterladen

• Wemos example webserver to control OnBoard LED

The post WeMos D1 R2 – Ganze Webseite mit html, css & js hosten appeared first on Nerd Corner.

Auch sollte der Fokus stehts auf clean Code legen und dieser ordentlich dokumentiert sein, besonders wenn ein Projekt größer wird zahlt sich ordentlich dokumentierte Arbeit aus. Um beispielsweise REST Endpunkte zu dokumentieren empfiehlt es sich Swagger zu benutzen. Die Swagger API Dokumentation bietet eine Übersicht über alle Endpunkte und sogar die Möglichkeit mit diesen zu interagieren.

Das könnte Sie auch interessieren: Angular Form SVG mit clickbaren Elementen

Liste der Komponenten

• Entwicklungsumgebung (z.B. VS Code)
• Node.js

Dokumentation mit Swagger

Obwohl Swagger recht bekannt ist, konnte ich keine detaillierte Anleitung für die Implementation finden. Ich möchte daher 2 Wege zur Implementierung von Swagger in einen bestehenden Node Server erklären. Die erste Möglichkeit besteht darin direkt zu jedem Endpunkt Swagger Parameter hinzuzufügen. Das ist wohl die schnellere Variante, kann allerdings abhängig von der Anzahl der Endpunkte unübersichtlich werden. In der zweiten Variante wird eine „swagger.json“ Datei erstellt, die die  Parameter der Endpunkte zusammenfasst.

Um Swagger nutzen zu können wird folgende Bibliothek bzw. deren Typerweiterung genutzt:

npm install --save  swagger-ui-express
npm install --save-dev @types/swagger-ui-express

Swagger erstellt eine Dokumentation der Endpunkte:

Diese können geöffnet werden und man sieht einen beispielhaften Request und einen beispielhaften Response:

Über den Button „Try it out“ kann direkt mit dem Endpunkt interagiert werden.

Swagger API Dokumentation mit Parametern

Diese Variante empfiehlt sich eher für kleinere Projekte. Zunächst müssen diese beiden Swagger Bibliotheken in das Projekt eingebunden werden:

npm install --save-dev @types/swagger-jsdoc 
npm install --save swagger-jsdoc

Die Bibliotheken werden in app.ts bzw. für nicht Typescript Nutzer app.js konfiguriert. Aufgrund der hier festgelegten Konfiguration befindet sich die Dokumentation unter „/api-docs“:

import express from "express";
import bodyParser from "body-parser";
import exampleRoutes from "./routes/example-route";
import swaggerJSDoc from "swagger-jsdoc";
import swaggerUi from "swagger-ui-express";

const app = express();

const options = {
  definition: {
    openapi: "3.0.1",
    info: {
      title: "REST API for Swagger Documentation",
      version: "1.0.0",
    },
    schemes: ["http", "https"],
    servers: [{ url: "http://localhost:3000/" }],
  },
  apis: [
    `${__dirname}/routes/example-route.ts`,
    "./dist/routes/example-route.js",
  ],
};

const swaggerSpec = swaggerJSDoc(options);

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
app.use(bodyParser.json());
app.use(exampleRoutes);

app.listen(3000);

Der Endpunkt wird mit den Parametern folgendermaßen beschrieben:

import { Router } from "express";
import { exampleFunction } from "../controller/example";

const router = Router();

/**
 * @swagger
 * /example:
 *      post:
 *          summary: Send the text to the server
 *          tags:
 *              - ExampleEndpoints
 *          description: Send a message to the server and get a response added to the original text.
 *          requestBody:
 *              required: true
 *              content:
 *                  application/json:
 *                      schema:
 *                          type: object
 *                          properties:
 *                              responseText:
 *                                  type: string
 *                                  example: This is some example string! This is an endpoint
 *          responses:
 *              201:
 *                  description: Success
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: object
 *                              properties:
 *                                  text:
 *                                      type: string
 *                                      example: This is some example string!
 *              404:
 *                  description: Not found
 *              500:
 *                  description: Internal server error
 */
router.post("/example", exampleFunction);

export default router;

Swagger API Dokumentation mit swagger.json

Um eine bessere Übersicht zu haben und um die Dokumentation nicht mit dem eigentlichen Code zu vermischen empfiehlt sich die Nutzung einer, oder gar mehrerer json Dateien. Bei der Nutzung von TypeScript muss die Swagger.json Datei in die rootDirectory:

Auch hier wirdzunächst die Konfiguration in app.ts bzw. für nicht Typescript Nutzer in app.js festgelegt. Hier wird ebenfalls der Domainpfad „/api-docs“ für die Dokumentation gewählt:

import express from "express";
import bodyParser from "body-parser";
import exampleRoutes from "./routes/example-route";
import swaggerUi from "swagger-ui-express";

import * as swaggerDocument from "./swagger.json";

const app = express();

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.use(bodyParser.json());

app.use(exampleRoutes);

app.listen(3000);

Wichtiger Hinweis: Um JSON Dateien in ein Typescript Projekt zu importieren muss dies in der tsconfig.json erlaubt werden. Außerdem muss die JSON Datei sich in der root directory befinden:

{
  "compilerOptions": {
    "target": "es2016" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
    "module": "commonjs" /* Specify what module code is generated. */,
    "rootDir": "./src" /* Specify the root folder within your source files. */,
    "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
    "resolveJsonModule": true /* Enable importing .json files. */,
    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
    "strict": true /* Enable all strict type-checking options. */,
    "skipLibCheck": true /* Skip type checking all .d.ts files. */
  }
}

Die vorherige Swagger Dokumentation mit Parametern würde somit in der swagger.json folgendermaßen aussehen:

{
  "openapi": "3.0.1",
  "info": {
    "title": "REST API for Swagger Documentation",
    "version": "1.0.0"
  },
  "schemes": ["http"],
  "servers": [{ "url": "http://localhost:3000/" }],
  "paths": {
    "/example": {
      "post": {
        "tags": ["ExampleEndpoints"],
        "summary": "Send a text to the server",
        "description": "Send a message to the server and get a response added to the original text.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExampleSchemaHeader"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleSchemaBody"
                }
              }
            }
          },
          "404": { "description": "Not found" },
          "500": { "description": "Internal server error" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ExampleSchemaBody": {
        "properties": {
          "responseText": {
            "type": "string",
            "example": "This is some example string! This is an endpoint"
          }
        }
      },
      "ExampleSchemaHeader": {
        "required": ["text"],
        "properties": {
          "text": {
            "type": "string",
            "example": "This is some example string!"
          }
        }
      }
    }
  }
}

Dateien zum Herunterladen

• Github Beispielprojekt für swagger Parameter
• Github Beispielprojekt für swagger.json

The post Swagger Api Doku zu Node Server hinzufügen appeared first on Nerd Corner.

Angular selbst überprüft regelmäßig das View Model auf Änderungen. Sollte sich aufgrund einer State Änderung das View Model verändern, rendert Angular die View neu, weil Angular automatisch das UI anpasst, wenn sich das Model verändert. Durch diese kontinuierlichen Beobachtungen wird die ganze Anwendung langsamer.

Zudem steigt mit dem traditionellen Pull Ansatz die Komplexität. Besonders, wenn mehrere Views dieselben Daten benötigen. Was passiert, wenn sich die Daten ändern? Wie werden die Views darüber informiert, dass neue Daten verfügbar sind? Callback Funktionen könnten helfen, aber dann wird die Anwendung schnell unübersichtlich. Außerdem wirken sie sich besonders bei größeren Anwendungen negativ auf die Handhabung und Wartung aus. Schließlich müssen die Objekte einzeln initialisiert werden und die Abhängigkeiten bzw. die Reihenfolge der Methoden beachtet werden.

Um dieses Problem zu umgehen kann eine Push basierte Architektur genutzt werden. Angular bietet hier mit RxJS und dem Fassaden Entwurfsmuster eine hervorragende Möglichkeit zur Implementierung! Die Implementierung wird anhand eines Angular Beispiels in diesem Blog Artikel erläutert und ist für alle Plattformen und Frameworks (Angular, React, Vue.js, usw.) übertragbar.

Liste der Komponenten:

• Entwicklungsumgebung
• Angular CLI

Was ist eine Fassade eigentlich?

Das Fassaden Entwurfsmuster ist ein zentrales Interface, welches mit verschiedenen Schnittstellen eines oder mehrerer untergeordneter Systeme kommuniziert. Es kann je nach Bedarf zusätzliche Funktionen sowohl vor als auch nach einer Client Anfrage ausführen.

Das Fassaden Objekt bietet eine einheitliche und meist vereinfachte Schnittstelle zu einer Menge von Schnittstellen eines Subsystems.

Es sorgt als Vermittler dafür, dass die Kommunikation bzw. der Zugriff auf die einzelnen Komponenten eines Subsystems vereinfacht und damit auch die direkte Abhängigkeit von diesen Komponenten minimiert wird. Es delegiert die Clientaufrufe so, dass Clients weder die Klassen noch ihre Beziehungen und Abhängigkeiten kennen müssen.

Das ist besonders in großen Systemen hilfreich, wenn ein Subsystem viele technisch orientierte Klassen enthält, die selten von außen verwendet werden. Die Verwendung einer Fassade senkt die Komplexität, da mehrere Schnittstellen zu einer zusammengefasst werden. Außerdem kann das Subsystem durch die lose Kopplung leichter erweitert werden.

Die PUSH Architektur

Für eine Push basierte Architektur können fortgeschrittene Entwurfsmuster wie Redux oder NgRx verwendet werden. Allerdings kann auch eine sehr elegante und performante push basierte Lösung mit RxJS erreicht werden.

Mit Hilfe der lang lebigen RxJS Observable streams können Veränderungen der Daten an alle Subscriber gepusht werden. Dazu subscriben die Views dem gewünschten Daten Stream. Verändern sich dann die Daten, werden die Änderungen über den Stream direkt an alle Subscriber gepusht ohne das der UI Thread geblockt wird.

Auf diese Art und Weise wird ein direkter Datenzugang verhindert und die Daten sind read-only. Die eigentliche Datenquelle wird ähnlich wie bei einer API angesprochen, die von den Views verwendet wird. Als zentrale Schnittstelle dient hier die eingangs beschriebene Fassade. Diese besteht aus Streams, die Daten liefern, wenn sich die Daten ändern und Methoden, um Änderungen an den Daten anzufordern oder bestimmte benutzerdefinierte Streams anzufordern.

Die eigentlichen Rohdaten sind erst verfügbar, nachdem sie durch den/die Stream(s) gepusht worden sind. Diese Abschirmung zentralisiert die gesamte Logik und zwingt die Views passiv auf die eingehenden Daten zu reagieren. Mit den Push basierten Diensten werden Angular View Komponenten hoch performant und nutzen dabei sowohl ChangeDetectionStrategy.OnPush, als auch die async Pipe für die gelieferten Stream Daten.

Daher ist das System lazy loading. Das UI-Framework braucht nicht nach Zustandsänderungen des View-Modells suchen und wartet stattdessen lazy darauf, dass ein neuer Zustand gepusht wird.

Praxisbeispiel

Als Beispiel für eine Push basierte Architektur dient eine einfache Anwendung, welche über den HTTP Request https://random-data-api.com/api/beer/random_beer?size=1 eine zufällige Bier Sorte erhält. Eine View zeigt die Biersorte an. Über ein kleines Input Feld kann die Anzahl der anzuzeigenden Biere variiert werden. Eine Fassade als zentrales Element pusht automatisiert die neuen Biersorten an die View, sobald diese verfügbar sind.

Als Vorbild für das Entwurfsmuster dient der Artikel von Thomas Burleson: https://thomasburlesonia.medium.com/push-based-architectures-with-rxjs-81b327d7c32d

Als erstes muss das State Management aufgesetzt werden:

export interface Beer {
  brand: string;
  name: string;
  style: string;
  hop: string;
  alcohol: string;
}

export interface BeerState {
  beerArray: Beer[];
  size: number;
}

Als nächstes initialisieren wir die Werte des Statemanagements der Fassade:

export interface BeerState {
  beerArray: Beer[];
  size: number;
}

let _state: BeerState = {
  beerArray: [],
  size: 4
};

Die Fassade nutzt RxJS Streams um Daten direkt an die Views zu pushen. Diese Streams können auch automatisiert bei einer Änderung der States einen Rest API call ausführen:

combineLatest(this.size$)
      .pipe(
        //switchMap: Maps values to observable. Cancels the previous inner observable.
        switchMap(([size]) => {
          return this.findBeerArray(size);
        })
      )
      .subscribe((beerArray) => {
        this.updateState({ ..._state, beerArray });
      });

Die Streams werden so aufgebaut, dass sie dauerhaft erhalten bleiben und nur bei einer Datenänderung aktiv werden:

export class BeerFacade {

  beerArray$ = this.state$.pipe(
    map((state) => state.beerArray),
    distinctUntilChanged()
  );

  size$ = this.state$.pipe(
    map((state) => state.size),
    distinctUntilChanged()
  );

  private updateState(state: BeerState) {
    this.store.next((_state = state));
  }
}

Für die bessere Handhabung werden die Streams zu einem Einzigen zusammengefasst:

vm$: Observable<BeerState> = combineLatest(this.beerArray$, this.size$).pipe(
    map(([beerArray, size]) => {
      return { beerArray, size };
    })
  );

Der HTTP Request kann in einen seperaten Data Service ausgelagert werden. Da es sich hierbei aber nur um ein kleines Beispielprogramm handelt, wird der Restcall innerhalb der Facade implementiert und ausgeführt:

/** RandomBeer REST call */
  private findBeerArray(size: number): Observable<Beer[]> {
    const url = `https://random-data-api.com/api/beer/random_beer?size=${size}`;
    return this.http.get<Beer[]>(url);
  }

Die Fassade und der View Model Stream können nun einfach initialisiert und genutzt werden. Es ist unglaublich wenig Code notwendig:

export class AppComponent {
  vm$: Observable<BeerState> = this.facadeService.vm$;

  //facadeService is public for direct usage in html
  constructor(public facadeService: RandomBeerFacadeService) {} 
  title = 'RandomBeerApp';
}

Die Daten des View Model Streams werden mit folgendem Codeschnippsel angezeigt:

<div *ngIf="vm$ | async as vm">  
  <ul>
    <li id="random-beer-list" *ngFor="let u of vm.beerArray">
      Brand: {{ u.brand }}, Alcohol: {{ u.alcohol }}, Hop: {{ u.hop }}
    </li>
  </ul>
  <input id="input-rand-beer" type="number" (change)="facadeService.updateSize($event)" />
</div>

Dabei sorgt die Async Pipe von Angular dafür, dass immer die aktuellsten Daten angezeigt werden. Hier findet sich eine genaue Erklärung der Async Pipe.

Da der Fassaden Service als public deklariert wurde, werden die Inputs direkt an die updateSize Funktion der Fassade weitergegeben:

updateSize(selectedSize: any) {
    const size = selectedSize.target.value;
    this.updateState({ ..._state, size });
  }

Als Resultat zeigt die Applikation zunächst 4 zufällige Biere an. Anschließend kann durch das Input Feld die Anzahl auf 7 erhöht werden. Dadurch wird die Funktion updateSize() aufgerufen, welche mittels updateState() den State des size$ streams aktualisiert. Als Folge dessen wird automatisiert ein neuer REST call ausgeführt und das Ergebnis an das View Model gepusht. Mit Hilfe der async Pipe werden somit die neusten Daten angezeigt. In unserem Fall die 7 zufälligen Biersorten.

Abschließend macht es Sinn die Funktionalität der einzelnen Fassaden Bestandteile zu testen:

it('should get individual Observable "stream" of vm data', (done) => {
    testFacade.vm$.subscribe((vm) => {
      expect(vm.size).toEqual(initStateMock.size);
      done();
    });
  });

  it('should update state values', (done) => {
    const updatedStateMock: TestBeerState = {
      beerArray: [
        {
          brand: 'Pabst Blue Ribbon',
          name: 'Two Hearted Ale',
          style: 'Merican Ale',
          hop: 'Sorachi Ace',
          alcohol: '2,9%',
        },
        {
          brand: 'Bud Light',
          name: 'La fin Du Monde',
          style: 'Stout',
          hop: 'Bullion',
          alcohol: '2,7%',
        },
      ],
      size: 2,
    };
    testFacade['updateState'](updatedStateMock);
    testFacade.vm$.subscribe((vm) => {
      expect(vm).toEqual(updatedStateMock);
      done();
    });
  });

  it('should update the size value', (done) => {
    const newSize = 9;
    const mockEvent = {
      target: {
        value: newSize,
      },
    };
    testFacade['updateSize'](mockEvent);
    testFacade.vm$.subscribe((vm) => {
      expect(vm.size).toEqual(newSize);
      done();
    });
  });

  it('should perform a mocked http request', (done) => {
    const httpMock: HttpTestingController = TestBed.inject(
      HttpTestingController
    );

    const mockResponse = {
      brand: 'Pabst Blue Ribbon',
      name: 'Two Hearted Ale',
      style: 'Merican Ale',
      hop: 'Sorachi Ace',
      alcohol: '2,9%',
    };

    testFacade['findBeerArray'](1);
    testFacade.vm$.subscribe((tb) => {
      expect(tb.beerArray).toBeTruthy();
      expect(tb.beerArray[0].brand).toBe(mockResponse.brand);
      expect(tb.beerArray[0].name).toBe(mockResponse.name);
      expect(tb.beerArray[0].style).toBe(mockResponse.style);
      expect(tb.beerArray[0].hop).toBe(mockResponse.hop);
      expect(tb.beerArray[0].alcohol).toBe(mockResponse.alcohol);

      done();
    });

    const mockRequest = httpMock.expectOne(
      'https://random-data-api.com/api/beer/random_beer?size=1'
    );
    mockRequest.flush(mockResponse);
  });

Dateien zum Herunterladen

• Source Code in GitHub

The post Wie man eine Angular Fassade mit PUSH Architektur programmiert appeared first on Nerd Corner.