Hinweise zum Programmierbeispiel

Juergen.Zimmermann@HS-Karlsruhe.de

Diese Datei ist in Markdown geschrieben und kann mit <Strg><Shift>v in Visual Studio Code leicht gelesen werden.

Näheres zu Markdown gibt es in einem Wiki

Nur in den ersten beiden Vorlesungswochen kann es Unterstützung bei Installationsproblemen geben.

Vorbereitung der Installation

• Das Beispiel nicht in einem Pfad mit Leerzeichen installieren. Viele Javascript-Bibliotheken werden unter Linux entwickelt und dort benutzt man keine Leerzeichen in Pfaden. Ebenso würde ich das Beispiel nicht auf dem Desktop auspacken bzw. installieren.

• Bei GitHub registrieren, falls man dort noch nicht registriert ist.

Installation

• Falls es das Unterverzeichnis node_modules NICHT gibt: Installation durch npm (Node Package Manager) in einer Powershell (s.u.), :
  • Die Installation der Software-Pakete erfolgt i.a. über NPM und damit über den Port 80 (oder 443 bei https). Wenn git benötigt wird, dann wird ssh aufgerufen und deshalb Port 22 benötigt.
  • Eine persönliche Firewall o.ä. kann diesen Port blockieren. Dann funktioniert die Installation natürlich nicht und man muss z.B. die eigene Firewall geeignet konfigurieren oder vorübergehend ausschalten.
  • Der Port 22 ist am Hochschul-Proxy nicht freigeschaltet.

    npm i

Künftige Routineaufgaben

Starten und Herunterfahren von MongoDB

    npm run mongo
    npm run mongo stop

JSON-Datensätze in MongoDB importieren und exportieren

    npm run mongo import
    npm run mongo export

Beim Importieren wird die Datei config\mongoimport\spiel.json verwendet. Beim Importieren darf der DB-Browser Mongo Express (s.u.) nicht gestartet sein.

Datenbankbrowser Compass

Defaultwerte für MongoDB beibehalten zzgl. Authentifizierung:

    Server:         localhost
    Port:           27017
    Authentication: admin/p

Alternativ könnte man auch Mongo Express verwenden, was allerdings immer wieder Probleme macht, wenn MongoDB über TLS angesprochen werden muss:

    npm run mongo mongoexpress

Bei Mongo Express wird ein Webserver gestartet. Über einen Webbrowser kann dann mit der URI https://localhost:8081/db/hskadb/spiel auf die Collection spiel in der Datenbank hska zugegriffen werden.

Übersetzung durch den TypeScript-Compiler in einer Powershell

    npm run tsc

• Zuerst die Codequalität mit tslint prüfen und dann
• .ts-Dateien durch tsc in das Verzeichnis dist übersetzen

Starten des Appservers (mit Node.js und Express)

Mit nodemon in einer Powershell

Durch nodemon (= Node Monitor) wird der Appserver so gestartet, dass er JavaScript-Dateien im laufenden Betrieb nachlädt, wenn sie später aktualisiert werden, weil z.B. eine TypeScript-Datei neu übersetzt wird. Beim Starten des Appservers wird mit mongoose auf MongoDB zugegriffen.

    npm start

Von Zeit zu Zeit hängt sich nodemon auf und muss dann halt neu gestartet werden.

Falls nodemon nicht vernünftig funktioniert, kann man auch den Appserver direkt starten (s.u.) und muss diesen dann bei jeder Änderung neu starten.

Ohne nodemon in einer Powershell

    npm run serve

Dadurch wird der eigene Node-basierte Server gestartet. Das ist aber nach jeder Übersetzung neu erforderlich.

Mocking der DB

    $env:MOCK_DB = "true"
    npm start

Dadurch wird der eigene Node-basierte Server gestartet, ohne dass auf die Datenbank zugegriffen wird. Stattdessen wird mit Mock-Objekten gearbeitet.

Interaktiver Client für GraphQL im Webbrowser

    https://localhost:8443/api

Beispielhafte Eingaben sind in der Date config\graphql\beispiele.txt.

Tests aufrufen

Voraussetzungen

• Der MongoDB-Server muss laufen
• Der Appserver darf nicht laufen

Aufruf in einer Powershell

    npm t

Statt t kann man auch test ausschreiben.

Empfohlene Entwicklungsumgebung

Visual Studio Code oder WebStorm

Visual Studio Code kann man kostenfrei herunterladen.

Tipps:

• <Strg>kc : Markierte Zeilen werden auskommentiert
• <Strg>ku : Bei markierten Zeilen wird der Kommentar entfernt
• <Strg><Shift>p: Terminal: Neues integriertes Terminal erstellen

Für WebStorm gibt es bei JetBrains auf Initiative von Jürgen Zimmermann eine Studenten-Lizenz, die für 1 Jahr gültig ist.

Für Visual Studio Code ist u.a. die Erweiterung REST Client aus dem Marketplace empfehlenswert.

Chrome mit Erweiterungen

JSON Viewer für GET-Requests

Aus dem Chrome Webstore installieren.

Recx Security Analyzer für Sicherheitslücken

Aus dem Chrome Webstore installieren.

Empfohlene Code-Konventionen

In Anlehnung an die Guidelines von TypeScript

• "Feature Filenames", z.B. spiel.service.ts
• Klassennamen und Enums mit PascalCase,
• Attribute und Funktionen mit camelCase,
• private Properties nicht mit vorangestelltem _,
• Interfaces nicht mit vorangestelltem I
• Barrel für häufige Imports, z.B.
  • shared\index.ts erstellen:

    export * from './bar';
    export * from './foo';

  • einfaches Importieren:

    import { Bar, Foo } from 'shared';

• [...].forEach() und [...].filter() statt for-Schleife
• Arrow-Functions statt anonyme Funktionen
• undefined verwenden, nicht: null
• Geschweifte Klammern bei if-Anweisungen
• Maximale Dateigröße: 400 Zeilen
• Maximale Funktionsgröße: 75 Zeilen

Sonstiges

Endlosrekursion bei JSON.stringify(obj)

Ein JSON-Objekt kann eine rekursive Datenstruktur haben, wie z.B.:

const obj: any = {
    id: 4711,
    foo: {
        bar: 'a string',
        rekursiv: obj,
    },
};

Bei einer solchen rekursiven Datenstruktur gibt es beim Aufruf von JSON.stringify(obj) eine Endlosrekursion und damit einen Stackoverflow. Bei den Request- und Response-Objekten von Express gibt es rekursive Datenstrukturen.

Alternative 1: Mit der Function stringify von fast-safe-stringify kann man dennoch ein Objekt mit einer rekursiven Datenstruktur in einen String konvertieren:

    import stringify from 'fast-safe-stringify'
    ...
    stringify(obj)   // statt JSON.stringify(obj)

Alternative 2: Mit der Function inspect von Node.js kann man dennoch ein Objekt mit einer rekursiven Datenstruktur in einen String konvertieren:

    import {inspect} from 'util'   // util ist Bestandteil von Node.js
    ...
    inspect(obj)   // statt JSON.stringify(obj)

Debugging mit Visual Studio Code

• Das Debug Icon in der Activity Bar anklicken
• Den Tab Terminal auswählen, dort in das Projektverzeichnis wechseln und dann nodemon als (Remote) Server starten:

    cd <Projektverzeichnis>
    nodemon -V

nodemon ruft dann die JS-Datei auf, die in package.json bei der Property main steht, d.h. dist\index.js.

Nun kann man Breakpoints setzen, indem man bei einer geöffneten .ts-Datei links von der Zeilennummer klickt. Beim Übersetzen hat nämlich der TypeScript-Compiler Dateien für das Source Mapping generiert.

Jetzt muss man nur noch links oben bei "Debugging starten" auf den linken grünen Button klicken (siehe auch .vscode\launch.json).

Am Ende nicht vergessen, im Terminal den Server mit <Strg>C zu beenden!

Dokumentation zum Debugging