Node.js Rezepte und Lösungen 1173622156, 9783836264556
587 97 9MB
German Pages [653] Year 2019
Polecaj historie
![Praktische Tupperware Rezepte [1. Aufl]](https://dokumen.pub/img/200x200/praktische-tupperware-rezepte-1-aufl.jpg)
![Großmutters geheime Rezepte [1 ed.]
9783828912861](https://dokumen.pub/img/200x200/gromutters-geheime-rezepte-1nbsped-9783828912861.jpg)
Table of contents :
Materialien zum Buch
Geleitwort des Fachgutachters
Vorwort
1 Initialisierung und Setup
1.1 Rezept 1: Node.js installieren
1.1.1 Arten der Installation
1.1.2 Lösung: Installation über Installationsdatei unter macOS
1.1.3 Lösung: Installation über Installationsdatei unter Windows
1.1.4 Lösung: Installation über Binärpaket unter macOS
1.1.5 Lösung: Installation über Binärpaket unter Windows
1.1.6 Lösung: Installation über Binärpaket unter Linux
1.1.7 Lösung: Installation über Paketmanager
1.1.8 Ausblick
1.2 Rezept 2: Mehrere Node.js-Versionen parallel betreiben
1.2.1 Lösung
1.2.2 Alternativen
1.2.3 Ausblick
1.3 Rezept 3: Ein neues Node.js-Package manuell erstellen
1.3.1 Lösung
1.3.2 Modulsyntax
1.3.3 Weitere Dateien
1.3.4 Best Practices für Node.js-Packages
1.3.5 Ausblick
1.4 Rezept 4: Ein neues Node.js-Package automatisch erstellen
1.4.1 Möglichkeiten zur Initialisierung von Packages
1.4.2 Lösung: Packages über den Kommandozeilenwizard erstellen
1.4.3 Lösung: Packages über Starter-Kits erstellen
1.4.4 Lösung: Packages über Code-Generatoren erstellen
1.4.5 Ausblick
1.5 Rezept 5: Den Kommandozeilenwizard von npm anpassen
1.5.1 Lösung: Standardwerte anpassen
1.5.2 Lösung: Eine individuelle Package-Initialisierung einrichten
1.5.3 Ausblick
1.6 Rezept 6: Abhängigkeiten richtig installieren und verwalten
1.6.1 Die verschiedenen Typen von Abhängigkeiten verstehen
1.6.2 Lösung: Installieren von Laufzeitabhängigkeiten
1.6.3 Lösung: Installieren von Entwicklungsabhängigkeiten
1.6.4 Lösung: Installieren von globalen Packages
1.6.5 Lösung: Installieren von globalen Packages ohne sudo-Rechte
1.6.6 Ausblick
1.7 Rezept 7: Packages in Mono-Repositorys organisieren
1.7.1 Lösung
1.7.2 Lerna
1.7.3 Aufbau von Mono-Repositorys
1.7.4 Packages innerhalb eines Mono-Repositorys anlegen
1.7.5 Projekt-globale Abhängigkeiten
1.7.6 Voraussetzung: Git
1.7.7 Workflow
1.7.8 Ausblick
1.8 Zusammenfassung
2 Package Management
2.1 Rezept 8: Semantische Versionierung richtig einsetzen
2.1.1 Exkurs: semantische Versionierung
2.1.2 Lösung: variable Versionsnummern verwenden
2.1.3 Lösung: exakte Versionsnummern verwenden
2.1.4 Die Datei package-lock.json
2.1.5 Die Datei npm-shrinkwrap.json
2.1.6 Ausblick
2.2 Rezept 9: Den alternativen Package Manager »Yarn« verwenden
2.2.1 Lösung
2.2.2 Einführung und Vergleich zu npm
2.2.3 Installation
2.2.4 Verwendung
2.2.5 Lock-Datei
2.2.6 Ausblick
2.3 Rezept 10: Den alternativen Package Manager »pnpm« verwenden
2.3.1 Lösung
2.3.2 Einführung und Vergleich zu npm
2.3.3 Installation
2.3.4 Verwendung
2.3.5 Ausblick
2.4 Rezept 11: Lokale Abhängigkeiten für die Entwicklung verlinken
2.4.1 Lösung
2.4.2 Alternativen
2.5 Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen
2.5.1 Lösung: allgemeine Informationen für ein Package ermitteln
2.5.2 Lösung: Downloadstatistik eines Packages ermitteln
2.5.3 Lösung: den Abhängigkeitsbaum eines Packages ermitteln
2.5.4 Ausblick
2.6 Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln
2.6.1 Lösung
2.6.2 Alternativen
2.6.3 Ausblick
2.7 Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln
2.7.1 Lösung
2.7.2 Weitere Features
2.7.3 Ausblick
2.8 Rezept 15: Veraltete Abhängigkeiten ermitteln
2.8.1 Lösung
2.8.2 Alternativen
2.9 Zusammenfassung
3 Logging und Debugging
3.1 Rezept 16: Logging für Node.js-Packages einrichten
3.1.1 Exkurs: Logging
3.1.2 Lösung: das »debug«-Package
3.1.3 Ausblick
3.2 Rezept 17: Logging für Node.js-Applikationen einrichten
3.2.1 Lösung: Logging mit »winston«
3.2.2 Lösung: Logging mit »bunyan«
3.2.3 Lösung: Logging mit »log4js-node«
3.2.4 Ausblick
3.3 Rezept 18: Logging über Adapter-Packages einrichten
3.3.1 Lösung
3.3.2 Ausblick
3.4 Rezept 19: Applikationen mit Chrome Developer Tools debuggen
3.4.1 Vorbereitung
3.4.2 Lösung
3.4.3 Ausblick
3.5 Rezept 20: Applikationen mit Visual Studio Code debuggen
3.5.1 Lösung
3.5.2 Ausblick
3.6 Rezept 21: Applikationen über die Kommandozeile debuggen
3.6.1 Lösung
3.6.2 Ausblick
3.7 Zusammenfassung
4 Konfiguration und Internationalisierung
4.1 Rezept 22: Applikationen konfigurieren über Umgebungsvariablen
4.1.1 Exkurs: Konfiguration von Applikationen
4.1.2 Lösung: Umgebungsvariablen mit der Node.js-API auslesen
4.1.3 Lösung: Umgebungsvariablen über .env-Datei definieren
4.1.4 Ausblick
4.2 Rezept 23: Applikationen konfigurieren über Konfigurationsdateien
4.2.1 Lösung: Konfigurationsdateien mit JSON
4.2.2 Lösung: Konfigurationsdateien mit JavaScript
4.2.3 Ausblick
4.3 Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente
4.3.1 Lösung: auf Kommandozeilenargumente zugreifen über die Standard-Node.js-API
4.3.2 Lösung: auf Kommandozeilenargumente zugreifen über »yargs«
4.3.3 Lösung: auf Kommandozeilenargumente zugreifen über »commander.js«
4.3.4 Ausblick
4.4 Rezept 25: Applikationen optimal konfigurierbar machen
4.4.1 Lösung
4.4.2 Ausblick
4.5 Rezept 26: Mehrsprachige Applikationen erstellen
4.5.1 Exkurs: i18n
4.5.2 Die Internationalization API
4.5.3 Lösung: Vergleich von Zeichenketten
4.5.4 Lösung: Formatierung von Datums- und Zeitangaben
4.5.5 Lösung: Formatierung von Zahlenwerten
4.5.6 Ausblick
4.6 Rezept 27: Sprachdateien verwenden
4.6.1 Verwenden von Sprachdateien mit »i18n«
4.6.2 Ausblick
4.7 Zusammenfassung
5 Dateisystem, Streams und Events
5.1 Rezept 28: Mit Dateien und Verzeichnissen arbeiten
5.1.1 Lösung
5.1.2 Dateien lesen
5.1.3 Dateien schreiben
5.1.4 Weitere Methoden
5.1.5 Über Verzeichnisse iterieren
5.1.6 Ausblick
5.2 Rezept 29: Dateien und Verzeichnisse überwachen
5.2.1 Einführung
5.2.2 Lösung: Dateien und Verzeichnisse überwachen mit dem »fs«-Modul
5.2.3 Lösung: Dateien und Verzeichnisse überwachen mit »chokidar«
5.2.4 Ausblick
5.3 Rezept 30: Daten mit Streams lesen
5.3.1 Exkurs: Streams
5.3.2 Lösung
5.3.3 Ausblick
5.4 Rezept 31: Daten mit Streams schreiben
5.4.1 Lösung
5.4.2 Ausblick
5.5 Rezept 32: Mehrere Streams über Piping kombinieren
5.5.1 Lösung
5.5.2 Piping im Produktionsbetrieb
5.5.3 Ausblick
5.6 Rezept 33: Eigene Streams implementieren
5.6.1 Lösung
5.6.2 Lösung: Einen Readable Stream implementieren
5.6.3 Lösung: Einen Writable Stream implementieren
5.6.4 Lösung: Einen Duplex Stream implementieren
5.6.5 Lösung: Einen Transform Stream implementieren
5.6.6 Ausblick
5.7 Rezept 34: Events versenden und empfangen
5.7.1 Lösung
5.7.2 Ausblick
5.8 Rezept 35: Erweiterte Features beim Event-Handling verwenden
5.8.1 Lösung
5.8.2 Ausblick
5.9 Zusammenfassung
6 Datenformate
6.1 Rezept 36: XML verarbeiten
6.1.1 Einführung: XML-Verarbeitung
6.1.2 Lösung 1: XML mit einem DOM-Parser verarbeiten
6.1.3 Lösung 2: XML mit einem SAX-Parser verarbeiten
6.1.4 Ausblick
6.2 Rezept 37: XML generieren
6.2.1 Lösung 1: XML generieren mit »xmlbuilder«
6.2.2 Lösung 2: XML generieren mit Template Strings
6.2.3 Ausblick
6.3 Rezept 38: RSS und Atom generieren und verarbeiten
6.3.1 Lösung: RSS und Atom generieren
6.3.2 Lösung: RSS und Atom verarbeiten
6.3.3 Ausblick
6.4 Rezept 39: CSV verarbeiten
6.4.1 Lösung
6.4.2 Ausblick
6.5 Rezept 40: HTML mit Template-Engines generieren
6.5.1 Einführung
6.5.2 Lösung 1: HTML generieren mit »Pug«
6.5.3 Lösung 2: HTML generieren mit »EJS«
6.5.4 Ausblick
6.6 Rezept 41: HTML mit der DOM-API generieren
6.6.1 Exkurs: das Document Object Model
6.6.2 Lösung
6.6.3 Ausblick
6.7 Rezept 42: YAML verarbeiten und generieren
6.7.1 Exkurs: das YAML-Format
6.7.2 Lösung: YAML lesen
6.7.3 Lösung: YAML generieren
6.7.4 Ausblick
6.8 Rezept 43: TOML verarbeiten
6.8.1 Lösung
6.8.2 Ausblick
6.9 Rezept 44: INI verarbeiten und generieren
6.9.1 Lösung: INI verarbeiten
6.9.2 Lösung: INI generieren
6.9.3 Ausblick
6.10 Rezept 45: JSON validieren
6.10.1 Einführung
6.10.2 Lösung
6.10.3 Ausblick
6.11 Rezept 46: JavaScript verarbeiten und generieren
6.11.1 Lösung: JavaScript verarbeiten
6.11.2 Lösung: JavaScript generieren
6.11.3 Ausblick
6.12 Rezept 47: CSS verarbeiten und generieren
6.12.1 Lösung: CSS mit »PostCSS« verarbeiten
6.12.2 Lösung: eigene Plugins für »PostCSS« schreiben
6.12.3 Ausblick
6.13 Zusammenfassung
7 Persistenz
7.1 Rezept 48: Auf eine MySQL-Datenbank zugreifen
7.1.1 Lösung
7.1.2 Ausblick
7.2 Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen
7.2.1 Lösung
7.2.2 Ausblick
7.3 Rezept 50: Objektrelationale Mappings definieren
7.3.1 Exkurs: Objektrelationale Mappings
7.3.2 Lösung
7.3.3 Ausblick
7.4 Rezept 51: Auf eine MongoDB-Datenbank zugreifen
7.4.1 Lösung
7.4.2 Ausblick
7.5 Rezept 52: Auf eine Redis-Datenbank zugreifen
7.5.1 Lösung
7.5.2 Redis als Pub/Sub
7.5.3 Ausblick
7.6 Rezept 53: Auf eine Cassandra-Datenbank zugreifen
7.6.1 Lösung
7.6.2 Ausblick
7.7 Zusammenfassung
8 Webanwendungen und Webservices
8.1 Rezept 54: Einen HTTP-Server implementieren
8.1.1 Lösung: einen Webserver mit der Standard-Node.js-API erstellen
8.1.2 Lösung: einen Webserver mit »Express« implementieren
8.1.3 Ausblick
8.2 Rezept 55: Eine Webanwendung über HTTPS betreiben
8.2.1 Lösung
8.2.2 Ausblick
8.3 Rezept 56: Eine REST-API implementieren
8.3.1 Exkurs: REST-APIs
8.3.2 Lösung: eine REST-API mit »Express« implementieren
8.3.3 Versionierung
8.3.4 Ausblick
8.4 Rezept 57: Einen HTTP-Client implementieren
8.4.1 Lösung: einen HTTP-Client mit der Standard-Node.js-API implementieren
8.4.2 Lösung: einen HTTP-Client mit »superagent« implementieren
8.4.3 Ausblick
8.5 Rezept 58: Authentifizierung implementieren
8.5.1 Lösung
8.5.2 Ausblick
8.6 Rezept 59: Authentifizierung mit »Passport.js« implementieren
8.6.1 Lösung
8.6.2 Ausblick
8.7 Rezept 60: Eine GraphQL-API implementieren
8.7.1 Exkurs: das Problem von REST
8.7.2 Lösung: dynamische APIs mit GraphQL
8.7.3 Ausblick
8.8 Rezept 61: Anfragen an eine GraphQL-API stellen
8.8.1 Lösung
8.8.2 Ausblick
8.9 Rezept 62: Eine GraphQL-API über HTTP betreiben
8.9.1 Lösung: GraphQL über HTTP betreiben
8.9.2 Lösung: GraphQL über »Express« betreiben
8.9.3 Lösung: GraphQL über den Apollo Server betreiben
8.9.4 Ausblick
8.10 Zusammenfassung
9 Sockets und Messaging
9.1 Rezept 63: Einen TCP-Server erstellen
9.1.1 Lösung
9.1.2 Ausblick
9.2 Rezept 64: Einen TCP-Client erstellen
9.2.1 Lösung
9.2.2 Ausblick
9.3 Rezept 65: Einen WebSocket-Server erstellen
9.3.1 Lösung
9.3.2 Ausblick
9.4 Rezept 66: Einen WebSocket-Client erstellen
9.4.1 Lösung
9.4.2 Ausblick
9.5 Rezept 67: Nachrichtenformate für WebSocket- Kommunikation definieren
9.5.1 Lösung
9.5.2 Ausblick
9.6 Rezept 68: Subprotokolle für WebSocket-Kommunikation definieren
9.6.1 Lösung
9.6.2 Ausblick
9.7 Rezept 69: Server-Sent Events generieren
9.7.1 Lösung: die Server-Seite implementieren
9.7.2 Lösung: die Client-Seite implementieren
9.7.3 Ausblick
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
9.8.1 Exkurs: Messaging
9.8.2 Einführung: AMQP
9.8.3 Installation eines Message-Brokers für AMQP
9.8.4 Lösung
9.8.5 Ausblick
9.9 Rezept 71: Einen MQTT-Broker erstellen
9.9.1 Exkurs: das Nachrichtenprotokoll MQTT
9.9.2 Lösung: einen MQTT-Broker installieren
9.9.3 Lösung: einen MQTT-Broker über Node.js starten
9.9.4 Ausblick
9.10 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
9.10.1 Lösung: einen MQTT-Client verwenden
9.10.2 Ausblick
9.11 Rezept 73: E-Mails versenden
9.11.1 Lösung
9.11.2 Ausblick
9.12 Zusammenfassung
10 Testing und TypeScript
10.1 Rezept 74: Unit-Tests schreiben
10.1.1 Exkurs: Unit-Tests und testgetriebene Entwicklung
10.1.2 Lösung: Unit-Test mit »Jest« schreiben
10.1.3 Ausblick
10.2 Rezept 75: Unit-Tests automatisch neu ausführen
10.2.1 Lösung
10.2.2 Ausblick
10.3 Rezept 76: Die Testabdeckung ermitteln
10.3.1 Lösung
10.3.2 Ausblick
10.4 Rezept 77: Unit-Tests für REST-APIs implementieren
10.4.1 Lösung
10.4.2 Ausblick
10.5 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren
10.5.1 Lösung
10.5.2 Ausblick
10.6 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
10.6.1 Lösung
10.6.2 Ausblick
10.7 Zusammenfassung
11 Skalierung, Performance und Sicherheit
11.1 Rezept 80: Externe Anwendungen als Unterprozess ausführen
11.1.1 Exkurs: Multithreading vs. Multiprocessing
11.1.2 Lösung
11.1.3 Ausblick
11.2 Rezept 81: Externe Anwendungen als Stream verarbeiten
11.2.1 Lösung
11.2.2 Ausblick
11.3 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen
11.3.1 Lösung
11.3.2 Ausblick
11.4 Rezept 83: Eine Node.js-Anwendung clustern
11.4.1 Lösung
11.4.2 Ausblick
11.5 Rezept 84: Unterprozesse über einen Prozessmanager verwalten
11.5.1 Lösung
11.5.2 Ausblick
11.6 Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln
11.6.1 Lösung: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln mit der Standard-Node.js-API
11.6.2 Lösung: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln mit »systeminformation«
11.6.3 Ausblick
11.7 Rezept 86: Speicherprobleme identifizieren
11.7.1 Lösung
11.7.2 Ausblick
11.8 Rezept 87: CPU-Probleme identifizieren
11.8.1 Lösung
11.8.2 Ausblick
11.9 Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen
11.9.1 Lösung: Schwachstellen erkennen mit npm
11.9.2 Lösung: Schwachstellen automatisch beheben mit npm
11.9.3 Lösung: Schwachstellen erkennen mit Third-Party-Tools
11.9.4 Lösung: Schwachstellen erkennen mit »Snyk«
11.9.5 Lösung: Schwachstellen erkennen mit »Retire.js«
11.9.6 Ausblick
11.10 Rezept 89: JavaScript dynamisch laden und ausführen
11.10.1 Einführung
11.10.2 Keine Lösung: JavaScript mit eval() ausführen
11.10.3 Lösung: JavaScript mit »vm« ausführen
11.10.4 Lösung: JavaScript mit »vm2« ausführen
11.10.5 Ausblick
11.11 Zusammenfassung
12 Native Module
12.1 Rezept 90: Native Node.js-Module mit der V8-API erstellen
12.1.1 Lösung
12.1.2 Ausblick
12.2 Rezept 91: Native Node.js-Module mit der NAN-API erstellen
12.2.1 Lösung
12.2.2 Ausblick
12.3 Rezept 92: Native Node.js-Module mit der N-API erstellen
12.3.1 Lösung
12.3.2 Ausblick
12.4 Rezept 93: Werte und Objekte zurückgeben mit der N-API
12.4.1 Lösung
12.4.2 Ausblick
12.5 Rezept 94: Callbacks aufrufen mit der N-API
12.5.1 Lösung
12.5.2 Ausblick
12.6 Rezept 95: Promises zurückgeben mit der N-API
12.6.1 Lösung
12.6.2 Ausblick
12.7 Rezept 96: Assertions verwenden mit der N-API
12.7.1 Lösung
12.7.2 Ausblick
12.8 Rezept 97: Native Node.js-Module debuggen
12.8.1 Lösung
12.8.2 Ausblick
12.9 Zusammenfassung
13 Publishing, Deployment und Microservices
13.1 Rezept 98: Eine private npm-Registry verwenden
13.1.1 Einführung: private npm-Registrys
13.1.2 Lösung: private npm-Registry mit Verdaccio
13.1.3 Lösung: private npm-Registry mit Artefakt-Repositorys
13.1.4 Ausblick
13.2 Rezept 99: Docker verstehen
13.2.1 Einführung
13.2.2 Grundlagen
13.2.3 Node.js unter Docker
13.2.4 Docker-Befehlsreferenz
13.2.5 Docker Compose
13.2.6 Befehlsreferenz Docker Compose
13.2.7 Docker User Interfaces
13.2.8 Ausblick
13.3 Rezept 100: Ein Docker Image für eine Node.js- Applikation erstellen
13.3.1 Lösung
13.3.2 Ausblick
13.4 Rezept 101: Einen Docker-Container starten
13.4.1 Lösung
13.4.2 Ausblick
13.5 Rezept 102: Microservice-Architekturen verstehen
13.5.1 Eigenschaften von Microservice-Architekturen
13.5.2 Technologien bei Microservice-Architekturen
13.5.3 Kommunikation mit Microservices
13.5.4 API Gateways
13.5.5 Ausblick
13.6 Rezept 103: Microservice-Architekturen aufsetzen mit Docker Compose
13.6.1 Lösung
13.6.2 Ausblick
13.7 Rezept 104: Den Quelltext bundeln und komprimieren mit Webpack
13.7.1 Lösung
13.7.2 Ausblick
13.8 Zusammenfassung
Anhang: Rezept 105
Index
Citation preview
An den Leser
Liebe Leserin, lieber Leser, Philip Ackermann, selbst Senior Software Developer, kennt die Zeitnot, die oft im Alltag dieses Berufsfeldes herrscht: Wenn es um die Entwicklung und Programmierung geht, steht die nächste Deadline meistens schon vor der Tür. Lösungen zu auftretenden Problemen müssen schnell und gezielt auffindbar sein und genau dafür wurde dieses Buch konzipiert. Mit Node.js können Sie auch komplexe Webanwendungen umsetzen, dabei leichtgewichtig und mit schnellen Resultaten arbeiten. Gute Stabilität und Performance: all das macht das JavaScript-Framework Node.js aus. Es ist ein fester Bestandteil der Webentwicklung und wird dies über viele Jahre auch noch bleiben. Mit diesem Buch haben Sie sich einen umfangreichen Helfer an die Seite geholt, der Ihnen alle wichtigen Fragen zur Arbeit mit Node.js beantwortet. Mit diesem praxisorientierten Nachschlagewerk bietet Philip Ackermann Ihnen über 100 Rezepte, die konkrete Lösungen für wiederkehrende Problemstellungen garantieren. Die Rezepte sind nach wichtigen Aufgabengebieten sortiert und folgen einem immer gleichen Aufbau, sodass Sie sich leicht im Buch orientieren können und stets schnell zum Ziel gelangen. Zudem finden Sie unter jedem Rezept Verweise zu verwandten Rezepten, die Ihnen die Navigation im Buch zusätzlich erleichtern und Ihnen neue Ansätze, Ideen und Inspirationen für Ihre Arbeit mit Node.js bieten. Dieses Buch wurde mit größter Sorgfalt geschrieben und hergestellt. Für den Fall, dass Sie dennoch Fehler finden oder inhaltliche Anregungen haben, scheuen Sie sich nicht, mit uns Kontakt aufzunehmen. Ihre Fragen und Vorschläge sind jederzeit willkommen.
Ihr Stephan Mattescheck Lektorat Rheinwerk Computing
[email protected] www.rheinwerk-verlag.de Rheinwerk Verlag · Rheinwerkallee 4 · 53227 Bonn
Auf einen Blick
Auf einen Blick 1
Initialisierung und Setup .....................................................................................
27
2
Package Management .........................................................................................
67
3
Logging und Debugging ...................................................................................... 103
4
Konfiguration und Internationalisierung ...................................................... 131
5
Dateisystem, Streams und Events ................................................................... 165
6
Datenformate ......................................................................................................... 211
7
Persistenz ................................................................................................................. 285
8
Webanwendungen und Webservices ............................................................. 333
9
Sockets und Messaging ....................................................................................... 391
10
Testing und TypeScript ........................................................................................ 449
11
Skalierung, Performance und Sicherheit ....................................................... 481
12
Native Module ........................................................................................................ 543
13
Publishing, Deployment und Microservices ................................................. 587
Impressum
Impressum Dieses E-Book ist ein Verlagsprodukt, an dem viele mitgewirkt haben, insbesondere: Lektorat Stephan Mattescheck, Anne Scheibe Gutachter Sebastian Springer Korrektorat Petra Schomburg, Hilter-Borgloh Herstellung E-Book Melanie Zinsler Covergestaltung Bastian Illerhaus Coverbilder Shutterstock: 1173622156 © AdresiaStock; iStock: 655381184 © nd3000 Satz E-Book SatzPro, Krefeld Bibliografische Information der Deutschen Nationalbibliothek: Die Deutsche Nationalbibliothek verzeichnet diese Publikation in der Deutschen Nationalbibliografie; detaillierte bibliografische Daten sind im Internet über http://dnb.d-nb.de abrufbar. ISBN 978-3-8362-6455-6 1. Auflage 2019 © Rheinwerk Verlag GmbH, Bonn 2019 www.rheinwerk-verlag.de
Inhalt
Inhalt Materialien zum Buch .......................................................................................................................
19
Geleitwort des Fachgutachters ......................................................................................................
21
Vorwort ..................................................................................................................................................
23
1
Initialisierung und Setup
27
Rezept 1: Node.js installieren ........................................................................................
27
1.1.1 1.1.2 1.1.3 1.1.4 1.1.5 1.1.6 1.1.7 1.1.8
Arten der Installation .......................................................................................... Lösung: Installation über Installationsdatei unter macOS .................... Lösung: Installation über Installationsdatei unter Windows ............... Lösung: Installation über Binärpaket unter macOS ................................. Lösung: Installation über Binärpaket unter Windows ............................ Lösung: Installation über Binärpaket unter Linux .................................... Lösung: Installation über Paketmanager ..................................................... Ausblick ...................................................................................................................
27 30 32 33 33 34 34 35
Rezept 2: Mehrere Node.js-Versionen parallel betreiben ................................
35
1.2.1 1.2.2 1.2.3
35 39 40
1.1
1.2
1.3
1.4
1.5
Lösung ...................................................................................................................... Alternativen ........................................................................................................... Ausblick ...................................................................................................................
Rezept 3: Ein neues Node.js-Package manuell erstellen ...................................
41
1.3.1 1.3.2 1.3.3 1.3.4 1.3.5
Lösung ...................................................................................................................... Modulsyntax .......................................................................................................... Weitere Dateien ................................................................................................... Best Practices für Node.js-Packages .............................................................. Ausblick ...................................................................................................................
41 42 43 43 44
Rezept 4: Ein neues Node.js-Package automatisch erstellen ..........................
45
1.4.1 1.4.2 1.4.3 1.4.4 1.4.5
Möglichkeiten zur Initialisierung von Packages ........................................ Lösung: Packages über den Kommandozeilenwizard erstellen ........... Lösung: Packages über Starter-Kits erstellen ............................................. Lösung: Packages über Code-Generatoren erstellen ............................... Ausblick ...................................................................................................................
45 45 48 48 49
Rezept 5: Den Kommandozeilenwizard von npm anpassen ...........................
49
1.5.1 1.5.2 1.5.3
49 51 54
Lösung: Standardwerte anpassen .................................................................. Lösung: Eine individuelle Package-Initialisierung einrichten ............... Ausblick ...................................................................................................................
5
Inhalt
1.6
Rezept 6: Abhängigkeiten richtig installieren und verwalten .......................
54
1.6.1 1.6.2 1.6.3 1.6.4 1.6.5 1.6.6
Die verschiedenen Typen von Abhängigkeiten verstehen ..................... Lösung: Installieren von Laufzeitabhängigkeiten ..................................... Lösung: Installieren von Entwicklungsabhängigkeiten .......................... Lösung: Installieren von globalen Packages ............................................... Lösung: Installieren von globalen Packages ohne sudo-Rechte ........... Ausblick ...................................................................................................................
54 56 57 57 58 59
Rezept 7: Packages in Mono-Repositorys organisieren .....................................
59
1.7.1 1.7.2 1.7.3 1.7.4 1.7.5 1.7.6 1.7.7 1.7.8
Lösung ...................................................................................................................... Lerna ......................................................................................................................... Aufbau von Mono-Repositorys ........................................................................ Packages innerhalb eines Mono-Repositorys anlegen ............................ Projekt-globale Abhängigkeiten ..................................................................... Voraussetzung: Git .............................................................................................. Workflow ................................................................................................................ Ausblick ...................................................................................................................
59 60 60 62 62 63 64 66
1.8
Zusammenfassung .............................................................................................................
66
2
Package Management
67
1.7
2.1
2.2
2.3
6
Rezept 8: Semantische Versionierung richtig einsetzen ...................................
67
2.1.1 2.1.2 2.1.3 2.1.4 2.1.5 2.1.6
67 68 70 71 72 73
Exkurs: semantische Versionierung .............................................................. Lösung: variable Versionsnummern verwenden ...................................... Lösung: exakte Versionsnummern verwenden ......................................... Die Datei package-lock.json ............................................................................. Die Datei npm-shrinkwrap.json ...................................................................... Ausblick ...................................................................................................................
Rezept 9: Den alternativen Package Manager »Yarn« verwenden ..............
73
2.2.1 2.2.2 2.2.3 2.2.4 2.2.5
Lösung ...................................................................................................................... Einführung und Vergleich zu npm ................................................................. Installation ............................................................................................................. Verwendung .......................................................................................................... Lock-Datei ...............................................................................................................
73 74 74 75 77
2.2.6
Ausblick ...................................................................................................................
78
Rezept 10: Den alternativen Package Manager »pnpm« verwenden ........
78
2.3.1 2.3.2
78 78
Lösung ...................................................................................................................... Einführung und Vergleich zu npm .................................................................
Inhalt
2.3.3 2.3.4 2.3.5
2.4
2.5
2.6
2.7
2.8
Installation ............................................................................................................. Verwendung .......................................................................................................... Ausblick ...................................................................................................................
80 81 84
Rezept 11: Lokale Abhängigkeiten für die Entwicklung verlinken ..............
84
2.4.1
Lösung ......................................................................................................................
85
2.4.2
Alternativen ...........................................................................................................
87
Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen .......
88
2.5.1 2.5.2 2.5.3 2.5.4
88 90 92 93
Lösung: allgemeine Informationen für ein Package ermitteln ............ Lösung: Downloadstatistik eines Packages ermitteln ............................. Lösung: den Abhängigkeitsbaum eines Packages ermitteln ................ Ausblick ...................................................................................................................
Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln ...............
94
2.6.1 2.6.2 2.6.3
94 95 96
Lösung ...................................................................................................................... Alternativen ........................................................................................................... Ausblick ...................................................................................................................
Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln .................................................................................................................................
97
2.7.1 2.7.2 2.7.3
97 98 98
Lösung ...................................................................................................................... Weitere Features .................................................................................................. Ausblick ...................................................................................................................
Rezept 15: Veraltete Abhängigkeiten ermitteln .................................................. 2.8.1 2.8.2
99
Lösung ...................................................................................................................... Alternativen ...........................................................................................................
99 100
2.9
Zusammenfassung .............................................................................................................
101
3
Logging und Debugging
103
3.1
Rezept 16: Logging für Node.js-Packages einrichten .........................................
103
3.1.1 3.1.2 3.1.3
Exkurs: Logging ..................................................................................................... Lösung: das »debug«-Package ......................................................................... Ausblick ...................................................................................................................
103 106 108
Rezept 17: Logging für Node.js-Applikationen einrichten ...............................
109
3.2.1 3.2.2 3.2.3 3.2.4
109 111 112 113
3.2
Lösung: Logging mit »winston« ...................................................................... Lösung: Logging mit »bunyan« ....................................................................... Lösung: Logging mit »log4js-node« ............................................................... Ausblick ...................................................................................................................
7
Inhalt
3.3
3.4
Rezept 18: Logging über Adapter-Packages einrichten .....................................
114
3.3.1 3.3.2
114 117
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
Rezept 19: Applikationen mit Chrome Developer Tools debuggen .............
118
3.4.1 3.4.2 3.4.3
Vorbereitung ......................................................................................................... Lösung ...................................................................................................................... Ausblick ...................................................................................................................
118 119 122
Rezept 20: Applikationen mit Visual Studio Code debuggen .........................
122
3.5.1
Lösung ......................................................................................................................
122
3.5.2
Ausblick ...................................................................................................................
124
Rezept 21: Applikationen über die Kommandozeile debuggen ....................
125
3.6.1 3.6.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
125 129
3.7
Zusammenfassung .............................................................................................................
129
4
Konfiguration und Internationalisierung
131
3.5
3.6
4.1
4.2
4.3
Rezept 22: Applikationen konfigurieren über Umgebungsvariablen .........
132
4.1.1 4.1.2 4.1.3 4.1.4
Exkurs: Konfiguration von Applikationen .................................................... Lösung: Umgebungsvariablen mit der Node.js-API auslesen ............... Lösung: Umgebungsvariablen über .env-Datei definieren .................... Ausblick ...................................................................................................................
132 132 134 137
Rezept 23: Applikationen konfigurieren über Konfigurationsdateien .......
137
4.2.1 4.2.2 4.2.3
Lösung: Konfigurationsdateien mit JSON ................................................... Lösung: Konfigurationsdateien mit JavaScript .......................................... Ausblick ...................................................................................................................
137 139 141
Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente ..............................................................................................................................
141
4.3.1 4.3.2 4.3.3
8
141
Lösung: auf Kommandozeilenargumente zugreifen über »yargs« .... Lösung: auf Kommandozeilenargumente zugreifen über »commander.js« ................................................................................................... Ausblick ...................................................................................................................
144
Rezept 25: Applikationen optimal konfigurierbar machen .............................
147
4.4.1 4.4.2
147 150
4.3.4
4.4
Lösung: auf Kommandozeilenargumente zugreifen über die Standard-Node.js-API .........................................................................................
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
145 147
Inhalt
4.5
Rezept 26: Mehrsprachige Applikationen erstellen ............................................
151
4.5.1 4.5.2 4.5.3 4.5.4 4.5.5 4.5.6
Exkurs: i18n ............................................................................................................ Die Internationalization API ............................................................................. Lösung: Vergleich von Zeichenketten ........................................................... Lösung: Formatierung von Datums- und Zeitangaben .......................... Lösung: Formatierung von Zahlenwerten ................................................... Ausblick ...................................................................................................................
151 152 153 156 158 161
Rezept 27: Sprachdateien verwenden .......................................................................
161
4.6.1 4.6.2
Verwenden von Sprachdateien mit »i18n« ................................................. Ausblick ...................................................................................................................
161 163
4.7
Zusammenfassung .............................................................................................................
163
5
Dateisystem, Streams und Events
165
5.1
Rezept 28: Mit Dateien und Verzeichnissen arbeiten ........................................
165
5.1.1 5.1.2 5.1.3 5.1.4 5.1.5 5.1.6
Lösung ...................................................................................................................... Dateien lesen ......................................................................................................... Dateien schreiben ................................................................................................ Weitere Methoden .............................................................................................. Über Verzeichnisse iterieren ............................................................................ Ausblick ...................................................................................................................
166 167 169 170 171 172
Rezept 29: Dateien und Verzeichnisse überwachen ...........................................
173
5.2.1 5.2.2
173
4.6
5.2
Einführung ............................................................................................................. Lösung: Dateien und Verzeichnisse überwachen mit dem »fs«-Modul ........................................................................................... Lösung: Dateien und Verzeichnisse überwachen mit »chokidar« ...................................................................................................... Ausblick ...................................................................................................................
175 178
Rezept 30: Daten mit Streams lesen ..........................................................................
178
5.3.1 5.3.2 5.3.3
Exkurs: Streams .................................................................................................... Lösung ...................................................................................................................... Ausblick ...................................................................................................................
178 180 182
Rezept 31: Daten mit Streams schreiben .................................................................
182
5.4.1 5.4.2
182 184
5.2.3 5.2.4
5.3
5.4
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
174
9
Inhalt
5.5
5.6
5.7
Rezept 32: Mehrere Streams über Piping kombinieren ....................................
184
5.5.1 5.5.2 5.5.3
Lösung ...................................................................................................................... Piping im Produktionsbetrieb .......................................................................... Ausblick ...................................................................................................................
185 188 190
Rezept 33: Eigene Streams implementieren ..........................................................
190
5.6.1 5.6.2 5.6.3 5.6.4 5.6.5 5.6.6
190 191 193 194 197 199
Lösung ...................................................................................................................... Lösung: Einen Readable Stream implementieren ..................................... Lösung: Einen Writable Stream implementieren ...................................... Lösung: Einen Duplex Stream implementieren ......................................... Lösung: Einen Transform Stream implementieren .................................. Ausblick ...................................................................................................................
Rezept 34: Events versenden und empfangen ......................................................
199
5.7.1 5.7.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
200 205
Rezept 35: Erweiterte Features beim Event-Handling verwenden ..............
206
5.8.1 5.8.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
206 208
5.9
Zusammenfassung .............................................................................................................
209
6
Datenformate
211
Rezept 36: XML verarbeiten ...........................................................................................
211
6.1.1 6.1.2 6.1.3 6.1.4
Einführung: XML-Verarbeitung ....................................................................... Lösung 1: XML mit einem DOM-Parser verarbeiten ................................. Lösung 2: XML mit einem SAX-Parser verarbeiten ................................... Ausblick ...................................................................................................................
212 213 215 218
Rezept 37: XML generieren ............................................................................................
218
6.2.1 6.2.2 6.2.3
Lösung 1: XML generieren mit »xmlbuilder« .............................................. Lösung 2: XML generieren mit Template Strings ...................................... Ausblick ...................................................................................................................
218 221 223
Rezept 38: RSS und Atom generieren und verarbeiten .....................................
224
6.3.1 6.3.2 6.3.3
Lösung: RSS und Atom generieren ................................................................. Lösung: RSS und Atom verarbeiten ................................................................ Ausblick ...................................................................................................................
224 227 229
Rezept 39: CSV verarbeiten ............................................................................................
229
6.4.1 6.4.2
229 232
5.8
6.1
6.2
6.3
6.4
10
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
Inhalt
6.5
Rezept 40: HTML mit Template-Engines generieren ..........................................
233
6.5.1 6.5.2 6.5.3 6.5.4
Einführung ............................................................................................................. Lösung 1: HTML generieren mit »Pug« ......................................................... Lösung 2: HTML generieren mit »EJS« .......................................................... Ausblick ...................................................................................................................
233 234 237 239
Rezept 41: HTML mit der DOM-API generieren .....................................................
239
6.6.1 6.6.2 6.6.3
Exkurs: das Document Object Model ............................................................ Lösung ...................................................................................................................... Ausblick ...................................................................................................................
239 241 244
Rezept 42: YAML verarbeiten und generieren .......................................................
244
6.7.1 6.7.2 6.7.3 6.7.4
Exkurs: das YAML-Format ................................................................................. Lösung: YAML lesen ............................................................................................. Lösung: YAML generieren .................................................................................. Ausblick ...................................................................................................................
244 245 251 252
Rezept 43: TOML verarbeiten ........................................................................................
253
6.8.1 6.8.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
253 259
Rezept 44: INI verarbeiten und generieren .............................................................
259
6.9.1 6.9.2 6.9.3
Lösung: INI verarbeiten ...................................................................................... Lösung: INI generieren ....................................................................................... Ausblick ...................................................................................................................
259 263 263
6.10 Rezept 45: JSON validieren .............................................................................................
264
6.6
6.7
6.8
6.9
6.10.1 6.10.2 6.10.3
Einführung ............................................................................................................. Lösung ...................................................................................................................... Ausblick ...................................................................................................................
264 266 269
6.11 Rezept 46: JavaScript verarbeiten und generieren ..............................................
270
6.11.1 6.11.2 6.11.3
Lösung: JavaScript verarbeiten ........................................................................ Lösung: JavaScript generieren ......................................................................... Ausblick ...................................................................................................................
6.12 Rezept 47: CSS verarbeiten und generieren ........................................................... 6.12.1 6.12.2 6.12.3
270 275 276 277
Lösung: CSS mit »PostCSS« verarbeiten ....................................................... Lösung: eigene Plugins für »PostCSS« schreiben ...................................... Ausblick ...................................................................................................................
277 282 284
6.13 Zusammenfassung .............................................................................................................
284
11
Inhalt
7
Persistenz
285
Rezept 48: Auf eine MySQL-Datenbank zugreifen ..............................................
285
7.1.1 7.1.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
285 291
Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen .....................................
292
7.2.1 7.2.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
292 299
Rezept 50: Objektrelationale Mappings definieren ............................................
299
7.3.1 7.3.2 7.3.3
Exkurs: Objektrelationale Mappings ............................................................. Lösung ...................................................................................................................... Ausblick ...................................................................................................................
299 301 307
Rezept 51: Auf eine MongoDB-Datenbank zugreifen ........................................
307
7.4.1 7.4.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
308 316
Rezept 52: Auf eine Redis-Datenbank zugreifen ..................................................
316
7.5.1 7.5.2 7.5.3
Lösung ...................................................................................................................... Redis als Pub/Sub ................................................................................................. Ausblick ...................................................................................................................
316 324 325
Rezept 53: Auf eine Cassandra-Datenbank zugreifen .......................................
326
7.6.1 7.6.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
326 332
7.7
Zusammenfassung .............................................................................................................
332
8
Webanwendungen und Webservices
333
Rezept 54: Einen HTTP-Server implementieren ....................................................
333
8.1.1 8.1.2 8.1.3
Lösung: einen Webserver mit der Standard-Node.js-API erstellen ..... Lösung: einen Webserver mit »Express« implementieren .................... Ausblick ...................................................................................................................
333 335 336
Rezept 55: Eine Webanwendung über HTTPS betreiben ..................................
337
8.2.1 8.2.2
337 341
7.1
7.2
7.3
7.4
7.5
7.6
8.1
8.2
8.3
12
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
Rezept 56: Eine REST-API implementieren ..............................................................
341
8.3.1 8.3.2
341 342
Exkurs: REST-APIs ................................................................................................. Lösung: eine REST-API mit »Express« implementieren ...........................
Inhalt
8.3.3 8.3.4
8.4
8.5
8.6
8.7
Versionierung ........................................................................................................ Ausblick ...................................................................................................................
353 354
Rezept 57: Einen HTTP-Client implementieren .....................................................
355
8.4.1
Lösung: einen HTTP-Client mit der Standard-Node.js-API implementieren ....................................................................................................
355
8.4.2 8.4.3
Lösung: einen HTTP-Client mit »superagent« implementieren .......... Ausblick ...................................................................................................................
356 358
Rezept 58: Authentifizierung implementieren .....................................................
359
8.5.1 8.5.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
359 365
Rezept 59: Authentifizierung mit »Passport.js« implementieren ................
366
8.6.1 8.6.2
366 370
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
Rezept 60: Eine GraphQL-API implementieren ......................................................
371
8.7.1 8.7.2 8.7.3
Exkurs: das Problem von REST ......................................................................... Lösung: dynamische APIs mit GraphQL ........................................................ Ausblick ...................................................................................................................
371 374 379
Rezept 61: Anfragen an eine GraphQL-API stellen ..............................................
379
8.8.1 8.8.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
380 383
Rezept 62: Eine GraphQL-API über HTTP betreiben .............................................
383
8.9.1 8.9.2 8.9.3 8.9.4
Lösung: GraphQL über HTTP betreiben ........................................................ Lösung: GraphQL über »Express« betreiben ............................................... Lösung: GraphQL über den Apollo Server betreiben ................................ Ausblick ...................................................................................................................
384 384 388 389
8.10 Zusammenfassung .............................................................................................................
390
9
Sockets und Messaging
391
Rezept 63: Einen TCP-Server erstellen .......................................................................
392
9.1.1 9.1.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
392 395
Rezept 64: Einen TCP-Client erstellen ........................................................................
396
9.2.1 9.2.2
396 400
8.8
8.9
9.1
9.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
13
Inhalt
9.3
9.4
9.5
9.6
9.7
9.8
9.9
Rezept 65: Einen WebSocket-Server erstellen .......................................................
400
9.3.1 9.3.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
400 405
Rezept 66: Einen WebSocket-Client erstellen ........................................................
405
9.4.1 9.4.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
405 407
Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren ...............................................................................................................................
407
9.5.1 9.5.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
407 412
Rezept 68: Subprotokolle für WebSocket-Kommunikation definieren .....
412
9.6.1 9.6.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
412 415
Rezept 69: Server-Sent Events generieren ..............................................................
415
9.7.1 9.7.2 9.7.3
Lösung: die Server-Seite implementieren .................................................... Lösung: die Client-Seite implementieren .................................................... Ausblick ...................................................................................................................
415 418 419
Rezept 70: Über AMQP auf RabbitMQ zugreifen .................................................
419
9.8.1 9.8.2 9.8.3 9.8.4 9.8.5
Exkurs: Messaging ............................................................................................... Einführung: AMQP ............................................................................................... Installation eines Message-Brokers für AMQP ........................................... Lösung ...................................................................................................................... Ausblick ...................................................................................................................
419 421 425 426 430
Rezept 71: Einen MQTT-Broker erstellen .................................................................
431
9.9.1
Exkurs: das Nachrichtenprotokoll MQTT .....................................................
431
9.9.2 9.9.3 9.9.4
Lösung: einen MQTT-Broker installieren ...................................................... Lösung: einen MQTT-Broker über Node.js starten .................................... Ausblick ...................................................................................................................
432 434 436
9.10 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen ...............................
436
9.10.1 9.10.2
Lösung: einen MQTT-Client verwenden ....................................................... Ausblick ...................................................................................................................
436 443
9.11 Rezept 73: E-Mails versenden .......................................................................................
443
9.11.1 9.11.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
443 446
9.12 Zusammenfassung .............................................................................................................
446
14
Inhalt
10 Testing und TypeScript 10.1 Rezept 74: Unit-Tests schreiben ................................................................................... 10.1.1 10.1.2 10.1.3
449 449
Exkurs: Unit-Tests und testgetriebene Entwicklung ............................... Lösung: Unit-Test mit »Jest« schreiben ........................................................ Ausblick ...................................................................................................................
449 451 457
10.2 Rezept 75: Unit-Tests automatisch neu ausführen .............................................
458
10.2.1 10.2.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
458 459
10.3 Rezept 76: Die Testabdeckung ermitteln .................................................................
459
10.3.1 10.3.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
460 463
10.4 Rezept 77: Unit-Tests für REST-APIs implementieren ........................................
463
10.4.1 10.4.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
463 467
10.5 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren ..........
468
10.5.1 10.5.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
469 475
10.6 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren ...................................................................................................................
475
10.6.1 10.6.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
475 479
10.7 Zusammenfassung .............................................................................................................
479
11 Skalierung, Performance und Sicherheit
481
11.1 Rezept 80: Externe Anwendungen als Unterprozess ausführen ................... 11.1.1 11.1.2 11.1.3
482
Exkurs: Multithreading vs. Multiprocessing ............................................... Lösung ...................................................................................................................... Ausblick ...................................................................................................................
482 483 485
11.2 Rezept 81: Externe Anwendungen als Stream verarbeiten .............................
486
11.2.1 11.2.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
486 489
11.3 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen .......................
489
11.3.1 11.3.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
489 495
15
Inhalt
11.4 Rezept 83: Eine Node.js-Anwendung clustern ....................................................... 11.4.1 11.4.2
495
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
496 499
11.5 Rezept 84: Unterprozesse über einen Prozessmanager verwalten ..............
499
11.5.1 11.5.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
499 504
11.6 Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln ...........................................................................................................
504
11.6.1
Lösung: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln mit der Standard-Node.js-API ................ Lösung: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln mit »systeminformation« ........................ Ausblick ...................................................................................................................
509 511
11.7 Rezept 86: Speicherprobleme identifizieren ..........................................................
511
11.6.2 11.6.3
11.7.1 11.7.2
504
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
512 519
11.8 Rezept 87: CPU-Probleme identifizieren ..................................................................
520
11.8.1 11.8.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
520 528
11.9 Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen .................................................................................................................................
528
11.9.1 11.9.2 11.9.3 11.9.4
Lösung: Schwachstellen erkennen mit npm ............................................... Lösung: Schwachstellen automatisch beheben mit npm ...................... Lösung: Schwachstellen erkennen mit Third-Party-Tools ...................... Lösung: Schwachstellen erkennen mit »Snyk« ..........................................
528 531 531 532
11.9.5 11.9.6
Lösung: Schwachstellen erkennen mit »Retire.js« ................................... Ausblick ...................................................................................................................
533 535
11.10 Rezept 89: JavaScript dynamisch laden und ausführen ....................................
535
11.10.1 11.10.2 11.10.3 11.10.4 11.10.5
Einführung ............................................................................................................. Keine Lösung: JavaScript mit eval() ausführen .......................................... Lösung: JavaScript mit »vm« ausführen ...................................................... Lösung: JavaScript mit »vm2« ausführen .................................................... Ausblick ...................................................................................................................
535 536 537 540 541
11.11 Zusammenfassung .............................................................................................................
541
16
Inhalt
12 Native Module
543
12.1 Rezept 90: Native Node.js-Module mit der V8-API erstellen ..........................
543
12.1.1 12.1.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
544 550
12.2 Rezept 91: Native Node.js-Module mit der NAN-API erstellen ......................
550
12.2.1 12.2.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
550 554
12.3 Rezept 92: Native Node.js-Module mit der N-API erstellen ............................
554
12.3.1 12.3.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
554 561
12.4 Rezept 93: Werte und Objekte zurückgeben mit der N-API ............................
561
12.4.1 12.4.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
561 568
12.5 Rezept 94: Callbacks aufrufen mit der N-API .........................................................
568
12.5.1 12.5.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
568 573
12.6 Rezept 95: Promises zurückgeben mit der N-API .................................................
573
12.6.1 12.6.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
573 576
12.7 Rezept 96: Assertions verwenden mit der N-API ..................................................
576
12.7.1 12.7.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
576 580
12.8 Rezept 97: Native Node.js-Module debuggen .......................................................
580
12.8.1 12.8.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
580 584
12.9 Zusammenfassung .............................................................................................................
584
13 Publishing, Deployment und Microservices
587
13.1 Rezept 98: Eine private npm-Registry verwenden ..............................................
588
13.1.1 13.1.2 13.1.3 13.1.4
Einführung: private npm-Registrys ................................................................ Lösung: private npm-Registry mit Verdaccio ............................................. Lösung: private npm-Registry mit Artefakt-Repositorys ........................ Ausblick ...................................................................................................................
588 589 592 595
17
Inhalt
13.2 Rezept 99: Docker verstehen ......................................................................................... 13.2.1 13.2.2 13.2.3 13.2.4 13.2.5 13.2.6 13.2.7 13.2.8
595
Einführung ............................................................................................................. Grundlagen ............................................................................................................ Node.js unter Docker .......................................................................................... Docker-Befehlsreferenz ..................................................................................... Docker Compose ................................................................................................... Befehlsreferenz Docker Compose .................................................................. Docker User Interfaces ....................................................................................... Ausblick ...................................................................................................................
595 596 598 600 603 604 605 606
13.3 Rezept 100: Ein Docker Image für eine Node.js-Applikation erstellen .......
607
13.3.1 13.3.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
607 612
13.4 Rezept 101: Einen Docker-Container starten .........................................................
612
13.4.1 13.4.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
613 616
13.5 Rezept 102: Microservice-Architekturen verstehen ............................................
616
13.5.1 13.5.2 13.5.3 13.5.4 13.5.5
Eigenschaften von Microservice-Architekturen ........................................ Technologien bei Microservice-Architekturen ........................................... Kommunikation mit Microservices ................................................................ API Gateways ......................................................................................................... Ausblick ...................................................................................................................
616 620 620 622 625
13.6 Rezept 103: Microservice-Architekturen aufsetzen mit Docker Compose ..................................................................................................................
625
13.6.1 13.6.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
625 631
13.7 Rezept 104: Den Quelltext bundeln und komprimieren mit Webpack ......
631
13.7.1 13.7.2
Lösung ...................................................................................................................... Ausblick ...................................................................................................................
631 638
13.8 Zusammenfassung .............................................................................................................
639
Anhang: Rezept 105 ...........................................................................................................................
641
Index ........................................................................................................................................................
643
18
0
Materialien zum Buch
Auf der Webseite zu diesem Buch stehen folgende Materialien für Sie zum Download bereit: 왘 alle Beispielprogramme
Gehen Sie auf https://www.rheinwerk-verlag.de/4698. Klicken Sie auf den Reiter Materialien zum Buch. Sie sehen die herunterladbaren Dateien samt einer Kurzbeschreibung des Dateiinhalts. Klicken Sie auf den Button Herunterladen, um den Download zu starten. Je nach Größe der Datei (und Ihrer Internetverbindung) kann es einige Zeit dauern, bis der Download abgeschlossen ist.
19
0
Geleitwort des Fachgutachters
Seit Ryan Dahl 2009 Node.js auf der JSConf in Berlin vorgestellt hat, um Sponsoren für das Projekt zu finden, hat sich viel getan. Die Idee hinter Node.js, eine leichtgewichtige und flexible Plattform für serverseitiges JavaScript zu schaffen, hat sich jedoch nicht geändert. Node.js kann mittlerweile auf eine zehnjährige Entwicklungsgeschichte zurückblicken. In dieser Zeit hat sich sowohl der Kern der Plattform als auch das gesamte Ökosystem rasant weiterentwickelt. Der Kern der Plattform mag zwar leichtgewichtig sein, er bietet Ihnen jedoch alle Schnittstellen, die Sie für die Entwicklung von Applikationen benötigen. Das schließt auf der einen Seite klassische Webapplikationen und auf der anderen Seite auch Kommandozeilen-Werkzeuge mit ein. Die Schnittstellen der Plattform sind bewusst allgemein gehalten, das bedeutet, dass Ihnen das »HTTP«-Modul bspw. den Zugriff auf das HTTP-Protokoll, aber darüber hinaus nicht viel mehr bietet. Für Sie als Entwickler würde die direkte Verwendung der Schnittstellen der Node.js-Kernmodule viel Arbeit bedeuten, da Sie bei einer Webapplikation ausgehend von der grundlegenden Implementierung des HTTP-Protokolls den Rest vollständig selbst implementieren müssten. An dieser Stelle kommt Ihnen der Node Package Manager mit seinem umfangreichen Repository zu Hilfe und stellt für nahezu jede Problemstellung eine Lösung zur Verfügung. Es ist jedoch nicht einfach, mit der Entwicklung von Node.js Schritt zu halten. Vor allem, wenn Sie sich vor Augen führen, dass es halbjährliche Major-Releases der Plattform gibt. Ganz zu schweigen vom Erscheinen ständig neuer Bibliotheken und Frameworks auf Basis von Node.js. Dieses Buch bietet Ihnen mit seinen Rezepten zu den verschiedenen Themen in der Node.js-Welt einen hilfreichen Wegweiser für die tägliche Arbeit. Lassen Sie sich beim Durchlesen und Stöbern von verschiedenen Lösungsansätzen inspirieren, und lernen Sie zahlreiche Pakete des Ökosystems kennen, die Sie in Ihre Applikation einbinden können. Bei den Rezepten handelt es sich jedoch um mehr als eine Kurzfassung der jeweiligen Dokumentation. Sie erfahren mehr über die Konzepte hinter den einzelnen Paketen und sind so mit etwas Übung nach kurzer Zeit in der Lage, die benötigten Pakete selbst zu finden, sie zu bewerten und zu integrieren. Auf den folgenden Seiten erfahren Sie, wie Sie Standardaufgaben wie die Umsetzung eines Webservers oder die Anbindung einer Datenbank meistern. Sie lernen, wie Sie mit dem Debugger auf Fehlersuche gehen, Ihre Applikation deployen und unter Last skalieren können. Aber auch exotischere Themen wie die Umsetzung und Einbindung nativer Module werden mit Erklärungen und konkreten Beispielen behandelt.
21
Geleitwort des Fachgutachters
Diese Rezeptsammlung ist der ideale Wegbegleiter auf Ihrem täglichen Weg mit Node.js. Ich wünsche Ihnen viel Spaß mit diesem Buch und der Arbeit mit Node.js.
Sebastian Springer
22
0
Vorwort
Das erste Mal in Kontakt kam ich mit Node.js vor ungefähr acht Jahren: Im Jahr 2011 arbeitete ich beim Fraunhofer-Institut für Angewandte Informationstechnik an einer Software zur Evaluierung von Websites hinsichtlich Aspekten wie Barrierefreiheit, Suchmaschinenoptimierung, Corporate Identity und Web Compliance im Allgemeinen. Die Software war in der ersten Version unter Verwendung des GUI-Frameworks Swing als reine Java-Desktopanwendung implementiert und später in Version 2 als Client-/Server-Webanwendung auf Basis von Webservices migriert worden. Die Software war zwar stabil, aber mit der Zeit merkten wir, dass wir immer mehr an die Grenzen von Java stießen. Bei den Websites, die mit der Software evaluiert werden sollten, handelte es sich größtenteils nicht mehr um statische Websites, sondern um Single-Page Applications, was wiederum verlangte, diese Applikationen auch auf Server-Seite zu rendern, um eine aussagekräftige Evaluierung durchführen zu können. Da die Möglichkeiten, die Java diesbezüglich zu dieser Zeit bot, für uns nicht zufriedenstellend waren, suchten wir nach Alternativen und fanden sie in dem Headless Browser PhantomJS, einem Browser ohne grafische Oberfläche, der über JavaScript gesteuert werden kann. Mit diesem ersten Schritt von Java in Richtung JavaScript führte eines zum anderen, und wir entschieden uns, im Hinblick auf Version 3 der Software zunächst einzelne Komponenten und im Laufe des anschließenden Refactorings nahezu alle Komponenten in JavaScript neu zu schreiben. Ausschlaggebender Punkt dafür war aber nicht PhantomJS, sondern ein anderer neuer Player im JavaScript-Universum: die Laufzeitumgebung Node.js (damals noch in Version 0.1), die es überhaupt erst möglich machte, JavaScript effizient auf dem Server auszuführen, und die aus genau diesem Grund maßgeblich für den erneuten Erfolg von JavaScript mitverantwortlich war und immer noch ist. Der Erfolg von JavaScript und Node.js ist nach wie vor ungebrochen. Ob im Bereich von Webanwendungen, mobiler Anwendungen, IoT-Anwendungen, Desktopanwendungen oder im Rahmen des Build-Prozesses. Ob auf einem herkömmlichen Server, in der Cloud oder auf einem Minicomputer wie dem Raspberry Pi: JavaScript und damit Node.js spielt mittlerweile in allen Bereichen eine wichtige Rolle und ist damit eine ernstzunehmende Konkurrenz für »die großen Sprachen« Java, C# oder PHP. Aktuelle Umfragen, Trends und die Popularität von Node.js-Projekten bei GitHub sind nur einige Indikatoren hierfür. Hinzu kommt die große Community und die Menge an Open-Source-Projekten: So listet bspw. die Package-Registry des Node.js Package Managers derzeit mehr als 1.000.000 Packages (zum Vergleich: Vor etwa
23
Vorwort
einem Jahr waren es noch rund 700.000 Packages) auf. Zudem gelten Node.jsAnwendungen als äußerst performant, sind dank nicht blockierender Ein- und Ausgabe hervorragend skalierbar und – auch aus Projektmanagementsicht – insofern erstrebenswert, als dass im besten Fall die gleichen JavaScript-Entwickler, die das Frontend entwickeln, auch in der Lage sind, das Backend zu entwickeln. Doch wie soll man sich im Dschungel der Packages zurechtfinden, und welche Aspekte sind relevant für die Implementierung von Node.js-Projekten? In diesem Buch habe ich Ihnen eine repräsentative Auswahl von praxiserprobten Techniken und Rezepten vorbereitet, die meine Erfahrung aus über acht Jahren Projekt- und (insbesondere) Produktentwicklung mit Node.js und über 20 Jahren in der Software- und Webentwicklung widerspiegeln. Dabei war mir wichtig, trotz komprimierter Rezept-Form ein Maximum an Informationsgehalt sicherzustellen und Ihnen so viel Insiderwissen wie möglich zu vermitteln.
Für wen ist dieses Buch? Wenn ich als Entwickler – entsprechende Grundkenntnisse in der Programmierung vorausgesetzt – eine neue Programmiersprache lernen möchte und die Wahl hätte zwischen einem Buch, das alle Grundlagen behandelt, und einem Buch, das mir auf den Punkt genau Problemstellungen und die dazu passenden Lösungen präsentiert, würde ich zu letzterem greifen. Mich würden in erster Linie nicht Fragen interessieren wie »Wie erstelle ich eine forSchleife?«, »Wie erzeuge ich Objekte?«, »Wie erstelle ich eine Variable vom Typ String?« (okay, diese Fragen würde ich mir auch stellen, aber sie sind doch vermutlich innerhalb weniger Minuten geklärt), sondern Fragen wie »Wie implementiere ich eine REST-API?«, »Wie greife ich auf Datenbanken zu?«, »Welche Tools und Bibliotheken gibt es für welchen Anwendungsfall?« und »Wie strukturiere ich meine Applikation?«. Node.js lernen Sie natürlich nicht allein dadurch, dass Sie ein Buch (oder mehrere) zu diesem Thema lesen. Sie müssen sich schon selbst die Hände schmutzig machen. Und hierbei, denke ich, eignet sich der rezeptartige Aufbau besonders gut. Mich haben immer schon Bücher, die diesem Aufbau folgen, mehr angesprochen, beispielsweise die Klassiker »Refactoring« von Martin Fowler, »Design Patterns – Elements of Reusable Object-Oriented Software« der »Gang of Four« oder – ebenfalls ein Klassiker, zumindest in der Java-Community – »Effective Java« von Joshua Block. Wenn Sie dies ähnlich wie ich sehen und einen rezeptartigen Aufbau ebenso als effizienter empfinden, können Sie bedenkenlos zu dem vorliegenden Buch greifen.
24
Vorwort
Wie ist dieses Buch aufgebaut? Insgesamt besteht das Buch aus 13 Kapiteln zu Themen, die ich als besonders wichtig empfinde, wenn es um die Entwicklung unter Node.js geht. Verteilt auf diese Kapitel sind insgesamt 105 Rezepte, mal mehr, mal weniger lang. Das liegt in der Natur der Sache: Wie man den Inhalt einer Datei einliest, ist einfach schneller erklärt als das Konzept und die Verwendung von GraphQL, Event-Handling ist schneller erklärt als die Besonderheiten und Features des MQTT-Protokolls, und wie man eine Webanwendung über HTTPS bereitstellt, ist schneller erklärt als das Deployment über Docker. Jedes Rezept beginnt mit einer konkreten, meist aus einem Satz bestehenden Problemstellung, anhand derer Sie – zusammen mit der sprechenden Überschrift des Rezeptes – direkt erkennen können, ob das Rezept für Ihren konkreten Anwendungsfall relevant ist oder nicht. Anschließend folgt immer der Abschnitt »Lösung«, in dem ich erläutere, wie Sie das beschriebene Problem am besten angehen und lösen. Jedes Rezept endet mit einem Abschnitt »Ausblick«, in dem ich einerseits auf weiterführende Informationen und alternative Lösungsstrategien eingehe, aber auch auf andere Rezepte verweise, die mit dem jeweils aktuellen Rezept verwandt sind. Den Quelltext zu den Rezepten können Sie übrigens auf der offiziellen Website zum Buch unter www.rheinwerk-verlag.de/nodejs_4698/ herunterladen. Alternativ dazu steht der Quelltext auch in einem GitHub-Repository unter https://github.com/cleancoderocker/nodejskochbuch zur Verfügung. Wenn Sie mein JavaScript-Profibuch »Professionell entwickeln mit JavaScript – Design, Patterns und Praxistipps« gelesen haben, wissen Sie, dass es in JavaScript nicht immer nur die eine richtige Technik gibt, um ein Problem zu lösen. Stattdessen führen viele verschiedene Wege zum Ziel. Und genauso verhält es sich auch mit der Entwicklung unter Node.js. Unabhängig von den JavaScript-Techniken, die natürlich auch unter Node.js relevant sind, gibt es oft verschiedene weitere Techniken, um die gegebenen Problemstellungen zu lösen. Auch hier gibt es nicht immer den einen richtigen Weg. Vielmehr sollen Sie mit den Rezepten und Lösungen in diesem Buch lernen, Problemstellungen richtig einzuschätzen und selbstständig in der Lage zu sein, die richtige Lösung anzuwenden.
Wie sollte ich das Buch durchlesen? Prinzipiell können Sie das Buch auf verschiedene Arten durchlesen bzw. durcharbeiten. Trotz des rezeptartigen Aufbaus folgt das Buch einem roten Faden, der sich vom ersten Rezept bis zum letzten Rezept durchzieht. In den allermeisten Fällen sind die Rezepte zwar vollständig unabhängig voneinander, und nur in einigen wenigen Fällen bauen einzelne Rezepte auf anderen Rezepten auf, allerdings sind Rezepte zu
25
Vorwort
grundlegenden Themen tendenziell weiter vorn im Buch angeordnet als Rezepte zu fortgeschrittenen Themen. Persönlich würde ich Ihnen also raten, das Buch von vorn bis hinten durchzuarbeiten. Damit ist sichergestellt, dass Ihnen nichts Wichtiges entgeht und Ihnen für spätere Rezepte kein Wissen aus vorherigen Rezepten fehlt. Als Kochbuch soll das Buch natürlich vor allem schnell für einen konkreten Anwendungsfall die entsprechende Lösung liefern. Es spricht also auch nichts dagegen, die Rezepte nach Bedarf durchzuarbeiten. Mit den sprechenden Rezept-Überschriften und dem Index sollten Sie schnell die entsprechende Lösung für eine konkrete Problemstellung finden. Zu guter Letzt soll das Buch natürlich auch als Nachschlagewerk dienen, das Sie immer wieder gern aus dem Regal ziehen, um Wissen bei Bedarf aufzufrischen. Genauso, wie ich das selbst noch heute immer wieder mit den oben genannten Klassikern mache.
Danksagung Am allermeisten möchte ich wie immer meiner Frau und meinen Kindern danken für ihre Geduld und Unterstützung während der Zeit, die ich an diesem Buch gearbeitet habe. Auch wenn ich dieses Mal versucht habe, das Schreiben in die sehr frühen Morgenstunden und sehr späten Abendstunden zu legen, bin ich dankbar für die Zeit, die sie mir hierfür gegeben haben. Außerdem bedanke ich mich bei meinem Lektor Stephan Mattescheck für die wie immer sehr professionelle und freundliche Zusammenarbeit, meiner Korrektorin Petra Schomburg sowie bei dem gesamten beteiligten Team im Rheinwerk Verlag. Auch Sebastian Springer gilt mein Dank für das wertvolle Fachgutachten und die vielen nützlichen Hinweise. Mein Dank gilt auch Max Bold von der Ebner Media Group, mit dessen freundlicher Genehmigung ich Auszüge aus Artikeln verwenden durfte, die ich für das Fachmagazin »web & mobile DEVELOPER« verfasst habe. Zu guter Letzt danke ich Ihnen, nicht nur für den Kauf dieses Buches, sondern für die Zeit, die Sie mit dem Lesen und Durcharbeiten verbringen. Ich hoffe, Sie haben viel Spaß dabei und können viel Neues dabei lernen. Außerdem würde ich mich sehr über Ihr Feedback freuen und stehe Ihnen unter [email protected] auch gern für Fragen und Anregungen zur Verfügung. Unter www.nodejskochbuch.de finden Sie zudem weitere Informationen und Updates zum Buch.
Philip Ackermann
26
Kapitel 1 Initialisierung und Setup Eine wichtige Grundlage für die effektive Entwicklung unter Node.js ist zum einen die richtige Konfiguration von Node.js und dem Node.js Package Manager (npm) sowie zum anderen das richtige Setup von Node.js-Projekten.
In diesem Kapitel zeige ich Ihnen, wie Sie Node.js und den Paketmanager von Node.js (npm) installieren und wie Sie schnell zwischen verschiedenen Node.js-Versionen hin und her wechseln (Rezepte 1 und 2). Außerdem zeige ich Ihnen, wie Sie Node.jsProjekte richtig aufsetzen, organisieren und konfigurieren (Rezepte 3 bis 7). 왘 Rezept 1: Node.js installieren 왘 Rezept 2: Mehrere Node.js-Versionen parallel betreiben 왘 Rezept 3: Ein neues Node.js-Package manuell erstellen 왘 Rezept 4: Ein neues Node.js-Package automatisch erstellen 왘 Rezept 5: Den Kommandozeilenwizard von npm anpassen 왘 Rezept 6: Abhängigkeiten richtig installieren und verwalten 왘 Rezept 7: Packages in Mono-Repositorys organisieren
1.1 Rezept 1: Node.js installieren Sie möchten Node.js unter macOS, Linux oder Windows installieren und wissen, welche unterschiedlichen Möglichkeiten zur Installation zur Verfügung stehen.
1.1.1 Arten der Installation Die Installation von Node.js ist unabhängig vom Betriebssystem relativ einfach und auf der Website von Node.js sehr gut dokumentiert. Ich möchte mich im Folgenden daher etwas kürzer halten und mich darauf konzentrieren, welche verschiedenen Möglichkeiten der Installation Sie haben und worin sich diese unterscheiden. Prinzipiell kann Node.js auf verschiedene Arten installiert werden: über eine Installationsdatei, über ein Binärpaket, über Paketmanager des jeweiligen Betriebssystems,
27
1
Initialisierung und Setup
über einen sogenannten Node.js Version Manager und durch Kompilieren der Quelltextdateien von Node.js. Schauen Sie sich diese Möglichkeiten der Reihe nach an. 왘 über eine Installationsdatei: Installationsdateien stehen unter https://nodejs.org/
en/download/ derzeit nur für macOS und Windows zum Download zur Verfügung (Abbildung 1.1). Für die meisten Anwendungsfälle reicht es dabei, die sogenannte LTS-Version, also die Version mit »Long Term Support« (siehe Kasten) zu verwenden. Möchten Sie für Ihre Applikation neuere Features nutzen, können Sie sich alternativ unter dem Register »Current« auch die Installationsdateien der jeweils letzten Node.js-Version herunterladen. Für den Produktiveinsatz empfiehlt sich der Einsatz der »Current«-Version in den meisten Fällen allerdings nicht, bzw. sollten Sie dann darauf achten, in Ihrer Applikation nur stabile Features von Node.js zu nutzen.
Abbildung 1.1 Node.js-Versionen zum Download 왘 über ein Binärpaket: Die Binärpakete können Sie ebenfalls unter https://node-
js.org/en/download/ herunterladen und anschließend ohne weitere Installation ausführen. Allerdings hat diese Variante den Nachteil, dass Node.js erst mal nicht systemweit in der Kommandozeile zur Verfügung steht. Um dem entgegenzuwirken, müssen Sie den Suchpfad des Systems manuell erweitern bzw. die Binärdateien entsprechend an einen Ort kopieren, der bereits im Suchpfad enthalten ist. 왘 über den Paketmanager des jeweiligen Betriebssystems: Für viele Betriebssyste-
me wie bspw. die unterschiedlichen Linux-Distributionen, aber auch für macOS und Windows stehen spezielle Paketmanager zur Verfügung, über die sich Software zentral installieren bzw. verwalten lässt. Auch Node.js lässt sich für die meisten Betriebssysteme auf diese Weise installieren. Dabei ist allerdings zu beachten, dass die jeweiligen Packages nicht vom Node.js Core Team gepflegt werden und es
28
1.1 Rezept 1: Node.js installieren
gegebenenfalls sein kann, dass Sie auf diesem Weg nicht die aktuellste Version von Node.js installieren können. Weitere Informationen zu dieser Installationsform finden Sie unter https://nodejs.org/en/download/package-manager/. 왘 über einen sogenannten Node.js Version Manager: Der Vorteil bei dieser Installa-
tionsart ist, dass Sie hierüber relativ komfortabel mehrere Versionen von Node.js parallel installieren und bei Bedarf von einer zur anderen Version wechseln können (Stichwort »Kompatibilitätstests«). Ich persönlich verwende diese Art der Installation und kann Ihnen das auch nur empfehlen – insbesondere, wenn Sie verschiedene Projekte verwalten oder wenn Sie schnell prüfen möchten, wie sich eine Applikation unter einer bestimmten Version verhält. Details zu der Installation über einen Node.js Version Manager finden Sie in Rezept 2. 왘 durch Kompilieren der Quelltextdateien: Dies ist sicherlich die aufwendigste In-
stallationsmöglichkeit, die nur in Ausnahmefällen sinnvoll ist, bspw. wenn Sie sich aktiv an der Entwicklung von Node.js beteiligen möchten. Auf diese Art der Installation werde ich aus Platzgründen nicht weiter eingehen und verweise daher auf die entsprechende Dokumentation von Node.js unter https://github.com/ nodejs/node/blob/master/BUILDING.md.
LTS-Versionen Der Release-Plan von Node.js sieht alle sechs Monate eine neue Major-Version vor, wobei die Releases mit geraden Versionsnummern im April und die Releases mit ungeraden Versionsnummern im Oktober veröffentlicht werden. Bei Veröffentlichung eines Release mit ungerader Versionsnummer geht die zuvor veröffentlichte Version in den LTS-Plan (»Long Term Support«) über. Mit anderen Worten: Jede LTS-Version hat immer eine gerade Versionsnummer, jede »Nicht-LTS-Version« eine ungerade Versionsnummer. Im LTS-Plan wird die jeweilige (gerade) Version 18 Monate lang gewartet (»maintained«). Apr 2019 Master
Jul 2019
Oct 2019
Jan 2020 Apr 2020
Jul 2020
Oct 2020
Jan 2021
Apr 2021
UNSTABLE
Node.js 6 Node.js 8 Node.js 10
MAINTENANCE ACTIVE
MAINTENANCE
Node.js 11 Node.js 12 Node.js 13
CURRENT
ACTIVE CURRENT
Abbildung 1.2 Release-Plan von Node.js
29
1
Initialisierung und Setup
1.1.2 Lösung: Installation über Installationsdatei unter macOS Für die Installation unter macOS laden Sie die pkg-Datei von der Downloadseite https://nodejs.org/en/download herunter. Wenn Sie diese Datei durch Doppelklick starten, öffnet sich der in Abbildung 1.3 gezeigte Installationswizard, der Sie durch die Installation führt (Abbildung 1.4 bis Abbildung 1.6).
Abbildung 1.3 Begrüßungsdialog der Node.js-Installation unter macOS
Abbildung 1.4 Lizenzinformationen für Node.js unter macOS
30
1.1 Rezept 1: Node.js installieren
Abbildung 1.5 Beginn der Installation von Node.js unter macOS
Abbildung 1.6 Bestätigungsdialog zur Installation von Node.js unter macOS
Nach erfolgreicher Installation steht Ihnen auf Ihrem System global der Befehl node zur Verfügung, über den Sie Node.js-Applikationen starten können. Um die Installation zu überprüfen, können Sie sich bspw. mithilfe von node -v die installierte Node.js-Version ausgeben lassen:
31
1
Initialisierung und Setup
$ node -v v12.3.1 Listing 1.1 Ausgabe der aktuell installierten Node.js-Version
Durch die Installation von Node.js werden noch zwei weitere wichtige Tools installiert: zum einen (seit Node.js-Version 0.6.3) der Node.js Package Manager (kurz npm), zum anderen (seit npm-Version 5.2.0) der npm Package Runner (kurz npx). Auf beides werde ich noch gesondert an anderer Stelle genauer eingehen, trotzdem können Sie schon jetzt prüfen, ob beide Tools erfolgreich installiert wurden: $ npm -v 6.9.0 $ npx -v 6.9.0 Listing 1.2 Ausgabe der aktuell installierten Versionen von npm und npx
1.1.3 Lösung: Installation über Installationsdatei unter Windows Für die Installation unter Windows verwenden Sie die msi-Datei, die ebenfalls auf der Downloadseite https://nodejs.org/en/download/ zum Download angeboten wird. Ein Starten dieser Datei öffnet den in Abbildung 1.7 gezeigten Installationswizard, wobei auch hier das meiste selbsterklärend und ähnlich wie bei der Installation unter macOS sein dürfte, sodass ich auf eine detaillierte Beschreibung und Abbildung entsprechender Screenshots verzichte.
Abbildung 1.7 Begrüßungsdialog der Node.js-Installation unter Windows
32
1.1 Rezept 1: Node.js installieren
Wie schon bei der Installation unter macOS werden durch die Installation von Node.js auch die Tools npm und npx installiert. Testen können Sie die erfolgreiche Installation über die folgenden Befehle: $ node -v v8.11.3 $ npm -v 5.6.0 $ npx -v 9.7.1 Listing 1.3 Ausgabe der aktuell installierten Versionen von Node.js, npm und npx
1.1.4 Lösung: Installation über Binärpaket unter macOS Das Binärpaket für macOS steht als gezipptes Tar-Archiv für 64 Bit auf der Downloadseite zur Verfügung. Wenn Sie diese Datei herunterladen und entpacken, finden Sie die ausführbare Datei node in dem entpackten Ordner unterhalb des Verzeichnisses bin. $ bin/node -v v8.11.3 $ bin/npm -v 5.6.0 $ bin/npx -v 9.7.1 Listing 1.4 Ausgabe der aktuell installierten Versionen nach Installation des Binärpakets unter macOS
1.1.5 Lösung: Installation über Binärpaket unter Windows Das Binärpaket für Windows steht als ZIP-Datei sowohl für 32 Bit als auch für 64 Bit zur Verfügung. Laden Sie die passende Datei herunter und entpacken Sie diese, finden Sie anschließend in dem entpackten Ordner u. a. die Datei node.exe. Diese Datei können Sie direkt per Doppelklick oder über die Kommandozeile ausführen: $ node.exe -v v8.11.3 $ npm -v 5.6.0 $ npx -v 9.7.1 Listing 1.5 Ausgabe der aktuell installierten Versionen nach Installation des Binärpakets unter Windows
33
1
Initialisierung und Setup
1.1.6 Lösung: Installation über Binärpaket unter Linux Das Binärpaket für Linux steht als Archiv-Datei für 32 Bit und 64 Bit zur Verfügung. Nach dem Download und dem anschließenden Entpacken dieser Datei finden Sie die ausführbare Datei node in dem entpackten Ordner unterhalb des Verzeichnisses bin: $ bin/node -v v8.11.3 $ bin/npm -v 5.6.0 $ bin/npx -v 9.7.1 Listing 1.6 Ausgabe der aktuell installierten Versionen nach Installation des Binärpakets unter Linux
1.1.7 Lösung: Installation über Paketmanager Node.js steht für viele verschiedene Betriebssysteme bzw. Paketmanager als Package zur Verfügung, wobei – wie eingangs erwähnt – die Packages nicht vom Node.js Core Team verwaltet werden und damit die Zuverlässigkeit und Aktualität vom Verwalter des Packages abhängt. Eine zumindest halbwegs offizielle Liste von vertrauenswürdigen Quellen finden Sie unter https://nodejs.org/en/download/package-manager/. So stehen dort u. a. Packages für Debian, Ubuntu, FreeBSD, OpenBSD, openSUSE, Android (experimentell) und viele weitere zur Verfügung. Ebenfalls einen Blick wert in diesem Zusammenhang ist das Git-Repository unter https://github.com/nodesource/distributions, in dem verschiedene Shell-Scripts angeboten werden, um Node.js auf unterschiedlichen Linux-Distributionen zu installieren. Auch für den Fall, dass Sie Node.js auf einem Raspberry Pi installieren möchten (bei dem oft das auf Debian basierende Betriebssystem Raspbian zum Einsatz kommt), ist das genannte Git-Repository eine gute Einstiegshilfe. So reichen bspw. die folgenden beiden Befehle, um Node.js auf einem Raspberry Pi zu installieren: curl -sL https://deb.nodesource.com/setup_11.x | sudo -E bash sudo apt install -y nodejs
Paketmanager für macOS und Windows Alternativ zu den in den vorherigen Abschnitten gezeigten Installationsmöglichkeiten für macOS und Windows können Sie auch die entsprechenden Paketmanager dieser Betriebssysteme nutzen, bspw. im Fall von macOS die Paketmanager Homebrew (https://brew.sh/index_de) oder MacPorts (https://www.macports.org/) und im Fall von Windows den Paketmanager Chocolatey (https://chocolatey.org/).
34
1.2
Rezept 2: Mehrere Node.js-Versionen parallel betreiben
1.1.8 Ausblick In diesem Rezept haben Sie gesehen, auf welche unterschiedlichen Weisen sich Node.js für verschiedene Betriebssysteme installieren lässt. Eine weitere Möglichkeit, die insbesondere dann interessant ist, wenn Sie parallel an verschiedenen Projekten arbeiten, die jeweils eine andere Node.js-Version voraussetzen, habe ich schon genannt, aber noch nicht im Detail gezeigt. Die Rede ist von einem Node.js Version Manager, dessen Verwendung ich Ihnen in folgendem Rezept im Detail vorstellen werde.
Verwandte Rezepte 왘 Rezept 2: Mehrere Node.js-Versionen parallel betreiben
1.2 Rezept 2: Mehrere Node.js-Versionen parallel betreiben Sie möchten mehrere Versionen von Node.js parallel betreiben, um während der Entwicklung schnell zwischen einzelnen Versionen wechseln zu können.
1.2.1 Lösung Bei der Entwicklung von Node.js-Applikationen ist es in vielen Fällen hilfreich, wenn man ohne großen Aufwand schnell zwischen verschiedenen Versionen von Node.js wechseln kann. Beispielsweise, wenn man in unterschiedliche Projekte involviert ist, die jeweils andere Versionen von Node.js erfordern, oder aber, wenn man die Kompatibilität einer Applikation bezüglich verschiedener Node.js-Versionen testen möchte. Ich empfehle Ihnen daher, langfristig unbedingt einen Node.js Version Manager zu verwenden.
Einen Node.js Version Manager installieren Einer der bekanntesten Node.js Version Manager ist nvm (https://github.com/creationix/nvm), der für Linux und macOS zur Verfügung steht (Alternativen für Windows finden Sie in Abschnitt 1.2.2, »Alternativen«. Als Voraussetzung für die Installation muss allerdings ein C++-Compiler installiert sein. Unter Linux installieren Sie dazu das »build-essential«-Package: $ sudo apt-get update $ sudo apt-get install build-essential
Für macOS reicht es, hierfür die Xcode Command Line Tools zu installieren: $ xcode-select --install
35
1
Initialisierung und Setup
Anschließend installieren Sie nvm wie folgt entweder über cURL oder Wget: $ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/ install.sh | bash
bzw. $ wget -qO- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/ install.sh | bash
Hinweis Durch die oben gezeigten Script-Aufrufe wird zum einen das Git-Repository von nvm lokal in das Verzeichnis /.nvm geklont, zum anderen das lokale Nutzerprofil (/.bash_ profile, /.zshrc, /.profile oder /.bashrc) angepasst, sodass nvm anschließend global verwendet werden kann. Alternativ können Sie diese Schritte auch manuell durchführen (siehe https://github.com/creationix/nvm#git-install).
Node.js-Versionen installieren Nach erfolgreicher Installation von nvm lassen sich einzelne Node.js-Versionen gezielt über den Befehl nvm install installieren. Um bspw. die aktuellste Version von Node.js zu installieren, verwenden Sie folgenden Befehl: $ nvm install node
Die aktuellste LTS-Version installieren Sie dagegen wie folgt: $ nvm install --lts
Alternativ können Sie dem Befehl auch eine exakte Versionsnummer übergeben. Um bspw. die Version 8.1.1 zu installieren, verwenden Sie folgenden Befehl: $ nvm install 8.1.1
Da sich nvm an der semantischen Versionierung orientiert, können Sie dabei auch einzelne Teile der Versionsnummer weglassen. Der Befehl $ nvm install 8.1
bspw. installiert die aktuellste Version 8.1, sprich die Version 8.1.x, wobei x für die aktuellste Patch-Version steht.
Node.js-Versionen wechseln Wenn Sie über nvm install eine neue Node.js-Version installieren, wird diese implizit auch als Standardversion gesetzt. Um explizit zu einer bereits installierten Version zu wechseln, können Sie den Befehl nvm use verwenden:
36
1.2
Rezept 2: Mehrere Node.js-Versionen parallel betreiben
$ nvm use 8.9.4 # Wechsel zu Version 8.9.4 $ nvm use 9.3 # Wechsel zu Version 9.3.0 $ nvm use node # Wechsel zur aktuellsten Version
Intern erstellt nvm bei einem Wechsel der Node.js-Version einen symbolischen Link vom node-Befehl zu der jeweiligen Node.js-Instanz.
Hinweis Über die Konfigurationsdatei .nvmrc (https://github.com/creationix/nvm#nvmrc, nicht zu verwechseln mit der npm-Konfigurationsdatei .npmrc) können Sie die zu verwendende Node.js-Version auch pro Projekt definieren. Ein anschließender Aufruf von npm use wechselt dann die Node.js-Version basierend auf dieser Konfigurationsdatei.
Ebenfalls nützlich: Über den Befehl nvm alias haben Sie die Möglichkeit, Aliasse zu erzeugen, die Sie dann in Kombination mit nvm use verwenden können: $ nvm alias development-version 8.9.4 # Erstellen eines Alias $ nvm use development-version # Wechsel zu Version 8.9.4 $ nvm unalias development-version # Löschen des Alias
Verfügbare Versionen ermitteln Welche Versionen von Node.js auf Ihrem Rechner installiert sind bzw. über nvm verwaltet werden, können Sie über den Befehl nvm ls ermitteln: $ nvm ls v7.10.0 v8.1.3 v8.4.0 -> v9.11.1 system default -> node (-> v9.11.1) node -> stable (-> v9.11.1) (default) stable -> 9.11 (-> v9.11.1) (default) iojs -> N/A (default) lts/* -> lts/carbon (-> N/A) lts/argon -> v4.9.1 (-> N/A) lts/boron -> v6.14.1 (-> N/A) lts/carbon -> v8.11.1 (-> N/A) Listing 1.7 Auflistung der verfügbaren Node.js-Versionen
37
1
Initialisierung und Setup
Um dagegen zu ermitteln, welche Versionen generell zur Verfügung stehen, verwenden Sie den Befehl nvm ls-remote: $ nvm ls-remote v0.1.14 v0.1.15 v0.1.16 v0.1.17 v0.1.18 v0.1.19 v0.1.20 ... v8.11.0 (LTS: Carbon) v8.11.1 (Latest LTS: Carbon) v9.0.0 ... v9.10.0 v9.10.1 v9.11.0 -> v9.11.1 Listing 1.8 Auflistung der installierten und zur Verfügung stehenden Node.js-Versionen (gekürzte Ausgabe)
Node.js-Versionen deinstallieren Wenn Sie eine einzelne Node.js-Version nicht länger benötigen, können Sie diese über den Befehl nvm uninstall wieder deinstallieren: $ nvm uninstall 0.11
Globale Packages beim Versionswechsel aktualisieren Wie Sie in Rezept 1 gesehen haben, wird bei der Installation von Node.js direkt auch der Node.js Package Manager npm installiert. Wenn Sie mithilfe von nvm verschiedene Versionen von Node.js installieren, werden folglich auch verschiedene Versionen von npm installiert. Dabei ist zu beachten, dass globale Packages nicht wie bei der »Single-Node.js-Installation« in einem einzigen Verzeichnis installiert werden, sondern jeweils getrennt pro Node.js-Version unter »~/.nvm/versions/node// lib/node_modules«. Dies hat zwar den netten Nebeneffekt, dass zur Installation von Packages keine sudo-Rechte notwendig sind (siehe auch Abschnitt 1.6.5, »Lösung: Installieren von globalen Packages ohne sudo-Rechte«), allerdings bedeutet dies auch, dass globale Packages nicht automatisch global für alle Node.js-Versionen zur Verfügung stehen: Wenn Sie für eine spezielle Node.js-Version ein globales Package installieren und dann zu einer anderen Node.js-Version wechseln, ist das jeweilige Package
38
1.2
Rezept 2: Mehrere Node.js-Versionen parallel betreiben
für diese Version nicht installiert. Doch nvm hat diesbezüglich vorgesorgt: Über den Parameter --reinstall-packages-from können Sie bei der Installation einer neuen Node.js-Version angeben, von welcher bereits installierten Version die globalen Packages übernommen (und nachinstalliert) werden sollen: $ nvm install v9.0.0 --reinstall-packages-from=8.9
Tabelle 1.1 gibt Ihnen eine Übersicht über die wichtigsten Befehle, die nvm zur Verfügung stellt. Befehl
Beschreibung
nvm install
Installiert die angegebene Node.js-Version.
nvm uninstall
Deinstalliert die angegebene Node.js-Version.
nvm use
Verwendet die angegebene Node.js-Version.
nvm current
Gibt die aktuell verwendete Node.js-Version aus.
nvm alias
Erzeugt ein Alias für die angegebene Node.js-Version.
nvm ls
Listet die lokal verfügbaren Node.js-Versionen auf.
nvm ls-remote
Listet die verfügbaren Node.js-Versionen auf, die generell für die Installation zur Verfügung stehen.
Tabelle 1.1 Übersicht über die wichtigsten Befehle von nvm
1.2.2 Alternativen Neben nvm gibt es noch einige andere Alternativen, um verschiedene Versionen von Node.js zu verwenden, die ich Ihnen im Folgenden vorstellen möchte.
Alternative Node.js Version Manager Alternativ zu nvm stehen eine Reihe weiterer Node.js Version Manager zur Verfügung. Die prominenteste Alternative dürfte »n« (https://github.com/tj/n) von TJ Holowaychuk sein, die Sie direkt als Node.js-Anwendung über npm installieren können (allerdings funktioniert »n« ebenfalls nicht unter Windows). Ebenfalls interessant ist das Tool avn (für »Automatic Version Switching«, https://github.com/wbyoung/avn), welches das automatische Wechseln der Node.js-Version abhängig von einer .node-version-Datei vornimmt. Wechselt man in ein Projekt mit solch einer Datei, wird automatisch die in dieser Datei enthaltene Version verwendet. Als Node.js Version Manager unterstützt avn dabei sowohl nvm als auch »n«.
39
1
Initialisierung und Setup
Node.js Version Manager für Windows Der Node.js Version Manager nvm funktioniert, wie bereits gesagt, nicht unter Windows. Es steht mit nvm-windows (https://github.com/coreybutler/nvm-windows) allerdings eine Alternative zur Verfügung (die übrigens trotz des ähnlichen Namens nicht von dem nvm-Team gewartet wird). nvm-windows ist in Go geschrieben und kann als Installationsdatei unter https://github.com/coreybutler/nvm-windows/releases heruntergeladen werden. Die Befehle von nvm-windows sind im Großen und Ganzen ähnlich den Befehlen von nvm (Tabelle 1.2). Befehl
Beschreibung
nvm install
Installiert die angegebene Node.js-Version.
nvm uninstall
Deinstalliert die angegebene Node.js-Version.
nvm use
Verwendet die angegebene Node.js-Version.
nvm list
Listet die verfügbaren Node.js-Versionen auf.
nvm list available
Listet die verfügbaren Node.js-Versionen auf, die generell für die Installation zur Verfügung stehen.
Tabelle 1.2 Übersicht über die wichtigsten Befehle von nvm-windows
CI-Systeme und Docker Ein Node.js Version Manager eignet sich sehr gut für das schnelle Wechseln zwischen verschiedenen Versionen auf einem Entwicklungsrechner. Für das automatische Testen einer Applikation unter verschiedenen Versionen empfiehlt es sich natürlich, langfristig auf automatisierte Techniken zurückzugreifen wie bspw. die Verwendung von CI-Systemen (Travis CI, Circle CI, GitLab CI, Jenkins etc.). Auch der Einsatz von Docker-Images, die jeweils eine spezielle Node.js-Version verwenden, ist sinnvoll. Docker-Images können Sie ohne viel Aufwand lokal erstellen und dann Ihre Node.js-Anwendung innerhalb eines Docker-Containers laufen lassen. Wie das geht, zeige ich Ihnen in Kapitel 13, »Publishing, Deployment und Microservices«.
1.2.3 Ausblick In diesem Rezept habe ich Ihnen gezeigt, wie Sie mithilfe eines Node.js Version Managers mehrere Versionen von Node.js parallel installieren und verwenden. Damit ist das Thema der Node.js-Installation abgeschlossen, und ich möchte Ihnen in den folgenden Rezepten zeigen, wie Node.js-Packages aufgebaut sein sollten und welche verschiedenen Möglichkeiten Sie haben, neue Node.js-Packages zu erstellen.
40
1.3
Rezept 3: Ein neues Node.js-Package manuell erstellen
Verwandte Rezepte 왘 Rezept 1: Node.js installieren 왘 Rezept 100: Ein Docker Image für eine Node.js-Applikation erstellen
1.3 Rezept 3: Ein neues Node.js-Package manuell erstellen Sie möchten ein neues Package für Node.js manuell erstellen und wissen, wie ein solches Package aufgebaut sein sollte.
1.3.1 Lösung Node.js-Packages werden im Wesentlichen (neben dem eigentlichen Quelltext versteht sich) durch die Konfigurationsdatei package.json definiert. In dieser Datei sind bspw. der Name eines Packages, dessen Versionsnummer, Links zur GitHub-Seite, Angaben zu den Autoren, Lizenzinformationen und vieles andere mehr enthalten. Auch der Einstiegspunkt in das Package (standardmäßig und in den meisten Fällen eine Datei mit dem Namen index.js) ist in der package.json-Datei verlinkt. Für ein einfaches Package reicht es also, wenn Sie über folgende Befehle entsprechende Dateien erstellen und mit dem Inhalt aus den folgenden Listings befüllen: $ $ $ $ $ $
mkdir codenode cd codenode touch package.json mkdir src touch src/Calculator.js touch index.js
Listing 1.9 Manuelles Erstellen eines Node.js-Packages über die Kommandozeile { "name": "codenode", "version": "1.0.0", "description": "A simple Node.js package.", "main": "index.js", "scripts": {}, "keywords": [ . "javascript", . "node.js" ],
41
1
Initialisierung und Setup
"author": "Philip Ackermann", "license": "MIT" } Listing 1.10 Typischer initialer Aufbau der »package.json«-Datei // src/Calculator.js module.exports = class Calculator { add(x, y) { return x + y; } } Listing 1.11 Einfache Beispiel-Klasse // index.js const Calculator = require('./src/Calculator'); module.exports = { Calculator } Listing 1.12 Initialer Aufbau der »index.js«-Datei
1.3.2 Modulsyntax Node.js richtet sich, wie Sie in den Listings für die Dateien index.js und Calculator.js sehen können, hinsichtlich der Moduldefinitionen nach der CommonJS-Modulsyntax (https://nodejs.org/docs/latest/api/modules.html). Dabei wird der Inhalt jeder Datei als eigenständiges Modul angesehen, und Sie definieren über module.exports, welche Komponenten eines Moduls nach außen exportiert werden sollen und damit von anderen Komponenten importiert werden können. Letzteres, das Importieren von Modulen, funktioniert über die globale Funktion require().
ES-Modulsyntax Langfristig wird es unter Node.js auch möglich sein, die Standardsyntax von ECMAScript, die sogenannte ES-Modulsyntax, zu verwenden, bei der die Schlüsselwörter export und import zum Einsatz kommen. Momentan befindet sich entsprechender Support für Node.js jedoch noch in einem experimentellen Zustand, sodass Sie bis auf Weiteres die CommonJS-Syntax verwenden sollten. Wenn in Zukunft entsprechender Support vorhanden ist, können Sie übrigens mithilfe von JavaScript-Transformatoren (siehe Rezept 46) die Modulsyntax auch automatisch an die neue Syntax anpassen.
42
1.3
Rezept 3: Ein neues Node.js-Package manuell erstellen
1.3.3 Weitere Dateien Neben den gezeigten Dateien ist es sinnvoll, einige weitere Konfigurationsdateien anzulegen. Folgende Tabelle 1.3 zeigt einige häufig verwendete Dateien, die typischerweise in Node.js-Packages zum Einsatz kommen. Datei
Beschreibung
.editorconfig
Enthält Konfigurationen bezüglich des verwendeten Code-Editors (siehe auch https://editorconfig.org/).
.gitattributes
Enthält Konfigurationen für Git
.gitignore
Enthält Dateien, die von Git ignoriert werden sollen. Wenn Sie den Quelltext Ihres Packages mithilfe von Git versionieren, sollten Sie hier das node_modules-Verzeichnis hinzufügen.
.npmrc
Enthält Konfigurationen für npm.
.travis.yml
Stellvertretend für alle CI-Systeme: enthält Konfigurationen für Travis-CI. Alternativ verwenden Sie je nach CI-System andere Konfigurationsdateien.
index.js
Einstiegsdatei in das Package.
LICENSE.md
Lizenzinformationen für das Package.
package.json
Konfigurationen für das Package.
README.md
Eine Datei, die das Package beschreibt, eventuell ergänzt durch Code-Beispiele und eine Dokumentation der öffentlichen API.
Tabelle 1.3 Relevante Konfigurationsdateien für Node.js-Projekte
1.3.4 Best Practices für Node.js-Packages Neben der in den vorherigen Abschnitten beschriebenen gängigen Struktur gibt es verschiedene Best Practices, die Sie beim Erstellen von Node.js-Packages beachten sollten. Nachfolgend eine Auswahl der wichtigsten Punkte: 왘 Schreibweise: Package-Namen sollten in Kleinbuchstaben (»lower case«) ge-
schrieben sein, einzelne Bestandteile des Namens gegebenenfalls durch Bindestriche getrennt. Beispiele hierfür sind »codenode«, »code-node« oder »codenode2«. Möchten Sie ein Package zudem über die offizielle npm-Registry (unter https:// www.npmjs.com/ bzw. https://registry.npmjs.org/) veröffentlichen, sollten Sie dies bereits bei der initialen Namenswahl beachten, da der Name des Packages global eindeutig sein muss. Privaten Packages muss dabei zusätzlich ein sogenannter Scope (auch: Namensraum) vorangestellt werden, bspw. »@myorganization/code-
43
1
Initialisierung und Setup
node«. Da dieser Name auch innerhalb des Quelltextes angegeben werden muss, bspw. beim Import (require('@myorganization/codenode')), kann es mit relativ viel Aufwand verbunden sein, wenn Sie diesen Namen nachträglich an allen Stellen im Code anpassen müssen. 왘 Größe: Packages sollten hinsichtlich der enthaltenen Komponenten und Funktio-
nalitäten möglichst klein sein, um eine möglichst große Wiederverwendbarkeit zu gewährleisten. 왘 Wiederverwendung: Wie immer in der Softwareentwicklung gilt auch für Node.js-
Packages: Erfinden Sie das Rad nicht jedes Mal neu. In der offiziellen npm-Registry sind derzeit (Februar 2019) rund 780.000 Packages gelistet (damit zählt npm in dieser Hinsicht übrigens zu den erfolgreichsten Package Managern; für einen Vergleich zu anderen Package Managern siehe auch http://www.modulecounts.com/). Bevor Sie sich die Arbeit machen, für eine bestimmte Problemstellung ein neues Package zu erstellen, recherchieren Sie zunächst, ob es nicht bereits eine entsprechende Lösung gibt. Achten Sie bei der Auswahl eines Packages auf Kennzahlen wie die Anzahl der Downloads (Popularität), den Zeitpunkt des letzten Updates (Aktualität), die Regelmäßigkeit von Updates (Aktivität), auf Aspekte wie Lizenz, Sicherheitslücken und Bug-Reports und darauf, welche Entwickler hinter dem Package stehen. Was Sie generell bezüglich der Verwendung von externen Packages beachten sollten, werde ich in Rezept 6 näher erläutern. 왘 Versionierung: Bezüglich der Versionierung von Node.js-Packages sollten Sie die
semantische Versionierung verwenden. Eine Versionsnummer, die sich nach der semantischen Versionierung richtet, besteht aus drei Teilen: der Major-Versionsnummer, der Minor-Versionsnummer und der Patch-Versionsnummer. Beispiele hierfür sind 1.0.0, 2.3.4 oder 2.3.15. Im Detail werde ich auf dieses Thema noch in Rezept 8 eingehen.
1.3.5 Ausblick Der in diesem Rezept besprochene Ansatz, ein Node.js-Package manuell anzulegen, ist, wenn man so will, der aufwendigste, weil Sie alle Konfigurationen von Hand anlegen müssen. Daher eignet sich dieser Ansatz eher nur zu Beginn, um die Struktur von Node.js-Packages zu verstehen. Wenn Sie mit dem Aufbau dagegen bereits vertraut sind, bietet es sich an, auf eine der automatisierten Lösungen zurückzugreifen, die ich Ihnen im folgenden Rezept vorstelle.
Verwandte Rezepte 왘 Rezept 4: Ein neues Node.js-Package automatisch erstellen 왘 Rezept 5: Den Kommandozeilenwizard von npm anpassen 왘 Rezept 8: Semantische Versionierung richtig einsetzen
44
1.4
Rezept 4: Ein neues Node.js-Package automatisch erstellen
왘 Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen 왘 Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln 왘 Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln 왘 Rezept 15: Veraltete Abhängigkeiten ermitteln
1.4 Rezept 4: Ein neues Node.js-Package automatisch erstellen Sie möchten ein neues Node.js-Package automatisch erstellen und wissen, welche Möglichkeiten es hierzu gibt.
1.4.1 Möglichkeiten zur Initialisierung von Packages Für das automatische Erstellen neuer Packages für Node.js bieten sich je nach Anwendungsfall verschiedene Möglichkeiten, die ich Ihnen im Folgenden vorstelle: 왘 Packages über den Kommandozeilenwizard erstellen (Abschnitt 1.4.2) 왘 Packages über Starter-Kits erstellen (Abschnitt 1.4.3) 왘 Packages über Code-Generatoren erstellen (Abschnitt 1.4.4) 왘 Packages über einen angepassten Kommandozeilenwizard erstellen (Rezept 5)
1.4.2 Lösung: Packages über den Kommandozeilenwizard erstellen Prinzipiell können Sie die Konfigurationsdatei package.json, wie in Rezept 3 gezeigt, manuell erstellen und entsprechenden Inhalt hinzufügen. Alternativ dazu stellt npm einen Kommandozeilenwizard zur Verfügung, den Sie über npm init starten können und der dann entsprechend Ihren Angaben eine vorkonfigurierte package.json-Datei erstellt (Listing 1.13). $ mkdir codenode $ cd codenode $ npm init This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install ` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. package name: (codenode) version: (1.0.0)
45
1
Initialisierung und Setup
description: A simple Node.js package. entry point: (index.js) test command: jest git repository: keywords: javascript, node.js author: Philip Ackermann license: (ISC) About to write to /Users/philipackermann/workspace/nodejskochbuch/codenode/ package.json: { "name": "codenode", "version": "1.0.0", "description": "A simple Node.js package.", "main": "index.js", "scripts": { "test": "jest" }, "keywords": [ "javascript", "node.js" ], "author": "Philip Ackermann", "license": "ISC" } Is this ok? (yes) Listing 1.13 Kommandozeilenwizard für das Erstellen neuer Node.js-Packages
Um den Kommandozeilenwizard zu beschleunigen, können Sie dem Befehl npm init den Parameter -y anhängen, was dazu führt, dass alle Fragen im Wizard direkt mit den jeweils vorausgewählten Standardantworten beantwortet werden: $ npm init -y Wrote to /Users/philipackermann /workspace/nodejskochbuch/codenode/ package.json: { "name": "codenode", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" },
46
1.4
Rezept 4: Ein neues Node.js-Package automatisch erstellen
"keywords": [], "author": "", "license": "ISC" } Listing 1.14 Schnelles Erstellen neuer Node.js-Packages mit Standardwerten
Standardwerte für Initialisierung In Rezept 5 zeige ich Ihnen, wie Sie Standardwerte für Autor, E-Mail etc. definieren können. Wenn Standardwerte gesetzt sind, wird im Wizard nicht danach gefragt und die entsprechenden Werte werden direkt für die Generierung der package.json-Datei verwendet.
Hinweis Wenn Sie das Verzeichnis, in dem Sie npm init ausführen, bereits als Git-Repository initialisiert haben, verwendet npm init die entsprechenden Metainformationen von Git und erzeugt die Eigenschaften repository, homepage und bugs in der package .json-Datei automatisch. $ echo -e "node_modules" > .gitignore $ git init $ git add . $ git commit -m "Initial commit" $ git remote add origin http://github.com// $ git push -u origin master $ npm init ...
Sie können auch ein mit npm init initialisiertes Package nachträglich mit git init als Git-Repository initialisieren und dann erneut npm init aufrufen. In diesem Fall werden die oben genannten Eigenschaften einfach in der bereits existierenden package.json-Datei ergänzt.
Der Weg über npm init stellt die generischste Möglichkeit dar, Node.js-Packages zu erstellen. Wie Sie gesehen haben, wird hierüber allerdings nur die package.json-Datei erzeugt, nicht aber die index.js-Datei oder andere projektspezifische Dateien und Verzeichnisstrukturen. Je nachdem, welche Art von Package Sie entwickeln, kann es daher hilfreich und vor allem zeitsparender sein, auf eine der im Folgenden beschriebenen Lösungen zurückzugreifen, die initial komplexere Package-Strukturen erzeugen bzw. bereitstellen.
47
1
Initialisierung und Setup
1.4.3 Lösung: Packages über Starter-Kits erstellen Eine Möglichkeit zur Generierung komplexerer Projektstrukturen sind sogenannte Starter-Kits bzw. Boilerplate-Projekte. Diese stehen meist in Form eines Git-Repositorys zur Verfügung, können lokal geklont und dann nach Belieben an die eigenen Anforderungen angepasst werden. Beispiele hierfür sind node-module-boilerplate (https://github.com/sindresorhus/node-module-boilerplate), das ein reines Node.jsPackage mit einer Reihe von Konfigurationsdateien erzeugt, und nodejs-api-starter (https://github.com/kriasoft/nodejs-api-starter), das eine komplette Struktur für APIBackends in Node.js unter Verwendung von GraphQL (https://graphql.org/, siehe Rezept 60) bereitstellt.
1.4.4 Lösung: Packages über Code-Generatoren erstellen Eine Alternative zu Starter-Kits sind Code-Generatoren, die ähnlich wie npm init funktionieren, dabei aber verschiedene Projekttypen unterstützen. Beispiele hierfür sind Neutrino.js (https://neutrino.js.org/, siehe Abbildung 1.8) und Yeoman (http://yeoman.io/). Für Express.js-Anwendungen (siehe Rezept 54) bietet sich zudem der offizielle Express Application Generator (https://expressjs.com/en/starter/generator.html) an, für React-Anwendungen der create-react-app-Generator (https://github.com/facebook/create-react-app), der das Grundgerüst einer React-Anwendung generiert.
Abbildung 1.8 Die verschiedenen Projekttypen bei Neutrino.js
Prinzipiell können Code-Generatoren auf drei verschiedene Weisen ausgeführt werden: 왘 Ausführen als globales Package: Hierbei wird der Generator als globales Package
installiert und anschließend über den entsprechenden globalen Befehl ausgeführt. Im Fall von create-react-app bspw.:
48
1.5
Rezept 5: Den Kommandozeilenwizard von npm anpassen
$ npm install create-react-app -g create-react-app example-react 왘 Ausführen über den npm Package Runner (npx): Hierbei wird der Generator tem-
porär installiert und über npx ausgeführt: $ npx create-react-app example-react 왘 Ausführen über einen npm Initializer: Seit npm 6.1.0 gibt es die Möglichkeit, dem
Befehl npm init einen sogenannten Initializer als Parameter zu übergeben. Intern lädt npm dann mithilfe von npx ein entsprechendes Package (wobei ein »create-« vorn an den Namen des Generators angefügt wird) und führt die Main-Datei dieses Packages aus: $ npm init react-app example-react
1.4.5 Ausblick In diesem Rezept haben Sie gesehen, welche Möglichkeiten es gibt, Node.js-Packages automatisch zu erstellen. Im nächsten Rezept gebe ich Ihnen einige Tipps dazu, wie sich npm konfigurieren und der Initialisierungsprozess des Kommandozeilenwizards individualisieren lässt, damit das Erstellen von Node.js-Packages noch einfacher und effektiver von der Hand geht.
Verwandte Rezepte 왘 Rezept 3: Ein neues Node.js-Package manuell erstellen 왘 Rezept 5: Den Kommandozeilenwizard von npm anpassen
1.5 Rezept 5: Den Kommandozeilenwizard von npm anpassen Sie möchten den Node.js Package Manager (npm) und dessen Kommandozeilenwizard für das Erstellen neuer Packages anpassen.
1.5.1 Lösung: Standardwerte anpassen npm speichert die Konfigurationen als Schlüssel/Wert-Paare in einer globalen Datei mit dem Namen .npmrc (siehe https://docs.npmjs.com/files/npmrc). Den Inhalt dieser Datei bzw. die dort definierten Konfigurationseigenschaften können Sie sich mit folgendem Befehl ausgeben lassen: $ npm config ls -l
Bezüglich der Initialisierung von Packages sind in der anschließenden Ausgabe insbesondere die Eigenschaften interessant, die mit dem Präfix »init-« beginnen. Diese
49
1
Initialisierung und Setup
Eigenschaften werden beim Anlegen neuer Node.js-Packages (siehe Rezept 4) von npm ausgelesen und direkt als Standardwerte für die Projektkonfigurationsdatei (package.json) verwendet. Konkret sind folgende Eigenschaften verfügbar: 왘 init-author-email: die E-Mail-Adresse des Package-Autors 왘 init-author-name: der Name des Package-Autors 왘 init-author-url: die URL zur Homepage des Package-Autors 왘 init-license: die verwendete Lizenz 왘 init-module: Pfad zu dem Modul, das für die Initialisierung von neuen Packages
verwendet wird (dazu gleich mehr in Abschnitt 1.5.2, »Lösung: Eine individuelle Package-Initialisierung einrichten«). 왘 init-version: die Versionsnummer, die für neue Packages verwendet werden soll
Diese Eigenschaften können Sie entsprechend Ihren Bedürfnissen anpassen. Wie das geht, zeige ich Ihnen im folgenden Abschnitt.
Verwalten der Konfigurationsdateien Für das Arbeiten mit der Konfiguration stellt npm den Befehl npm config bzw. weitere Unterbefehle zur Verfügung. Über den Befehl npm config set bzw. dessen Shortcut npm set haben Sie bspw. die Möglichkeit, die Standardwerte für E-Mail, Name etc. zu definieren: $ $ $ $
npm npm npm npm
set set set set
init.author.email "[email protected]" init.author.name "Philip Ackermann" init.url "philipackermann.de" init.license "MIT"
Anschließend speichert npm die Werte intern in der Datei .npmrc: $ cat ~/.npmrc [email protected] init.author.name=Philip Ackermann init.url=philipackermann.de init.license=MIT
Über den Befehl npm config get können Sie sich für eine Eigenschaft den entsprechenden Wert ausgeben lassen: $ npm config get init.author.email [email protected]
Wenn Sie nun wie über den Befehl npm init den Kommandozeilenwizard für das Erstellen eines neuen Packages aufrufen, verwendet npm die in der Konfiguration definierten Standardwerte:
50
1.5
Rezept 5: Den Kommandozeilenwizard von npm anpassen
npm init -y Wrote to /Users/philipackermann/workspace/example/package.json: { "name": "example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT" }
Hinweis Die Konfigurationsdatei .npmrc kann an verschiedenen Stellen definiert werden: zum einen global pro Nutzer, zum anderen aber auch global für alle Nutzer sowie (lokal) pro Package. Darüber hinaus verwendet npm selbst intern eine weitere Konfigurationsdatei, die sich allerdings nicht verändern lässt.
1.5.2 Lösung: Eine individuelle Package-Initialisierung einrichten Wenn Ihnen das Definieren der im vorherigen Abschnitt genannten Standardwerte nicht ausreicht, haben Sie auch die Möglichkeit, den Initialisierungsprozess, der durch npm init angestoßen wird, über ein eigenes Script zu erweitern bzw. anpassen, das über die Konfigurationseigenschaft init-module definiert werden kann. Standardmäßig ist diese Eigenschaft mit dem Wert ~/.npm-init.js belegt, zeigt also auf eine Datei .npm-init.js im Nutzerverzeichnis: $ npm config get init-module /Users/philipackermann/.npm-init.js
Um das Initialisierungsscript anzupassen, müssen Sie die entsprechende Datei jedoch zunächst anlegen, denn standardmäßig gibt es unter dem angegebenen Pfad gar keine solche Datei. Um zu sehen, wie sich der Initialisierungsprozess nach eigenen Bedürfnissen anpassen lässt, erstellen Sie also diese Datei und fügen den Code aus Listing 1.15 hinzu. Über module.exports definieren Sie hier die Struktur der package.json-Datei, die über die Initialisierung erstellt werden soll. Hier können Sie zum einen Standardwerte festlegen, bspw. wie in Listing 1.15 den Bereich für die devDependencies vorgeben. Zum anderen können Sie auch Dateien oder Verzeichnisstruk-
51
1
Initialisierung und Setup
turen erzeugen, wie im Beispiel die Dateien LICENSE, README.MD und .eslintrc.json. Darüber hinaus haben Sie durch Verwendung der Funktion prompt() die Möglichkeit, Eingaben vom Nutzer abzufangen. const fs = require('fs'); fs.writeFileSync('LICENSE'); fs.writeFileSync('README.md'); fs.writeFileSync('.eslintrc.json'); fs.mkdirSync('test'); const GIT_USER = 'cleancoderocker'; module.exports = { name: prompt('Name', basename || package.name), version: prompt('Version', '0.0.1', package.version), description: prompt('Description', (description) => description), main: prompt('Entry point', 'index.js', (entryPoint) => fs.writeFileSync(entryPoint, '') ), author: 'Philip Ackermann', license: 'MIT', scripts: { test: 'npx jest --verbose', lint: 'npx eslint test/*.js index.js', coverage: 'npx jest --coverage' }, repository: { type: 'git', url: `git://github.com/${GIT_USER}/${basename}.git` }, files: ['package.json', 'README.md', 'LICENSE', 'index.js'], bugs: { url: `https://github.com/${GIT_USER}/${basename}/issues` }, homepage: `https://github.com/${GIT_USER}/${basename}`, keywords: prompt('Keywords', (keywords) => keywords.split(/\s+/)), devDependencies: { eslint: '*', jest: '*' } }; Listing 1.15 Angepasstes Initialisierungsscript
52
1.5
Rezept 5: Den Kommandozeilenwizard von npm anpassen
Rufen Sie nun den Befehl npm init auf, sieht die Ausgabe des Kommandozeilenwizards wie folgt aus: $ npm init This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install ` afterwards to install a package and save it as a dependency in the package.json file. Press ^C at any time to quit. Name: (codenode) Version: (0.0.1) Description: Custom npm init Entry point: (index.js) Keywords: javascript nodejs About to write to /Users/philipackermann/codenode/package.json: { "name": "codenode", "version": "0.0.1", "description": "Custom npm init", "author": "Philip Ackermann", "license": "MIT", "scripts": { "test": "npx jest --verbose", "lint": "npx eslint test/*.js index.js", "coverage": "npx jest --coverage" }, "repository": { "type": "git", "url": "git://github.com/cleancoderocker/codenode.git" }, "files": [ "package.json", "README.md", "LICENSE", "index.js" ],
53
1
Initialisierung und Setup
"bugs": { "url": "https://github.com/cleancoderocker/codenode/issues" }, "homepage": "https://github.com/cleancoderocker/codenode", "keywords": [ "javascript", "nodejs" ], "devDependencies": { "eslint": "*", "jest": "*" } } Is this ok? (yes) Listing 1.16 Ausgabe des angepassten Initialisierungsscripts
1.5.3 Ausblick In diesem Rezept haben Sie gesehen, wie Sie npm bezüglich der Initialisierung von neuen Packages anpassen können. Dank der Möglichkeit, das Initialisierungsscript von npm nach Belieben zu implementieren, können Sie Ihren Ideen freien Lauf lassen und sehr komplexe Initialisierungsprozesse implementieren. Im nächsten Rezept wenden wir uns dem Thema Abhängigkeiten zu, und ich werde ich Ihnen zeigen, wie Sie diese richtig installieren und verwalten.
1.6 Rezept 6: Abhängigkeiten richtig installieren und verwalten Sie möchten Abhängigkeiten für ein Package richtig installieren und verwalten.
1.6.1 Die verschiedenen Typen von Abhängigkeiten verstehen Bei der Installation von Abhängigkeiten für ein Package oder eine Applikation sind vorab folgende Punkte zu beachten: 왘 Handelt es sich um eine Abhängigkeit, die zur Laufzeit benötigt wird, oder um eine
Abhängigkeit, die nur während der Entwicklung benötigt wird? 왘 Handelt es sich bei der Abhängigkeit um ein Tool, das Sie global installieren möch-
ten, oder um eine Abhängigkeit, die von einem Ihrer Packages verwendet wird?
54
1.6
Rezept 6: Abhängigkeiten richtig installieren und verwalten
왘 Welche Version einer Abhängigkeit möchten Sie installieren, und wie können Sie
sicherstellen, dass Sie immer mit der exakten Versionsnummer arbeiten? 왘 Welche Informationen bezüglich Aktualität, Lizenzen, Stabilität etc. sind verfüg-
bar (siehe die Rezepte in Kapitel 2, »Package Management«)? Abhängigkeiten eines Packages werden, wie bereits erwähnt, in der Konfigurationsdatei package.json verwaltet. Dazu gibt es in dieser Datei folgende Bereiche: 왘 dependencies: In diesem Bereich sind die Abhängigkeiten aufgelistet, die für das
Ausführen des Packages, also zur Laufzeit, benötigt werden (Laufzeitabhängigkeiten bzw. Runtime Dependencies). Beispiele hierfür sind das Webframework Express (https://expressjs.com) oder die Hilfsbibliothek zur funktionalen Programmierung »lodash« (https://lodash.com/). 왘 devDependencies: Dieser Bereich enthält diejenigen Abhängigkeiten, die während
der Entwicklung benötigt werden (Entwicklungsabhängigkeiten oder etwas gebräuchlicher das englische Äquivalent Development Dependencies). Dies können bspw. Testframeworks wie Jest (https://jestjs.io/) oder mocha (https://mochajs.org/), Linting-Tools wie eslint (https://eslint.org/) oder prettier (https://prettier.io/), Dokumentationstools wie esdoc (https://esdoc.org/) oder Transpiler wie Babel (https://babeljs.io/) sein (etwas detaillierter als in dem vorliegenden Buch gehe ich auf die genannten Tools übrigens in meinem Buch »Professionell entwickeln mit JavaScript – Design, Patterns, Praxistipps« ein, das ebenfalls im Rheinwerk Verlag erschienen ist). 왘 peerDependencies: Dieser Bereich enthält Abhängigkeiten, die nicht direkt von
dem Package benötigt werden, aber doch zur Laufzeit vorhanden sein müssen. Typisches Beispiel dazu, wann dies der Fall ist, ist die Entwicklung von Plugins: Wenn Sie bspw. ein Plugin für Express entwickeln, besteht von diesem Plugin nicht zwangsweise eine direkte Abhängigkeit zu Express. Wohl aber muss zur Laufzeit Express vorhanden sein, damit das Plugin ausgeführt werden kann. 왘 bundledDependencies/bundleDependencies: Dieser Bereich enthält die Abhängigkei-
ten, die beim Publishing des Packages im Bundle enthalten sein sollen. Mit anderen Worten: Der Quelltext dieser Abhängigkeiten ist Teil des entsprechenden Packages und wird mit dem Package publiziert. 왘 optionalDependencies: Dieser Bereich enthält die Abhängigkeiten, die nicht zwangs-
weise benötigt werden. Wenn eine als optional definierte Abhängigkeit während der Installation nicht gefunden wurde oder die Installation der Abhängigkeit fehlschlägt, liefert npm keinen Fehler, sondern fährt mit der Installation fort. Trotzdem sollten Sie innerhalb Ihrer Applikation (bspw. durch die Verwendung von try/catch) entsprechende Maßnahmen treffen, wenn die Abhängigkeit nicht vorhanden ist.
55
1
Initialisierung und Setup
Hinweis Globale Packages sind keine Abhängigkeiten und werden daher auch nicht in der Datei package.json verwaltet.
In der Praxis werden Sie es wahrscheinlich in den meisten Fällen mit Laufzeitabhängigkeiten oder Entwicklungsabhängigkeiten zu tun haben. Daher werden im Folgenden nur diese beiden Fälle detaillierter betrachtet.
1.6.2 Lösung: Installieren von Laufzeitabhängigkeiten Neue Laufzeitabhängigkeiten lassen sich über den Befehl npm install bzw. dessen Shortcut npm i installieren. Seit npm 5 werden Abhängigkeiten dabei direkt auch in die Konfigurationsdatei geschrieben (davor mussten Sie dies über den Parameter --save selbst angeben: npm install --save). $ $ $ $ $ {
mkdir dependencies-example cd dependencies-example npm init -y npm install express cat package.json "name": "dependencies-example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT", "dependencies": { "express": "^4.16.3" }
} Listing 1.17 package.json nach der Installation einer Laufzeitabhängigkeit
Rufen Sie innerhalb eines Packages npm install dagegen ohne Parameter auf, werden automatisch alle Abhängigkeiten installiert, die in der package.json-Datei des Packages aufgeführt sind, inklusive aller indirekten Abhängigkeiten (auch: transitiven Abhängigkeiten) versteht sich.
56
1.6
Rezept 6: Abhängigkeiten richtig installieren und verwalten
1.6.3 Lösung: Installieren von Entwicklungsabhängigkeiten Für das Installieren von Abhängigkeiten, die während der Entwicklung eines Packages relevant sind, verwenden Sie dagegen den Parameter --save-dev oder dessen Shortcut -D. Anschließend wird die entsprechende Abhängigkeit (seit npm 5) automatisch in den Bereich devDependencies geschrieben: $ npm install supertest --save-dev $ cat package.json { "name": "dependencies-example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT", "dependencies": { "express": "^4.16.3" }, "devDependencies": { "supertest": "^3.0.0" } } Listing 1.18 »package.json« nach der Installation einer Testabhängigkeit
1.6.4 Lösung: Installieren von globalen Packages Ein Package global zu installieren ist eigentlich nur dann sinnvoll, wenn es sich dabei um ein Tool handelt, das Sie projektunabhängig und global über die Kommandozeile verwenden wollen. Ein Beispiel hierfür ist das Tool »license-checker« (https:// www.npmjs.com/package/license-checker), auf das ich in Rezept 13, »Lizenzen der verwendeten Abhängigkeiten ermitteln«, näher eingehen werde. Mit dem seit npm-Version 5.2.0 verfügbaren npm Package Runner (npx) ist es allerdings auch möglich, solche Tools bequem auszuführen, ohne dass sie global installiert sein müssen. Globale Packages lassen sich installieren, indem Sie dem Befehl npm install den Parameter -g anhängen. Dabei ist zu beachten, dass das Installieren von globalen Packages unter macOS und Linux sudo-Rechte erfordert, da sich das Verzeichnis für
57
1
Initialisierung und Setup
globale Packages standardmäßig unter /usr/local befindet. Den entsprechenden Installationsbefehl müssen Sie daher unter diesen Betriebssystemen als sudo ausführen: $ sudo npm install jest -g
Alternativ dazu stehen Ihnen aber auch verschiedene Möglichkeiten zur Verfügung, um globale Packages ohne sudo-Rechte zu installieren, wie im nächsten Abschnitt beschrieben wird.
1.6.5 Lösung: Installieren von globalen Packages ohne sudo-Rechte Wie oben gesagt, werden globale Packages standardmäßig unter dem Verzeichnis /usr/local installiert (Details hierzu finden Sie auch unter https://docs.npmjs.com/ files/folders). Überprüfen können Sie dies, indem Sie sich die entsprechende npmKonfiguration prefix ausgeben lassen: $ npm config get prefix /usr/local
Um globale Packages ohne sudo-Rechte installieren zu können, haben Sie nun verschiedene Möglichkeiten: 왘 Ändern der Rechte: Hierbei ändern Sie die Rechte an dem Verzeichnis /usr/local
derart, dass nicht nur der Superuser, sondern auch der aktuelle Nutzer Schreibrechte an diesem Verzeichnis bekommt: $ sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share} 왘 Alternatives Verzeichnis: Hierbei definieren Sie ein anderes Verzeichnis als /usr/
local für das Speichern von globalen Packages: # $ # $ # $ # $
neues Verzeichnis erstellen mkdir ~/npm-global-packages Konfiguration anpassen npm config set prefix ~/npm-global-packages Pfad anpassen export PATH=$PATH:~/npm-global-packages/bin Terminal aktualisieren source ~/.profile
왘 Node.js Version Manager: Dies ist die meiner Meinung nach effektivste und nut-
zerfreundlichste Variante, die ich Ihnen in Rezept 2 vorgestellt habe.
58
1.7
Rezept 7: Packages in Mono-Repositorys organisieren
Hinweis Wenn ich im weiteren Verlauf des Buches globale Packages installiere, verwende ich den jeweiligen Installationsbefehl ohne die Angabe von sudo, weil ich einen Node.js Version Manager verwende. Dies empfehle ich Ihnen übrigens auch unbedingt! Falls Sie dies aber aus bestimmten Gründen nicht möchten und auch nicht wie oben beschrieben entsprechende Anpassungen vorgenommen haben, um globale Packages ohne sudo-Rechte installieren zu können, müssten Sie gegebenenfalls entsprechende Angaben hinzufügen.
1.6.6 Ausblick In diesem Rezept haben Sie gesehen, wie Sie Sie mithilfe von npm Abhängigkeiten installieren können. In Kapitel 2, »Package Management«, werde ich Ihnen zwei alternative Package Manager vorstellen, die beide ihre eigenen Vorteile gegenüber npm versprechen.
1.7 Rezept 7: Packages in Mono-Repositorys organisieren Sie möchten nicht jedes Ihrer Node.js-Packages als eigenes Git-Repository verwalten.
1.7.1 Lösung Ein wesentliches Designprinzip bei der Entwicklung mit Node.js ist es, den Code getreu dem Motto »small is beautiful« in möglichst kleine, wiederverwendbare Packages zu strukturieren. In der Extremform kann dies so weit gehen, dass sogar einzelne Funktionen in Form eines Packages bereitgestellt werden (dann spricht man auch von Micro-Packages). Schnell sammeln sich dann mehrere Dutzend, wenn nicht Hunderte verschiedene Packages im eigenen Workspace an. Doch auch ohne die Extremform der Micro-Packages kann es in komplexeren Projekten schnell unübersichtlich werden, wenn diese aus 50, 100 oder noch mehr Packages bestehen und jedes Package dabei in einem eigenen Git-Repository verwaltet werden muss. Abhängigkeiten wollen verwaltet, Build-Prozesse organisiert und das Deployment in die npm-Registry konfiguriert werden. Wenn dies für jedes Package separat pro Repository gemacht werden muss, kann dies schnell zu relativ viel Verwaltungs- und Organisationsaufwand führen. Aus diesen Gründen strukturieren Entwickler bekannter Frameworks wie Angular (https://angular.io/), React (https://reactjs.org/), Meteor (https://www.meteor.com/)
59
1
Initialisierung und Setup
und Ember (https://www.emberjs.com/) oder bekannte Tools wie Babel (https:// babeljs.io/) und Jest (https://jestjs.io/) ihren Code mittlerweile in sogenannten MonoRepositorys, kurz Mono-Repos oder auch Multi-Package-Repositorys. Die Idee dabei ist es, nicht jedes Package in einem eigenen Git-Repository zu speichern, sondern mehrere zusammengehörige Packages in einem einzelnen Git-Repository zu verwalten. Die Vorteile liegen auf der Hand: Zum einen müssen Sie sich dann nicht mit mehreren Git-Repositorys herumschlagen, zum anderen lassen sich der Build-Prozess und das Deployment für alle Packages stark vereinfachen.
1.7.2 Lerna Ein Tool, das Ihnen beim Anlegen und Verwalten von Mono-Repositorys helfen kann, ist Lerna (https://github.com/lerna/lerna). Ursprünglich als Teil von Babel (https:// babeljs.io/) entwickelt, ist Lerna mittlerweile ein eigenständiges Node.js-Package, sodass Sie es wie gewohnt über npm als globale Abhängigkeit installieren können: $ npm i -g lerna
Anschließend verwenden Sie das Tool über den Befehl lerna, wobei, wie Sie gleich sehen werden, eine Reihe verschiedener Parameter zur Verfügung stehen.
1.7.3 Aufbau von Mono-Repositorys Mono-Repositorys definieren sich im Wesentlichen durch ihre Struktur und über zwei globale Konfigurationsdateien: zum einen über eine package.json-Datei, die Metainformationen für alle verwalteten Packages enthält, zum anderen über eine Konfigurationsdatei namens lerna.json, die wiederum Lerna-spezifische Metainformationen enthält. Die einzelnen Packages wiederum werden standardmäßig in einem Unterverzeichnis mit dem Namen packages einsortiert, sodass die Gesamtstruktur eines Mono-Repositorys wie folgt aussieht: multirepo/ node_modules/ packages/ package1/ node_modules/ src/ index.js package.json package2/
60
1.7
Rezept 7: Packages in Mono-Repositorys organisieren
package3/ package4/ package5/ package6/ package.json lerna.json
Diese Struktur können Sie zwar manuell erzeugen, einfacher ist aber der Weg über die bereitgestellten Kommandozeilentools mithilfe des Befehls lerna init, worüber sich zumindest die beiden Konfigurationsdateien automatisch generieren lassen: $ mkdir multirepo $ cd multirepo $ lerna init lerna notice cli v3.2.1 lerna info Creating package.json lerna info Creating lerna.json lerna info Creating packages directory lerna success Initialized Lerna files $ cat package.json { "name": "root", "private": true, "devDependencies": { "lerna": "^3.2.1" } } $ cat lerna.json { "packages": [ "packages/*" ], "version": "0.0.0" }
Durch den oberen Befehl wird zum einen das Package Lerna als Abhängigkeit zu der package.json-Datei hinzugefügt und zum anderen die Konfigurationsdatei lerna.json erzeugt. Zu Anfang enthält diese Datei lediglich eine Angabe darüber, in welchem Verzeichnis die Packages liegen, sowie eine Versionsnummer, die global für alle Packages gilt. Darüber hinaus wird durch den Befehl das Mono-Repository auch als GitRepository initialisiert, zu erkennen an dem versteckten Verzeichnis .git, das die entsprechenden Daten für Git enthält.
61
1
Initialisierung und Setup
1.7.4 Packages innerhalb eines Mono-Repositorys anlegen Die Struktur der einzelnen Packages in einem Mono-Repository unterscheidet sich nicht von Packages, die als Single-Package-Repository verwaltet werden. Das heißt bspw., dass jedes Package weiterhin über seine eigene package.json-Datei verfügt und darüber z. B. auch seine eigenen Abhängigkeiten definieren kann. Durch folgende Befehle legen Sie bspw. zwei Packages an und installieren jeweils eine externe Abhängigkeit pro Package: $ $ $ $ # $ $ $ $ $ # $
cd packages mkdir my-first-package cd my-first-package/ npm init -y Installation einer Beispiel-Abhängigkeit npm i express cd .. mkdir my-second-package cd my-second-package/ npm init -y Installation einer weiteren Beispiel-Abhängigkeit npm i mqtt
1.7.5 Projekt-globale Abhängigkeiten Für Abhängigkeiten, die von allen oder den meisten Packages verwendet werden, bspw. solche, die nur während der Entwicklung benötigt werden, ist es in den meisten Fällen sinnvoll, diese in der »globalen« package.json anzugeben: $ cd ../.. # Wechsel auf oberste Projektebene $ npm i jest -D $ cat package.json { "name": "root", "private": true, "devDependencies": { "jest": "^23.5.0", "lerna": "^3.2.1" } }
Dieses Vorgehen hat mehrere Vorteile: Zum einen ist auf diese Weise sichergestellt, dass alle Packages die gleiche Version der verwendeten Abhängigkeit haben, zum anderen reduziert sich die Installationszeit für die entsprechende Abhängigkeit, da
62
1.7
Rezept 7: Packages in Mono-Repositorys organisieren
sie – logisch – nur einmal für alle Packages (und nicht einmal für jedes Package) installiert wird.
Scoped Packages Wenn Sie sich dafür entscheiden, ein Mono-Repository zu verwenden, ist es sinnvoll, die Packages als Scoped Packages anzulegen (siehe Rezept 3 und https://docs.npmjs.com/misc/scope), damit die Zugehörigkeit beim Publishing auch durch den Namen widergespiegelt wird.
1.7.6 Voraussetzung: Git Damit Lerna korrekt funktioniert, greift es auf Informationen aus Git-Commits zu. Um einen ersten Commit zu erzeugen und in ein entferntes Git-Repository zu übertragen, gehen Sie daher wie folgt vor. Zunächst sollten Sie sicherstellen, dass die Dateien unter node_modules in Git hochgeladen werden, und einen entsprechenden Eintrag in der Datei .gitignore anlegen: $ echo "node_modules" >> .gitignore
Fügen Sie anschließend alle bereits angelegten Dateien zu einem ersten Git-Commit zusammen: $ git add . $ git commit -m "Initial commit" [master (root-commit) 7e08437] Initial commit 7 files changed, 5746 insertions(+) create mode 100644 .gitignore create mode 100644 lerna-debug.log create mode 100644 lerna.json create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 packages/my-first-package/package.json create mode 100644 packages/my-second-package/package.json
Anschließend definieren Sie über git remote add origin das entfernte Git-Repository (Voraussetzung hierfür ist, dass Sie ein entsprechendes Git-Repository bereits angelegt haben, bspw. über die Weboberfläche von GitHub oder GitLab, je nachdem, welchen Anbieter Sie verwenden). $ git remote add origin https://github.com/cleancoderocker/monorepo.git
Waren die Schritte bis hierher erfolgreich, laden Sie über git push die Änderungen auf den Git-Server:
63
1
Initialisierung und Setup
$ git push -u origin master Counting objects: 12, done. Delta compression using up to 4 threads. Compressing objects: 100% (9/9), done. Writing objects: 100% (12/12), 42.58 KiB | 0 bytes/s, done. Total 12 (delta 1), reused 0 (delta 0) remote: Resolving deltas: 100% (1/1), done. To https://github.com/cleancoderocker/monorepo.git * [new branch] master -> master Branch master set up to track remote branch master from origin.
1.7.7 Workflow Lerna stellt wie erwähnt eine Reihe von Befehlen zur Verfügung, von denen Sie die wichtigsten in Tabelle 1.4 sehen: Befehl
Beschreibung
lerna init
Initialisierung eines Multi-Package-Repositorys
lerna bootstrap
Installation aller Abhängigkeiten der Packages
lerna publish
Veröffentlichen aller Packages auf npm
lerna updated
Überprüfen, welche Packages seit dem letzten Release geändert wurden
lerna import
Importieren eines Packages aus externem Repository
lerna clean
Entfernen aller node_modules-Verzeichnisse in allen Packages
lerna diff
Vergleich von Packages mit vorherigem Release
lerna run
Ausführen eines npm-Skripts in jedem Package
lerna exec
Ausführen eines Kommandozeilenbefehls in jedem Package
lerna ls
Auflisten aller Module
Tabelle 1.4 Die wichtigsten Befehle von Lerna
Den Befehl lerna init haben Sie bereits kennengelernt. Ebenfalls nützlich ist der Befehl lerna bootstrap, der dafür sorgt, dass die Abhängigkeiten aller Packages installiert werden. Mit anderen Worten: Lerna ruft für jedes Package den Befehl npm install auf (sehr praktisch!). Zusätzlich werden für alle Packages im Mono-Repository, die als Abhängigkeit von einem anderen Package im Repository verwendet werden, sym-
64
1.7
Rezept 7: Packages in Mono-Repositorys organisieren
bolische Links erzeugt, was bei der Entwicklung enorm hilfreich ist (siehe auch Rezept 11). # Aus Demonstrationszwecken: # löschen der installierten Abhängigkeiten $ lerna clean lerna notice cli v3.2.1 lerna info Removing the following directories: lerna info clean packages/my-first-package/node_modules lerna info clean packages/my-second-package/node_modules ? Proceed? Yes lerna info clean removing /Users/philipackermann/workspace/multirepo/packages/ my-first-package/node_modules lerna info clean removing /Users/philipackermann/workspace/multirepo/packages/ my-second-package/node_modules lerna success clean finished $ lerna bootstrap lerna notice cli v3.2.1 lerna info Bootstrapping 2 packages lerna info Installing external dependencies lerna info Symlinking packages and binaries lerna success Bootstrapped 2 packages
Nimmt Ihnen Lerna bis hierhin schon viel Arbeit ab, wird es bezüglich des Deployments bzw. Publishings noch besser. Der Befehl lerna publish sorgt dafür, dass die Versionsnummer für alle Packages, die sich seit dem letzten Release geändert haben, entsprechend hochgezählt wird. Dabei kann über einen Kommandozeilendialog ausgewählt werden, ob es sich um einen »Patch«, einen »Minor Change«, einen »Major Change« oder um einen »Custom Change« handelt: $ lerna publish lerna notice cli v3.2.1 lerna info current version 0.0.0 lerna info Looking for changed packages since initial commit. ? Select a new version (currently 0.0.0) (Use arrow keys) > Patch (0.0.1) Minor (0.1.0) Major (1.0.0) Prepatch (0.0.1-alpha.0) Preminor (0.1.0-alpha.0) Premajor (1.0.0-alpha.0) Custom Prerelease Custom Version
65
1
Initialisierung und Setup
Aber nicht nur das: lerna publish sorgt außerdem dafür, dass entsprechende Tags und Commits für die neue Version in Git erzeugt und alle Packages separat bei npm publiziert werden.
1.7.8 Ausblick Für kleinere Projekte, die aus wenigen Packages bestehen, ergibt die Struktur in einem Mono-Repository nur wenig Sinn. Bei größeren Projekten allerdings, die aus 20, 30 oder mehr Packages bestehen, sollten Sie durchaus frühzeitig überlegen, ob die Packages nicht als Mono-Repository strukturiert werden sollten. Einen Eindruck hiervon können Sie sich bspw. im Git-Repository von Babel.js unter https://github. com/babel/babel/tree/master/packages verschaffen. Stellen Sie sich den Konfigurationsaufwand vor, der hierfür notwendig wäre, wenn all diese Packages in separaten Git-Repositorys verwaltet würden!
1.8 Zusammenfassung In diesem Kapitel haben Sie verschiedene Rezepte bezüglich der Initialisierung von Node.js-Projekten kennengelernt. Sie wissen jetzt, wie Sie 왘 Node.js installieren (Rezept 1), 왘 mehrere Node.js-Versionen parallel betreiben (Rezept 2), 왘 ein neues Node.js-Package manuell erstellen (Rezept 3), 왘 ein neues Node.js-Package automatisch erstellen (Rezept 4), 왘 den Kommandozeilenwizard von npm anpassen (Rezept 5), 왘 Abhängigkeiten richtig installieren und verwalten (Rezept 6), 왘 Packages in Mono-Repositorys organisieren (Rezept 7).
Damit ist der Grundstein für die nächsten Kapitel gelegt, und Sie können sich voll auf die Entwicklung von Node.js-Applikationen konzentrieren. Im folgenden Kapitel gehe ich auf das Thema Package Management und das Verwalten von Abhängigkeiten ein.
66
Kapitel 2 Package Management In diesem Kapitel zeige ich Ihnen, wie Sie die Abhängigkeiten von Node.js-Projekten richtig verwalten. Dazu zählen Aspekte wie Versionierung, Sicherheit, Updates, Lizenzen und einiges mehr.
Im Folgenden zeige ich Ihnen, wie Sie Packages richtig versionieren (Rezept 8), zwei alternative Package Manager anstelle von npm verwenden (Rezepte 9 und 10) und was bezüglich des Package Managements bzw. des Verwaltens von Abhängigkeiten zu beachten ist (Rezepte 11 bis 15). 왘 Rezept 8: Semantische Versionierung richtig einsetzen 왘 Rezept 9: Den alternativen Package Manager »Yarn« verwenden 왘 Rezept 10: Den alternativen Package Manager »pnpm« verwenden 왘 Rezept 11: Lokale Abhängigkeiten für die Entwicklung verlinken 왘 Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen 왘 Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln 왘 Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln 왘 Rezept 15: Veraltete Abhängigkeiten ermitteln
2.1 Rezept 8: Semantische Versionierung richtig einsetzen Sie möchten verstehen, was es mit der semantischen Versionierung, quasi dem Standard in Bezug auf die Versionierung von Software – die auch in vielen Open-SourceProjekten eingesetzt wird –, auf sich hat und wie sich diese konkret im Fall von Node.js-Packages einsetzen lässt.
2.1.1 Exkurs: semantische Versionierung Die Versionsnummern von Node.js-Packages richten sich nach der sogenannten semantischen Versionierung (https://semver.org/). Dabei haben Versionsnummern einen besonderen Aufbau, bestehend aus einer Major-Version, einer Minor-Version und einer Patch-Version, jeweils getrennt durch ein Komma: .. . Ein Beispiel: Bei der Versionsnummer 1.2.27 hätte die Major-Version den
67
2
Package Management
Wert 1, die Minor-Version den Wert 2 und die Patch-Version den Wert 27. So weit, so einfach. Doch was genau kennzeichnet die unterschiedlichen Bestandteile einer semantischen Versionsnummer? 왘 Major: Major bezeichnet die Hauptversionsnummer, die dann erhöht wird, wenn
die öffentliche API des Packages sich geändert hat und inkompatibel mit der vorherigen Version ist (API Change). 왘 Minor: Minor bezeichnet die Unterversionsnummer, die dann erhöht wird, wenn
neue Features zu einem Package dazukommen, die öffentliche API aber weiterhin abwärtskompatibel bleibt. 왘 Patch: Patch bezeichnet die Patchversionsnummer, die bei Bugfixes erhöht wird.
Die öffentliche API bleibt – selbstredend – wie auch bei der Minor-Version weiterhin abwärtskompatibel. 왘 Darüber hinaus ist es möglich, über sogenannte Labels die Versionsnummer wei-
ter zu verfeinern. Labels werden dabei – durch einen Bindestrich getrennt – hinter die Patch-Version geschrieben, bspw. 2.0.0-beta oder 2.0.0-rc (»rc« für Release Candidate). Im Folgenden möchte ich Ihnen zeigen, wie sich diese semantische Versionierung bei Node.js-Packages verwenden lässt und was Sie hierbei beachten sollten.
2.1.2 Lösung: variable Versionsnummern verwenden Wenn Sie bei der Installation von Packages mit npm install keine exakte Versionsnummer angeben, wird standardmäßig die aktuelle Version installiert (das ist jeweils die Version, die in der npm-Registry mit dem Tag »latest« versehen ist). $ npm install express $ cat package.json { "name": "dependencies-example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT", "dependencies": {
68
2.1
Rezept 8: Semantische Versionierung richtig einsetzen
"express": "^4.16.3" } } Listing 2.1 Installation mit variablen Versionsnummern
Die generierte Versionsnummer für die jeweilige Abhängigkeit in der package.jsonDatei hat dabei ein ^-Zeichen vorangestellt. In der semantischen Versionierung bedeutet dies, dass eine Abhängigkeit erfüllt ist, wenn sich die Patch-Version oder die Minor-Version ändern, nicht aber, wenn sich die Major-Version ändert. Ein Beispiel: Die Angabe »^4.16.3« bedeutet, dass sowohl die Version »4.16.4« (Änderung der Patch-Version) als auch die Version »4.17.0« (Änderung der Minor-Version) gültig wären, nicht aber die Version »5.0.0« (Änderung der Major-Version). Mit anderen Worten: Bei einer Angabe von »^4.16.3« würde npm bei der Installation der entsprechenden Abhängigkeit auch eine Version »4.16.4« oder eine Version »4.17.0« installieren (soweit verfügbar), nicht aber eine Version »5.0.0« (für weitere Informationen zu diesem Verhalten empfehle ich Ihnen die Websites unter https:// docs.npmjs.com/about-semantic-versioning und https://semver.npmjs.com/). Neben dem ^-Zeichen können Sie bei der Definition von semantischen Versionsnummern in der package.json-Datei auch das ~-Zeichen verwenden, und zwar, um Versionsnummern zu definieren, für die sich nur die Patch-Version ändern darf. Dazu auch ein Beispiel: Die Angabe »~4.16.3« würde bedeuten, dass die Version »4.16.4« gültig wäre, nicht aber die Version »4.17.0« und schon gar nicht die Version »5.0.0«. Prinzipiell eignet sich die Auszeichnung über das ^-Zeichen und das ~-Zeichen meiner Ansicht nach nur während der Entwicklung, sprich wenn man mit mehreren Entwicklern parallel an verschiedenen Packages und Abhängigkeiten arbeitet: Ändert sich dann während der Entwicklung eine Versionsnummer (was zu diesem Zeitpunkt ja häufig passieren kann), muss nicht jedes Mal die Versionsnummer in der package.json-Datei angepasst werden, damit man den aktuellen Stand bekommt.
Hinweis Während der parallelen Entwicklung an mehreren Packages, die sich gegenseitig als Abhängigkeit haben, bietet es sich zudem an, die Packages lokal miteinander zu verlinken (siehe Rezept 11) oder direkt als Mono-Repository zu strukturieren (siehe Rezept 7).
Im Produktiveinsatz rate ich Ihnen jedoch vom Gebrauch des ^-Zeichens und des ~-Zeichens ab, da sich hierdurch schwer zu findende Fehler einschleichen können. Das Problem ist nämlich, dass in der Praxis nicht sichergestellt ist, dass sich wirklich
69
2
Package Management
alle Entwickler von Packages an die Regeln der semantischen Versionierung halten. So kommt es durchaus vor, dass sich die API eines Packages ändert, vom Entwickler aber nur die Minor- oder Patch-Version erhöht wird. Wenn Sie dann ein Update machen, können innerhalb Ihrer Anwendung Fehler auftreten, die nicht immer auf den ersten Blick erkannt werden können.
2.1.3 Lösung: exakte Versionsnummern verwenden Um das vorgenannte Problem zu umgehen, rate ich Ihnen, ausschließlich exakte Versionen für die Abhängigkeiten Ihres Packages verwenden. Hierzu haben Sie zwei Möglichkeiten: Zum einen können Sie bei der Installation eines Packages den Parameter --save-exact bzw. dessen Shortcut -E verwenden. Durch diesen zusätzlichen Parameter wird die Abhängigkeit unter Angabe der exakten aktuellen Versionsnummer in die package.json-Datei geschrieben: $ npm install express -E $ cat package.json { "name": "dependencies-example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT", "dependencies": { "express": "4.16.3" } } Listing 2.2 Installation mit exakten Versionsnummern
Alternativ dazu können Sie in der Konfigurationsdatei .npmrc die Eigenschaft saveexact auf true setzen. Dadurch werden im Folgenden bei allen Aufrufen von npm install exakte Versionsnummern verwendet. $ echo -e "save-exact = true" > .npmrc $ npm install express $ cat package.json {
70
2.1
Rezept 8: Semantische Versionierung richtig einsetzen
"name": "dependencies-example", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT", "dependencies": { "express": "4.16.3" } } Listing 2.3 Installation mit exakten Versionsnummern über Konfigurationsdatei
2.1.4 Die Datei package-lock.json Im vorherigen Abschnitt haben Sie gesehen, wie Sie bei der Installation von direkten Abhängigkeiten exakte Versionsnummern verwenden können und warum dies wichtig ist. Allerdings haben Sie dadurch das Problem der variablen semantischen Versionsnummern nur halb gelöst. Denn was dadurch noch nicht sichergestellt ist, ist, dass direkte Abhängigkeiten ihrerseits in ihrer package.json-Dateien Abhängigkeiten mit exakten Versionsnummern definieren. Direkte Abhängigkeiten Ihres Packages können also durchaus bei der Definition der (für Ihr Package indirekten) Abhängigkeiten variable Versionsnummern verwenden. Ein npm install vor einer Woche könnte sich dann prinzipiell von einem npm install heute unterscheiden, und zwar, wenn sich die indirekten Abhängigkeiten zwischenzeitlich geändert haben. Aus diesen Gründen generiert npm seit Version 5 standardmäßig beim Ausführen von npm install eine Datei mit dem Namen package-lock.json, die alle Abhängigkeiten mit ihren exakten Versionsnummern (inklusive der Abhängigkeiten von Abhängigkeiten) enthält und damit den exakten Stand des Packages zu einem bestimmten Zeitpunkt repräsentiert. Wenn Sie innerhalb eines Packages, das die Datei packagelock.json enthält, den Befehl npm install aufrufen, werden exakt die Versionen der Abhängigkeiten installiert, die in dieser Datei enthalten sind. $ cat package-lock.json { "name": "dependencies-example", "version": "1.0.0", "lockfileVersion": 1,
71
2
Package Management
"requires": true, "dependencies": { ... "express": { "version": "4.16.3", "resolved": "https://registry.npmjs.org/express/-/express-4.16.3.tgz", "integrity": "sha1-avilAjUNsyRuzEvs9rWjTSL37VM=", "requires": { "accepts": "1.3.5", "array-flatten": "1.1.1", "body-parser": "1.18.2", "content-disposition": "0.5.2", "content-type": "1.0.4", "cookie": "0.3.1", "cookie-signature": "1.0.6", "debug": "2.6.9", "depd": "1.1.2", "encodeurl": "1.0.2", ... } }, ... } } Listing 2.4 Aufbau der Datei »package-lock.json« (Ausschnitt)
Hinweis Damit alle Entwickler im Team mit der exakt gleichen Version arbeiten, sollten Sie die Datei package-lock.json in das verwendete Versionsverwaltungssystem hochladen.
2.1.5 Die Datei npm-shrinkwrap.json Die älteren Versionen von npm (< 5) generieren bei einem npm install keine Datei package-lock.json. Um den exakten Stand eines Packages bzw. seiner Abhängigkeiten zu erhalten, musste man sich des Befehls npm shrinkwrap bedienen (https://docs.npmjs.com/cli/shrinkwrap). Dieser Befehl generiert eine Datei npm-shrinkwrap.json, die exakt den gleichen Inhalt hat wie die Datei package-lock.json. Wie man in der folgenden Ausgabe des Programms sieht, wird eine vorhandene package-lock.json automatisch in npm-shrinkwrap.json umbenannt.
72
2.2
Rezept 9: Den alternativen Package Manager »Yarn« verwenden
$ npm shrinkwrap npm notice package-lock.json has been renamed to npm-shrinkwrap.json. npm-shrinkwrap.json will be used for future installations.
Doch auch wenn beide Dateien den gleichen Inhalt haben, gibt es einige Unterschiede, wie npm die Dateien behandelt: 왘 Die Datei package-lock.json wird beim Publishing eines Packages nicht hochgela-
den, npm-shrinkwrap.json dagegen schon. 왘 package-lock.json-Dateien von Abhängigkeiten werden ignoriert, npm-shrink-
wrap.json-Dateien von Abhängigkeiten dagegen nicht. 왘 npm-shrinkwrap.json-Dateien sind abwärtskompatibel, d. h., sie funktionieren
auch mit älteren npm-Versionen, package-lock.json-Dateien dagegen erst seit npm 5
2.1.6 Ausblick Sie wissen jetzt, wie Sie Packages in Node.js mithilfe der semantischen Versionierung richtig versionieren und was es dabei zu beachten gilt. Besonders wichtig ist Folgendes: Auch wenn ein Package, das Sie als Abhängigkeit einbinden, die semantische Versionierung verwendet, ist dies noch keine Garantie dafür, dass sich die Entwickler des jeweiligen Packages auch wirklich an die Regeln der semantischen Versionierung halten. Es kann immer sein, dass ein Package bspw. ein API Change einführt, aber lediglich die Minor-Version hochzählt o. Ä. In solchen Fällen sollten Sie die Entwickler auf dieses Missgeschick hinweisen, denn die semantische Versionierung ergibt nur Sinn, wenn sich alle an die entsprechenden Regeln halten.
2.2 Rezept 9: Den alternativen Package Manager »Yarn« verwenden Sie möchten statt npm den alternativen Package Manager Yarn verwenden.
2.2.1 Lösung Konkurrenz belebt das Geschäft. So auch bei den Package Managern, die es mittlerweile für Node.js gibt. Auch wenn standardmäßig npm derjenige Package Manager ist, der mit Node.js installiert wird, spricht nichts dagegen, auf einen anderen Package Manager zurückzugreifen. In diesem und dem nächsten Rezept stelle ich Ihnen dazu zwei Alternativen vor. Los geht es mit dem bekannteren Yarn, im anschließenden Rezept folgt dann die Beschreibung von pnpm, einer (noch) nicht so verbreiteten Alternative.
73
2
Package Management
2.2.2 Einführung und Vergleich zu npm Yarn (https://github.com/yarnpkg) wurde von Facebook entwickelt und ist vor allem aus der Tatsache heraus entstanden, dass npm lange Zeit keine Möglichkeit vorsah, eine exakte Beschreibung der verwendeten Abhängigkeiten anzugeben. So war es bei Verwendung von variablen semantischen Versionsnummern innerhalb der Konfigurationsdatei package.json nicht sichergestellt, dass npm install für eine Applikation beim Aufruf zum Zeitpunkt x die identischen Abhängigkeiten installierte wie beim Aufruf zum Zeitpunkt y, weil sich zwischen zwei Installationen natürlich immer die Versionsnummer von Abhängigkeiten oder von deren Abhängigkeiten ändern kann (siehe Rezept 8). Erst seit Version 5 generiert npm die Datei package-lock.json, die wirklich die exakten Versionsnummern für alle Abhängigkeiten (auch der indirekten) zum Zeitpunkt x festhält, sodass spätere Installationen auf Basis dieser LockDatei den exakt gleichen Stand haben. Die ursprüngliche Idee einer solchen Lock-Datei allerdings stammt von Yarn (dort heißt die entsprechende Lock-Datei yarn.lock). Und auch darüber hinaus wirbt Yarn mit einer Reihe weiterer Vorteile gegenüber npm, von denen die folgenden beiden die wichtigsten sind: 왘 Parallele Installation von Abhängigkeiten: Im Gegensatz zu npm, bei dem die Ab-
hängigkeiten sequenziell installiert werden, geschieht die Installation von Packages bei Yarn parallel, d. h., die Installation von Abhängigkeiten ist in der Regel schneller als bei der Installation mit npm. 왘 Zusätzliche Befehle: Yarn bietet eine Reihe nützlicher Befehle von Haus aus an,
bspw. zum Ermitteln von Lizenzen, für das Sie normalerweise auf Third-PartyTools angewiesen sind (siehe Rezept 13).
Facebook Da Yarn von Facebook entwickelt wird, ist es auch häufig in Projekten zu finden, die ebenfalls von Facebook stammen, bspw. React, GraphQL oder React Native.
2.2.3 Installation Yarn steht für alle gängigen Betriebssysteme zur Verfügung, für entsprechende Installationsbeschreibungen möchte ich Sie an dieser Stelle auf die offizielle Dokumentation unter https://yarnpkg.com/en/docs/install verweisen. Dort finden Sie bspw. Beschreibungen für die Installation unter macOS, Windows sowie für verschiedene Linux-Distributionen. Prinzipiell kann Yarn auch mithilfe von npm über npm install -g yarn installiert werden, allerdings wird von dieser Möglichkeit aus Sicherheitsgründen abgeraten.
74
2.2
Rezept 9: Den alternativen Package Manager »Yarn« verwenden
Wenn Sie Yarn nicht auf Ihrem Rechner installieren bzw. es vor der Installation erst einmal testen möchten, bietet sich die Verwendung eines Docker-Containers an (Docker lässt sich relativ einfach für alle Betriebssysteme installieren, Details dazu finden Sie auf der entsprechenden Website unter https://docs.docker.com/install/). Sowohl die häufig für Node.js verwendeten Docker-Images unter https://hub.docker. com/r/mhart/alpine-node/ als auch die offiziellen Docker-Images unter https://hub. docker.com/_/node/ haben mittlerweile sowohl npm als auch Yarn standardmäßig vorinstalliert. Um bspw. einen Docker-Container auf Basis des offiziellen Node.jsDocker-Images zu erzeugen und sich direkt mit der Kommandozeile innerhalb des Containers zu verbinden, verwenden Sie folgenden Befehl: $ docker run -it node /bin/bash
2.2.4 Verwendung Nach erfolgreicher Installation (bzw. Starten des Docker-Containers) steht Ihnen global der Befehl yarn zur Verfügung, über den Sie den Package Manager verwenden können. Ähnlich wie bei npm können Sie bspw. den Befehl yarn init dazu verwenden, ein neues Node.js-Package zu erzeugen. Anschließend startet ein gegenüber npm leicht abgewandelter Wizard, mit dessen Hilfe Sie allgemeine Informationen zum Package wie z. B. den Namen, eine Beschreibung, die Versionsnummer, Angaben zum Autor und der Lizenz definieren können: $ mkdir app $ cd app/ $ yarn init yarn init v1.9.4 question name (app): question version (1.0.0): question description: question entry point (index.js): question repository url: question author: Philip Ackermann question license (MIT): question private: success Saved package.json Done in 9.98s Listing 2.5 Generierung eines Packages mit Yarn
Prinzipiell stellt Yarn die gleichen Befehle wie npm zur Verfügung, auch wenn sie sich vom Namen her teilweise unterscheiden (siehe Tabelle 2.1 für einen direkten Vergleich der Befehle zwischen npm und Yarn). So geschieht die Installation von Abhän-
75
2
Package Management
gigkeiten nicht wie bei npm über den Unterbefehl install, sondern über den Unterbefehl add. Um bspw. »express« als Abhängigkeit zu installieren, verwenden Sie folgenden Befehl, der im Übrigen gegenüber der Installation mit npm auch eine deutlich umfangreichere Ausgabe erzeugt: $ yarn add express yarn add v1.9.4 info No lockfile found. [1/4] Resolving packages... [2/4] Fetching packages... [3/4] Linking dependencies... [4/4] Building fresh packages... success Saved lockfile. success Saved 27 new dependencies. info Direct dependencies └─ [email protected] info All dependencies ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected] ├─ [email protected]
76
2.2
Rezept 9: Den alternativen Package Manager »Yarn« verwenden
├─ [email protected] └─ [email protected] Done in 2.60s. Listing 2.6 Hinzufügen einer Abhängigkeit mit Yarn
npm-Befehl
yarn-Befehl
npm install react --save
yarn add react
npm uninstall react --save
yarn remove react
npm install jest --save-dev
yarn add jest --dev
npm update --save
yarn upgrade
npm install react --global
yarn global add react
npm init
yarn init
npm link
yarn link
npm outdated
yarn outdated
npm publish
yarn publish
npm run
yarn run
npm cache clean
yarn cache clean
npm login
yarn login
npm logout
yarn logout
npm test
yarn test
Tabelle 2.1 Analoge npm-Befehle in Yarn
2.2.5 Lock-Datei Jedes Mal, wenn Sie über yarn add eine neue Abhängigkeit installieren oder innerhalb eines existierenden Projekts den Befehl yarn ausführen, generiert Yarn eine Datei yarn.lock, die – genau wie die Datei package-lock.json – einen exakten Stand aller Abhängigkeiten enthält und die Sie ebenfalls in Ihr Versionsverwaltungssystem einchecken sollten. Wenn andere Entwickler sich dann Ihr Package herunterladen, ist dadurch sichergestellt, dass alle mit den gleichen Versionen der Abhängigkeiten arbeiten. Seit Yarn 1.7.0 ist es zudem möglich, eine bestehende Datei package-lock.json bzw. den dort enthaltenen Zustand der Abhängigkeiten über yarn import zu importieren.
77
2
Package Management
Prinzipiell ist es ohnehin relativ einfach, von npm zu Yarn zu wechseln, zumal beide das Format der package.json-Konfigurationsdatei nutzen und standardmäßig auf die offizielle npm-Registry zugreifen.
2.2.6 Ausblick Yarn ist eine ausgereifte Alternative zu npm, die immer wieder neue, produktive Ideen entwickelt, um das Package Management noch einfacher zu machen. Einige dieser Ideen (wie bspw. das Konzept der Lock-Datei) hat npm mittlerweile übernommen. Die Entscheidung, ob man Yarn oder npm für das Package Management einsetzt, ist letztendlich auch eine Frage des persönlichen Geschmacks und in welchem Projekt und mit welchem Team man arbeitet. Im nächsten Rezept stelle ich Ihnen einen weiteren Package Manager vor, der noch ein bisschen anders arbeitet als Yarn und npm.
Verwandte Rezepte 왘 Rezept 10: Den alternativen Package Manager »pnpm« verwenden
2.3 Rezept 10: Den alternativen Package Manager »pnpm« verwenden Sie möchten statt npm den alternativen Package Manager pnpm verwenden.
2.3.1 Lösung Eine weitere, jüngere Alternative zu npm und dem im vorherigen Rezept vorgestellten Yarn ist der Package Manager pnpm (https://pnpm.js.org/), der laut eigenen Angaben bis zu dreimal so schnell arbeitet wie npm.
2.3.2 Einführung und Vergleich zu npm Das Vorgehen von pnpm unterscheidet sich dabei in zwei Punkten grundsätzlich sowohl von npm als auch von Yarn. Während die letzteren beiden die Abhängigkeiten innerhalb des jeweiligen Packages speichern, speichert pnpm die Abhängigkeiten immer global. Und während npm (seit Version 3) und Yarn die Abhängigkeiten in einer flachen Hierarchie speichern, verwaltet pnpm die Abhängigkeiten hierarchisch. Um die Bedeutung dessen im Detail zu verstehen, muss man sich zunächst in Erinnerung rufen, wie npm die Abhängigkeiten vor der Version 3 speicherte. Damals hatte
78
2.3
Rezept 10: Den alternativen Package Manager »pnpm« verwenden
jede Abhängigkeit eines Packages ihrerseits ein node_modules-Verzeichnis, in dem die Abhängigkeiten der jeweiligen Abhängigkeit gespeichert waren, von denen wiederum jede ihrerseits ein node_modules-Verzeichnis hatte, usw.: node_modules └─ foo ├─ index.js ├─ package.json └─ node_modules └─ bar ├─ index.js └─ package.json
Wie sich herausstellte, hatte dieser Ansatz allerdings zwei Probleme: Zum einen führte dies schnell zu einer sehr tiefen Verzeichnisstruktur, was wiederum zu sehr langen Pfadangaben und zu Problemen unter Windows führte. Zum anderen wurde auf diese Weise innerhalb eines Projekts ein und dasselbe Package häufig mehrfach gespeichert, nämlich immer dann, wenn es als Abhängigkeit von mehreren anderen Packages referenziert wurde. Aus diesen beiden Gründen speichert npm seit Version 3 die Abhängigkeiten in einer flachen Hierarchie: node_modules ├─ foo │ ├─ index.js │ └─ package.json └─ bar ├─ index.js └─ package.json
pnpm löst die genannten Probleme auf eine andere Weise: Und zwar verwendet es dazu keine flache Anordnung der Abhängigkeiten, sondern eine hierarchische Anordnung unter Verwendung von Links, die jeweils auf die globale Installation des jeweiligen Packages zeigen: node_modules ├─ foo -> .registry.npmjs.org/foo/1.0.0/node_modules/foo └─ .registry.npmjs.org ├─ foo/1.0.0/node_modules │ ├─ bar -> ../../bar/2.0.0/node_modules/bar │ └─ foo │ ├─ index.js │ └─ package.json └─ bar/2.0.0/node_modules
79
2
Package Management
└─ bar ├─ index.js └─ package.json
Der Vorteil dieses Ansatzes: Jedes Package, das als Abhängigkeit verwendet wird, muss nur einmal (global) gespeichert werden und nicht für jedes Projekt, welches das Package einbindet. Daraus ergibt sich eine enorme Einsparung von Speicherplatz. Darüber hinaus ist auch die Installation im Einzelfall schneller, weil bereits global vorhandene Packages (die bereits durch andere Projekte installiert wurden) einfach nur verlinkt, aber nicht bei jeder Installation neu heruntergeladen werden müssen. Links werden zudem nur für die direkten Abhängigkeiten eines Packages erstellt. Das ist zum einen sehr viel übersichtlicher, weil dann im node_modules-Verzeichnis des jeweiligen Packages auch nur die direkten Abhängigkeiten auftauchen und nicht wie bei npm oder Yarn auch die Abhängigkeiten der Abhängigkeiten (ein Beispiel dazu folgt in wenigen Momenten). Zum anderen läuft man so aber auch nicht Gefahr, versehentlich eine indirekte Abhängigkeit direkt in seinem Package zu verwenden, ohne diese Abhängigkeit als direkte Abhängigkeit zu definieren.
Hinweis Exakte Informationen zu den Abhängigkeiten speichert pnpm pro Package in der Datei shrinkwrap.yaml, die damit die Aufgabe der Datei package-lock.json (und npmshrinkwrap.json, siehe Rezept 8) von npm bzw. der Datei yarn.lock von Yarn übernimmt (Rezept 9).
2.3.3 Installation pnpm kann entweder über ein Installationsskript oder über npm installiert werden. Möchten Sie das Installationsskript nutzen, verwenden Sie dazu folgenden Befehl: $ curl -L https://unpkg.com/@pnpm/self-installer | node
Für die Installation über npm verwenden Sie dagegen folgenden Befehl: $ npm install -g pnpm
Weiterführende Informationen zu Installationen finden Sie unter https://pnpm.js. org/docs/en/installation.html. Wie schon für Yarn gilt auch für pnpm: Wenn Sie diesen Package Manager zunächst einmal in einer unabhängigen Umgebung testen möchten, bietet sich auch hier die Verwendung eines Docker-Containers an. Zwar gibt es zum Zeitpunkt der Drucklegung dieses Buches noch kein offizielles Docker Image für pnpm, allerdings ist es
80
2.3
Rezept 10: Den alternativen Package Manager »pnpm« verwenden
relativ einfach, ein solches selbst zu erzeugen (ein installiertes Docker vorausgesetzt). Speichern Sie dazu einfach folgenden Code in einer Datei Dockerfile: FROM node:latest RUN curl -L https://unpkg.com/@pnpm/self-installer | node
Rufen Sie jetzt folgenden Befehl auf, um auf Basis dieser Dockerfile-Datei ein Docker Image mit dem Namen pnpm zu erzeugen (im Detail werden wir uns des Themas Docker noch in Kapitel 13, »Publishing, Deployment und Microservices«, annehmen. Dort zeige ich Ihnen auch, wie Sie eine Node.js-Applikation in Form eines DockerImages deployen können): $ docker build -t pnpm .
Anschließend starten Sie mit folgendem Befehl wie schon im vorherigen Rezept einen Docker-Container, dieses Mal aber auf Basis des gerade manuell erzeugten Docker-Images: $ docker run -it pnpm /bin/bash
Innerhalb des Containers steht Ihnen nun neben Node.js auch pnpm zur Verfügung: $ node -v v10.11.0 $ pnpm -v 2.16.2
2.3.4 Verwendung Die Verwendung von pnpm hat Ähnlichkeit mit der Verwendung von npm. Die meisten Befehle haben dabei sogar den gleichen Namen, sodass man sich nicht wie bei Yarn an neue Befehle gewöhnen muss. Um ein neues Package zu generieren, verwenden Sie bspw. den Befehl pnpm init, wodurch genau wie bei npm init ein entsprechender Wizard gestartet wird, über den Sie Informationen wie den Namen, die Version und eine Beschreibung des Packages sowie Angaben zu Package-Autor und Versionsnummer definieren können: $ mkdir app $ cd app/ $ pnpm init This utility will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults. See `npm help json` for definitive documentation on these fields and exactly what they do. Use `npm install ` afterwards to install a package and save it as a dependency in the package.json file.
81
2
Package Management
Press ^C at any time to quit. package name: (app) version: (1.0.0) description: entry point: (index.js) test command: git repository: keywords: javascript author: Philip Ackermann license: (ISC) About to write to /app/package.json: { "name": "app", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [ "javascript" ], "author": "Philip Ackermann", "license": "ISC" } Is this OK? (yes) Listing 2.7 Generierung eines Packages mit pnpm
Einen Überblick über die in pnpm zur Verfügung stehenden Befehle und die analogen Befehle in npm finden Sie in Tabelle 2.2. Die Installation von Abhängigkeiten bspw. erfolgt wie auch bei npm über den Unterbefehl install: $ pnpm install express Packages: +51 +++++++++++++++++++++++++++++++++++++++++++++++++++ Resolving: total 51, reused 0, downloaded 51, done dependencies: + express 4.16.3 Listing 2.8 Hinzufügen einer Abhängigkeit mit pnpm
82
2.3
Rezept 10: Den alternativen Package Manager »pnpm« verwenden
Wenn Sie sich nach der Installation des Packages den Inhalt des Verzeichnisses ausgeben lassen, werden Sie übrigens – wie zu Beginn gesagt – feststellen, dass wirklich auch nur »express« als Abhängigkeit aufgelistet ist und das Verzeichnis dementsprechend sehr aufgeräumt wirkt: $ ls node_modules/ express
Zum Vergleich: Wenn Sie das Gleiche über npm oder Yarn machen, enthält der node_ modules-Ordner auch die Abhängigkeiten der Abhängigkeiten: $ cd .. $ mkdir app2 $ cd app2/ $ npm init -y $ npm install express $ ls node_modules/ accepts content-disposition debug encodeurl finalhandler iconv-lite ...
npm-Befehl
pnpm-Befehl
npm install react --save
pnpm install react
npm uninstall react --save
pnpm uninstall react
npm install jest --save-dev
pnpm install jest --save-dev
npm update --save
pnpm update
npm install react --global
pnpm install react --global
npm init
pnpm init
npm link
pnpm link
npm outdated
pnpm outdated
npm publish
pnpm publish
npm run
pnpm run
Tabelle 2.2 Analoge npm-Befehle in pnpm
83
2
Package Management
npm-Befehl
pnpm-Befehl
npm login
pnpm login
npm logout
pnpm logout
npm test
pnpm test
Tabelle 2.2 Analoge npm-Befehle in pnpm (Forts.)
Neben den in Tabelle 2.2 gezeigten Befehlen stellt pnpm noch einige weitere nützliche Befehle zur Verfügung. Beispielsweise können Sie über pnpm import auf Basis einer package-lock.json- oder einer npm-shrinkwrap.json-Datei eine entsprechende shrinkwrap.yaml-Datei generieren. Über pnpm recursive können Sie zudem verschiedene Unterbefehle wie install, update oder outdated rekursiv auf mehrere Packages anwenden (sehr praktisch!). Letzterer Befehl ermittelt übrigens die veralteten Abhängigkeiten von einem Package (wie das mit npm funktioniert, zeige ich Ihnen in Rezept 13).
2.3.5 Ausblick Sie kennen jetzt mit npm, Yarn und pnpm die wichtigsten und relevantesten Package Manager für Node.js und wissen, worin sie sich unterscheiden. Es gibt zwar noch einige andere Package Manager, die aber nicht wirklich relevant geworden sind bzw. keine große Verbreitung gefunden haben. Ein Projekt, das man aber im Auge behalten sollte, ist tink (https://www.npmjs.com/package/tink), das vom npm-Team entwickelt wird, sich derzeit aber noch in einem sehr experimentellen Status befindet und noch nicht für den Produktiveinsatz verwendet werden sollte.
Verwandte Rezepte 왘 Rezept 9: Den alternativen Package Manager »Yarn« verwenden
2.4 Rezept 11: Lokale Abhängigkeiten für die Entwicklung verlinken Sie möchten Packages lokal miteinander verlinken, um Änderungen an lokalen Abhängigkeiten direkt mitzubekommen und so die parallele Entwicklung an mehreren Packages zu beschleunigen.
84
2.4
Rezept 11: Lokale Abhängigkeiten für die Entwicklung verlinken
2.4.1 Lösung Wenn Sie den allgemeinen Best Practices für Node.js folgen, möglichst kleine Packages mit dedizierten Aufgaben zu erstellen (siehe Abschnitt 1.3.4, »Best Practices für Node.js-Packages«, in Rezept 3), werden Sie bereits innerhalb kürzester Zeit eine ansehnliche Anzahl von Packages in Ihrem Workspace wiederfinden. Wenn Sie dabei gleichzeitig an mehreren Packages arbeiten und einige dieser Packages Abhängigkeiten von anderen dieser Packages sind, ist es am einfachsten, die entsprechenden Packages miteinander zu verlinken. Auf diese Weise werden Änderungen in einem Package direkt für die anderen Packages sichtbar, ohne dass Sie umständlich erst die Änderungen in die npm-Registry oder das entsprechende Git-Repository hochladen und dann im anderen Package wieder über ein npm install herunterladen müssen. Im Folgenden zeige ich Ihnen anhand eines einfachen Beispiels, wie Sie Packages lokal miteinander verlinken. Erstellen Sie dazu zwei Beispiel-Packages mit folgenden Konfigurationen. Zunächst die Konfiguration für das Package, das als Abhängigkeit verwendet werden soll: { "name": "my-first-package", "version": "1.0.0", "description": "", "main": "index.js", "scripts": {}, "keywords": [], "author": "Philip Ackermann ", "license": "MIT" } Listing 2.9 Konfigurationsdatei für my-first-package
Anschließend die Konfigurationsdatei für das Package, welches das erste Package als Abhängigkeit einbindet: { "name": "my-second-package", "version": "1.0.0", "description": "", "main": "index.js", "scripts": {}, "keywords": [], "dependencies": { "my-first-package": "1.0.0"
85
2
Package Management
}, "author": "Philip Ackermann ", "license": "MIT" } Listing 2.10 Konfigurationsdatei für my-second-package
Legen Sie zusätzlich im ersten Package folgende index.js-Datei an: // my-first-package/index.js module.exports = { sayHello() { return 'Hello'; } }
Und ergänzen Sie im zweiten Package folgende Datei start.js, in die das erste Package eingebunden wird: // my-second-package/start.js const myFirstPackage = require('my-first-package'); console.log(myFirstPackage.sayHello());
Um Packages miteinander zu verlinken, stellt npm den Befehl npm link zur Verfügung, wobei das Erstellen einer Verlinkung in zwei Schritten erfolgt. In unserem Beispiel hat das Package my-second-package das Package my-first-package als Abhängigkeit. Daher wechseln Sie als Erstes in das Verzeichnis my-first-package und führen dort folgenden Befehl aus: $ npm link
Durch diesen Befehl erstellt npm einen symbolischen Link von dem globalen Package-Verzeichnis (bei mir z. B. usr/local/lib/node_modules/my-first-package) auf das aktuelle Verzeichnis (also auf das Verzeichnis my-first-package). Die Ausgabe des Befehls bestätigt dies: up to date in 0.079s /usr/local/lib/node_modules/my-first-package -> /Users/philipackermann/ workspace/nodejskochbuch/linking/my-first-package
Im zweiten Schritt wechseln Sie in das Verzeichnis my-second-package und führen dort folgenden Befehl aus: $ npm link my-first-package
Dies wiederum erstellt einen symbolischen Link von dem node_modules-Verzeichnis im aktuellen Projekt auf den symbolischen Link von eben:
86
2.4
Rezept 11: Lokale Abhängigkeiten für die Entwicklung verlinken
/Users/philipackermann/workspace/nodejskochbuch/linking/my-second-package/ node_modules/my-first-package -> /usr/local/lib/node_modules/my-firstpackage -> /Users/philipackermann/workspace/nodejskochbuch/linking/my-firstpackage
Wenn Sie nun das Start-Script aus dem zweiten Package aufrufen, dann sollte auf der Konsole die Meldung »Hello« erscheinen: $ node my-second-package/start.js Hello
Ändern Sie jetzt die Implementierung der Methode sayHello() im ersten Package, und geben Sie statt »Hello« den Wert »Hello World« zurück. Wenn Sie anschließend erneut das Start-Script aufrufen, sollte jetzt direkt die aktualisierte Ausgabe erscheinen: $ node my-second-package/start.js Hello World
Sie sehen also: Änderungen an abhängigen Packages sind durch die Verlinkung direkt für andere Packages sichtbar. Effektiver ist das Arbeiten an mehreren Packages nur, wenn Sie diese in Mono-Repositorys organisieren (siehe Rezept 7).
2.4.2 Alternativen Prinzipiell gibt es auch noch zwei andere Möglichkeiten, Packages lokal miteinander zu verknüpfen, von denen ich Ihnen aber abrate (zu dem Warum gleich mehr). Aus Gründen der Vollständigkeit seien die beiden Möglichkeiten dennoch kurz erwähnt. Die erste Möglichkeit besteht darin, eine Abhängigkeit über npm install unter Angabe des relativen Pfades zu der Abhängigkeit zu installieren: $ npm install ../my-first-package ... + [email protected] updated 1 package in 0.642s
Dadurch wird in der package.json-Datei das entsprechende Package als relative Pfadangabe referenziert: $ cat package.json { "name": "my-second-package", "version": "1.0.0", "description": "", "main": "index.js", "scripts": {},
87
2
Package Management
"keywords": [], "dependencies": { "my-first-package": "file:../my-first-package" }, "author": "Philip Ackermann ", "license": "MIT" }
Die zweite Lösung besteht darin, ein verwendetes Package innerhalb Ihres Packages nicht über den Namen, sondern über den relativen Pfad einzubinden: const otherPackage = require('../my-first-package');
Der Nachteil beider Lösungen dürfte klar sein: Der Code funktioniert nur dann, wenn das eingebundene Package auf dem jeweiligen Rechner oder Server auch in dem angegebenen Verzeichnis liegt. Das widerspricht aber in gewisser Weise dem modularen Gedanken von Node.js, und spätestens beim Deployment werden Sie hierbei Probleme bekommen. Es sei denn, Sie verwenden Mono-Repositorys, bei denen diese Vorgehensweise aufgrund der Struktur der Packages erlaubt ist. Ansonsten gilt: Vergessen Sie die beiden Lösungen ganz schnell wieder, und verwenden Sie stattdessen npm link, um Packages lokal zu verknüpfen.
Verwandte Rezepte 왘 Rezept 7: Packages in Mono-Repositorys organisieren
2.5 Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen Sie möchten Informationen über Packages abrufen, bspw. hinsichtlich der Lizenzen, der Popularität, der aktiven Entwickler o. Ä.
2.5.1 Lösung: allgemeine Informationen für ein Package ermitteln Bevor Sie ein Package das erste Mal als Abhängigkeit verwenden, sollten Sie sich die Mühe machen, ein paar generelle Informationen zu dem Package einzuholen. Hierzu zählen Angaben zur Popularität, den Entwicklern hinter dem Package, Lizenzinformationen und einiges mehr. In diesem Rezept zeige ich Ihnen einige Möglichkeiten, diese Informationen zu ermitteln. Allgemeine Informationen können Sie über die npm-Registry unter https://www. npmjs.com abrufen. Da die meisten Packages zudem über ein entsprechendes (öffentliches) Git-Repository verwaltet werden, finden Sie entsprechende Informatio-
88
2.5
Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen
nen auch auf den jeweiligen Projektseiten. Darüber hinaus stellt npm von Haus aus den Befehl npm view zur Verfügung, über den Sie bestimmte Informationen zu einem Package direkt über die Kommandozeile einholen können (https://docs.npmjs.com/ cli/view). Um bspw. die Informationen für das Package »express« zu ermitteln, verwenden Sie den Befehl wie folgt: $ npm view express
Anschließend erhalten Sie einen Kurzbericht mit verschiedenen Informationen über das Package (Listing 2.11). Dazu zählen: 왘 die aktuelle Version des Packages 왘 die Lizenz des Packages 왘 die Abhängigkeiten des Packages 왘 die Anzahl der Versionen 왘 eine Kurzbeschreibung 왘 Kategorien bzw. Schlüsselwörter 왘 Angaben zur Art der Distribution 왘 die Maintainer des Packages 왘 der Zeitpunkt der zuletzt veröffentlichten Version [email protected] | MIT | deps: 30 | versions: 259 Fast, unopinionated, minimalist web framework http://expressjs.com/ keywords: express, framework, sinatra, web, rest, restful, router, app, api dist .tarball https://registry.npmjs.org/express/-/express-4.16.3.tgz .shasum: 6af8a502350db3246ecc4becf6b5a34d22f7ed53 .unpackedSize: 205.6 kB dependencies: accepts: ~1.3.5 cookie: 0.3.1 finalhandler: 1.1.1 path-to-regexp: 0.1.7 array-flatten: 1.1.1 debug: 2.6.9 fresh: 0.5.2 proxy-addr: ~2.0.3 body-parser: 1.18.2 depd: ~1.1.2 merge-descriptors: 1.0.1
89
2
Package Management
qs: 6.5.1 content-disposition: 0.5.2 encodeurl: 1.0.2 methods: 1.1.2 range-parser: ~1.2.0 content-type: 1.0.4 escape-html: 1.0.3 on-finished: ~2.3.0 safe-buffer: 5.1.1 cookie-signature: 1.0.6 etag: 1.8.1 parseurl: 1.3.2 send: 0.16.2 (...and 6 more.) maintainers: - dougwilson - hacksparrow - jasnell - mikeal dist-tags: latest: 4.16.3 published 5 months ago by dougwilson Listing 2.11 Ausgabe von npm view
Um gezielt auf einzelne Informationen aus dieser Auflistung zuzugreifen, stehen Ihnen darüber hinaus verschiedene Unterbefehle zur Verfügung, bspw.: $ npm view express license MIT $ npm view express version 4.16.3
Möchten Sie die Informationen automatisch verarbeiten (bspw. im Rahmen eines Build-Prozesses, um gegebenenfalls eine Warnung bei Lizenzen zu generieren, die nicht verwendet werden sollen), verwenden Sie am besten den Parameter --json, wodurch Sie die Informationen zum Package im JSON-Format erhalten.
2.5.2 Lösung: Downloadstatistik eines Packages ermitteln Von der Popularität eines Packages lassen sich in den meisten Fällen auch Rückschlüsse auf die Qualität des Packages ziehen: Bei Packages, die häufig verwendet werden, ist die Wahrscheinlichkeit höher, dass Bugs schneller gefunden und auch schneller behoben werden als bei Packages, die weniger häufig verwendet werden.
90
2.5
Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen
Manuell können Sie die Downloadstatistik eines Packages über die Weboberfläche der offiziellen npm-Registry (https://www.npmjs.com) ermitteln (Abbildung 2.1). Eine alternative Weboberfläche finden Sie unter https://npm-stat.com (Abbildung 2.2).
Abbildung 2.1 In der npm-Registry finden Sie nützliche Informationen zu Packages.
Abbildung 2.2 npm-stat.com stellt detaillierte Informationen zu Downloadstatistiken für Packages zur Verfügung.
91
2
Package Management
2.5.3 Lösung: den Abhängigkeitsbaum eines Packages ermitteln Um einen allgemeinen Überblick über Ihre bereits verwendeten Abhängigkeiten in Form eines vollständigen Abhängigkeitsbaums zu ermitteln, bietet npm den Befehl npm ls an. Über diesen Abhängigkeitsbaum können Sie zum einen relativ einfach herausfinden, welche indirekten Abhängigkeiten Sie in Ihrem Package eingebunden haben, zum anderen sehen Sie auch, über welchen Abhängigkeitspfad eine Abhängigkeit eingebunden ist. Schauen Sie sich das anhand eines Beispiels an. Erstellen Sie zunächst ein einfaches Beispiel-Package, und installieren Sie eine Laufzeitabhängigkeit und eine Entwicklungsabhängigkeit: $ $ $ $ $
mkdir example cd example npm init -y npm install express npm install supertest --save-dev
Rufen Sie anschließend npm ls auf, und Sie erhalten den vollständigen Abhängigkeitsbaum inklusive der exakten Versionsnummern (im folgenden Listing 2.12 aus Platzgründen nicht komplett abgebildet). $ npm ls [email protected] /Users/philipackermann/workspace/nodejskochbuch/ example ├─┬ [email protected] │ ├─┬ [email protected] │ │ ├─┬ [email protected] │ │ │ └── [email protected] │ │ └── [email protected] │ ├── [email protected] │ ├─┬ [email protected] │ │ ├── [email protected] │ │ ├── [email protected] deduped │ │ ├── [email protected] deduped │ │ ├── [email protected] deduped │ │ ├─┬ [email protected] │ │ │ ├── [email protected] deduped │ │ │ ├── [email protected] │ │ │ ├── [email protected] deduped │ │ │ └── [email protected] deduped
92
2.5
Rezept 12: Informationen zu verwendeten Abhängigkeiten abrufen
│ │ ├── [email protected] │ ... └─┬ [email protected] ├── [email protected] deduped └─┬ [email protected] ├── [email protected] ├── [email protected] ├─┬ [email protected] │ └── [email protected] deduped ├── [email protected] ├─┬ ... Listing 2.12 Ausgabe des Abhängigkeitsbaums (Ausschnitt)
Über den Parameter --depth können Sie dabei auch die Tiefe definieren, bis zu welcher die Abhängigkeiten aufgelistet werden. Der Aufruf npm ls --depth 1 bspw. listet nur die direkten Abhängigkeiten der von Ihrem Package eingebundenen Packages auf, der Befehl npm ls --depth 2 die direkten Abhängigkeiten und deren direkte Abhängigkeiten usw. Möchten Sie lediglich die Runtime-Abhängigkeiten auflisten, verwenden Sie den Parameter --production bzw. dessen Shortcut --prod. Analog dazu lassen sich über --development bzw. --dev nur die Test-Abhängigkeiten auflisten.
Hinweis Bei dem Package »supertest« handelt es sich übrigens um ein Package für das Testen von REST-APIs bzw. allgemeiner zum Testen von HTTP-Schnittstellen. Im Detail schauen wir uns das Package noch in Rezept 77 an.
2.5.4 Ausblick In diesem Rezept haben Sie gesehen, wie Sie allgemeine Informationen zu Packages abrufen können. In den folgenden Rezepten werden wir uns damit beschäftigen, was zu beachten ist, wenn Sie Packages als Abhängigkeit ausgewählt haben, und welche Dinge Sie dann grundsätzlich und regelmäßig überprüfen sollten.
Verwandte Rezepte 왘 Rezept 77: Unit-Tests für REST-APIs implementieren
93
2
Package Management
2.6 Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln Sie möchten die Lizenzen aller verwendeten Abhängigkeiten ermitteln, inklusive der Lizenzen von indirekten Abhängigkeiten.
2.6.1 Lösung Bei der Fülle an Packages, die man in der Regel bei der Entwicklung einer Node.jsAnwendung verwendet, ist es unabdingbar, einen Überblick über die verwendeten Lizenzen zu haben. In Rezept 12 haben Sie bereits gesehen, wie Sie die Lizenz für ein einzelnes Package ermitteln können. Wenn Sie viele verschiedene Abhängigkeiten verwenden (inklusive indirekter Abhängigkeiten ist man schnell im dreistelligen Bereich), ist es natürlich wenig praktikabel, wenn Sie die Lizenzen für jedes Package einzeln ermitteln. Ein Tool, das Ihnen diesbezüglich einiges an Arbeit abnehmen kann, ist »licensechecker« (https://github.com/davglass/license-checker), das Sie über folgenden Befehl installieren: $ npm install -g license-checker
Anschließend steht Ihnen der gleichnamige Befehl license-checker zur Verfügung, der Ihnen für alle (direkten und indirekten) Abhängigkeiten Lizenzangaben ausgibt: $ license-checker ├─ [email protected] │ ├─ licenses: MIT │ ├─ repository: https://github.com/jshttp/accepts │ ├─ path: /Users/cleancoderocker/Documents/workspaces/nodejskochbuch/ example/node_modules/accepts │ └─ licenseFile: /Users/cleancoderocker/Documents/workspaces/nodejskochbuch/ example/node_modules/accepts/LICENSE ├─ [email protected] │ ├─ licenses: MIT │ ├─ repository: https://github.com/blakeembrey/array-flatten │ ├─ publisher: Blake Embrey │ ├─ email: [email protected] │ ├─ url: http://blakeembrey.me │ ├─ path: /Users/cleancoderocker/Documents/workspaces/nodejskochbuch/ example/node_modules/array-flatten │ └─ licenseFile: /Users/cleancoderocker/Documents/workspaces/nodejskochbuch/ example/node_modules/array-flatten/LICENSE Listing 2.13 Ausgabe von »license-checker« (Ausschnitt)
94
2.6
Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln
Hinweis Alternativ können Sie dieses Tool auch über npx ausführen. Dies gilt im Übrigen für alle Tools, die ich in diesem Buch verwende. Der Befehl wäre dann im konkreten Fall: $ npx license-checker
Um diese Informationen (bspw. für die automatische Weiterverarbeitung) im JSONFormat zu bekommen, können Sie einfach den Parameter --json anhängen. Wenn Sie lediglich an einer Übersicht über die verschiedenen verwendeten Lizenzen interessiert sind, verwenden Sie stattdessen den Parameter --summary: $ license-checker --summary ├─ MIT*: 15 ├─ MIT: 3 ├─ UNKNOWN: 2 ├─ Custom: https://secure.travis-ci.org/shtylman/node-cookie.png: 1 └─ ISC: 1
Darüber hinaus haben Sie über weitere Parameter verschiedene Möglichkeiten, das Ermitteln der Lizenzen zu beeinflussen: So können Sie über die Parameter --production und --development bestimmen, ob nur die Laufzeitabhängigkeiten oder nur die Entwicklungsabhängigkeiten überprüft werden sollen. Über den Parameter --exclude können Sie zusätzlich einzelne Packages ausschließen, die beim Ermitteln der Lizenzen nicht berücksichtigt werden sollen. Eine genaue Beschreibung weiterer Parameter finden Sie auf der Webseite des Tools unter https://www.npmjs.com/ package/license-checker.
Lizenzen Wenn Sie sich nicht sicher sind, welche Lizenzen für Sie infrage kommen, empfehle ich Ihnen die Website https://choosealicense.com/licenses/, die einen sehr schönen und verständlichen Überblick über die Bedeutungen und Unterschiede verschiedener Lizenzen gibt.
2.6.2 Alternativen Über das Tool »npm-consider« (https://github.com/delfrrr/npm-consider) können Sie sich Informationen zu den Lizenzen eines Packages (und dessen Abhängigkeiten) einholen, ohne das Package vorher zu installieren: $ npm install -g npm-consider $ npm-consider install --save express [email protected] (updated 5 months ago)
95
2
Package Management
Packages 51 Size 535 KB Licenses Permissive 51 ? What is next? Details # ... (siehe Screenshot)
Abbildung 2.3 Ausgabe von »npm-consider«
2.6.3 Ausblick Sie wissen jetzt, wie Sie die Lizenzen für alle Abhängigkeiten eines Packages ermitteln können. Im nächsten Rezept zeige ich Ihnen, wie Sie solche Abhängigkeiten ermitteln, die in der Konfigurationsdatei eines Packages fehlen oder von einem Package nicht (mehr) verwendet werden.
Verwandte Rezepte 왘 Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln 왘 Rezept 15: Veraltete Abhängigkeiten ermitteln
96
2.7
Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln
2.7 Rezept 14: Nicht verwendete oder fehlende Abhängigkeiten ermitteln Sie möchten diejenigen Abhängigkeiten ermitteln, die entweder nicht verwendet werden oder die verwendet werden, aber nicht als Abhängigkeit in der Konfigurationsdatei des jeweiligen Packages definiert sind.
2.7.1 Lösung Im Laufe der Entwicklung eines Node.js-Packages kann es schnell passieren, dass sich Abhängigkeiten in der package.json-Datei ansammeln, die in der endgültigen Version des Packages nicht mehr benötigt werden. Dies kann bspw. passieren, wenn Sie auf der Suche nach einem geeigneten Package mehrere Packages testweise installieren und sich letztendlich für nur eines davon entscheiden, oder auch dann, wenn Sie im Laufe der Entwicklung ein Package durch ein alternatives Package ersetzen und vergessen, das vorherige Package zu deinstallieren bzw. aus der package.json-Datei zu entfernen. Umgekehrt kann es natürlich auch vorkommen, dass Sie vergessen, Packages korrekt in der package.json-Datei zu definieren und das Package lediglich über require() innerhalb Ihres Packages importieren. Dies kann in der Praxis schnell übersehen werden, z. B. wenn das eingebundene Package eine indirekte Abhängigkeit und daher im node_modules-Verzeichnis vorhanden ist. Wird das Package im Laufe der Zeit als Abhängigkeit von der direkten Abhängigkeit entfernt, kommt es dann zu einem Fehler (der Package Manager pnpm beugt dem vor, indem er im node_modules-Verzeichnis nur die direkten Abhängigkeiten speichert, siehe Rezept 10). Aus diesen Gründen rate ich Ihnen dazu, Ihre Packages regelmäßig hinsichtlich nicht benötigter bzw. überflüssiger und fehlender Packages zu überprüfen. Ein Tool, das Ihnen hierbei helfen kann, ist npm-check (https://github.com/dylang/npm-check). Installieren können Sie npm-check über folgenden Befehl: $ npm install -g npm-check
Um das Tool in der Anwendung zu sehen, erstellen Sie sich zunächst ein BeispielPackage: $ mkdir example $ cd example $ npm init -y
Installieren Sie nun »express« als Abhängigkeit, ohne es innerhalb des Packages zu verwenden: $ npm install express
97
2
Package Management
Erzeugen Sie anschließend eine Datei start.js, in die Sie die Bibliothek »lodash« einbinden, ohne diese jedoch in Ihre package.json-Datei einzubinden: $ echo "const _ = require('lodash');" > start.js
Wenn Sie jetzt den Befehl npm-check aufrufen, werden zwei Probleme erkannt: zum einen, dass »express« zwar als Abhängigkeit definiert ist, aber nicht im Quelltext verwendet wird, zum anderen, dass »lodash« im Quelltext verwendet wird, aber nicht als Abhängigkeit definiert ist: $ npm-check express NOTUSED? Still using express? Depcheck did not find code similar to require('express') or import from 'express'. Check your code before removing as depcheck isn't able to foresee all ways dependencies can be used. Use --skip-unused to skip this check. To remove this package: npm uninstall --save express lodash MISSING! Not installed. PKG ERR! Not in the package.json. Found in: /start.js
2.7.2 Weitere Features Neben dem reinen Überprüfen von nicht verwendeten und veralteten Abhängigkeiten bietet npm-check auch die Möglichkeit, die entsprechenden Fehler direkt zu aktualisieren, indem Sie dem Befehl den Parameter --update (interaktives Update) oder den Parameter --update-all (automatisches, nicht interaktives Update) übergeben. Zudem haben Sie die Möglichkeit, die Überprüfung auf Laufzeitabhängigkeiten oder Entwicklungsabhängigkeiten zu begrenzen (Parameter --production bzw. --devonly). Ebenfalls praktisch: Der Parameter --save-exact sorgt dafür, dass für alle Abhängigkeiten die exakte Versionsnummer in der package.json-Datei aktualisiert wird (siehe auch Abschnitt 2.1.3 in Rezept 8).
2.7.3 Ausblick Sie wissen jetzt, wie Sie fehlende und nicht mehr verwendete Abhängigkeiten ermitteln. Im nächsten Rezept zeige ich Ihnen, wie Sie veraltete Abhängigkeiten ermitteln, also solche Abhängigkeiten, zu denen es Updates gibt und für die Sie in Ihrem Package noch eine veraltete Versionsnummer verwenden.
98
2.8
Rezept 15: Veraltete Abhängigkeiten ermitteln
2.8 Rezept 15: Veraltete Abhängigkeiten ermitteln Sie möchten ermitteln, welche Abhängigkeiten veraltet sind bzw. zu welchen Abhängigkeiten es Updates gibt.
2.8.1 Lösung Wenn es für eine Ihrer Abhängigkeiten ein Update gibt, sollten Sie dieses – sofern möglich – auch anwenden. Ob es ein Update gibt, können Sie entweder über die Homepage des jeweiligen Packages herausfinden oder über die offizielle npm-Registry. Darüber hinaus stellt Ihnen npm den Befehl npm outdated zur Verfügung, um direkt alle veralteten Abhängigkeiten eines Packages zu ermitteln. Um die Funktionsweise besser zu veranschaulichen, installieren Sie zunächst eine ältere Version von »express«. $ npm install [email protected]
Rufen Sie nun npm outdated auf, erhalten Sie als Ausgabe verschiedene Angaben zu der veralteten Abhängigkeit. Dies sind zum einen die aktuell installierte Version (im Beispiel die Version 3.2.6) sowie zum anderen die Version, die getreu der semantischen Versionierung ohne Kompatibilitätsprobleme installiert werden kann (im Beispiel 3.21.2), und des Weiteren die aktuellste zur Verfügung stehende Version (im Beispiel 4.16.3). $ npm outdated Package Current Wanted Latest Location express 3.2.6 3.21.2 4.16.3 example
Um nun die aktuellste Version zu installieren, die laut semantischer Versionierung keine Kompatibilitätsprobleme bereitet, verwenden Sie den Befehl npm update: $ npm update npm WARN deprecated [email protected]: connect 2.x series is deprecated npm WARN [email protected] No description npm WARN [email protected] No repository field. + [email protected] added 79 packages from 37 contributors, removed 5 packages, updated 16 packages and audited 213 packages in 7.207s found 21 vulnerabilities (11 low, 2 moderate, 8 high) run `npm audit fix` to fix them, or `npm audit` for details
Ein erneuter Aufruf von npm outdated zeigt nun, dass die Version entsprechend den Vorgaben der semantischen Versionierung aktualisiert wurde:
99
2
Package Management
$ npm outdated Package Current Wanted Latest Location express 3.21.2 3.21.2 4.16.3 example
2.8.2 Alternativen Alternativ zu npm outdated können Sie das Tool npm-check-updates (https://github.com/tjunnone/npm-check-updates) verwenden. Installieren können Sie das Tool wie folgt: $ npm install -g npm-check-updates $ npm install [email protected] $ ncu Using /Users/cleancoderocker/Documents/workspaces/digital-landscape/ nodejskochbuch/example/package.json ⸨░░░░░░░░░░░░░░░░░░⸩ : : express ^3.2.6 → ^4.16.3 Run ncu with -u to upgrade package.json
Über den Befehl ncu -u können Sie anschließend die Abhängigkeit in der aktuellsten Version installieren: $ ncu -u Using /Users/cleancoderocker/Documents/workspaces/digital-landscape/examples/ example/package.json ⸨░░░░░░░░░░░░░░░░░░⸩ : : express ^3.2.6 → ^4.16.3 Upgraded /Users/cleancoderocker/Documents/workspaces/digital-landscape/ examples/example/package.json $ ncu Using /Users/cleancoderocker/Documents/workspaces/digital-landscape/examples/ example/package.json ⸨░░░░░░░░░░░░░░░░░░⸩ : : All dependencies match the latest package versions :)
Ebenfalls einen Blick wert ist der Online-Dienst unter https://david-dm.org/ (Abbildung 2.4), der Ihnen einen visuellen Überblick über die Abhängigkeiten Ihres Packages gibt. Den Status kann man sich zudem in Form eines Icons auf seine ProjektWebsite (oder die entsprechende GitHub- oder Projektseite auf der Website der npmRegistry) einbinden. So lässt sich auf einen Blick an zentraler Stelle erkennen, ob Abhängigkeiten veraltet sind oder nicht.
100
2.9
Zusammenfassung
Abbildung 2.4 Die Webseite »david-dm.org«
2.9 Zusammenfassung In diesem Kapitel haben Sie verschiedene Rezepte bezüglich des Package Managements kennengelernt. Sie wissen jetzt, wie Sie 왘 semantische Versionsnummern richtig verwenden (Rezept 8), 왘 den Package Manager Yarn verwenden (Rezept 9), 왘 den Package Manager pnpm verwenden (Rezept 10), 왘 Packages lokal miteinander verlinken (Rezept 11), 왘 Informationen zu verwendeten Abhängigkeiten einholen (Rezept 12), 왘 Lizenzen verwendeter Abhängigkeiten ermitteln (Rezept 13), 왘 nicht verwendete oder fehlende Abhängigkeiten ermitteln (Rezept 14), 왘 veraltete Abhängigkeiten ermitteln (Rezept 15).
Im nächsten Kapitel lernen Sie, welche Möglichkeiten Sie haben, Node.js-Applikationen zu debuggen, und wie Sie Logging richtig einsetzen.
101
Kapitel 3 Logging und Debugging In diesem Kapitel zeige ich Ihnen, wie Sie Node.js-Anwendungen debuggen und für das Logging konfigurieren.
Im Folgenden schauen wir uns zwei wichtige Aspekte an, die bei der Fehlersuche in Node.js-Applikationen helfen können: In den Rezepten 16 bis 18 zeige ich Ihnen, wie Sie das Logging einrichten, und in den Rezepten 19 bis 21 stelle ich Ihnen verschiedene Möglichkeiten vor, Node.js-Anwendungen zu debuggen. 왘 Rezept 16: Logging für Node.js-Packages einrichten 왘 Rezept 17: Logging für Node.js-Applikationen einrichten 왘 Rezept 18: Logging über Adapter-Packages einrichten 왘 Rezept 19: Applikationen mit Chrome Developer Tools debuggen 왘 Rezept 20: Applikationen mit Visual Studio Code debuggen 왘 Rezept 21: Applikationen über die Kommandozeile debuggen
3.1 Rezept 16: Logging für Node.js-Packages einrichten Sie möchten dafür sorgen, dass in Ihren Node.js-Packages Logging-Informationen ausgegeben werden.
3.1.1 Exkurs: Logging Während des Lebenszyklus einer Applikation ist es hilfreich, gewisse Informationen zu protokollieren, z. B. Zustände von Objekten, Werte von Variablen, Fehlermeldungen, Nutzerinformationen oder andere Informationen bezüglich des aktuellen Programmzustands. Solche Informationen können Ihnen dann bspw. dabei helfen, in Produktivsystemen Fehlerursachen zu finden oder generell einen Überblick über die Abläufe einer Applikation zu erhalten. Node.js und andere JavaScript-Laufzeitumgebungen, wie sie z. B. in Browsern zum Einsatz kommen, stellen standardmäßig das console-Objekt zur Verfügung, mit dessen Hilfe Sie auf die Kommandozeile zugreifen und Informationen darauf ausgeben können. Das console-Objekt stellt dabei u. a. die Methoden info(), warn() und error()
103
3
Logging und Debugging
zur Verfügung, um allgemeine Informationen, Warnungen oder Fehler auszugeben (Listing 3.1). Je nach Laufzeitumgebung und verwendeter Methode wird die Ausgabe dann gegebenenfalls farbig hervorgehoben und/oder mit einem entsprechenden Icon versehen, damit Sie schnell zwischen dem Typ der Ausgabe unterscheiden können. console.log('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { console.error(error.message); } Listing 3.1 Logging über das »console«-Objekt
Auch wenn man während der Entwicklung relativ schnell dazu neigt, das Logging über das console-Objekt zu implementieren, rate ich Ihnen dringend davon ab, sobald ein Package oder eine Applikation etwas umfangreicher wird. Das wesentliche Problem bei der Verwendung des console-Objekts ist nämlich, dass sich einzelne Typen von Ausgaben nicht gezielt an- bzw. abschalten lassen. So ist es bspw. nicht ohne Weiteres möglich, für Ihre gesamte Applikation nur Fehlermeldungen auszugeben, normale Meldungen aber zu unterdrücken. Auch das gezielte An- bzw. Abschalten der Log-Ausgabe bestimmter Komponenten einer Applikation oder das Umleiten von Log-Ausgaben in eine Datei oder auf einen Logging-Server ist auf diese Weise nicht möglich. Besser ist es daher, auf professionellere Lösungen zurückzugreifen. Welche Sie dabei verwenden, hängt im Wesentlichen davon ab, welche Art von Node.js-Projekt Sie entwickeln: 왘 Entwickeln Sie ein Node.js-Package, das von anderen Node.js-Packages oder
Node.js-Applikationen eingebunden werden soll, greifen Sie am besten auf das »debug«-Package (https://github.com/visionmedia/debug) zurück (dieses Rezept), weil dies eine besonders schlanke Logging-Bibliothek ist. 왘 Entwickeln Sie eine komplexere Node.js-Applikation, verwenden Sie am besten
eine Logging-Bibliothek wie »winston« (https://github.com/winstonjs/winston), »bunyan« (https://github.com/trentm/node-bunyan) und »log4js-node« (https:// github.com/log4js-node/log4js-node), einen Port von log4js (https://github.com/ stritti/log4js) für Node.js (Rezept 17).
104
3.1
Rezept 16: Logging für Node.js-Packages einrichten
왘 Entwickeln Sie eine Microservice-Anwendung oder generell eine komplexere
Node.js-Anwendung, ist es zudem sinnvoll, die Logging-Ausgabe zur besseren Analyse zentral zu verwalten bzw. an zentraler Stelle zu sammeln, bspw. über Tools wie den ELK-Stack (bestehend aus der Suchmaschine Elasticsearch, dem LogVerarbeitungs-Tool Logstash und der Weboberfläche Kibana, https://www.elastic. co/de/elk-stack). Übrigens: Wie Sie mithilfe von Node.js Microservice-Anwendungen konzipieren und implementieren, zeige ich Ihnen in Kapitel 13, »Publishing, Deployment und Microservices«, in den Rezepten 102 (Microservice-Architekturen verstehen) und 103 (Microservice-Architekturen aufsetzen mit Docker Compose). Die Verwendung der genannten Logging-Lösungen bietet verschiedene Vorteile: 왘 Timestamps: Logging-Meldungen können mit einem Zeitstempel versehen wer-
den, was später bei der Analyse der Log-Daten hilfreich ist. 왘 Log-Levels: Über sogenannte Log-Levels können Sie gezielt – auch zur Laufzeit
einer Applikation – die Art einer Meldung definieren, z. B. ob es sich um einen Fehler, eine Warnung, eine Debug-Ausgabe oder eine generelle Information handelt (siehe Tabelle 3.1). 왘 Namespaces: Bestimmte Komponenten einer Applikation lassen sich zu Name-
spaces bzw. Logging-Gruppen zusammenfassen, sodass sich gezielt definieren lässt, für welche Komponenten das Logging aktiviert sein soll und für welche nicht. 왘 Log-Analyse: Das Ziel der protokollierten Meldungen lässt sich nahezu frei wäh-
len. So ist es bspw. möglich, die Meldungen in Dateien, Datenbanken, über HTTP an spezielle Webservices oder über UDP an Logging-Dienste wie Logstash (https:// www.elastic.co/de/products/logstash) zu übertragen. Dies hilft Ihnen bei der Analyse von Logs und beim Finden von Fehlern. Analysetools wie der erwähnte ELKStack sind in diesem Zusammenhang auf jeden Fall einen Blick wert. Log-Level
Beschreibung
fatal
Die Anwendung wird aufgrund eines Fehlers gestoppt und steht nicht mehr zur Verfügung.
error
Die aktuelle Anfrage konnte nicht bearbeitet werden bzw. erzeugte einen Fehler, die Anwendung als Ganzes wird aber weiterhin ausgeführt.
warn
Hinweis über eine Auffälligkeit im Programmablauf
info
Informationen zu einer normalen Operation
Tabelle 3.1 Typische Levels für das Logging
105
3
Logging und Debugging
Log-Level
Beschreibung
debug
detaillierte Informationen zu einer normalen Operation
trace
sehr detaillierte Informationen
Tabelle 3.1 Typische Levels für das Logging (Forts.)
3.1.2 Lösung: das »debug«-Package Falls Sie ein Package entwickeln, dessen Ziel es ist, von anderen Packages oder Node.js-Applikationen verwendet zu werden, empfehle ich Ihnen den Einsatz des »debug«-Packages (https://github.com/visionmedia/debug), das Sie wie folgt installieren: $ npm install debug
Anschließend binden Sie das Package wie gewohnt über require() ein und erstellen über den Aufruf von debug() eine Logger-Funktion, wobei Sie als Parameter einen Namespace übergeben, über den Sie später den Logger an- oder ausschalten können. Anschließend rufen Sie die Logger-Funktion wie folgt auf: // src/start-debug.js const debug = require('debug'); const logger = debug('my-application'); logger('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { logger(error.message); } Listing 3.2 Logging mit dem »debug«-Package
Standardmäßig produziert das »debug«-Package keine Ausgabe, d. h., wenn Sie das obige Programm über node src/start-debug.js starten, sehen Sie auf der Konsole erst mal nichts. Um das Logging zu aktivieren, müssen Sie den verwendeten Namespace als Wert für die Umgebungsvariable DEBUG hinzufügen. Diese können Sie über ent-
106
3.1
Rezept 16: Logging für Node.js-Packages einrichten
sprechende Kommandozeilenbefehle definieren, am einfachsten ist es aber, diese beim Start des Programms wie folgt mitzugeben (siehe auch Rezept 22 in Kapitel 4, »Konfiguration und Internationalisierung«): $ DEBUG=my-application node src/start-debug.js my-application Program started +0ms my-application Example error +3ms
Hinweis Da das »debug«-Package sehr weit verbreitet ist und von vielen anderen bekannten Packages verwendet wird (laut npm-Registry derzeit von mehr als 27.000), können Sie das Logging dieser Packages ebenfalls über die Umgebungsvariable DEBUG steuern. Für eine Applikation, die das Webframework Express verwendet können Sie das Logging bspw. wie folgt aktivieren: $ DEBUG=express* node server.js
Auf die weiteren Möglichkeiten von Namespaces und die Funktion von Wildcards gehe ich im Folgenden genauer ein.
Wildcards Über Namespaces können Sie exakt steuern, welche Log-Meldungen ausgegeben werden sollen und welche nicht. Um das noch besser nachvollziehen zu können, passen Sie das obige Programm wie in Listing 3.3 zu sehen an. const const const const const
debug = require('debug'); logger = debug('my-application'); errorLogger = debug('my-application:error'); function1Logger = debug('my-application:function1'); function2Logger = debug('my-application:function2');
logger('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { errorLogger(error.message); }
107
3
Logging und Debugging
function function1() { function1Logger('function1() executing'); setTimeout(function1, 500); } function1(); function function2() { function2Logger('function2() executing'); setTimeout(function2, 500); } function2(); Listing 3.3 Verwenden von hierarchischen Namespaces mit dem »debug«-Package
Das Programm wurde hier um zwei Funktionen (function1() und function2()) sowie um drei weitere Logger (function1Logger, function2Logger und errorLogger) ergänzt: Der Logger function1Logger wird dabei von der Funktion function1() verwendet, der Logger function2Logger von der Funktion function2() und der Logger errorLogger für das Logging von Fehlermeldungen. Wenn Sie nun das Programm über den gleichen Befehl wie eben starten, werden Sie feststellen, dass nur Folgendes ausgegeben wird: my-application Program started +0ms
Der Grund: Die drei neu hinzugefügten Logger werden durch die Namespace-Angabe my-application nicht abgedeckt. Um alle Log-Meldungen unterhalb dieses Namespaces zu aktivieren, müssen Sie daher Wildcards einsetzen. So können Sie bspw. über DEBUG=my-application.* nur die drei neu hinzugefügten Logger aktivieren und über DEBUG=my-application* alle der insgesamt vier Logger: $ DEBUG=my-application* node start-debug.js my-application Program started +0ms my-application:error Example error +0ms my-application:function1 function1() executing my-application:function2 function2() executing my-application:function1 function1() executing my-application:function2 function2() executing
+0ms +0ms +505ms +505ms
3.1.3 Ausblick Das »debug«-Package eignet sich insbesondere dann, wenn Sie ein Node.js-Package implementieren. Wenn Sie dagegen eine Node.js-Applikation implementieren, gibt
108
3.2
Rezept 17: Logging für Node.js-Applikationen einrichten
es noch einige andere Logging-Bibliotheken, die Sie in Betracht ziehen sollten. Welche das sind und welche zusätzlichen Features sie anbieten, zeige ich in dem folgenden Rezept. Allerdings spricht auch nichts dagegen, das »debug«-Package auch für das Logging in Node.js-Applikationen zu verwenden und umgekehrt die im Folgenden beschriebenen Bibliotheken auch für das Logging in Node.js-Packages. Die in diesem Buch vollzogene Unterscheidung gibt Ihnen nur eine grobe Richtlinie, was ich für sinnvoll halte.
Verwandte Rezepte 왘 Rezept 17: Logging für Node.js-Applikationen einrichten 왘 Rezept 18: Logging über Adapter-Packages einrichten
3.2 Rezept 17: Logging für Node.js-Applikationen einrichten Sie möchten dafür sorgen, dass Ihre Applikation Logging-Informationen speichert.
3.2.1 Lösung: Logging mit »winston« Ein Package, das sich für das Logging in Node.js-Applikationen anbietet, ist das Package »winston« (https://github.com/winstonjs/winston), das Sie über folgenden Befehl installieren können: $ npm install winston`
Um »winston« verwenden zu können, erstellen Sie, wie in Listing 3.4 zu sehen, über die Methode createLogger() zunächst eine Logger-Instanz. Als Parameter übergeben Sie dabei ein Konfigurationsobjekt, über das Sie bspw. das Log-Level, das Format der Log-Meldungen sowie sogenannte Transports definieren können. Über Letztere lässt sich die Ausgabe der Log-Meldungen z. B. in Dateien, in Datenbanken oder an Webservices weiterleiten. »winston« liefert von Haus aus schon einige Transport-Möglichkeiten mit, lässt sich dank Plugin-System aber um beliebige weitere Transports erweitern. Eine Übersicht über existierende Transports finden Sie unter https:// github.com/winstonjs/winston/blob/master/docs/transports.md. Dazu zählen bspw. Transports für MongoDB (Rezept 49), Cassandra (Rezept 53) und Elasticsearch. Transports lassen sich zudem kombinieren, sodass Sie z. B. die Log-Ausgabe gleichzeitig auf die Konsole ausgeben, in eine Datei schreiben und per UDP an Logstash zur LogAnalyse senden können. In Listing 3.4 sehen Sie zudem, dass ein Transport-Typ auch mehrfach verwendet werden kann. Hier werden bspw. zwei Transports vom Typ
109
3
Logging und Debugging
winston.transports.File definiert: Der eine schreibt nur die Fehlermeldungen in die
Datei error.log, der andere alle Arten von Meldungen in die Datei all.log. const winston = require('winston'); const logger = winston.createLogger({ level: 'info', format: winston.format.json(), transports: [ new winston.transports.Console(), new winston.transports.File({ filename: 'error.log', level: 'error' }), new winston.transports.File({ filename: 'all.log' }) ] }); // Ausgabe auf Konsole logger.info('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { // Ausgabe in Datei logger.error(error.message); } Listing 3.4 Logging mit »winston«
In Listing 3.4 wird als Ausgabeformat für die Meldungen das JSON-Format verwendet. Neben JSON unterstützt »winston« aber auch weitere Formate und erlaubt über die Methode winston.format() sogar die Definition individueller Ausgabeformate.
Browser-Support Beachten Sie: Derzeit kann »winston« noch nicht wie andere JavaScript-LoggingBibliotheken im Browser verwendet werden, sondern nur unter Node.js. Zum Zeit-
110
3.2
Rezept 17: Logging für Node.js-Applikationen einrichten
punkt der Drucklegung dieses Buches ist laut offizieller Roadmap (https://github. com/winstonjs/winston/blob/master/CONTRIBUTING.md#roadmap) Browser-Support erst mit einer der nächsten Versionen geplant. Sollten Sie also ein Package entwickeln, das sowohl unter Node.js als auch in Browsern funktionieren soll (Stichwort Isormophic JavaScript), ist »winston« momentan keine Option.
3.2.2 Lösung: Logging mit »bunyan« Das Package »bunyan« (https://github.com/trentm/node-bunyan) gilt als besonders schlanke und schnelle Logging-Bibliothek, bietet allerdings im Gegensatz zu »winston« auch nur JSON als Logging-Format an. Installieren können Sie »bunyan« über folgenden Befehl: $ npm install bunyan
Wie schon bei »winston« erstellen Sie auch bei »bunyan« über createLogger() zunächst eine Logger-Instanz (Listing 3.5) und definieren dabei über ein Konfigurationsobjekt Details wie das Log-Level und das Ziel für die Log-Meldungen. Letzteres definieren Sie über die Eigenschaft streams (wollen Sie nur eine einzelne Ausgabe definieren, können Sie dies auch über Eigenschaft stream machen). Streams funktionieren dabei ähnlich wie die Transports bei »winston« und lassen sich ebenfalls kombinieren. So ist es auch bei »bunyan« relativ einfach möglich, die Log-Ausgabe parallel an mehrere Streams weiterzuleiten. In Listing 3.5 bspw. werden zwei Streams verwendet: Meldungen vom Typ »info« werden an die Standardausgabe weitergeleitet und Meldungen vom Typ »error« in die Datei error.log. const bunyan = require('bunyan'); const logger = bunyan.createLogger({ name: 'example-logger', level: 'info', streams: [ { level: 'info', stream: process.stdout }, { level: 'error', path: 'error.log' } ] });
111
3
Logging und Debugging
// Ausgabe auf Konsole logger.info('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { // Ausgabe in Datei logger.error(error.message); } Listing 3.5 Logging mit »bunyan«
Browser-Support Im Unterschied zu »winston« kann »bunyan« sowohl unter Node.js als auch – dank Browserify (http://browserify.org/) und Webpack (https://webpack.js.org/) – im Browser verwendet werden. Für Packages, die sowohl unter Node.js als auch im Browser funktionieren sollen, ist »bunyan« als Logging-Bibliothek daher momentan die bessere Wahl.
3.2.3 Lösung: Logging mit »log4js-node« Ein weiteres Package für das Logging unter Node.js ist das Package »log4js«. Die Installation des Packages geschieht über folgenden Befehl: $ npm install log4js`
Anschließend binden Sie das Package über require('log4js') in Ihre Applikation ein. Das Konfigurieren und Erzeugen einer Logger-Instanz geschieht im Gegensatz zu dem bei »winston« und »bunyan« in zwei Schritten: Wie in Listing 3.6 zu sehen, konfigurieren Sie zunächst über die Methode configure() u. a., wohin die Meldungen geschrieben werden sollen. Auch hierbei übergeben Sie ein Konfigurationsobjekt, über das Sie u. a. über die Eigenschaft appenders verschiedene Ausgaben definieren können (analog zu den Transports in »winston« und den Streams in »bunyan«). Anschließend erzeugen Sie über einen Aufruf von getLogger() eine entsprechend konfigurierte Logger-Instanz. const log4js = require('log4js'); log4js.configure({
112
3.2
Rezept 17: Logging für Node.js-Applikationen einrichten
appenders: { file: { type: 'file', filename: 'error.log' } }, categories: { default: { appenders: ['file'], level: 'info' } } }); const logger = log4js.getLogger('file'); // Ausgabe auf Konsole logger.info('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { // Ausgabe in Datei logger.error(error.message); } Listing 3.6 Logging mit »log4js-node«
3.2.4 Ausblick Ob Sie für das Logging »winston«, »bunyan« oder »log4js-node« verwenden, ist letztendlich wie so oft bei Third-Party-Node.js-Packages eine Frage des persönlichen Geschmacks. Alle drei Bibliotheken sind mehr oder weniger gleich stark vertreten und unterscheiden sich nur in den Details (Ausnahme: Browser-Support). Wenn Sie sich nicht festlegen möchten, bietet sich die Verwendung einer sogenannten AdapterKlasse bzw. eines Adapter-Packages an. Was dahintersteckt, zeige ich Ihnen im nächsten Rezept.
113
3
Logging und Debugging
3.3 Rezept 18: Logging über Adapter-Packages einrichten Sie möchten den Zugriff auf die konkrete Logging-Bibliothek abstrahieren und sich die Flexibilität erhalten, diese im Laufe der Entwicklung auszutauschen.
3.3.1 Lösung Wenn Sie sich nicht entscheiden können, welches der vorgestellten Logging-Packages Sie verwenden möchten, oder wenn Sie sich die Flexibilität erhalten möchten, ohne großen Aufwand von einem Package zu einem anderen Package wechseln zu können, sind Sie am besten beraten, ein sogenanntes Adapter-Package zu erstellen. Dessen Prinzip ist nicht auf das Logging beschränkt und lässt sich auch auf andere Aspekte wie bspw. den Datenbankzugriff oder den Zugriff auf Messaging-System anwenden. Die Idee dabei ist es, den Zugriff auf den jeweiligen Aspekt (in diesem Fall auf das Logging) innerhalb Ihres Packages oder Ihrer Applikation zu abstrahieren und über dieses Adapter-Package zu steuern (Abbildung 3.1). Dieses Package stellt dann die einzige Verbindung zu der konkreten externen Bibliothek bzw. dem externen Package dar (vergleiche auch das Adapter-Entwurfsmuster der Gang of Four).
Eigener Code
Eigener Code
Eigener Code
Eigener Code
Eigener Code
Eigener Code
Adapter-Package
Externes Package
Externes Package
Abbildung 3.1 Das Prinzip von Adapter-Packages
Der Vorteil: Möchten Sie im Laufe eines Projekts von einer Bibliothek zu einer anderen Bibliothek wechseln, müssen Sie nicht mehrere Hundert Stellen innerhalb Ihres Quelltextes anpassen, sondern nur die entsprechende Adapter-Klasse. Um das besser zu veranschaulichen, möchte ich Ihnen im Folgenden zeigen, wie Sie eine entsprechende Adapter-Klasse für den Zugriff auf eine Logging-Bibliothek implementieren.
114
3.3
Rezept 18: Logging über Adapter-Packages einrichten
Erstellen Sie dazu zunächst eine Datei LoggerAdapter.js mit dem Code aus Listing 3.7. Diese Klasse bildet die Basisklasse für die im weiteren Verlauf des Rezepts implementierte konkrete Adapter-Klasse und stellt gewissermaßen die API bereit (man könnte auch von Interfaces sprechen, wenn JavaScript Interfaces hätte). Const error = method => new Error(Method ${method}() must be implemented by subclass.); module.exports = class LoggerAdapter { info(/* message, …optionals */) { throw error('info'); } error(/* message, ...optionals */) { throw error('error'); } warn(/* message, ...optionals */) { throw error('warn'); } debug(/* message, ...optionals */) { throw error('debug'); } trace(/* message, ...optionals */) { throw error('trace'); } fatal(/* message, ...optionals */) { throw error('fatal'); } }; Listing 3.7 Basis-Adapter-Klasse
Erstellen Sie anschließend eine weitere Datei BunyanLoggerAdapter.js, die als konkrete Logging-Bibliothek »bunyan« verwenden wird, und kopieren Sie den Code aus Listing 3.8 in diese Datei. Die Klasse BunyanLoggerAdapter stellt die konkrete Implementierung der API von LoggerAdapter bereit. Die Implementierung ist dabei relativ simpel, weil die Methodenaufrufe einfach an die Logger-Instanz (this._logger) delegiert werden. Je nachdem aber, inwieweit die API Ihrer Adapter-Klasse und die API der jeweiligen externen Bibliothek auseinanderliegen, kann die Implementierung auch durchaus komplexer sein.
115
3
Logging und Debugging
const bunyan = require('bunyan'); const LoggerAdapter = require('./LoggerAdapter'); module.exports = class BunyanLoggerAdapter extends LoggerAdapter { constructor({ name = 'Bunyan Logger Adapter', level = 'debug' } = {}) { super(); this._logger = bunyan.createLogger({ name, level }); } info(message, ...optionals) { this._logger.info(message, ...optionals); } error(message, ...optionals) { this._logger.error(message, ...optionals); } warn(message, ...optionals) { this._logger.warn(message, ...optionals); } debug(message, ...optionals) { this._logger.debug(message, ...optionals); } trace(message, ...optionals) { this._logger.trace(message, ...optionals); } fatal(message, ...optionals) { this._logger.fatal(message, ...optionals); } get logger() { return this._logger; } }; Listing 3.8 Logging-Adapter für »bunyan«
116
3.3
Rezept 18: Logging über Adapter-Packages einrichten
Eigentlich wären Sie jetzt schon fertig und hätten eine Adapter-Klasse für »bunyan«, die Sie über new BunyanLoggerAdapter() instanziieren und anschließend entsprechend der definierten API verwenden könnten. Allerdings empfiehlt sich noch eine kleine Erweiterung, damit Sie diesen Konstruktoraufruf nur an zentraler Stelle verwalten müssen und damit vermeiden, bei dem Wechsel der Adapter-Klasse den Konstruktoraufruf überall im Code aktualisieren zu müssen. Erreicht werden kann dies auf verschiedene Art und Weise, z. B. über folgenden Code, der in einer separaten Datei Logger.js gespeichert wird: const LoggerAdapter = require('./BunyanLoggerAdapter'); module.exports = LoggerAdapter;
Anschließend kann die Datei wie folgt eingebunden werden und Ihr Code bleibt sowohl frei von Abhängigkeiten zur konkreten Logging-Bibliothek (denn die befindet sich in der Klasse BunyanLoggerAdapter) als auch frei von einer Verbindung zum konkreten Konstruktor (denn die befindet sich in der Datei Logger.js): const Logger = require('./Logger'); const logger = new Logger(); logger.info('Program started'); const throwError = () => { throw new Error('Example error'); }; try { throwError(); } catch (error) { logger.error(error.message); } Listing 3.9 Einbinden und Verwenden der Adapter-Klasse
3.3.2 Ausblick In diesem Rezept haben Sie gesehen, wie der Zugriff auf konkrete externe Bibliotheken durch Adapter-Klassen bzw. Adapter-Packages abstrahiert werden kann. Das Prinzip bietet sich wie gesagt nicht nur im Fall des Loggings an, sondern eignet sich prinzipiell immer dann, wenn Sie sich die Flexibilität bewahren möchten, im Laufe der Entwicklung die konkrete externe Bibliothek auszutauschen. Andere Anwendungsfälle, in denen der Einsatz von Adapter-Packages sinnvoll ist, sind der Zugriff auf Datenbanken (siehe Kapitel 7, »Persistenz«) und die Kommunikation mit Messaging-Systemen (siehe Kapitel 9, »Sockets und Messaging«).
117
3
Logging und Debugging
3.4 Rezept 19: Applikationen mit Chrome Developer Tools debuggen Sie möchten eine Node.js-Applikation mit den Chrome Developer Tools debuggen.
3.4.1 Vorbereitung Node.js-Applikationen können Sie auf verschiedene Arten debuggen. In diesem und den nächsten Rezepten möchte ich Ihnen eine Auswahl davon vorstellen, wobei als Grundlage das Beispielprogramm aus Listing 3.10 dienen soll. Konkret werde ich Ihnen folgende Debugging-Möglichkeiten zeigen: 왘 Debugging über Chrome Developer Tools (dieses Rezept) 왘 Debugging über Visual Studio Code (Rezept 20) 왘 Debugging über die Kommandozeile (Rezept 21)
Erstellen Sie also zunächst ein Beispielprojekt über folgende Befehle: $ $ $ $ $
mkdir example cd example npm init -y mkdir src touch src/start.js
Kopieren Sie anschließend den Code aus Listing 3.10 in die Datei start.js. Zu sehen ist hier eine einfache for-Schleife, die für zehn Iterationen läuft und in jeder Iteration die Methode (asynchrone) wait() aufruft, die wiederum nach fünf Sekunden den zurückgegebenen Promise »resolved«. Mit anderen Worten: In jeder Iteration der forSchleife wird fünf Sekunden gewartet und dann die Schleife fortgeführt. const wait = (timeout = 5000) => { return new Promise((resolve, reject) => { setTimeout(resolve, timeout); }); }; (async () => { for (let i = 0; i < 10; i++) { console.log('wait'); await wait(); console.log('waited'); } })(); Listing 3.10 Beispielprogramm für das Debugging
118
3.4
Rezept 19: Applikationen mit Chrome Developer Tools debuggen
3.4.2 Lösung Eine der gängigsten Möglichkeiten, eine Node.js-Applikation zu debuggen, führt über die im Chrome-Browser integrierten Chrome Developer Tools (https://developers. google.com/web/tools/chrome-devtools/). Der Vorteil: Diese Tools sind im ChromeBrowser bereits vorinstalliert und den meisten Webentwicklern ohnehin aus der Webentwicklung bekannt. So ist in der Regel keine große Umstellung bzw. Eingewöhnung notwendig, um sich zurechtzufinden. Damit Sie eine Node.js-Applikation aber überhaupt mit den Chrome Developer Tools debuggen können, müssen Sie die Applikation zunächst mit dem Parameter --inspect aufrufen: $ node --inspect src/start.js Debugger listening on ws://127.0.0.1:9229/11c10f5e-3b45-4de2-a029-9fa162fd709f For help see https://nodejs.org/en/docs/inspector
Durch diesen Parameter startet Node.js intern den Debugger und stellt standardmäßig über den Port 9229 einen WebSocket-Server zur Verfügung, über den entsprechende Debugging-Tools die Verbindung mit der jeweiligen Applikation im DebugModus aufnehmen können. Starten Sie jetzt den Chrome-Browser, und öffnen Sie die URL chrome://inspect (Abbildung 3.2).
Abbildung 3.2 Verwaltung der Debugger in Chrome
Hinweis Wenn Sie mehrere Node.js-Anwendungen parallel debuggen, können Sie über --inspect=[host:port] auch zusätzlich den Port (und den Hostnamen) angeben, unter dem der Debug-Server gestartet werden soll. Allerdings müssen Sie dabei beachten, dass Sie eventuell unter chrome://inspect erst noch unter Configure... den entsprechenden Port (und Hostnamen) in den Target Discovery Settings ergänzen müssen.
119
3
Logging und Debugging
Merke Verwenden Sie für das Starten einer Node.js-Applikation im Debug-Modus den Parameter --inspect (bzw. --inspect-brk, um den Debugger automatisch an der ersten Code-Zeile anzuhalten). Die beiden Parameter --debug und --debug-brk werden seit Node.js 12 nicht mehr unterstützt.
Unter dem Bereich Remote Target sollte nun die eben gestartete Anwendung aufgelistet sein. Klicken Sie unterhalb des Eintrags auf Inspect, öffnen sich die Chrome Developer Tools (Abbildung 3.3). Über den Reiter Sources gelangen Sie nun in die Ansicht, in der Sie den Debugger steuern können. So können Sie wie gewohnt Haltepunkte (Breakpoints) definieren, indem Sie links neben eine Code-Zeile klicken, über die Tool-Leiste schrittweise durch den Code navigieren, Variablenbelegungen einsehen, Ausdrücke auswerten und vieles andere mehr.
Abbildung 3.3 Chrome Developer Tools
Breakpoints von außen definieren Manchmal reicht es nicht, den Debugger erst dann zu öffnen bzw. Breakpoints erst dann zu definieren, wenn die Applikation schon gestartet wurde, bspw. wenn Sie den Startprozess Ihrer Applikation debuggen möchten. Für Anwendungsfälle wie diesen haben Sie zwei Möglichkeiten: Zum einen können Sie den Debugger direkt dazu ver-
120
3.4
Rezept 19: Applikationen mit Chrome Developer Tools debuggen
anlassen, bei der ersten Anweisung Ihrer Applikation anzuhalten, und zwar, indem Sie statt des Parameters --inspect den Parameter --inspect-brk übergeben: $ node --inspect-brk src/start.js
Zum anderen können Sie innerhalb Ihres Applikationscodes an beliebiger Stelle das debugger-Schlüsselwort verwenden, durch das der Debugger an genau dieser Stelle im Code anhält (Listing 3.11 und Abbildung 3.4). const wait = (timeout = 5000) => { return new Promise((resolve, reject) => { setTimeout(resolve, timeout); }); }; (async () => { for (let i = 0; i < 10; i++) { console.log('wait'); debugger; await wait(); console.log('waited'); } })(); Listing 3.11 Verwendung des »debugger«-Schlüsselworts
Abbildung 3.4 Am »debugger«-Schlüsselwort hält der Debugger
121
3
Logging und Debugging
Produktivcode Im Produktivcode hat dieses Schlüsselwort allerdings nichts zu suchen, auch wenn es von Node.js nur dann berücksichtigt wird, wenn die entsprechende Anwendung im Debug-Modus gestartet wird.
3.4.3 Ausblick Die Chrome Developer Tools eignen sich meines Erachtens hervorragend, um Node.js-Applikationen in verschiedenen Kontexten zu debuggen. Wenn Sie dagegen alles aus einer Hand haben wollen, sprich Entwicklungsumgebung und Debugger, dann kann ich Ihnen auch das im nächsten Rezept vorgestellte Visual Studio Code empfehlen.
3.5 Rezept 20: Applikationen mit Visual Studio Code debuggen Sie möchten eine Node.js-Applikation mit Visual Studio Code debuggen.
3.5.1 Lösung Neben den Chrome Developer Tools, die praktischerweise direkt mit Chrome installiert sind, bieten verschiedene IDEs wie z. B. WebStorm (https://www.jetbrains.com/ webstorm/) oder Visual Studio Code (https://code.visualstudio.com/) ebenfalls Möglichkeiten, direkt aus der IDE heraus eine Applikation im Debug-Modus zu starten. Intern passiert hierbei nichts anderes, als dass die Applikation mit dem Parameter --inspect gestartet und im Hintergrund ein Socket-Server hochgefahren wird, mit dem sich die IDE dann verbindet. Im Folgenden möchte ich Ihnen zeigen, wie Sie Node.js-Anwendungen mit Visual Studio Code debuggen können, mittlerweile die IDE meiner Wahl, wenn es um die Entwicklung von Node.js- bzw. JavaScript-Anwendungen im Allgemeinen geht.
Applikationen aus dem Menü debuggen Um mit Visual Studio Code ein Programm im Debug-Modus zu starten, wählen Sie aus dem Hauptmenü den Eintrag Debuggen und im anschließenden Untermenü den Eintrag Debugging starten (alternativ dazu können Sie den Debug-Modus auch direkt über die (F5)-Taste starten). Anschließend wechselt Visual Studio Code (sofern noch nicht geschehen) in die Debugging-Ansicht (Abbildung 3.5), in der Ihnen die typischen Bereiche zur Verfügung stehen:
122
3.5
Rezept 20: Applikationen mit Visual Studio Code debuggen
왘 Über den Bereich Variablen können Sie bspw. die Belegung der aktuellen Varia-
blen einsehen. 왘 Über den Bereich Überwachen ist es möglich, Ausdrücke zu formulieren, die zur
Laufzeit ausgewertet werden. 왘 Der Bereich Aufrufliste enthält den Stack-Trace. 왘 Über den Bereich Haltepunkte verwalten Sie die Breakpoints. 왘 Über die Toolbar am oberen Rand des Editors steuern Sie den eigentlichen
Debugger.
Abbildung 3.5 Debugging-Ansicht in Visual Studio Code
Applikationen über die Start-Konfiguration debuggen Alternativ zu dem im vorherigen Abschnitt beschriebenen Weg, eine Node.js-Applikation zu debuggen, haben Sie in Visual Studio Code auch die Möglichkeit, sogenannte Launch Configurations zu definieren. Der Vorteil: In diesen Konfigurationen können Sie bspw. auch Umgebungsvariablen definieren, die für die Applikation notwendig sind, und andere Aspekte wie z. B. das automatische Transpilieren von JavaScript-Code. Die Launch Configurations werden in der globalen Konfigurationsdatei launch.json verwaltet. Um diese zu öffnen, wählen Sie aus dem Hauptmenü den Eintrag Debug • Open Configurations oder Debug • Add Configuration..., um direkt eine neue Konfiguration in der Datei anzulegen. Fügen Sie nun unter dem Bereich configurations die Konfiguration aus Listing 3.12 hinzu:
123
3
Logging und Debugging
{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "My example debug application", "program": "${workspaceFolder}/nodejskochbuch/example/src/start.js" }, ... } Listing 3.12 Launch Configuration von Visual Studio Code
Anschließend können Sie die Anwendung aus der Debug-Ansicht heraus über das Drop-down-Menü oben links direkt im Debug-Modus starten (siehe Abbildung 3.6).
Abbildung 3.6 Starten einer Launch Configuration
Hinweis Für weitere Details zum Thema Debugging unter Visual Studio Code empfiehlt sich die offizielle Dokumentation unter https://code.visualstudio.com/docs/nodejs/nodejs-debugging. Dort finden Sie bspw. Informationen zum Thema Source Maps (für den Fall, dass Sie Code debuggen möchten, der bspw. von TypeScript nach JavaScript transpiliert wurde).
3.5.2 Ausblick Die Chrome Developer Tools und Visual Studio Code (oder andere IDEs) bieten mittlerweile hervorragende Möglichkeiten, um Node.js-Applikationen zu debuggen.
124
3.6
Rezept 21: Applikationen über die Kommandozeile debuggen
Dank des Remote-Debuggings über WebSockets können Sie dabei auch auf entfernte Rechner zugreifen, vorausgesetzt der entsprechende Debug-Port ist freigegeben. So ist es bspw. ohne Weiteres möglich, auf diese Weise eine Node.js-Anwendung zu debuggen, die innerhalb eines Docker-Containers läuft, und auch Anwendungen, die innerhalb eines Kubernetes-Clusters in einem Pod laufen, stellen kein Problem dar (das Einzige, was Sie hierbei machen müssen, ist, mit den Kommandozeilentools von Kubernetes den entsprechenden Port über den Befehl kubectl port-forward von dem jeweiligen Cluster auf Ihren Rechner weiterzuleiten). Für Fälle, in denen Ihnen entweder keine IDE oder keine Chrome Developer Tools zur Verfügung stehen oder in denen Sie generell nicht per Remote-Debugging auf eine Anwendung zugreifen können und Ihnen nur der Zugriff per Kommandozeile gewährt ist, können Sie Node.js-Anwendungen auch per Kommandozeile debuggen. Wie das funktioniert, zeige ich Ihnen im nächsten Rezept. In Kapitel 10, »Testing und TypeScript«, werde ich Ihnen außerdem zeigen, wie Sie TypeScript-Anwendungen debuggen können, und in Kapitel 12, »Native Module«, wie Sie native Module bzw. nativen (C/C++)-Code debuggen können.
Verwandte Rezepte 왘 Rezept 21: Applikationen über die Kommandozeile debuggen 왘 Rezept 97: Native Node.js-Module debuggen
3.6 Rezept 21: Applikationen über die Kommandozeile debuggen Sie möchten eine Node.js-Applikation über die Kommandozeile debuggen.
3.6.1 Lösung Um eine Node.js-Applikation mit dem Node.js-Debugger zu starten, rufen Sie diese mit dem Unterbefehl inspect auf (nicht zu verwechseln mit dem Parameter --inspect, über den Sie, wie in den vorherigen Rezepten gesehen, eine Applikation im Debug-Modus starten): $ node inspect start.js < Debugger listening on ws://127.0.0.1:9229/ea17562c-4906-4884-872ac981ceb92f77 < For help see https://nodejs.org/en/docs/inspector < Debugger attached. Break on start in start.js:1 > 1 (function (exports, require, module, __filename, __dirname) { const wait = (timeout = 5000) => {
125
3
Logging und Debugging
2 return new Promise((resolve, reject) => { 3 setTimeout(resolve, timeout); debug>
Dies startet den Debugger, pausiert ihn an der ersten Code-Zeile und öffnet eine Debugger-Konsole, über die Sie verschiedene Befehle absetzen können. Um z. B. einen Breakpoint hinzuzufügen, verwenden Sie den Befehl setBreakpoint(), wobei Sie als ersten Parameter den Namen des Scripts und als zweiten Parameter die Code-Zeile übergeben. Folgender Befehl bspw. setzt einen Breakpoint an Zeile 9 im Script start.js: debug> setBreakpoint('start.js', 9) 4 }); 5 }; 6 7 (async () => { 8 for (let i = 0; i < 10; i++) { > 9 console.log('wait'); 10 debugger; 11 await wait(); 12 console.log('waited'); 13 } 14 })();
Über den Befehl cont bzw. dessen Shortcut c können Sie die Programmausführung fortsetzen, was im Beispiel dazu führt, dass der Debugger das Programm bis zu dem gerade definierten Breakpoint ausführt: debug> cont break in start.js:9 7 (async () => { 8 for (let i = 0; i < 10; i++) { > 9 console.log('wait'); 10 debugger; 11 await wait();
Um den Wert einzelner Variablen einzusehen, verwenden Sie den Befehl exec, gefolgt von dem Namen der Variablen. Um bspw. den aktuellen Wert der Variablen i auszugeben, rufen Sie Folgendes auf: debug> exec i 0
Über den Befehl next (bzw. n) bewegen Sie den Debugger um einen Schritt weiter. Wenn Sie diesen Befehl dreimal hintereinander ausführen, hält der Debugger anschließend am Aufruf der Funktion wait():
126
3.6
Rezept 21: Applikationen über die Kommandozeile debuggen
debug> next < wait break in start.js:10 8 for (let i = 0; i < 10; i++) { * 9 console.log('wait'); >10 debugger; 11 await wait(); 12 console.log('waited'); debug> next break in start.js:11 * 9 console.log('wait'); 10 debugger; >11 await wait(); 12 console.log('waited'); 13 } debug> next break in start.js:11 * 9 console.log('wait'); 10 debugger; >11 await wait(); 12 console.log('waited'); 13 }
Über step (bzw. s) springen Sie in eine Funktion hinein: debug> step break in start.js:2 1 (function (exports, require, module, __filename, __dirname) { const wait = (timeout = 5000) => { > 2 return new Promise((resolve, reject) => { 3 setTimeout(resolve, timeout); 4 }); debug> exec timeout 5000
Und über den Befehl out (bzw. o) springen Sie aus einer Funktion wieder heraus: debug> out break in start.js:11 * 9 console.log('wait'); 10 debugger; >11 await wait(); 12 console.log('waited'); 13 }
127
3
Logging und Debugging
Darüber hinaus können Sie über pause mit der Ausführung des jeweiligen Scripts pausieren, über watch() bzw. unwatch() Überwachungsausdrücke definieren bzw. wieder löschen, über backtrace den aktuellen Methodenaufruf-Stack ausgeben und über list() den die aktuelle Code-Zeile umgebenden Code ausgeben (siehe auch Tabelle 3.2). Weitere Informationen zum Debuggen auf der Kommandozeile finden Sie unter https://nodejs.org/api/debugger.html. Befehl
Shortcut
Beschreibung
cont
c
Setzt die Programmausführung fort.
next
n
Setzt den Debugger einen Schritt weiter.
step
s
Springt in eine Funktionhinein.
out
o
Springt aus einer Funktion heraus.
pause
–
Pausiert den Debugger.
setBreakpoint()
sb()
Setzt einen Breakpoint an der aktuellen Zeile.
setBreakpoint(line)
sb(line)
Setzt einen Breakpoint an einer bestimmten Zeile.
setBreakpoint('fn()')
sb('fn()')
Setzt einen Breakpoint an der ersten Anweisung der übergebenen Funktion.
setBreakpoint( 'script.js', line )
sb( 'script.js', line )
Setzt einen Breakpoint an einer bestimmten Zeile des übergebenen Scripts.
clearBreakpoint( 'script.js', line )
cb( 'script.js', line )
Löscht einen Breakpoint von einer bestimmten Zeile des übergebenen Scripts.
backtrace
bt
Gibt den Methodenaufruf-Stack aus.
list(lines)
–
Gibt den aktuellen Script-Kontext aus, wobei die Anzahl der vorher und nachher mit ausgegebenen Zeilen durch den Parameter lines beeinflusst werden kann.
Tabelle 3.2 Überblick über die Befehle des kommandozeilenbasierten Node.js-Debuggers
128
3.7
Zusammenfassung
Befehl
Shortcut
Beschreibung
watch(expr)
–
Fügt einen Ausdruck zu den WatchExpressions hinzu.
unwatch(expr)
–
Entfernt einen Ausdruck von den Watch-Expressions.
watchers
–
Gibt die aktuellen Watch-Expressions inklusive ihrer aktuellen Werte aus.
repl
–
Öffnet einen REPL (Read-Eval-Print Loop) in dem aktuellen Script-Kontext.
exec expr
–
Führt einen Ausdruck in dem aktuellen Script-Kontext aus.
run
–
Führt ein Script aus.
restart
–
Startet ein Script neu.
kill
–
Beendet ein Script.
Tabelle 3.2 Überblick über die Befehle des kommandozeilenbasierten Node.js-Debuggers (Forts.)
3.6.2 Ausblick Sie wissen jetzt, wie Sie Node.js-Anwendungen mithilfe der Kommandozeile debuggen können. Allerdings ergibt die Verwendung eines kommandozeilebasierten Debuggers meiner Meinung nach nur in Ausnahmefällen Sinn (oder wenn man ein gewisses Faible für das reine Arbeiten mit der Kommandozeile hat). Die Komfortabilität eines GUI-gestützten Debuggers wie den in den vorherigen Rezepten gezeigten Chrome Developer Tools und Visual Studio Code ist mit einem kommandozeilenbasierten Debugger einfach nicht gegeben.
Verwandte Rezepte 왘 Rezept 19: Applikationen mit Chrome Developer Tools debuggen 왘 Rezept 97: Native Node.js-Module debuggen
3.7 Zusammenfassung In diesem Kapitel haben Sie verschiedene Rezepte bezüglich des Loggings und des Debuggings kennengelernt. Sie wissen jetzt, wie Sie
129
3
Logging und Debugging
왘 Logging für Node.js-Packages einrichten (Rezept 16), 왘 Logging für Node.js-Applikationen einrichten (Rezept 17), 왘 Logging über Adapter-Packages einrichten (Rezept 18), 왘 Applikationen mit den Chrome Developer Tools debuggen (Rezept 19), 왘 Applikationen mit Visual Studio Code debuggen (Rezept 20), 왘 Applikationen über die Kommandozeile debuggen (Rezept 21).
Im nächsten Kapitel lernen Sie dann, was es bezüglich der Konfiguration von Node.jsApplikation alles zu beachten gibt.
130
Kapitel 4 Konfiguration und Internationalisierung In diesem Kapitel lernen Sie, wie Sie Anwendungen optimal konfigurieren und für den mehrsprachigen Einsatz vorbereiten.
Konfigurationsdaten einer Anwendung, wie z. B. bei Webservern der Hostname und der Port oder bei Datenbanken die Verbindungseinstellungen wie Nutzername und Passwort, sollten Sie nicht direkt im Code definieren, sondern von außen konfigurierbar machen. Das gilt nicht nur für JavaScript unter Node.js, sondern auch für andere Programmiersprachen und ist Bestandteil der Twelve-Factor-App-Methodologie (siehe https://12factor.net/ und insbesondere https://12factor.net/config). Der Vorteil einer flexiblen Konfiguration gegenüber hart kodierten Werten liegt auf der Hand: Anwendungen können auf diese Weise dynamisch konfiguriert und an die entsprechenden Bedingungen angepasst werden, ohne dass sie neu gebaut oder deployed werden müssen. Darüber hinaus ist es in den meisten Fällen sinnvoll, eine Applikation auch so zu strukturieren, dass sie relativ einfach an verschiedene Sprachen angepasst werden kann (Stichwort Internationalisierung). In diesem Kapitel zeige ich Ihnen daher, wie Sie Node.js-Applikationen am besten konfigurieren (Rezepte 22 bis 25) und was es bezüglich der Mehrsprachigkeit von Node.js-Applikationen zu beachten gilt (Rezepte 26 und 27). 왘 Rezept 22: Applikationen konfigurieren über Umgebungsvariablen 왘 Rezept 23: Applikationen konfigurieren über Konfigurationsdateien 왘 Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente 왘 Rezept 25: Applikationen optimal konfigurierbar machen 왘 Rezept 26: Mehrsprachige Applikationen erstellen 왘 Rezept 27: Sprachdateien verwenden
131
4
Konfiguration und Internationalisierung
4.1 Rezept 22: Applikationen konfigurieren über Umgebungsvariablen Sie möchten Ihre Applikation über Umgebungsvariablen konfigurierbar machen.
4.1.1 Exkurs: Konfiguration von Applikationen Prinzipiell lassen sich Node.js-Applikationen über folgende Techniken konfigurieren, die ich Ihnen in diesem und den folgenden Rezepten vorstellten möchte: 왘 über Umgebungsvariablen (dieses Rezept) 왘 über Konfigurationsdateien (Rezept 23) 왘 über Kommandozeilenargumente (Rezept 24) 왘 Eine optimal konfigurierbare Applikation ist zudem zugleich
über alle drei Techniken konfigurierbar (Rezept 25).
4.1.2 Lösung: Umgebungsvariablen mit der Node.js-API auslesen Unter Node.js werden Umgebungsvariablen über das Objekt process.env verwaltet, auf das sowohl lesend als auch schreibend zugegriffen werden kann. Listing 4.1 zeigt ein Beispiel für den lesenden Zugriff: In diesem Beispiel wird über das »http«-Modul ein einfacher Webserver erstellt (siehe auch Rezept 54, »Einen HTTP-Server implementieren«), wobei der zu verwendende Port über eine Umgebungsvariable definiert werden kann. Ist keine entsprechende Umgebungsvariable definiert, wird der Default-Wert »8080« verwendet (dafür sorgt das logische ODER ||). In der Funktion connectDatabase() werden zudem drei weitere Umgebungsvariablen ausgelesen (wobei die Funktion nur zu Demonstrationszwecken enthalten ist und keine wirkliche Logik enthält). const http = require('http'); const const const const
PORT = process.env.PORT || 8080; DB_HOST = process.env.DB_HOST || 'localhost'; DB_USER = process.env.DB_USER; DB_PASS = process.env.DB_PASS;
const connectDatabase = () => { console.log(`Connecting to database at ${DB_HOST}`); // Die folgenden beiden Zeilen nur zu Demonstrationszwecken console.log(`Username: ${DB_USER}`);
132
4.1
Rezept 22: Applikationen konfigurieren über Umgebungsvariablen
console.log(`Password: ${DB_PASS}`); }; const app = http.createServer((request, response) => response.send('Hello World') ); app.listen(PORT, () => { connectDatabase(); console.log(`Server is running on port ${PORT}`); }); Listing 4.1 Verwenden von Umgebungsvariablen unter Node.js
Kopieren Sie den Code, und speichern Sie ihn innerhalb Ihres Projekts unter src/server.js. Rufen Sie anschließend die Anwendung wie folgt auf: $ node src/server.js
Da noch keine Umgebungsvariablen definiert sind, verwendet die Applikation jeweils die Standardwerte. Die Ausgabe lautet daher: Connecting to database at localhost Username: undefined Password: undefined Server is running on port 8080
Stoppen Sie nun die Anwendung, und definieren Sie die in der Applikation verwendeten Umgebungsvariablen. Unter Linux und macOS verwenden Sie dazu den Befehl export: $ $ $ $
export export export export
PORT=8081 DB_HOST=127.0.0.1 DB_USER=admin DB_PASS=secret
Unter Windows verwenden Sie dagegen den Befehl set: $ $ $ $
set set set set
PORT=8081 DB_HOST=127.0.0.1 DB_USER=admin DB_PASS=secret
Starten Sie anschließend die Applikation erneut, werden die Werte aus den Umgebungsvariablen gelesen und entsprechend ausgegeben:
133
4
Konfiguration und Internationalisierung
$ node src/server.js Connecting to database at 127.0.0.1 Username: admin Password: secret Server is running on port 8081
Der Einfachheit halber lassen sich Umgebungsvariablen auch direkt beim Starten einer Node.js-Applikation angeben, und zwar indem Sie diese dem Befehl node voranstellen: $ PORT=8082 DB_HOST=127.0.0.1 DB_USER=root DB_PASS=12345 node src/server.js Connecting to database at localhost Username: root Password: 12345 Server is running on port 8082
Praktischer als das Definieren von Umgebungsvariablen per Kommandozeile ist allerdings die Verwendung einer Konfigurationsdatei, in der die Umgebungsvariablen definiert werden. Wie das funktioniert, zeige ich Ihnen im nächsten Abschnitt.
4.1.3 Lösung: Umgebungsvariablen über .env-Datei definieren Ein Package, das ich Ihnen für die Definition und das Verwenden von Umgebungsvariablen empfehlen kann, ist das Package »dotenv« (https://github.com/motdotla/dotenv). Der Vorteil: Umgebungsvariablen können in Form von Schlüssel/Wert-Paaren bequem über eine Konfigurationsdatei .env definiert werden, die dann von »dotenv« eingelesen und entsprechend am Objekt process.env gesetzt werden. Zudem kann die Konfigurationsdatei relativ schnell zwischen Entwicklern ausgetauscht werden und nach den eigenen Wünschen lokal angepasst werden.
Hinweis Beachten Sie aber, dass Sie .env-Dateien nicht in Ihr Versionskontrollsystem hochladen sollten. So vermeiden Sie, dass sensible Daten wie bspw. Zugangsdaten für Datenbanken in falsche Hände geraten. Ergänzen Sie gegebenenfalls einen entsprechenden Eintrag in der .gitignore-Datei Ihres Projektes.
Das Package »dotenv« lässt sich über folgenden Befehl installieren: $ npm install dotenv
Wie Sie das Package verwenden, sehen Sie in Listing 4.2. Prinzipiell müssen Sie lediglich das Package über require() einbinden und die Funktion load() aufrufen. Standardmäßig sucht »dotenv« dann im Wurzelverzeichnis des jeweiligen Projekts nach der Datei .env und liest die dort definierten Umgebungsvariablen ein.
134
4.1
Rezept 22: Applikationen konfigurieren über Umgebungsvariablen
const http = require('http'); if (process.env.NODE_ENV !== 'production') { // Ausnahmsweise: require() mitten im Code require('dotenv').load(); } const const const const
PORT = process.env.PORT || 8080; DB_HOST = process.env.DB_HOST || 'localhost'; DB_USER = process.env.DB_USER; DB_PASS = process.env.DB_PASS;
const connectDatabase = () => { console.log(`Connecting to database at ${DB_HOST}`); // Die folgenden beiden Zeilen nur zu Demonstrationszwecken console.log(`Username: ${DB_USER}`); console.log(`Password: ${DB_PASS}`); }; const app = http.createServer((request, response) => response.send('Hello World') ); app.listen(PORT, () => { connectDatabase(); console.log(`Server is running on port ${PORT}`); }); Listing 4.2 Verwenden von Umgebungsvariablen mit »dotenv«
Die Umgebungsvariable NODE_ENV Wenn Sie das »dotenv«-Package nicht im Produktiveinsatz verwenden möchten, können Sie dies übrigens, wie in Listing 4.2 gezeigt, über die Umgebungsvariable process.env.NODE_ENV sicherstellen. Dieser Variablen kommt unter Node.js eine besondere Bedeutung zu: Über sie lässt sich definieren, in welcher Umgebung eine Node.js-Anwendung ausgeführt wird. Entsprechend kann sie verschiedene Werte annehmen, wie bspw. »development«, »staging«, »production« oder »testing«. Frameworks wie Express (https://expressjs.com), SailsJS (https://sailsjs.com) oder Mongoose (https://mongoosejs.com) nutzen diese Angabe dann, um ihr Verhalten je nach Umgebung entsprechend anzupassen. Beispielsweise sind die Log-Ausgaben unter »development« umfangreicher als unter »production«.
135
4
Konfiguration und Internationalisierung
Kopieren Sie sich den Code aus Listing 4.2, und speichern Sie ihn unter src/server-dotenv.js. Legen Sie außerdem im Wurzelverzeichnis des Projekts eine .env-Datei mit folgendem Inhalt an: PORT = 8081 DB_HOST = 127.0.0.1 DB_USER = admin DB_PASS = secret
Rufen Sie nun die Anwendung wie folgt auf: $ node src/server-dotenv.js
Dann sollte die Ausgabe wie folgt lauten: Connecting to database at 127.0.01 Username: admin Password: secret Server is running on port 8081
Hinweis Achten Sie beim Aufruf darauf, dass Sie die Anwendung aus dem Wurzelverzeichnis des Projekts aufrufen. Ansonsten kann der Pfad zur .env-Datei nicht richtig aufgelöst werden. Beachten Sie auch, dass durch »dotenv« bereits existierende Umgebungsvariablen nicht überschrieben werden. Wenn Sie also noch die Umgebungsvariablen gesetzt haben, werden die Werte aus diesen Umgebungsvariablen gelesen und nicht aus der gerade erstellten .env-Datei.
Wenn Sie Ihren bestehenden Code nicht anpassen möchten, sprich das »dotenv«Package nicht direkt im Code einbinden möchten, können Sie dies auch beim Starten der Anwendung über den Zusatz -r dotenv/config dynamisch machen. Auf diese Weise bleibt Ihr Code frei von diesbezüglichen Anpassungen. $ node -r dotenv/config src/server.js Connecting to database at localhost Username: admin Password: secret Server is running on port 8081
Merke: Packages beim Starten laden Der Parameter -r (bzw. die Langform --require) sorgt dafür, dass das als weiterer Parameter übergebene Package beim Starten einer Node.js-Applikation dynamisch geladen wird, ohne dass Sie das Package per require() im Code einbinden müssen.
136
4.2 Rezept 23: Applikationen konfigurieren über Konfigurationsdateien
4.1.4 Ausblick Eine Applikation über Umgebungsvariablen konfigurierbar zu machen gehört mittlerweile zum guten Stil und erlaubt es Ihnen, Ihre Applikation relativ einfach und dynamisch zu konfigurieren. Jedes Mal, wenn Sie innerhalb einer Applikation Konstanten verwenden (bspw. Verbindungseinstellungen zu Datenbanken oder Webservices), sollten Sie sich genau überlegen, ob es nicht Sinn ergibt, den Wert der Konstanten auch über Umgebungsvariablen konfigurierbar zu machen. Darüber hinaus ist es sinnvoll, Applikationen auch über Konfigurationsdateien konfigurierbar zu machen. Wie das funktioniert, schauen wir uns im nächsten Rezept an.
4.2 Rezept 23: Applikationen konfigurieren über Konfigurationsdateien Sie möchten Ihre Applikation über Konfigurationsdateien konfigurierbar machen.
4.2.1 Lösung: Konfigurationsdateien mit JSON Neben der Konfiguration über Umgebungsvariablen, wie im vorherigen Rezept gezeigt, lässt sich die Konfiguration einer Applikation auch über Konfigurationsdateien vornehmen. Ansatzweise haben Sie dies bereits am Beispiel von .env-Dateien im vorherigen Rezept gesehen, dort allerdings nur als Mittel zum Zweck, die Umgebungsvariablen an zentraler Stelle definieren zu können. Komplexere Konfigurationen, die eine geschachtelte Struktur aufweisen, können mit .env-Dateien allerdings nicht definiert werden. In solchen Fällen müssen Sie auf andere Formate zurückgreifen. Am naheliegendsten ist dabei das JSON-Format. Es wird nativ von Node.js (bzw. JavaScript) unterstützt und ist aufgrund seiner Einfachheit sehr beliebt und verbreitet (und hat auch als Austauschformat in den vergangenen Jahren dem XML-Format ernsthaft Konkurrenz gemacht, wenn nicht sogar XML als Austauschformat verdrängt). Listing 4.3 zeigt ein Beispiel für eine JSON-Konfiguration: { "server": { "port": 8080 }, "database": { "host": "localhost", "user": "admin",
137
4
Konfiguration und Internationalisierung
"pass": "secret" } } Listing 4.3 Konfigurationsdatei in JSON
Bequemerweise lassen sich JSON-Dateien direkt über require() in eine Anwendung einbinden (Listing 4.4). Das Einlesen der entsprechenden Datei und das Parsen in ein JSON-Objekt übernimmt Node.js intern für Sie, sodass Sie anschließend direkt auf die definierten Konfigurationseigenschaften zugreifen können: const http = require('http'); const config = require('./config.json'); const const const const
PORT = config.server.port; DB_HOST = config.database.host; DB_USER = config.database.user; DB_PASS = config.database.pass;
const connectDatabase = () => { console.log(`Connecting to database at ${DB_HOST}`); // Die folgenden beiden Zeilen nur zu Demonstrationszwecken console.log(`Username: ${DB_USER}`); console.log(`Password: ${DB_PASS}`); }; const app = http.createServer((request, response) => response.send('Hello World') ); app.listen(PORT, () => { connectDatabase(); console.log(`Server is running on port ${PORT}`); }); Listing 4.4 Einlesen einer JSON-Konfiguration über »require()«
Sie sollten allerdings beachten, dass bei der Verwendung von require() der Caching Mechanism von Node.js aktiv wird: Dateien, die über require() eingebunden sind, werden nur beim ersten Mal vom Dateisystem geladen, alle weiteren Aufrufe greifen direkt auf den Cache zu. Mit anderen Worten: Die JSON-Datei wird über require() nur beim ersten Mal eingelesen. Wenn Sie aber die gleiche Konfiguration innerhalb einer Applikation an anderer Stelle über require() einlesen, werden die Daten dann aus dem Cache geladen. Dies kann in vielen Fällen ausreichend sein und dank des
138
4.2 Rezept 23: Applikationen konfigurieren über Konfigurationsdateien
Cachings auch genau das, was man möchte. Sollten Sie allerdings zur Laufzeit innerhalb der Applikation (oder von außerhalb) auch in die JSON-Konfigurationsdatei schreiben, werden diese Aktualisierungen nicht in den Cache übernommen und bei weiteren Ladevorgängen der Konfigurationsdatei nicht berücksichtigt. Möchten Sie dagegen, dass eine Konfigurationsdatei auch zur Laufzeit einer Anwendung aktualisiert werden kann, verwenden Sie besser das Modul »fs« aus der Node.js-StandardAPI (siehe Rezept 28), um die Datei jedes Mal aus dem Dateisystem zu lesen: const const const const const const ...
http = require('http'); fs = require('fs'); path = require('path'); configPath = path.join(__dirname, 'config.json'); content = fs.readFileSync(configPath); config = JSON.parse(content);
Listing 4.5 Einlesen einer JSON-Konfiguration über das »fs«-Modul
Hinweis Das Verwenden der Funktion readFileSync() aus dem »fs«-Modul eignet sich übrigens nur für das Einlesen von kleinen Dateien (für Konfigurationsdateien in der Regel der Fall). Größere Dateien sollten Sie dagegen mit der asynchronen Variante readFile() oder besser direkt über sogenannte Streams einlesen. Auf diese Möglichkeiten werde ich in Kapitel 5, »Dateisystem, Streams und Events«, in Rezept 28 und Rezept 30 näher eingehen.
4.2.2 Lösung: Konfigurationsdateien mit JavaScript Eine Einschränkung von JSON ist, dass die Konfigurationen nur statisch definiert werden können, eine weitere Einschränkung, dass keine Kommentare erlaubt sind. In dieser Hinsicht flexibler ist die Verwendung von Konfigurationsdateien direkt in JavaScript, in denen Sie die Konfiguration als Objekt definieren und über module.exports entsprechend exportieren: const config = { // Server-Konfiguration server: { port: 8080 }, // Datenbank-Konfiguration database: { host: 'localhost',
139
4
Konfiguration und Internationalisierung
user: 'admin', pass: 'secret' } }; module.exports = config; Listing 4.6 Konfigurationsdatei in JavaScript
Der Vorteil gegenüber JSON: Innerhalb einer JavaScript-Konfigurationsdatei sind Sie viel flexibler bezüglich der Definition der Konfigurationsdaten. So ist es z. B. relativ einfach möglich, innerhalb von JavaScript-Konfigurationen Daten dynamisch aus Umgebungsvariablen einzulesen, indem Sie (wie im vorherigen Rezept gesehen) auf das Objekt process.env zugreifen: const config = { server: { port: process.env.PORT || }, database: { host: process.env.DB_HOST user: process.env.DB_USER pass: process.env.DB_PASS } }; module.exports = config;
8080
|| 'localhost', || 'admin', || 'secret'
Listing 4.7 Einlesen von Umgebungsvariablen in JavaScript-Konfiguration
Ebenso wie JSON-Konfigurationen können Sie selbstverständlich auch JavaScriptKonfiguration wie gewohnt über require() einbinden: const http = require('http'); const config = require('./config'); const const const const
PORT = config.server.port; DB_HOST = config.database.host; DB_USER = config.database.user; DB_PASS = config.database.pass;
const connectDatabase = () => { console.log(`Connecting to database at ${DB_HOST}`); // Die folgenden beiden Zeilen nur zu Demonstrationszwecken console.log(`Username: ${DB_USER}`); console.log(`Password: ${DB_PASS}`); };
140
4.3
Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente
const app = http.createServer((request, response) => response.send('Hello World') ); app.listen(PORT, () => { connectDatabase(); console.log(`Server is running on port ${PORT}`); }); Listing 4.8 Einlesen einer JavaScript-Konfiguration über »require()«
4.2.3 Ausblick In diesem Rezept haben Sie gesehen, wie Sie Node.js-Applikationen mithilfe von Konfigurationsdateien konfigurieren können. Als Datenformate bieten sich dank der nativen Unterstützung JSON und JavaScript an. Aber auch andere Formate sind in diesem Zusammenhang stark verbreitet. In Kapitel 6, »Datenformate«, werde ich Ihnen diesbezüglich noch die Formate YAML, TOML und INI vorstellen und zeigen, wie sich diese Formate unter Node.js verarbeiten lassen. Doch zunächst schauen wir uns im nächsten Rezept an, wie man unter Node.js auf Kommandozeilenargumente zugreifen kann.
Verwandte Rezepte 왘 Rezept 42: YAML verarbeiten und generieren 왘 Rezept 43: TOML verarbeiten 왘 Rezept 44: INI verarbeiten und generieren
4.3 Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente Sie möchten eine Applikation über Kommandozeilenargumente konfigurierbar machen oder generell auf Kommandozeilenargumente zugreifen.
4.3.1 Lösung: auf Kommandozeilenargumente zugreifen über die Standard-Node.js-API Für den Zugriff auf Kommandozeilenargumente stellt Node.js über die Standard-API das process-Objekt zur Verfügung. Bei diesem Objekt handelt es sich um ein globales Objekt, das implizit in jeder Node.js-Anwendung zur Verfügung steht, ohne zuvor
141
4
Konfiguration und Internationalisierung
importiert werden zu müssen (https://nodejs.org/api/process.html). In der Eigenschaft argv dieses Objekts wiederum ist ein Array hinterlegt, das die gesamten Argumente enthält, die beim Starten der entsprechenden Anwendung übergeben wurden. An erster Stelle in diesem Array ist dabei der absolute Pfad der ausführbaren Datei enthalten, über die die Anwendung gestartet wurde (bspw. /usr/local/bin/ node), und an zweiter Stelle der absolute Pfad zu der JavaScript-Datei, die gestartet wurde. Erst an dritter Stelle beginnen die eigentlichen Argumente, die der jeweiligen Anwendung übergeben wurden: #!/usr/bin/env node process.argv.forEach((value, index) => { console.log(${index}: ${value}); }); Listing 4.9 Zugriff auf Kommandozeilenargumente
Ruft man dieses Programm z. B. mit dem Befehl node src/start.js nodejs is cool auf, lautet die Ausgabe wie folgt: 0: 1: 2: 3: 4:
/usr/local/bin/node /Users/philipackermann/workspace/nodejskochbuch/configuration/src/start.js nodejs is cool
Flags definieren Komplexere Kommandozeilenanwendungen ermöglichen es in der Regel, Argumente mithilfe von Flags anzugeben, die bspw. durch ein oder zwei vorangehende --Zeichen definiert werden. Für eine Kommandozeilenanwendung z. B., über die HTTPAnfragen gestellt werden sollen, würden entsprechende Parameter vermutlich wie folgt aussehen: $ node src/start-arguments.js --url http://localhost:8080/api/v1.0/users --method GET --headers "Accept: application/json"
Der Vorteil dieser Vorgehensweise ist, dass Nutzer beim Aufruf der jeweiligen Anwendung nicht auf die exakte Reihenfolge der Argumente achten müssen. Obigen Aufruf könnte man bspw. auch wie folgt abändern: $ node src/start-arguments.js --method GET --url http://localhost:8080/api/v1.0/users --headers "Accept: application/json"
142
4.3
Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente
Wenn Sie diese Flexibilität innerhalb Ihrer Kommandozeilenanwendung zur Verfügung stellen wollen, ist das unter Verwendung von process.argv relativ umständlich, weil Sie dazu über alle Argumente iterieren und die entsprechenden Werte den Parameternamen zuordnen müssten. Eine einfache Implementierung würde z. B. wie folgt aussehen: #!/usr/bin/env node const parameters = {}; let current; process.argv.forEach((value, index) => { if (value.startsWith('--')) { current = value.substring(2); } else { parameters[current] = value; } }); const { url = 'http://localhost', method = 'GET', body = '', headers = '' } = parameters; console.log(`Sending HTTP request URL: ${url} Method: ${method} Body: ${body} Headers: ${headers}`); Listing 4.10 Unterstützung von benannten Argumenten
Alternativ zu dem direkten Zugriff auf die Argumente über process.argv empfiehlt sich daher die Verwendung von Packages, die den Zugriff abstrahieren und auch komplexere Anwendungsfälle wie die eben gezeigten Flags vereinfachen. Beispiele hierfür sind »minimist« (https://github.com/substack/minimist), »node-optimist« (https:// github.com/substack/node-optimist), »yargs« (https://github.com/yargs/yargs) oder »commander« (https://github.com/tj/commander.js). Persönlich empfehle ich Ihnen die beiden letztgenannten, da sie kaum Wünsche offen lassen und zudem auf GitHub eine höhere Aktivität seitens der Entwickler aufweisen.
143
4
Konfiguration und Internationalisierung
Hinweis Die erste Zeile aus den vorherigen Listings wird aufgrund der vorangestellten Raute und des Ausrufezeichens (#!) auch als Shebang Line (oder auch Magic Line) bezeichnet (https://de.wikipedia.org/wiki/Shebang). Über sie lässt sich unter Unix-basierten Betriebssystemen ein Befehl definieren, der beim direkten Aufruf der jeweiligen Datei intern zum Ausführen der Datei verwendet wird. Wenn Sie diese Zeile weglassen würden, könnten Sie das entsprechende Node.jsProgramm nur über den Befehl node ausführen. Mit der Zeile #!/usr/bin/env node ist es dagegen auch möglich, die Datei direkt auszuführen. Voraussetzung hierfür ist allerdings, dass die Datei zuvor als ausführbar definiert wurde: $ chmod +x ./src/start-arguments.js $ ./src/start-arguments.js --url http://localhost:8080/api/v1.0/users --method GET --headers "Accept: application/json"
4.3.2 Lösung: auf Kommandozeilenargumente zugreifen über »yargs« Das Package »yargs« (https://github.com/yargs/yargs) vereinfacht den Zugriff auf Kommandozeilenargumente, indem es Ihnen ein Objekt zur Verfügung stellt, dessen Eigenschaften den (benannten) Argumenten mit den dazugehörigen Werten entsprechen. Installieren können Sie das Package für ein Projekt wie folgt: $ npm install yargs
Erstellen Sie anschließend eine Script-Datei start-yargs.js, und kopieren Sie den Inhalt aus Listing 4.11 hinein. #!/usr/bin/env node const yargs = require('yargs'); const { url = 'http://localhost', method = 'GET', body = '', headers = '' } = yargs.argv; console.log(`Sending HTTP request URL: ${url}
144
4.3
Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente
Method: ${method} Body: ${body} Headers: ${headers}`); Listing 4.11 Zugriff auf Kommandozeilenargumente mit »yargs«
Wie Sie in Listing 4.11 sehen können, enthält das Objekt yargs.argv die gesamten Argumente als gleichnamige Eigenschaften und bietet damit das von Haus an, was wir vorhin in Listing 4.10 von Hand implementiert hatten. Der Aufruf der Applikation dagegen ist der gleiche: $ node src/start-yargs.js \ --url http://localhost:8080/api/v1.0/users \ --method GET \ --headers "Accept: application/json" Sending HTTP request URL: http://localhost:8080/api/v1.0/users Method: GET Headers: Accept: application/json
4.3.3 Lösung: auf Kommandozeilenargumente zugreifen über »commander.js« Ein alternatives Package, das Ihnen ebenfalls beim Zugriff auf Kommandozeilenargumente hilft, ist das Package »commander.js« (https://github.com/tj/commander.js/). Über folgenden Befehl installieren Sie das Package für Ihr Projekt: $ npm install commander
Erstellen Sie anschließend eine Script-Datei (start-commander.js), und kopieren Sie den Inhalt aus Listing 4.11 hinein. #!/usr/bin/env node const program = require('commander'); program .version('1.0.0') .option('-u, --url [url]', 'The request URL') .option('-m, --method [method]', 'The HTTP method') .option('-b, --body [body]', 'The request body') .option('-h, --headers [headers]', 'The request headers') .parse(process.argv); const { url = 'http://localhost',
145
4
Konfiguration und Internationalisierung
method = 'GET', body = '', headers = '' } = program; console.log(`Sending HTTP request URL: ${url} Method: ${method} Body: ${body} Headers: ${headers}`); Listing 4.12 Zugriff auf Kommandozeilenargumente mit »commander.js«
Wie Sie in Listing 4.12 sehen, stellt das über require('commander') eingebundene Objekt program seine API in Form einer sogenannten Fluent API zur Verfügung (siehe Kasten), über die Sie die Konfiguration der Kommandozeilenanwendung vornehmen. Über den Aufruf option() definieren Sie dabei, welche Parameter die Anwendung akzeptiert. Dieser Methode übergeben Sie den Namen des jeweiligen Parameters (bzw. einen entsprechenden Shortcut, bspw. --url und -u), einen Platzhalter für das konkrete Argument (bspw. [url]) sowie eine Kurzbeschreibung. Über den Aufruf parse(), dem Sie die in process.argv enthaltenen Argumente übergeben, werden diese geparst, den zuvor definierten Parametern zugeordnet und dem Objekt program als gleichnamige Eigenschaften hinzugefügt. Anschließend können Sie einfach auf die entsprechenden Eigenschaften des Objekts program zugreifen.
Fluent APIs Unter einer Fluent API versteht man eine API, deren Methodenaufrufe jeweils ein Objekt zurückgeben (in der Regel immer das gleiche), auf dem erneut die API bzw. Methoden der API aufgerufen werden. Der Code wirkt dadurch flüssiger und leichter zu lesen, weil nicht bei jedem Methodenaufruf das jeweilige Objekt angegeben werden muss. Im Detail gehe ich auf das Thema Fluent APIs in meinem Buch »Professionell entwickeln mit JavaScript – Design, Patterns, Praxistipps« ein. Dort zeige ich u. a. auch, welche Techniken es gibt, um eine Fluent API zu erstellen.
Hilfe Basierend auf den über option() definierten Parametern, erzeugt »commander.js« praktischerweise direkt eine Hilfe. Aufrufen können Sie diese über folgenden Befehl. $ ./src/start-commander.js --help Usage: start-commander [options]
146
4.4
Rezept 25: Applikationen optimal konfigurierbar machen
Options: -V, -u, -m, -b, -h, -h,
--version --url [url] --method [method] --body [body] --headers [headers] --help
output the version number The request URL The HTTP method The request body The request headers output usage information
4.3.4 Ausblick Sowohl »yargs« als auch »commander.js« bieten deutlich mehr Features als den vereinfachten Zugriff auf Kommandozeilenargumente. Prinzipiell lassen sich mit beiden Packages auch komplette Kommandozeilenanwendungen implementieren. Darauf möchte ich an dieser Stelle aus Platzgründen jedoch nicht weiter eingehen. Stattdessen möchte ich Ihnen im nächsten Rezept ein Package vorstellen, mit dem sich Node.js-Applikationen optimal konfigurieren lassen. Optimal deswegen, weil es das Package sehr einfach ermöglicht, Konfigurationen über Konfigurationsdateien, über Umgebungsvariablen und über Kommandozeilenargumente zu definieren.
4.4 Rezept 25: Applikationen optimal konfigurierbar machen Sie möchten eine Node.js-Applikation optimal konfigurierbar machen, sprich diese über Umgebungsvariablen, Kommandozeilenargumente und Konfigurationsdateien konfigurierbar machen.
4.4.1 Lösung Wie in Rezept 22: Applikationen konfigurieren über Umgebungsvariablen erwähnt, gilt es als Best Practice, eine Applikation sowohl über Umgebungsvariablen als auch über Konfigurationsdateien und des Weiteren über Kommandozeilenargumente konfigurierbar zu machen. Prinzipiell haben Sie in den vorherigen drei Rezepten auch die entsprechenden Techniken bzw. Packages kennengelernt, um dieses Best Practice zu implementieren. Langfristig ist es allerdings sinnvoll, hierfür auf entsprechende Helfer-Packages zurückgreifen, bspw. »nconf« (https://github.com/indexzero/nconf ), »node-config« (https://github.com/lorenwest/node-config) oder »convict« (https://github.com/mozilla/node-convict).
147
4
Konfiguration und Internationalisierung
Im Folgenden möchte ich Ihnen Letzteres vorstellen, das Sie über folgenden Befehl installieren können: $ npm install convict
Anschließend binden Sie das Package wie gewohnt über require() ein und definieren über den Aufruf convict() die entsprechende Konfiguration (Listing 4.13). Als Parameter übergeben Sie dabei ein Objekt, welches das Schema für die Konfiguration definiert. Über dieses Schema können Sie exakt bestimmen, woher die jeweilige Konfiguration geladen wird und welche Kriterien sie erfüllen soll. So können Sie z. B. über default den Standardwert einer Konfigurationsvariablen definieren, über env eine entsprechende Umgebungsvariable, aus welcher der Wert gelesen wird, und über arg den Namen eines Kommandozeilenarguments, das von »convict« dann entsprechend für die jeweilige Konfigurationsvariable verwendet wird. Die Angabe sensitive sorgt zudem dafür, dass bei der Ausgabe der Konfiguration über toString() für den Wert der jeweiligen Variable der Platzhalter »[Sensitive]« verwendet wird, was wiederum verhindert, dass sensible Informationen wie Passwörter oder API-Keys ungewollt auf die Konsole bzw. in Log-Dateien geschrieben werden. Nach der Definition des Schemas laden Sie über den Aufruf von loadFile() schließlich die konkrete Konfigurationsdatei im JSON-Format. »convict« erstellt dann eine Konfiguration, in der die Daten aus dieser JSON-Datei, eventuell vorhandene Umgebungsvariablen und Kommandozeilenargumente sowie die im Schema definierten Default-Werte zusammenfügt sind. Über die Methode validate() haben Sie zudem die Möglichkeit, die eingelesene Konfiguration im Abgleich mit dem Schema auf Gültigkeit hin zu überprüfen. const convict = require('convict'); const path = require('path'); // 1.) Definition des Konfigurationsschemas const config = convict({ server: { port: { doc: 'The server port', format: 'port', default: 'localhost', env: 'PORT', arg: 'port' } }, database: { host: { doc: 'Database host',
148
4.4
Rezept 25: Applikationen optimal konfigurierbar machen
format: '*', default: 'localhost' }, user: { doc: 'Username', format: String, default: 'admin' }, pass: { doc: 'Password', format: String, default: 'secret', sensitive: true } } }); / 2.) Laden der Konfigurationsdatei config.loadFile(path.join(__dirname, config.json)); // 3.) Validierung gegen Konfigurationsschema config.validate({ allowed: 'strict' }); module.exports = config; Listing 4.13 Konfigurationsdatei mit »convict«
Um das Package in Aktion zu sehen, speichern Sie den Code aus Listing 4.13 in einer Datei server.js. Erstellen Sie außerdem eine Datei config.json mit folgendem Inhalt: { "server": { "port": 8080 }, "database": { "host": "127.0.0.1", "pass": "12345" } } Listing 4.14 Eine einfache Konfigurationsdatei in JSON
Wenn Sie nun die Applikation starten, sollte die Ausgabe wie folgt aussehen, da die Konfiguration aus der JSON-Datei und den Default-Werten gebildet wird. Genauer
149
4
Konfiguration und Internationalisierung
heißt dies, die Werte »127.0.0.1« (Datenbank-Hostname), »12345« (Datenbank-Passwort) und »port« (Server-Port) werden aus der Konfigurationsdatei gelesen, der Wert »admin« (Datenbank-Nutzer) dagegen aus den Standardwerten. $ node server.js Connecting to database at 127.0.0.1 Username: admin Password: 12345 Server is running on port 8080
Definieren Sie nun zusätzlich (entweder über einen separaten Befehl oder direkt beim Aufruf) für die Konfigurationsvariable server.port eine entsprechende Umgebungsvariable, und rufen Sie das Programm erneut auf: $ PORT=8081 node server.js
Wie in der anschließenden Ausgabe zu sehen, wird nun der Wert für den Port von der Umgebungsvariable verwendet: Connecting to database at 127.0.0.1 Username: admin Password: 12345 Server is running on port 8081
Wenn Sie jetzt beim Aufruf des Programms stattdessen ein Kommandozeilenargument angeben, wird der Wert für den Port aus diesem verwendet: $ node server.js --port 8082 Connecting to database at 127.0.0.1 Username: admin Password: 12345 Server is running on port 8082
4.4.2 Ausblick Zusammenfassend bietet Ihnen ein Package wie »convict« von Haus aus die größte Flexibilität hinsichtlich der Konfiguration von Node.js-Applikationen. Damit geben Sie den Nutzern Ihrer Applikation die Möglichkeit, die Konfiguration flexibel über Dateien, Umgebungsvariablen und Kommandozeilenargumente zu steuern. Im den nächsten beiden Rezepten zeige ich Ihnen, wie sich Node.js-Applikationen zudem im Hinblick auf Internationalisierung konfigurieren lassen.
Verwandte Rezepte 왘 Rezept 22: Applikationen konfigurieren über Umgebungsvariablen 왘 Rezept 23: Applikationen konfigurieren über Konfigurationsdateien
150
4.5
Rezept 26: Mehrsprachige Applikationen erstellen
왘 Rezept 24: Applikationen konfigurieren über Kommandozeilenargumente 왘 Rezept 42: YAML verarbeiten und generieren 왘 Rezept 43: TOML verarbeiten 왘 Rezept 44: INI verarbeiten und generieren
4.5 Rezept 26: Mehrsprachige Applikationen erstellen Sie möchten mehrsprachige Applikationen erstellen.
4.5.1 Exkurs: i18n Internationalisierung (bzw. die Kurzform i18n, die für das i und das letzte n sowie die dazwischenliegenden 18 Buchstaben in dem englischen Wort Internationalization steht) bezeichnet das Vorgehen, eine Applikation so zu strukturieren, dass sie ohne großen Aufwand an verschiedene Sprachen (oder noch allgemeiner: an verschiedene Regionen) angepasst werden kann. Das betrifft die Aspekte Sprachdateien, Zahlenwerte, Datums- und Zeitangaben sowie Locales, die ich im Folgenden beschreibe, bevor ich auf die weitere Einteilung eingehe.
Sprachdateien Für die Anpassung an verschiedene Sprachen werden Textbausteine einer Applikation pro unterstützte Sprache bzw. Region in separaten Dateien als Schlüssel/WertPaare vorgehalten und innerhalb der Applikation über den jeweiligen Schlüssel referenziert. Abhängig von der vom Nutzer eingestellten Sprache werden dann die für diese Sprache definierten Textbausteine geladen.
Zahlenwerte, Datums- und Zeitangaben Neben solchen Sprachbausteinen muss hinsichtlich der Internationalisierung auch die Formatierung von Zahlenwerten, Datums- und Zeitangaben berücksichtigt werden, da sich je nach Sprache bzw. Region auch hier die Formatierung unterscheidet: In Deutschland steht bei Datumsangaben z. B. zuerst der Tag, dann der Monat, dann das Jahr, jeweils mit einem Punkt voneinander getrennt (z. B. 12.08.2017). In den USA dagegen steht an erster Position der Monatsname, gefolgt von Tag und Jahr, wobei das Slash-Symbol als Trennzeichen verwendet wird (z. B. 08/12/2017). In Großbritannien wiederum wird dagegen eine Anordnung wie in Deutschland verwendet, als Trennzeichen aber wie bei der amerikanischen Schreibweise das Slash-Symbol (z. B. 12/08/2017).
151
4
Konfiguration und Internationalisierung
Bei Zahlenwerten oder Währungsangaben ist es ähnlich: Während in Deutschland der Punkt als Tausendertrennzeichen verwendet wird, als Trennzeichen der Nachkommastellen das Komma und das Währungssymbol hinter dem Zahlenwert steht (bspw. 123.456,79 €), verhält es sich in den USA genau umgekehrt: Als Tausendertrennzeichen wird dort das Komma verwendet, als Nachkommatrennzeichen der Punkt, und das Währungssymbol steht vor dem Zahlenwert (bspw. € 123,456.79).
Locales Das Festlegen von Sprache bzw. einer Region, in der eine bestimmte Sprache gesprochen wird, geschieht über sogenannte Locales. Dabei handelt es sich um Identifier (auch Language Tags genannt), die genau definieren, welche Sprache verwendet werden soll und wie Zahlenwerte, Datums- und Zeitangaben formatiert werden sollen. Generell besteht ein Language Tag aus durch Minuszeichen getrennten Buchstabenund Zahlenkombinationen, sogenannten Sub Tags. An erster Stelle steht das Language Sub Tag, bspw. »de« für Deutsch, »en« für Englisch oder »it« für Italienisch. Alle weiteren Sub Tags sind optional, bspw. das Region Sub Tag: Das Locale »de-DE« z. B. steht für Deutsch, wie es in Deutschland gesprochen wird, das Locale »de-AT« dagegen für Deutsch, wie es in Österreich gesprochen wird, das Locale »en-US« definiert Englisch, wie es in den USA gesprochen wird, und das Locale »en-UK« Englisch, wie es in Großbritannien gesprochen wird (weitere Informationen zu Locales und deren Aufbau finden Sie im IETF-Dokument BCP47 unter https://tools.ietf.org/html/bcp47).
Einteilung In diesem Rezept möchte ich Ihnen die sogenannte Internationalization API vorstellen und Ihnen zeigen, wie Sie mithilfe dieser API (und jeweils unter Berücksichtigung von i18n) Datums- und Zeitangaben sowie Zahlenwerte formatieren und Zeichenketten miteinander vergleichen können. Im nächsten Rezept gehe ich dann darauf ein, wie Sie eine Node.js-Applikation mit Sprachdateien konfigurierbar machen und abhängig von der Sprache (bzw. dem Locale) unterschiedliche Sprachdateien in die Applikation laden.
4.5.2 Die Internationalization API Die ECMAScript 2017 Internationalization API (https://tc39.github.io/ecma402/) adressiert die in der Einleitung geschilderte Problematik und ermöglicht die sprachabhängige Formatierung von Zahlenwerten, Datums- und Zeitangaben sowie den sprachabhängigen Vergleich von Zeichenketten. Die API orientiert sich an bestehenden Internationalization APIs wie denen des .NET Frameworks oder der Java Internationalization API und wird sowohl im Browser als auch unter Node.js unterstützt (https://nodejs.org/api/intl.html).
152
4.5
Rezept 26: Mehrsprachige Applikationen erstellen
Den Einstiegspunkt in die Internationalization API bildet das globale Objekt Intl, das folgende drei Typen zur Verfügung stellt: 1. Collator: Dieser Typ ermöglicht den Vergleich von Zeichenketten unter Berücksichtigung von i18n (Abschnitt 4.5.3). 2. DateTimeFormat: Der Typ DateTimeFormat ermöglicht die Formatierung von Datums- und Zeitangaben unter Berücksichtigung von i18n (Abschnitt 4.5.4). 3. NumberFormat: Dieser Typ ermöglicht die Formatierung von Zahlenwerten unter Berücksichtigung von i18n (Abschnitt 4.5.5).
4.5.3 Lösung: Vergleich von Zeichenketten Für den Vergleich von Zeichenketten steht Ihnen der Typ Collator zur Verfügung, über dessen Methode compare() Sie zwei Zeichenketten miteinander vergleichen können (Listing 4.15). Die Methode gibt dabei wie üblich für Vergleichsfunktionen einen von drei Zahlenwerten zurück, je nachdem ob die erste Zeichenkette in der Sortierung hinter der zweiten Zeichenkette eingeordnet wird (Wert 1), davor eingeordnet wird (Wert –1) oder ob beide Zeichenketten als gleichwertig erkannt werden. const nameCollator = new Intl.Collator('de-DE'); console.log(nameCollator.compare('Mustermann', 'Meier')); // 1 console.log(nameCollator.compare('Meier', 'Mustermann')); // -1 console.log(nameCollator.compare('Meier', 'Meier')); // 0 Listing 4.15 Vergleich von Zeichenketten unter Berücksichtigung von Lokalisierungsinformationen
Über die Eigenschaft sensitivity des Konfigurationsobjekts, das Sie der Konstruktorfunktion Collator optional als zweiten Parameter übergeben können (Listing 4.16), ist es möglich, die Art und Weise, wie zwei Zeichenketten miteinander verglichen werden, weiter anzupassen. Der Wert base bspw. sorgt dafür, dass alle Zeichen, die die gleiche Basis haben (z. B. die Buchstaben á, a und A), als gleichwertig interpretiert werden: const nameCollator = new Intl.Collator('de-DE'); const nameCollatorBase= new Intl.Collator('de-DE', { sensitivity: 'base' } ); console.log(nameCollator.compare('Mueller', 'mueller')); // Rückgabewert 1, da "M" und "m" als verschieden interpretiert // werden
153
4
Konfiguration und Internationalisierung
console.log(nameCollatorBase.compare('Mueller', 'mueller')); // Rückgabewert 0, da "M" und "m" als gleich interpretiert werden Listing 4.16 Vergleich von Zeichenketten unter Berücksichtigung von Lokalisierungsinformationen
Sortierung von Zeichenketten Praktischerweise lässt sich die compare()-Methode auch für die Sortierung von Arrays einsetzen. Dazu übergeben Sie die Methode einfach, wie in Listing 4.17 gezeigt, der Array-Methode sort() als Parameter: const names = [ 'Mustermann, Max', 'Müller, Max', 'Mustermann, Moritz', 'Mueller, Moritz', 'Meier, Petra', 'Meier, Peter' ]; const nameCollator = new Intl.Collator('de-DE', { usage: 'sort' } ); const sorted = names.sort(nameCollator.compare); console.log(sorted); // [ // "Meier, Peter", // "Meier, Petra", // "Mueller, Moritz", // "Müller, Max", // "Mustermann, Max", // "Mustermann, Moritz" //] Listing 4.17 Sortierung mit »Intl.Collator«
Über den Kennzeichner u können Sie innerhalb eines Locales zudem sogenannte Unicode-Extensions definieren, wobei jeweils Schlüssel/Wert-Paare anzugeben sind: Listing 4.18, das auf Listing 4.17 aufbaut, zeigt bspw., wie mithilfe des Locales »de-DE-uco-phonebk« eine Sortierung wie im Telefonbuch erreicht wird, sprich ä wie ae interpretiert wird, ö wie oe und ü wie ue:
154
4.5
Rezept 26: Mehrsprachige Applikationen erstellen
const names = [ 'Mustermann, Max', 'Müller, Max', 'Mustermann, Moritz', 'Mueller, Moritz', 'Meier, Petra', 'Meier, Peter' ]; const phonebookCollator = collator( 'de-DE-u-co-phonebk', { usage: 'sort' } ); const sorted = names.sort(phonebookCollator.compare); console.log(sorted); // [ // "Meier, Peter", // "Meier, Petra", // "Müller, Max", // "Mueller, Moritz", // "Mustermann, Max", // "Mustermann, Moritz" //] Listing 4.18 Sortierung wie im Telefonbuch
Insgesamt bietet die Internationalization API bzw. die Intl.Collactor-Klasse verschiedene Konfigurationsmöglichkeiten für den Vergleich von Zeichenketten. Eine Übersicht dazu liefert Tabelle 4.1: Eigenschaft
Events
localeMatcher
Der zu verwendende Matching-Algorithmus. Kann entweder den Wert »lookup« oder den Wert »best fit« haben. Ersterer definiert den in unter https://tools.ietf.org/html/rfc4647#section-3.4 spezifizierten Algorithmus, letzterer liefert den besten Treffer für die jeweilige Laufzeitumgebung.
Tabelle 4.1 Übersicht über die Konfigurationsmöglichkeiten von »Intl.Collator«
155
4
Konfiguration und Internationalisierung
Eigenschaft
Events
usage
Angabe darüber, ob der Vergleich durch den Collator für die Sortierung von Zeichenketten oder für die Suche nach Zeichenketten verwendet werden soll. Mögliche Werte sind entsprechend »sort« und »search«.
sensitivity
Angabe darüber, welche Zeichen als ungleich erachtet werden sollen. Mögliche Werte sind »base«, »accent«, »case« und »variant«.
ignorePunctuation
Boolesche Angabe darüber, ob Satzzeichen ignoriert werden sollen.
numeric
Boolesche Angabe darüber, ob Zeichenketten numerisch verglichen werden sollen.
caseFirst
Boolesche Angabe darüber, ob Kleinbuchstaben oder Großbuchstaben in der Sortierung vorn stehen.
Tabelle 4.1 Übersicht über die Konfigurationsmöglichkeiten von »Intl.Collator« (Forts.)
4.5.4 Lösung: Formatierung von Datums- und Zeitangaben Für die Formatierung von Datums- und Zeitangaben verwenden Sie den Typ DateTimeFormat bzw. dessen Methode format(), die eine Objektinstanz von Date als Parameter erwartet und eine den Konfigurationen entsprechende Zeichenkette zurückgibt, die das Datumsobjekt repräsentiert (Listing 4.19). const date = new Date(Date.UTC(2016, 8, 15, 8, 0, 0)); // 2016-9-15 console.log(new Intl.DateTimeFormat('de').format(date)); // 9/15/2016 console.log(new Intl.DateTimeFormat('en').format(date)); // 2016-9-15 10:00:00 Listing 4.19 Formatierung von Datums- und Zeitangaben
Alternativ dazu können Sie die Methoden toLocaleString(), toLocaleDateString() und toLocaleTimeString() direkt an der entsprechenden Date-Objektinstanz verwenden: const date = new Date(Date.UTC(2016, 8, 15, 8, 0, 0)); console.log(date.toLocaleString('de')); // 9/15/2016, 10:00:00 AM console.log(date.toLocaleString('en'));
156
4.5
Rezept 26: Mehrsprachige Applikationen erstellen
// 2016-9-15 console.log(date.toLocaleDateString('de')); // 9/15/2016 console.log(date.toLocaleDateString('en')); // 10:00:00 console.log(date.toLocaleTimeString('de')); // 10:00:00 AM console.log(date.toLocaleTimeString('en')); Listing 4.20 Formatierung von Datums- und Zeitangaben über »Date«-Methoden
Darüber hinaus kann dem Konstruktor von DateTimeFormat auch ein Konfigurationsobjekt übergeben werden, über das weitere Eigenschaften der Formatierung beeinflusst werden können (Details siehe Tabelle 4.2). console.log(new Intl.DateTimeFormat('de', { weekday: 'long', era: 'long', year: '2-digit', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', timeZoneName: 'long' }).format(date)); // Donnerstag, 15. 09 16 n. Chr., // 10:00:00 Mitteleuropäische Sommerzeit Listing 4.21 Anpassen der Formatierung über weitere Konfigurationseigenschaften
Eigenschaft
Events
localeMatcher
Der zu verwendende Matching-Algorithmus.
timeZone
Die zu verwendende Zeitzone.
hour12
Boolesche Angabe darüber, ob 12 Stunden oder 24 Stunden als Basis zugrunde gelegt werden sollen.
formatMatcher
Der zu verwendende Matching-Algorithmus.
Tabelle 4.2 Übersicht über die Konfigurationsmöglichkeiten von »Intl.DateTimeFormat«
157
4
Konfiguration und Internationalisierung
Eigenschaft
Events
weekday
Angabe zur Formatierung des Wochentags. Mögliche Werte sind »narrow«, »short« und »long«.
era
Angabe zur Formatierung des Zeitalters. Mögliche Werte sind »narrow«, »short« und »long«.
year
Angabe zur Formatierung des Jahres. Mögliche Werte sind »numeric« und »2-digit«.
month
Angabe zur Formatierung des Monats. Mögliche Werte sind »numeric«, »2-digit«, »narrow« und »short«.
day
Angabe zur Formatierung des Tages. Mögliche Werte sind »numeric« und »2-digit«.
hour
Angabe zur Formatierung der Stunden. Mögliche Werte sind »numeric« und »2-digit«.
minute
Angabe zur Formatierung der Minuten. Mögliche Werte sind »numeric« und »2-digit«.
second
Angabe zur Formatierung der Sekunden. Mögliche Werte sind »numeric« und »2-digit«.
timeZoneName
Angabe zur Formatierung der Zeitzone. Mögliche Werte sind »short« und »long«.
Tabelle 4.2 Übersicht über die Konfigurationsmöglichkeiten von »Intl.DateTimeFormat« (Forts.)
4.5.5 Lösung: Formatierung von Zahlenwerten Die Formatierung von Zahlenwerten funktioniert vom Prinzip her ähnlich wie die Formatierung von Datums- und Zeitangaben: Auch der Konstruktor von NumberFormat erwartet als ersten Parameter das Locale sowie optional als zweiten Parameter ein Konfigurationsobjekt zur weiteren Verfeinerung der Formatierung (Details siehe Tabelle 4.3). So können Sie z. B. bei Währungsbeträgen über die Eigenschaft currency die Währung und über die Eigenschaft minimumFractionDigits bzw. die Eigenschaft maximumFractionDigits die minimale und maximale Anzahl an Nachkommastellen definieren: const number = 123456.789; console.log( new Intl.NumberFormat('de-DE', {
158
4.5
Rezept 26: Mehrsprachige Applikationen erstellen
style: 'currency', currency: 'EUR' } ).format(number) ); // 123.456,79 € console.log( new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' } ).format(number) ); // €123,456.79 console.log( new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'USD' } ).format(number) ); // 123.456,79 $ console.log( new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' } ).format(number) ); // $123,456.79 console.log( new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR', maximumSignificantDigits: 5 } ).format(number) );
159
4
Konfiguration und Internationalisierung
// 123.460 € console.log( new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR', minimumFractionDigits: 5 } ).format(number) ); // 123.456,78900 € Listing 4.22 Formatierung von Zahlenwerten
Eigenschaft
Events
localeMatcher
Der zu verwendende Matching-Algorithmus.
style
Der zu verwendende Formatierungsstil. Zur Auswahl stehen »decimal« für normale Zahlenformatierung, »currency« für Währungsformatierung und »percent« für Prozentangaben.
currency
Die bei der Währungsformatierung zu verwendende Währung, bspw. »EUR« für Euro oder »USD« für USDollar.
currencyDisplay
Angabe darüber, wie bei der Währungsformatierung die Währung dargestellt werden soll. Mögliche Werte sind »symbol« für die Verwendung von Symbolen, »code« für den entsprechenden ISO-Währungscode oder »name« für den Namen der Währung (»Euro«, »Dollar«).
useGrouping
Boolesche Angabe darüber, ob Trennzeichen (wie bspw. Tausendertrennzeichen) verwendet werden sollen (z. B. »1.000.000«).
minimumIntegerDigits
Minimale Anzahl der Stellen, die eine Zahl bei der Formatierung haben soll. Verfügt eine Zahl nicht über diese Mindestanzahl, wird – von vorn beginnend – mit Nullen aufgefüllt.
Tabelle 4.3 Übersicht über die Konfigurationsmöglichkeiten von »Intl.NumberFormat«
160
4.6
Rezept 27: Sprachdateien verwenden
Eigenschaft
Events
minimumFractionDigits
Minimale Anzahl der Nachkommastellen, die eine Zahl bei der Formatierung haben soll. Verfügt eine Zahl nicht über diese Mindestanzahl, wird – von der letzten Ziffer ausgehend – mit Nullen aufgefüllt.
maximumFractionDigits
Maximale Anzahl der Nachkommastellen, die eine Zahl bei der Formatierung haben soll. Verfügt eine Zahl über mehr Stellen, wird entsprechend gerundet.
minimumSignificantDigits
Minimale Anzahl der signifikanten Stellen, die eine Zahl bei der Formatierung haben soll. Verfügt eine Zahl nicht über diese Mindestanzahl, wird – von der letzten Ziffer ausgehend – mit Nullen aufgefüllt.
maximumSignificantDigits
Maximale Anzahl der signifikanten Stellen, die eine Zahl bei der Formatierung haben soll. Verfügt eine Zahl über mehr signifikante Stellen, wird entsprechend gerundet.
Tabelle 4.3 Übersicht über die Konfigurationsmöglichkeiten von »Intl.NumberFormat« (Forts.)
4.5.6 Ausblick In diesem Rezept haben Sie gesehen, wie Sie abhängig von i18n-Einstellungen Zeichenketten vergleichen sowie Datums- und Zeitangaben sowie Zahlenwerte formatieren können. Im nächsten Rezept zeige ich Ihnen, wie Sie abhängig von i18n-Einstellungen Sprachdateien in eine Applikation laden.
4.6 Rezept 27: Sprachdateien verwenden Sie möchten die Texte einer Applikation in Sprachdateien verwalten, um diese abhängig von der gewählten Sprache laden und damit die Applikation mehrsprachig konfigurieren zu können.
4.6.1 Verwenden von Sprachdateien mit »i18n« Für das Verwalten von Textbausteinen in Sprachdateien bietet die Internationalization API leider keinen Support an. Allerdings stehen Ihnen ausgereifte Bibliotheken zur Verfügung, die Ihnen diesbezüglich die Arbeit erleichtern. Ein Beispiel hierfür ist das Package »i18n«, das Sie wie folgt installieren: $ npm install i18n
161
4
Konfiguration und Internationalisierung
Legen Sie anschließend in Ihrem Projekt ein Verzeichnis locales an, und speichern Sie dort die beiden folgenden JSON-Sprachdateien als Dateien de.json und en.json. { "Greeting": "Hallo Welt", "Message": "Dies ist ein Beispiel für Internationalisierung.", "Questions": { "Question1": "Wie lautet Ihr Name?", "Question2": "Wie alt sind Sie?" } } Listing 4.23 Sprachdatei für die deutsche Übersetzung (de.json) { "Greeting": "Hello World", "Message": "This is an internationalization example.", "Questions": { "Question1": "What's your name?", "Question2": "What's your age?" } } Listing 4.24 Sprachdatei für die englische Übersetzung (en.json)
Das Package »i18n« binden Sie anschließend wie gewohnt über require() ein (Listing 4.25) und initialisieren es über die Methode configure(). Als Parameter übergeben Sie hierbei ein Konfigurationsobjekt, über das sich bspw. die von Ihrer Applikation unterstützten Locales, das Default-Locale und das Verzeichnis mit den JSON-Sprachdateien definieren lassen. Um außerdem wie in den Beispiel-JSON-Dateien die geschachtelte Objektschreibweise verwenden zu können, müssen Sie im Konfigurationsobjekt die Eigenschaft objectNotation auf true setzen (weitere Informationen zur Konfiguration finden Sie unter https://github.com/mashpie/i18n-node#i18nconfigure). Anschließend können Sie innerhalb Ihrer Applikation über die Methode i18n.__() unter Angabe des jeweiligen Schlüssels auf den entsprechenden Sprachbaustein zugreifen. const i18n = require('i18n'); const path = require('path'); const directory = path.join(__dirname, '..', 'locales'); i18n.configure({ locales: ['en', 'de'],
162
4.7
Zusammenfassung
directory, defaultLocale: 'de', objectNotation: true }); console.log(i18n.__('Greeting')); console.log(i18n.__('Message')); console.log(i18n.__('Questions.Question1')); console.log(i18n.__('Questions.Question2')); Listing 4.25 i18n für Zeichenketten
Pluralization Unabhängig von i18n bietet das Package »i18n« ein sehr nützliches Feature, das allgemein als Pluralization bekannt ist. Die Idee dabei ist es, einzelne Textbausteine abhängig davon zu laden, ob etwas im Singular oder im Plural ausgegeben werden soll. Ein Beispiel: Angenommen, Sie schreiben eine Anwendung, über die man Musikkünstler und deren Alben verwalten und u. a. nach Alben und Songs suchen kann. Oberhalb der Suchergebnisse soll ausgegeben werden, ob nur ein Song oder mehrere Songs gefunden wurden. Analog dazu sollte die Ausgabe entweder »Es wurde 1 Song gefunden« oder (bspw.) »Es wurden 5 Songs gefunden« lauten. Was Sie unter normalen Umständen per Hand mit Template Strings implementieren müssten, liefert das Package »i18n« praktischerweise direkt mit.
4.6.2 Ausblick Dank der Techniken aus diesem und dem vorherigen Rezept wissen Sie jetzt, wie Sie eine Node.js-Applikation auf Basis von i18n-Einstellungen konfigurieren können. Auch wenn Sie anfangs noch nicht planen sollten, eine Applikation mehrsprachig anzubieten, sollten Sie sich trotzdem überlegen, ob es nicht sinnvoll ist, Textbausteine in Sprachdateien auszulagern. Der Mehraufwand ist dank des »i18«-Packages sehr überschaubar, erlaubt es Ihnen aber später, ohne viel Aufwand weitere Sprachen zu unterstützen.
4.7 Zusammenfassung In diesem Kapitel haben Sie verschiedene Rezepte bezüglich der Konfiguration und Internationalisierung von Node.js-Projekten kennengelernt. Sie wissen jetzt, wie Sie 왘 Applikationen konfigurieren über Umgebungsvariablen (Rezept 22), 왘 Applikationen konfigurieren über Konfigurationsdateien (Rezept 23),
163
4
Konfiguration und Internationalisierung
왘 Applikationen konfigurieren über Kommandozeilenargumente (Rezept 24), 왘 Applikationen optimal konfigurieren (Rezept 25), 왘 Mehrsprachige Applikationen erstellen (Rezept 26), 왘 Sprachdateien verwenden (Rezept 27).
Im nächsten Kapitel lernen Sie, wie Sie die Ein- und Ausgabe richtig verwenden, mit Dateien arbeiten und wie Sie Events und Streams verwenden.
164
Kapitel 5 Dateisystem, Streams und Events In diesem Kapitel beschäftigen wir uns mit dem Zugriff auf das Dateisystem und schauen uns zwei wesentliche Konzepte von Node.js an: Datenverarbeitung über Streams und event-basierte Kommunikation.
In den folgenden Rezepten zeige ich Ihnen, wie Sie mit Dateien und Verzeichnissen arbeiten, wie Sie bspw. Dateien lesen oder schreiben, wie Sie Dateien und Verzeichnisse anlegen und wieder löschen, wie Sie über Verzeichnisinhalte iterieren, Dateien bezüglich Änderungen überwachen und vieles Nützliche mehr (Rezepte 28 und 29). Anschließend stelle ich Ihnen zwei wichtige allgemeine Konzepte von Node.js vor: zum einen, wie Sie Daten effektiv mit Streams (Rezepte 30 bis 33) verarbeiten, z. B. dann, wenn Sie große Mengen von Daten verarbeiten müssen. Zum anderen werden wir uns das Thema der event-basierten Kommunikation anschauen: Hier werden Sie lernen, wie Sie unter Node.js Events versenden und empfangen können, um auf diese Weise eine Entkopplung zwischen einzelnen Komponenten einer Node.js-Applikation zu erreichen (Rezepte 34 und 35). 왘 Rezept 28: Mit Dateien und Verzeichnissen arbeiten 왘 Rezept 29: Dateien und Verzeichnisse überwachen 왘 Rezept 30: Daten mit Streams lesen 왘 Rezept 31: Daten mit Streams schreiben 왘 Rezept 32: Mehrere Streams über Piping kombinieren 왘 Rezept 33: Eigene Streams implementieren 왘 Rezept 34: Events versenden und empfangen 왘 Rezept 35: Erweiterte Features beim Event-Handling verwenden
5.1 Rezept 28: Mit Dateien und Verzeichnissen arbeiten Sie möchten wissen, wie Sie unter Node.js mit Dateien und Verzeichnissen arbeiten, bspw. Dateien lesen, Verzeichnisse anlegen oder löschen.
165
5
Dateisystem, Streams und Events
5.1.1 Lösung Für das Arbeiten mit Dateien und Verzeichnissen stellt Node.js standardmäßig das »fs«-Modul zur Verfügung, das bereits eine Reihe von Datei- und Verzeichnisoperationen enthält (eine Übersicht über die entsprechenden Funktionen der API finden Sie in der API-Dokumentation von Node.js unter https://nodejs.org/api/fs.html). Ich würde Ihnen aber dazu raten, statt des »fs«-Moduls direkt das Package »fs-extra« (https://github.com/jprichardson/node-fs-extra) zu verwenden. Es enthält alle Funktionen von »fs«, erweitert dieses Modul aber um zusätzliche nützliche Funktionen, die bspw. das Kopieren, Löschen oder Anlegen von Dateien und Verzeichnissen vereinfachen. Darüber hinaus können Sie die (asynchronen) Funktionen von »fs-extra« optional in Kombination mit Promises verwenden, während Sie bei dem »fs«-Modul je nach Node.js-Version mit Callbacks vorliebnehmen müssen (auf die Nachteile von Callbacks bzw. die daraus teils resultierende Callback Hell möchte ich an dieser Stelle nicht näher eingehen. Im Internet finden Sie dazu jede Menge Beispiele, und auch in meinem Buch »Professionell entwickeln mit JavaScript« gehe ich detaillierter auf diese Problematik ein und zeige auch, wie man sie vermeiden kann). Erst seit Node.js 10 stehen die Funktionen des »fs«-Moduls alternativ auch in Form einer Promise-basierten Variante zur Verfügung (das Modul müssten Sie dann aber über den Namen »fs/promises« importieren). In den folgenden Abschnitten möchte ich Ihnen daher zeigen, wie Sie das Package »fs-extra« verwenden. Installieren können Sie das Package über folgenden Befehl: $ npm install fs-extra
Tipp Wenn Sie innerhalb einer bestehenden Applikation bereits das Modul »fs« eingebunden haben, aber auch die Vorzüge der Funktionen aus »fs-extra« nutzen möchten, brauchen Sie beim Importieren nur das »fs-extra«-Package anstatt des »fs«-Moduls anzugeben: const fs = require('fs');
wird also zu: const fs = require('fs-extra');
Da die API von »fs-extra« kompatibel mit der API von »fs« ist, müssen Sie in Ihrer Applikation sonst nichts weiter ändern (die API von »fs-extra« funktioniert übrigens auch mit Callbacks).
166
5.1
Rezept 28: Mit Dateien und Verzeichnissen arbeiten
5.1.2 Dateien lesen Um Dateien zu lesen, haben Sie (wie auch bei vielen der anderen Dateioperationen) die Möglichkeit, dies entweder asynchron oder synchron auszuführen. Ersteres machen Sie mithilfe der Funktion readFile(), die, wie in Listing 5.1 zu sehen, entweder über eine Promise-API verwendet werden kann oder – so würden Sie kompatibel mit dem »fs«-Modul bleiben – über eine Callback-API. Der jeweilige Callback wird aufgerufen, wenn die Datei vollständig gelesen wurde. Innerhalb des Callbacks haben Sie dann Zugriff auf den Inhalt der eingelesenen Datei in Form eines Buffers, den Sie über die Methode toString() wiederum in eine Zeichenkette umwandeln können. Alternativ dazu können Sie der Funktion readFile() als zusätzlichen Parameter auch ein Konfigurationsobjekt übergeben, über das sich u. a. das Encoding der einzulesenden Datei angeben lässt. Für den Fall, dass Sie ein solches Encoding mit angeben, wird der Callback direkt mit einem String anstatt mit einem Buffer aufgerufen. const fs = require('fs-extra'); const path = require('path'); const INPUT = path.join(__dirname, '..', 'data', 'input', 'input.txt'); // Callback-API fs.readFile(INPUT, (error, content) => { if (error) { return console.error(error); } console.log(content.toString()); }); // Promise-API fs .readFile(INPUT) .then((content) => { console.log(content.toString()); }) .catch((error) => { console.error(error); }); Listing 5.1 Asynchrones Lesen von Dateien
167
5
Dateisystem, Streams und Events
Tipp Für das Erstellen von Pfaden empfehle ich Ihnen, wie in Listing 5.1 gezeigt, den Einsatz des »path«-Moduls der Standard-Node.js-API. Dieses Modul bietet nützliche Funktionen rund um das Arbeiten mit Pfadangaben für Dateien und Verzeichnisse, und Sie müssen sich nicht um betriebssystemspezifische Eigenarten wie Pfadtrenner o. Ä. kümmern.
Alternativ zu readFile() können Sie über die Funktion readFileSync() das Lesen einer Datei synchron durchführen. Das äquivalente synchron arbeitende Beispiel zu dem Code von eben sehen Sie in Listing 5.2. Anstatt wie bei der asynchronen Variante den Inhalt der eingelesenen Datei im entsprechenden Callback zu erhalten, liefert die Funktion readFile() diesen direkt als Rückgabewert. Dabei gilt wie zuvor: Haben Sie nicht explizit über ein Konfigurationsobjekt das Encoding angegeben, liefert die Funktion einen Buffer zurück, den Sie über toString() in eine Zeichenkette umwandeln können. const fs = require('fs-extra'); const path = require('path'); const INPUT = path.join(__dirname, '..', 'data', 'input', 'input.txt'); try { const content = fs.readFileSync(INPUT); console.log(content.toString()); } catch (error) { console.error(error); } Listing 5.2 Synchrones Lesen von Dateien
Das synchrone Lesen von Dateien bietet sich allerdings eigentlich nur an, wenn die einzulesenden Dateien vergleichsweise klein sind, da der Aufruf von readFileSync() ein blockierender Aufruf ist. Das heißt, durch diesen Aufruf wird das Ausführen weiteren JavaScript-Codes so lange unterbrochen, bis der vollständige Inhalt der Datei eingelesen wurde (siehe auch https://nodejs.org/de/docs/guides/blocking-vs-nonblocking/). Unabhängig davon bietet sich in den meisten Fällen jedoch ohnehin die Verwendung der asynchronen Funktion readFile() an. Diese Funktion ist nicht blockierend und entspricht demnach – wie alle asynchronen Funktionen – den Best Practices unter Node.js.
168
5.1
Rezept 28: Mit Dateien und Verzeichnissen arbeiten
Allerdings sollten Sie für das Lesen von großen Dateien weder readFileSync() noch readFile() verwenden, da in beiden Fällen (also egal ob synchron oder asynchron) der gesamte Inhalt der jeweiligen Datei in den Speicher gelesen wird, bevor Sie damit weiterarbeiten können. Stattdessen sollten Sie für das Arbeiten mit großen Dateien auf Streams zurückgreifen. Wie Sie Streams für das Lesen von Dateien verwenden, zeige ich Ihnen in Rezept 30.
5.1.3 Dateien schreiben Auch bezüglich des Schreibens von Dateien steht Ihnen sowohl eine asynchron arbeitende Funktion als auch eine synchron arbeitende Funktion zur Verfügung. Die Anwendung ersterer, der Funktion writeFile(), sehen Sie in Listing 5.3: Als Parameter übergeben Sie dabei den Pfad zu der Datei, die geschrieben werden soll, und den zu schreibenden Inhalt. Optional können Sie als dritten Parameter noch ein Konfigurationsobjekt übergeben, mit dessen Hilfe sich weitere Optionen wie bspw. das Encoding angeben lassen. const fs = require('fs-extra'); const path = require('path'); const OUTPUT = path.join(__dirname, '..', 'data', 'output', 'output.txt'); const content = 'Hello World'; fs .writeFile(OUTPUT, content) .then(() => { console.log('Datei erstellt'); }) .catch((error) => { console.error(error); }); Listing 5.3 Asynchrones Schreiben von Dateien
In Listing 5.4 dagegen sehen Sie die Anwendung der synchron arbeitenden Funktion writeFileSync(): const fs = require('fs-extra'); const path = require('path'); const OUTPUT = path.join(__dirname, '..', 'data', 'output', 'output.txt'); const content = 'Hello World';
169
5
Dateisystem, Streams und Events
try { fs.writeFileSync(OUTPUT, content); console.log('Datei erstellt'); } catch (error) { console.error(error); } Listing 5.4 Synchrones Schreiben von Dateien
Wie für das Lesen großer Dateien gilt auch für das Schreiben großer Dateien: Verwenden Sie statt der Methoden writeFile() und writeFileSync() besser Streams, weil es dabei nicht zu Speicherproblemen kommen kann. Wie Sie Dateien mithilfe von Streams schreiben, lernen Sie in Rezept 31.
5.1.4 Weitere Methoden Neben den Methoden, die ohnehin schon implizit durch die Standard-Node.js-API bzw. das »fs«-Modul zur Verfügung stehen, bietet »fs-extra« die in Tabelle 5.1 gezeigten zusätzlichen Methoden. Dies sind insbesondere Utility-Methoden, die man beim Arbeiten mit dem »fs«-Modul vermisst bzw. teils aufwendig selbst implementieren muss. Methode
Beschreibung
copy()/copySync()
Kopiert eine Datei oder ein Verzeichnis.
emptyDir()/ emptyDirSync()
Stellt sicher, dass ein Verzeichnis existiert und leer ist. Wenn das Verzeichnis nicht leer ist, werden die Inhalte gelöscht. Wenn es das Verzeichnis nicht gibt, wird es entsprechend angelegt.
ensureFile()/ ensureFileSync()
Stellt sicher, dass es eine Datei gibt. Wenn es die Datei nicht gibt, wird sie angelegt, inklusive eventuell benötigter Verzeichnisse, die sich aus dem Dateipfad ergeben.
ensureDir()/ ensureDirSync()
Stellt sicher, dass es ein Verzeichnis gibt. Wenn es das Verzeichnis nicht gibt, wird es angelegt, inklusive eventuell benötigter weiterer Verzeichnisse, die sich aus dem Pfad ergeben.
ensureLink()/ ensureLinkSync()
Stellt sicher, dass es einen Link gibt. Wenn es den Link nicht gibt, wird er angelegt, inklusive eventuell benötigter weiterer Verzeichnisse, die sich aus dem Pfad ergeben.
Tabelle 5.1 Zusätzliche Methoden des »fs-extra«-Packages
170
5.1
Rezept 28: Mit Dateien und Verzeichnissen arbeiten
Methode
Beschreibung
ensureSymlink()/ ensureSymlinkSync()
Wie ensureLink() bzw. ensureLinkSync(), allerdings für symbolische Links.
mkdirp()/mkdirpSync()
Alias für ensureDir() bzw. ensureDirSync()
mkdirs()/mkdirsSync()
Alias für ensureDir() bzw. ensureDirSync()
move()/moveSync()
Verschiebt Dateien und Verzeichnisse.
outputFile()/ outputFileSync()
Wie writeFile() bzw. writeFileSync(), allerdings werden Verzeichnisse angelegt, die sich aus dem Dateipfad ergeben und noch nicht existieren.
outputJson()/ outputJsonSync()
Wie writeJson() bzw. writeJsonSync() (siehe unten), allerdings werden Verzeichnisse angelegt, die sich aus dem Dateipfad ergeben und noch nicht existieren.
pathExists()/ pathExistsSync()
Prüft, ob es einen Datei- oder Verzeichnispfad gibt.
readJson()/ readJsonSync()
Liest JSON-Dateien und wandelt sie entsprechend in JSONObjekte um.
remove()/removeSync()
Löscht eine Datei oder ein Verzeichnis.
writeJson()/ writeJsonSync()
Speichert ein JSON-Objekt in einer Datei.
Tabelle 5.1 Zusätzliche Methoden des »fs-extra«-Packages (Forts.)
5.1.5 Über Verzeichnisse iterieren Ein Anwendungsfall, dem man bei dem Arbeiten mit Dateien relativ häufig begegnet, ist das rekursive Iterieren über Verzeichnisstrukturen. Das Package »fs-extra« bietet hierfür leider keine entsprechende Funktionalität an. Zumindest nicht mehr, denn das Package »klaw« (https://github.com/jprichardson/node-klaw), das genau diese Funktionalität bereitstellt, war ursprünglich Teil von »fs-extra«, wurde aber vor einiger Zeit als eigenes Package ausgelagert. Installieren können Sie das Package über folgenden Befehl: $ npm install klaw
Über den Aufruf von klaw() erzeugen Sie, wie in Listing 5.5 zu sehen, ausgehend von einem Verzeichnispfad einen sogenannten Readable Stream (siehe Rezept 30), also einen lesbaren Datenstrom, der rekursiv alle Dateien und Unterverzeichnisse in dem
171
5
Dateisystem, Streams und Events
entsprechenden Verzeichnis durchwandert (ein gebräuchlicher Fachbegriff hierfür ist übrigens auch File Walking). Jedes Mal, wenn dieser File Walker auf eine Datei oder ein Verzeichnis trifft, wird das Event »data« ausgelöst. In dem entsprechenden Event-Listener haben Sie dann Zugriff auf ein Objekt, das den jeweiligen Pfad sowie einige Statistiken zu der Datei beziehungsweise dem Verzeichnis enthält (siehe auch https://nodejs.org/api/fs.html# fs_class_fs_stats). In Listing 5.5 bspw. wird auf diese Weise rekursiv über alle Verzeichnisse und Dateien in dem Verzeichnis ../data/input iteriert. Für jedes Verzeichnis und jede Datei wird der entsprechende Pfad ausgegeben sowie der Zeitpunkt, an dem das Verzeichnis bzw. die Datei erstellt wurde. Handelt es sich um eine Datei, wird zudem der Inhalt der Datei eingelesen und ebenfalls auf die Konsole ausgegeben. const fs = require('fs-extra'); const klaw = require('klaw'); const path = require('path'); const INPUT = path.join(__dirname, '..', 'data', 'input'); const stream = klaw(INPUT); stream.on('data', (item) => { const filePath = item.path; const timeCreated = item.stats.birthtime.toUTCString(); console.log(filePath); console.log(timeCreated); if (item.stats.isFile()) { const content = fs.readFileSync(filePath).toString(); console.log(content); } }); stream.on('end', () => { console.log('done'); }); Listing 5.5 Rekursives Iterieren über Verzeichnisse
5.1.6 Ausblick Sie kennen jetzt die wichtigsten Funktionen, die Ihnen über das Modul »fs« der Node.js-Standard-API und über das Package »fs-extra« für das Arbeiten mit Dateien und Verzeichnissen zur Verfügung stehen. Wenn Sie dagegen mit großen Dateien ar-
172
5.2
Rezept 29: Dateien und Verzeichnisse überwachen
beiten, egal ob lesend oder schreibend, stoßen Sie mit den entsprechenden Funktionen aus »fs« und »fs-extra« an ihre Grenzen. In solchen Fällen greifen Sie besser auf Streams zurück, die ich Ihnen später in diesem Kapitel vorstelle. Für das rekursive Iterieren über Verzeichnisse mithilfe des Packages »klaw« gibt es viele Anwendungsfälle, bspw. um bestimmte Dateien zu finden oder generell bestimmte Operationen auf Dateien auszuführen. Wenn Ihre Node.js-Applikation unter einem Unix-basierten Betriebssystem läuft, stehen durch die jeweilige Kommandozeile unter Umständen direkt entsprechende Befehle zur Verfügung (z. B. der Befehl find für das Suchen nach Dateien), und es ist eventuell zielführender und effektiver, diesen Befehl einfach aus Node.js heraus aufzurufen und dessen Ausgabe zu verarbeiten, anstatt entsprechende Funktionalität in JavaScript mühsam selbst zu implementieren. Wie Sie externe Anwendungen aus einer Node.js-Applikation heraus aufrufen, zeige ich Ihnen in Kapitel 11, »Skalierung, Performance und Sicherheit«, in Rezept 80 und Rezept 81.
Verwandte Rezepte 왘 Rezept 30: Daten mit Streams lesen 왘 Rezept 31: Daten mit Streams schreiben 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten
5.2 Rezept 29: Dateien und Verzeichnisse überwachen Sie möchten über Änderungen an Dateien oder Verzeichnissen informiert werden, bspw. wenn eine Datei neu erstellt, überschrieben oder gelöscht wird.
5.2.1 Einführung Das Überwachen von Dateien und Verzeichnissen kann für verschiedene Anwendungsgebiete hilfreich sein. Viele Tools, die bspw. bei der Entwicklung von Webanwendungen zum Einsatz kommen, wie etwa der Entwicklungs-Server von Webpack (https://github.com/webpack/webpack-dev-server), überwachen Dateien und Verzeichnisse, um bei Änderungen die entsprechenden Dateien zu kompilieren (z. B. TypeScript in JavaScript oder CSS-Präprozessorsprachen wie Sass in CSS) und anschließend die Webanwendung im Browser neu zu laden. Auch bei Synchronisierungstools wie Dropbox, Google Drive oder OneDrive von Microsoft werden Dateien und Verzeichnisse überwacht und bei Änderungen mit dem Server synchronisiert.
173
5
Dateisystem, Streams und Events
5.2.2 Lösung: Dateien und Verzeichnisse überwachen mit dem »fs«-Modul Für Node.js steht Ihnen in der Standard-API die Methode watch() des »fs«-Moduls zur Verfügung (Listing 5.6). Die Methode erwartet als ersten Parameter den Pfad zu der Datei oder dem Verzeichnis in Form eines Strings, eines Buffers oder einer URL. Optional können Sie als weiteren Parameter ein Konfigurationsobjekt übergeben, über das sich bspw. konfigurieren lässt, ob bei der Überwachung von Verzeichnissen auch Unterverzeichnisse mit einbezogen werden sollen. Als letzter Parameter kann zudem eine Funktion als Event-Listener übergeben werden, die bei Änderungen an Dateien und Verzeichnissen aufgerufen wird. Alternativ lassen sich über die Methode on() an dem von watch() zurückgegebenen Objekt weitere Event-Listener registrieren. Jeder Event-Listener wird dabei mit zwei Parametern aufgerufen: zum einen mit dem Typ des Events und zum anderen mit dem Namen der entsprechenden Datei bzw. des entsprechenden Verzeichnisses. const fs = require('fs'); const watcher = fs.watch(__dirname, (event, filename) => { console.log('Listener 1'); console.log(event); console.log(filename); }); watcher.on('change', (event, filename) => { console.log('Listener 2'); console.log(event); console.log(filename); }); Listing 5.6 Dateien überwachen mit der Node.js Standard-API
So einfach die Verwendung der Funktion watch() ist, so hat sie doch auch ihre Nachteile. Der größte Nachteil dürfte dabei sein, dass die Funktion nicht unter allen Betriebssystemen konsistent ist und unter bestimmten Umständen überhaupt nicht zur Verfügung steht (siehe https://nodejs.org/docs/latest/api/fs.html#fs_caveats). Die ebenfalls in dem »fs«-Modul vorhandene Funktion watchFile(), die noch aus frühen Node.js-Tagen stammt und nur das Überwachen von Dateien ermöglicht (nicht aber von Verzeichnissen), sollte übrigens nicht verwendet werden: Sie funktioniert zwar unter allen Betriebssystemen, ist dafür aber nicht sehr performant: Während watch() native Funktionalitäten des jeweiligen Betriebssystems verwendet, um Änderungen zu registrieren, prüft watchFile() in regelmäßigen Abständen aktiv, ob sich
174
5.2
Rezept 29: Dateien und Verzeichnisse überwachen
eine Datei geändert hat, was sich wiederum auch auf die CPU auswirkt, wenn überhaupt keine Änderungen vorliegen. Aus diesen Gründen rate ich Ihnen zu einer anderen Lösung, wenn es um das Überwachen von Dateien und Verzeichnissen geht, und zwar zu dem im Folgenden vorgestellten Package »chokidar«.
5.2.3 Lösung: Dateien und Verzeichnisse überwachen mit »chokidar« Wie eben erwähnt, haben die Methoden watch() und watchFile() aus dem »fs«Modul einige Nachteile. Dies haben auch die Entwickler des Packages »chokidar« (https://github.com/paulmillr/chokidar) erkannt und einen Wrapper um die Standard-API gebaut, der einige Verbesserungen bezüglich des Überwachens von Dateien und Verzeichnissen mit sich bringt. Das Package »chokidar« wird mittlerweile in vielen Tools eingesetzt wie bspw. – um nur einige der bekannteren Tools zu nennen – dem Build-Tool Gulp (https://gulpjs.com/), dem Testrunner karma (https://karma-runner.github.io), dem Process Manager PM2 (http://pm2.keymetrics.io/), den Synchronisierungstools BrowserSync (https://browsersync.io/) und nodemon (https://github.com/remy/nodemon), dem Code-Editor Visual Studio Code (https://code.visualstudio.com/) sowie dem eingangs erwähnten Webpack. Allein schon aufgrund dieser Popularität können Sie das Package relativ bedenkenlos in Ihren Projekten einsetzen.
Installation und Verwendung Um »chokidar« in Aktion zu sehen, legen Sie ein neues Package an, und installieren Sie »chokidar« als Abhängigkeit mithilfe von npm. Erzeugen Sie außerdem ein Verzeichnis, das »chokidar« gleich bezüglich Änderungen überwachen soll: $ $ $ $ $
mkdir watchfiles cd watchfiles npm init -y npm install chokidar mkdir files
Wie Sie »chokidar« verwenden, sehen Sie in Listing 5.7. Über die Methode watch() können Sie einzelne Watcher-Instanzen erstellen (also Objektinstanzen, die für das Überwachen von Dateien bzw. Verzeichnissen verantwortlich sind), wobei als erster Parameter die zu überwachenden Dateien und Verzeichnisse und als zweiter Parameter verschiedene optionale Konfigurationen zu übergeben sind. Die Pfade zu den Dateien und Verzeichnisse lassen sich entweder in Form eines Strings, eines String-Arrays oder als sogenanntes Glob-Pattern (siehe https://en.wikipedia.org/wiki/Glob_(programming)) angeben. An den einzelnen Watcher-Instanzen
175
5
Dateisystem, Streams und Events
wiederum lassen sich Event-Listener für verschiedene Events registrieren, bspw. für das Hinzufügen und Löschen von Verzeichnissen oder das Hinzufügen, Löschen und Ändern von Dateien (siehe Tabelle 5.2 für eine vollständige Übersicht). const chokidar = require('chokidar'); const watcher = chokidar.watch('./files/*.css', { ignored: /[\/\\]\./, persistent: true }); watcher .on('add', path => { console.log(`Datei ${path} hinzugefügt`); }) .on('addDir', path => { console.log(`Verzeichnis ${path} hinzugefügt`); }) .on('change', path => { console.log(`Datei ${path} geändert`); }) .on('unlink', path => { console.log(`Datei ${path} entfernt`); }) .on('unlinkDir', path => { console.log(`Verzeichnis ${path} entfernt`); }) .on('error', error => { console.error('Fehler aufgetreten', error); }) .on('ready', () => { console.log(`Initialer Datei-Scan abgeschlossen. Warte ...`); }); watcher.on('change', (path, stats) => { if (stats) { console.log(`Datei ${path} geändert, neue Dateigröße: ${stats.size}`); } }); Listing 5.7 Überwachen von Dateien und Verzeichnissen mit »chokidar«
176
5.2
Rezept 29: Dateien und Verzeichnisse überwachen
Event
Beschreibung
add
Wird ausgelöst, wenn eine Datei hinzugefügt wurde.
addDir
Wird ausgelöst, wenn ein Verzeichnis hinzugefügt wurde.
change
Wird ausgelöst, wenn eine Datei geändert wurde.
error
Wird ausgelöst, wenn ein Fehler auftritt.
raw
Enthält die rohen Informationen bei Änderungen. Wird bspw. auch dann ausgelöst, wenn Dateien hinzugefügt oder geändert werden, die nicht durch die definierte Watch-Expression berücksichtigt werden.
ready
Wird ausgelöst, wenn der initiale Scan der zu überwachenden Dateien und Verzeichnisse abgeschlossen wurde.
unlink
Wird ausgelöst, wenn eine Datei gelöscht wurde.
unlinkDir
Wird ausgelöst, wenn ein Verzeichnis gelöscht wurde.
Tabelle 5.2 Events von »chokidar«
Erzeugen Sie nun eine Datei mit dem Namen start.js, kopieren Sie den Code aus Listing 5.7 dort hinein, und starten Sie das Programm anschließend über folgenden Befehl: $ node start.js Initialer Datei-Scan abgeschlossen. Warte ...
Wenn Sie nun innerhalb des Verzeichnisses files eine CSS-Datei erzeugen, sprich eine Datei mit der Endung »css«, wird der Event-Listener für das »add«-Event aufgerufen und die entsprechende Meldung auf der Konsole ausgegeben. Analog werden die Event-Listener für das »change«-Event aufgerufen, wenn Sie den Inhalt der Datei ändern und dann speichern, und die Event-Listener für das »unlink«-Event, wenn Sie die Datei wieder löschen: Datei files/styles.css hinzugefügt Datei files/styles.css geändert Datei files/styles.css entfernt
Dieses relativ einfache Programm können Sie nun nach Belieben erweitern: Beispielsweise wäre es denkbar, neu hinzugefügte oder geänderte CSS-Dateien automatisch mit einem CSS-Parser zu parsen und auf syntaktische Korrektheit zu überprüfen (wie Sie CSS mit JavaScript verarbeiten können, lernen Sie übrigens in Rezept 47). Statt CSS können Sie das Ganze natürlich auch für andere Datenformate anwenden. In Kapitel 6, »Datenformate«, werde ich Ihnen zeigen, wie Sie verschiedenste Daten-
177
5
Dateisystem, Streams und Events
formate unter Node.js verarbeiten oder erzeugen können. Den Fantasien sind diesbezüglich also keine Grenzen gesetzt.
5.2.4 Ausblick Das Überwachen von Verzeichnissen und Dateien wird Ihnen bei der Entwicklung von Node.js-Applikationen immer mal wieder begegnen. Im weiteren Verlauf des Buches werden wir noch an einigen Stellen auf dieses Thema zurückkommen, bspw. wenn ich Ihnen in Rezept 75 zeige, wie Sie Unit-Tests automatisch neu ausführen, wenn sich der für die Tests relevante Quelltext ändert, oder auch in Rezept 79, in dem ich Ihnen zeige, wie Sie TypeScript-basierte Node.js-Applikationen bei Änderungen am Quelltext automatisch neu kompilieren. Alternativ zu dem in diesem Kapitel vorgestellten Package »chokidar« können Sie natürlich auch bestehende Unix-Befehle wie bspw. tail (http://man7.org/linux/manpages/man1/tail.1.html) als Unterprozess aus einer Node.js-Applikation heraus aufrufen und die entsprechende Ausgabe des Befehls innerhalb Ihrer Applikation weiterverarbeiten. In diesem Fall lohnt sich ein Blick auf Rezept 80 und Rezept 81 in Kapitel 11, »Skalierung, Performance und Sicherheit«, in denen ich Ihnen zeige, wie Sie externe Anwendungen oder Befehle aus Node.js heraus aufrufen.
Verwandte Rezepte 왘 Rezept 47: CSS verarbeiten und generieren 왘 Rezept 75: Unit-Tests automatisch neu ausführen 왘 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten 왘 Rezept 104: Den Quelltext bundeln und komprimieren mit Webpack
5.3 Rezept 30: Daten mit Streams lesen Sie möchten eine große Menge an Daten lesen und dabei sicherstellen, dass es zu keinen Speicherproblemen kommt.
5.3.1 Exkurs: Streams Ein wesentliches Konzept, das bei Node.js eine wichtige Rolle spielt, sind sogenannte Streams. Dabei handelt es sich um Datenströme, die ihre Daten entweder aus einer Quelle lesen (dann spricht man von Readable Streams bzw. lesbaren Streams) oder
178
5.3
Rezept 30: Daten mit Streams lesen
in ein Ziel schreiben (dann spricht man von Writable Streams bzw. schreibbaren Streams). Der wesentliche Vorteil von Streams gegenüber anderen Arten der Ein- und Ausgabe ist die Performance und die Möglichkeit, sie miteinander zu kombinieren. Neben Readable Streams und Writable Streams gibt es unter Node.js noch zwei weitere Arten von Streams: Duplex Streams bezeichnen Streams, die sowohl lesbar als auch schreibbar sind. Transform Streams basieren auf Duplex Streams, vereinfachen aber deren API.
Anwendungsfälle von Streams Der Einsatz von Streams ist bspw. immer dann sinnvoll, wenn es tendenziell zu Performance- oder Speicherproblemen beim Lesen oder Schreiben von Daten kommen könnte. Wenn Sie z. B. eine große Menge von Daten verarbeiten möchten, etwa große Dateien einlesen oder schreiben (Bild-, Video- oder Log-Dateien) oder große Daten von einem Webserver herunterladen möchten, sollten Sie dies immer mithilfe von Streams machen. Würden Sie dagegen große Dateien ohne Streams einlesen (etwa wie in Rezept 28 gezeigt unter Verwendung der Methode readFile() aus dem Modul »fs«), muss die gesamte Datei in den Speicher geladen werden, was schnell zu Performance- bzw. Speicherproblemen führen kann. Mit Streams dagegen ist es möglich, Daten Stück für Stück einzulesen und diese Daten über entsprechende Event-Listener zu verarbeiten.
Weitere Anwendungsfälle für Readable Streams Neben dem Verarbeiten von großen Dateien ist die Verwendung von Streams auch in vielen anderen Fällen sinnvoll. Eine Übersicht über weitere Anwendungsfälle für Readable Streams finden Sie in nachstehender Auflistung (eine entsprechende Auflistung für Writable Streams finden Sie dagegen im nächsten Rezept): 왘 HTTP-Anfragen vom Client, die auf dem Server verarbeitet werden 왘 HTTP-Antworten vom Server, die auf dem Client verarbeitet werden 왘 Übertragung von Daten über Sockets 왘 Standardausgabe und Standardfehlerausgabe von Kindprozessen, die im Eltern-
prozess verarbeitet werden 왘 Standardeingabe von Anwendungen, die im jeweiligen Prozess verarbeitet werden
Darüber hinaus stellen viele der Node.js-Packages, die ich Ihnen in diesem Buch zeige, ihre APIs oftmals in Form einer Stream-API zur Verfügung. Beispiele hierfür sind der XML-Parser »sax-js« (Rezept 36) und der RSS- bzw. Atom-Parser »feedparser« (Rezept 38).
179
5
Dateisystem, Streams und Events
5.3.2 Lösung Um große Dateien mithilfe von Readable Streams einzulesen, gehen Sie wie in Listing 5.8 vor. Im Gegensatz zu readFile() aus dem »fs«-Modul verwenden Sie createReadStream() aus dem gleichen Modul, um zunächst einen Readable Stream für die jeweilige Datei zu erzeugen. Standardmäßig geben Readable Streams die eingelesenen Daten als rohen Binär-Buffer zurück. Alternativ können Sie, wie weiter unten in Listing 5.8 gezeigt, der Funktion createReadStream() ein Konfigurationsobjekt übergeben und dort über die Eigenschaft encoding das zu verwendende Encoding definieren. Da alle Stream-Klassen von der Klasse EventEmitter ableiten (der Standardklasse aus der Node.js-API für das Unterstützen von Events, siehe auch Rezept 34), können Sie entsprechende Event-Listener über die Methode on() registrieren. Eine Übersicht der Events, die bei der Verwendung eines Readable Streams ausgelöst werden können, zeigt Tabelle 5.3. Event
Beschreibung
close
Wird ausgelöst, wenn der Stream geschlossen wurde.
data
Wird ausgelöst, wenn Daten gelesen wurden.
end
Wird ausgelöst, wenn keine weiteren Daten im Stream vorhanden sind.
error
Wird ausgelöst, wenn ein Fehler aufgetreten ist.
readable
Wird ausgelöst, wenn Daten im Stream zum Lesen bereitstehen.
Tabelle 5.3 Events bei Readable Streams
Prinzipiell unterscheidet die Stream-API zwischen zwei verschiedenen Modi: Im Paused Mode (den Sie in Listing 5.8 sehen und der standardmäßig aktiviert ist) werden Sie über das »readable«-Event darüber informiert, dass Daten im Stream zum Lesen bereitstehen. Um die Daten dann konkret auszulesen, rufen Sie auf der StreamInstanz die Methode read() auf. const fs = require('fs'); const path = require('path'); const INPUT = path.join(__dirname, '..', 'large.file'); const readableStream = fs.createReadStream(INPUT, { encoding: 'utf-8' });
180
5.3
Rezept 30: Daten mit Streams lesen
readableStream.on('readable', () => { const data = readableStream.read(); console.log(data); }); readableStream.on('end', () => { console.log('File reading completed'); }); Listing 5.8 Lesen von Dateien über Readable Streams im Paused Mode
Im Flowing Mode dagegen werden die Daten von der Datenquelle so schnell wie möglich in den Stream geschrieben. Dieser Modus ist standardmäßig nicht aktiviert und muss erst explizit aktiviert werden, bspw. wie in Listing 5.9 zu sehen, indem Sie einen Event-Listener für das »data«-Event registrieren. const fs = require('fs'); const path = require('path'); const INPUT = path.join(__dirname, '..', 'large.file'); const readableStream = fs.createReadStream(INPUT); readableStream.on('data', (data) => { console.log(data.toString('utf-8')); }); readableStream.on('end', () => { console.log('File reading completed'); }); Listing 5.9 Lesen von Dateien über Readable Streams im Flowing Mode
Wenn Sie vom Flowing Mode wieder in den Paused Mode wechseln möchten, können Sie dies über einen Aufruf der Methode pause() auf dem Stream-Objekt erreichen. Um umgekehrt wieder vom Paused Mode in den Flowing Mode zu wechseln, verwenden Sie dagegen die Methode resume(). Beachten Sie aber, dass im Flowing Mode die Daten nur fließen, wenn auch ein EventListener für das »data«-Event registriert wurde. Ist dies nicht der Fall, und Sie wechseln trotzdem über den Aufruf von resume() vom Paused Mode in den Flowing Mode, werden keine Daten verarbeitet.
181
5
Dateisystem, Streams und Events
5.3.3 Ausblick Readable Streams eignen sich für das Lesen bzw. Verarbeiten von Daten. Im nächsten Rezept zeige ich Ihnen, wie Sie mithilfe von Writable Streams Daten schreiben können. Auf das Kombinieren von Streams (Stichwort: Piping) komme ich dagegen in Rezept 32 zurück.
Verwandte Rezepte 왘 Rezept 28: Mit Dateien und Verzeichnissen arbeiten 왘 Rezept 31: Daten mit Streams schreiben 왘 Rezept 32: Mehrere Streams über Piping kombinieren 왘 Rezept 36: XML verarbeiten 왘 Rezept 38: RSS und Atom generieren und verarbeiten
5.4 Rezept 31: Daten mit Streams schreiben Sie möchten eine große Menge an Daten schreiben und dabei sicherstellen, dass es zu keinen Speicherproblemen kommt.
5.4.1 Lösung Im vorherigen Rezept haben Sie gesehen, wie Sie Daten mithilfe von Readable Streams lesen können. In diesem Rezept zeige ich Ihnen, wie Sie Daten mithilfe von Writable Streams schreiben können. Einige Beispiele, in denen die Verwendung von Writable Streams sinnvoll sein kann, zeigt folgende Liste: 왘 HTTP-Anfragen, die von dem Client versendet werden 왘 HTTP-Antworten, die vom Server an den Client versendet werden 왘 Schreiben von großen Dateien 왘 Übertragung von Daten über Sockets 왘 Standardeingabe von Kindprozessen 왘 Standardausgabe und Standardfehlerausgabe von Anwendungen, die im jewei-
ligen Prozess verarbeitet werden Wie Sie eine (große) Datei mithilfe eines Writable Streams schreiben, zeigt Listing 5.10. Analog zu createReadStream() zum Erzeugen eines Readable Streams verwenden Sie hier die Methode createWriteStream() des »fs«-Moduls und haben anschließend die Möglichkeit, über die Methode write() Daten in den Stream zu schreiben. Als ersten Parameter übergeben Sie dabei die zu schreibenden Daten entweder in
182
5.4
Rezept 31: Daten mit Streams schreiben
Form einer Zeichenkette oder in Form eines Buffers. Optional können Sie als zweiten Parameter das Encoding definieren und als dritten Parameter eine Callback-Funktion, die nach Schreiben der jeweiligen Daten aufgerufen wird. Beim Schreiben in einen Stream kann es allerdings passieren, dass das Schreiben der Daten über die Methode write() schneller geschieht, als der Stream die Daten verarbeiten kann. Die Daten werden innerhalb des Streams zwar in einem Buffer vorgehalten, dieser kann unter Umständen aber auch zu einem Bottleneck hinsichtlich der Performance und Speicherauslastung werden. Ob ein Stream bereit ist, weitere Daten zu empfangen, können Sie daher an dem booleschen Rückgabewert der Methode write() erkennen: Hat dieser den Wert true, können Sie bedenkenlos weitere Daten in den Stream schreiben. Hat er dagegen den Wert false, sollten Sie auf das »drain«-Event warten (siehe Tabelle 5.4), das immer dann ausgelöst wird, wenn der Buffer des Streams geleert wurde und der Stream wieder bereit ist, neue Daten zu empfangen. Tun Sie dies nicht, kann es zu Speicherproblemen und infolgedessen zum Absturz der jeweiligen Applikation kommen. Um zu signalisieren, dass das Schreiben der Daten beendet ist, können Sie zudem die Methode end() verwenden. Optional können Sie dabei als ersten Parameter weitere Daten übergeben, die vor dem Schließen des Streams noch geschrieben werden sollen, als zweiten Parameter das zu verwendende Encoding und als dritten Parameter eine Callback-Funktion, die aufgerufen wird, wenn die Bearbeitung des Streams beendet wurde. const fs = require('fs'); const path = require('path'); const INPUT = path.join(__dirname, '..', 'large.file'); const writableStream = fs.createWriteStream(INPUT); writableStream.on('finish', () => { console.log('File writing completed'); }); for (let i = 0; i { // Callback, wenn Daten geschrieben } );
183
5
Dateisystem, Streams und Events
} writableStream.end(); Listing 5.10 Schreiben von Dateien über Writable Streams
Event
Beschreibung
close
Wird ausgelöst, wenn der Stream geschlossen wurde.
drain
Wird ausgelöst, wenn der Stream wieder bereit ist, Daten zu verarbeiten.
error
Wird ausgelöst, wenn ein Fehler aufgetreten ist.
finish
Wird ausgelöst, wenn die Verarbeitung des Streams abgeschlossen bzw. die Methode end() aufgerufen wird.
pipe
Wird ausgelöst, wenn ein Readable Stream in den Writable Stream weitergeleitet wird (siehe Rezept 32, »Mehrere Streams über Piping kombinieren«).
unpipe
Wird ausgelöst, wenn ein Readable Stream nicht mehr in den Writable Stream weitergeleitet wird (siehe Rezept 32).
Tabelle 5.4 Events bei Writable Streams
5.4.2 Ausblick Im vorherigen Rezept haben Sie gelernt, wie Sie Readable Streams verwenden, im aktuellen Rezept, wie Sie Writable Streams verwenden. Ausgerüstet mit diesem Basiswissen für die Funktionsweise und Verwendung von Streams, möchte ich Ihnen im nächsten Rezept zeigen, wie Sie verschiedene Streams über sogenanntes Piping miteinander kombinieren können, also bspw. Daten über einen Readable Stream einlesen und diese Daten direkt in einen Writable Stream weiterleiten können.
Verwandte Rezepte 왘 Rezept 28: Mit Dateien und Verzeichnissen arbeiten 왘 Rezept 30: Daten mit Streams lesen 왘 Rezept 32: Mehrere Streams über Piping kombinieren
5.5 Rezept 32: Mehrere Streams über Piping kombinieren Sie möchten mehrere Streams mithilfe von Piping kombinieren.
184
5.5
Rezept 32: Mehrere Streams über Piping kombinieren
5.5.1 Lösung Ein weiteres wichtiges Konzept von Streams ist das sogenannte Piping. Hierüber ist es möglich, die Daten eines Readable Streams (oder eines Transform Streams) direkt in einen Writable Stream (oder einen Transform Stream) weiterzuleiten. Vergleichbar ist das Piping unter Node.js mit dem gleichnamigen Konzept aus Unix-basierten Shells oder auch MS-DOS, bei denen Kommandozeilenbefehle jeweils über das |-Symbol sehr vielfältig miteinander kombiniert werden können. In Node.js können Sie die Methode pipe() wie folgt verwenden, um einzelne Streams miteinander zu kombinieren: readablestream .pipe(transformStream1) .pipe(transformStream2) .pipe(writableStream);
Als Praxisbeispiel möchte ich Ihnen im Folgenden zeigen, wie Sie mithilfe des Pipings Dateien komprimieren und dekomprimieren können.
Anwendungsbeispiel: Komprimieren von Dateien Für das Komprimieren und das Dekomprimieren von Dateien stellt die Node.js-API das Modul »zlib« (https://nodejs.org/api/zlib.html) zur Verfügung, das praktischerweise direkt entsprechende Streams bereitstellt. Um bspw. eine Datei zu komprimieren, gehen Sie, wie in Listing 5.11 gezeigt, vor, und erstellen folgende drei Streams: 1. Über die Methode fs.createReadStream() erzeugen Sie zunächst einen Readable Stream. Mit diesem Stream sollen die zu komprimierenden Daten eingelesen werden. 2. Die Methode zlib.createGzip() liefert als Rückgabewert einen Transform Stream, der die eingelesenen Daten komprimiert. 3. Anschließend erzeugen Sie über einen Aufruf der Funktion fs.createWriteStream() einen Writable Stream. Dieser Stream wiederum ist dafür zuständig, die komprimierten Daten in eine (neue) Datei zu schreiben. Nachdem alle drei Streams initialisiert sind, geschieht der eigentliche Aufruf der Komprimierung durch das Hintereinanderschalten der einzelnen Streams mithilfe der Methode pipe(). Diese wird im ersten Schritt auf dem Readable Stream (inputStream) aufgerufen, wobei der Methode derjenige Stream zu übergeben ist, an den die eingelesenen Daten weitergeleitet werden sollen. Mit anderen Worten: Hier ist der Stream zu übergeben, der für die Komprimierung zuständig ist (gzip). Dank Fluent API lassen sich die einzelnen Aufrufe von pipe() sehr übersichtlich direkt hintereinanderschalten. Durch den zweiten Aufruf von pipe(), dem Sie wiede-
185
5
Dateisystem, Streams und Events
rum den Writable Stream übergeben (outputStream), definieren Sie, dass die Daten, die aus dem Komprimierungs-Stream herauskommen, direkt in den Writable Stream weitergeleitet werden. const fs = require('fs-extra'); const path = require('path'); const zlib = require('zlib'); const INPUT = path.join(__dirname, '..', 'data', 'input', 'logs.log'); const OUTPUT = path.join(__dirname, '..', 'data', 'logs.log.gz'); // 1. Stream zum Einlesen der zu komprimierenden Datei const inputStream = fs.createReadStream(INPUT); // 2. Stream für das Komprimieren der eingelesenen Daten const gzip = zlib.createGzip(); // 3. Stream für das Schreiben der Archiv-Datei const outputStream = fs.createWriteStream(OUTPUT); inputStream // Einlesen der Datei .pipe(gzip) // Komprimieren der eingelesenen Daten .pipe(outputStream); // Schreiben der Archiv-Datei Listing 5.11 ZIP-Dateien packen
Anwendungsbeispiel: Dekomprimieren von Dateien Das analoge Beispiel für das Dekomprimieren, also das Entpacken von gezippten Dateien, sehen Sie in Listing 5.12. Die Vorgehensweise ist dabei die gleiche wie zuvor, nur in die andere Richtung: Jetzt dient die gezippte Datei als Eingabe, weswegen Sie hierfür einen Readable Stream erzeugen. Dessen Ausgabe wird über die Methode pipe() als Eingabe für den Dekomprimierungs-Stream verwendet und dessen Ausgabe als Eingabe für den Writable Stream, der die entpackten Datei letztendlich in die Zieldatei schreibt. const fs = require('fs-extra'); const path = require('path'); const zlib = require('zlib'); const INPUT = path.join(__dirname, '..', 'data', 'logs.log.gz'); const OUTPUT = path.join(__dirname, '..', 'data', 'output'); const OUTPUT_FILE = path.join(OUTPUT, 'logs.log');
186
5.5
Rezept 32: Mehrere Streams über Piping kombinieren
fs.emptyDirSync(OUTPUT); inputStream.pipe(gunzip).pipe(outputStream); // 1. Stream zum Einlesen der zu dekomprimierenden Datei const inputStream = fs.createReadStream(INPUT); // 2. Stream für das Dekomprimieren der eingelesenen Daten const gzip = zlib.createGunzip(); // 3. Stream für das Schreiben der Archiv-Datei const outputStream = fs.createWriteStream(OUTPUT_FILE); inputStream // Einlesen der Datei .pipe(gunzip) // Dekomprimieren der eingelesenen Daten .pipe(outputStream); // Schreiben der Archiv-Datei Listing 5.12 ZIP-Dateien entpacken
Weitere Anwendungsbeispiele Streams begegnen Ihnen in der Node.js-Standard-API und in vielen anderen Node.jsPackages. Über folgende Code-Zeile sorgen Sie bspw. dafür, dass die Standardeingabe direkt in die Standardausgabe weitergeleitet wird (process.stdin ist ein Readable Stream, process.stdout ein Writable Stream). process.stdin.pipe(process.stdout); Listing 5.13 Weiterleiten der Standardeingabe in die Standardausgabe
Wenn Sie diese Zeile als Node.js-Applikation aufrufen, werden alle Eingaben, die Sie anschließend in die Kommandozeile schreiben, direkt auch ausgegeben. In Kapitel 9, »Sockets und Messaging«, in Rezept 63 zeige ich Ihnen, wie Sie einen TCP-Server in Node.js implementieren. Wenn Sie diesen Server starten, können Sie sich z. B. über folgende Code-Zeilen über Streams mit dem Server verbinden (der Aufruf net.connect() gibt ein Objekt vom Typ net.Socket zurück, das wiederum ein Duplex Stream ist, also sowohl Readable als auch Writable). const net = require('net'); process.stdin // Standardeingabe lesen .pipe(net.connect(1337)) // Zum TCP-Server verbinden .pipe(process.stdout); // Die Antwort des TCP-Server ausgeben Listing 5.14 Weiterleiten der Standardeingabe an einen TCP-Server und weiter in die Standardausgabe
187
5
Dateisystem, Streams und Events
5.5.2 Piping im Produktionsbetrieb So schön das in den vorherigen Abschnitten vorgestellte Piping auch ist, hat die Verwendung der pipe()-Methode einen gravierenden Nachteil: Und zwar sieht die Methode keine direkte Fehlerbehandlung vor. Das heißt, wenn in einer Pipeline an irgendeiner Stelle in einem der Streams ein Fehler auftritt, wird dies nicht an die anderen Streams übermittelt, und diese werden infolgedessen auch nicht automatisch geschlossen, was wiederum zu Speicherproblemen führen kann. Um dem entgegenzuwirken, müssten Sie also für alle Streams in einer Pipeline entsprechende Event-Listener für das »error«-Event und das »close«-Event registrieren und bei Auftreten eines Fehlers in einem der Streams die jeweils anderen Streams in der Pipeline manuell schließen. Das klingt nicht nur aufwendig, sondern ist es auch, weswegen sich diesbezüglich die Verwendung des Packages »pump« (https://www.npmjs.com/package/pump) als Best Practice durchgesetzt hat, das intern genau das oben Beschriebene macht, sprich Event-Listener registriert und nicht geschlossene Streams bei Auftreten eines Fehlers automatisch schließt. Das entsprechend angepasste Beispiel für das Komprimieren von Dateien zeigt Listing 5.15. Die einzelnen Streams werden jetzt nicht mehr direkt über die Methode pipe() miteinander verbunden, sondern als Parameter der Funktion pump() übergeben. Über den letzten Parameter dieser Funktion können Sie zudem eine CallbackFunktion übergeben, anhand derer Sie ebenfalls über eventuelle Fehler benachrichtigt werden. Um das eigentliche Schließen der Streams müssen Sie sich hierbei aber nicht kümmern. const const const const
fs = path zlib pump
require('fs-extra'); = require('path'); = require('zlib'); = require('pump');
const INPUT = path.join(__dirname, '..', 'data', 'input', 'logs.log'); const OUTPUT = path.join(__dirname, '..', 'data', 'logs.log.gz'); const inputStream = fs.createReadStream(INPUT); const outputStream = fs.createWriteStream(OUTPUT); const gzip = zlib.createGzip(); pump( inputStream, gzip, outputStream,
188
5.5
Rezept 32: Mehrere Streams über Piping kombinieren
(error) => { if (error) { console.error('Zipping failed.'); } else { console.log('Zipping succeeded.'); } } ); Listing 5.15 Fehlerbehandlung bei Streams mithilfe des Packages »pump«
Auch das Team hinter Node.js lernt aus seinen Fehlern, und so wurde mit Node.js 10 etwas Vergleichbares wie das Package »pump« eingeführt. Und zwar ist es seitdem möglich, über die Funktion pipeline() aus dem Node.js-Standard-Package »stream« das zu erreichen, was vorher nur umständlich manuell oder über das Package »pump« möglich war. Die Verwendung ist dabei nahezu identisch mit der bei »pump«, wie folgendes Listing zeigt, d. h., auch der Funktion pipeline() übergeben Sie die entsprechenden Streams in der Reihenfolge, in der die Streams hintereinandergeschaltet werden sollen, sowie als letzten Parameter eine Callback-Funktion, um auf Fehler oder das Abarbeiten der Pipeline reagieren zu können. const const const const
fs = require('fs-extra'); path = require('path'); zlib = require('zlib'); { pipeline } = require('stream');
const INPUT = path.join(__dirname, '..', 'data', 'input', 'logs.log'); const OUTPUT = path.join(__dirname, '..', 'data', 'logs.log.gz'); const inputStream = fs.createReadStream(INPUT); const outputStream = fs.createWriteStream(OUTPUT); const gzip = zlib.createGzip(); pipeline( inputStream, gzip, outputStream, (error) => { if (error) { console.error('Zipping failed.'); } else {
189
5
Dateisystem, Streams und Events
console.log('Zipping succeeded.'); } } ); Listing 5.16 Fehlerbehandlung bei Streams seit Node.js 10
5.5.3 Ausblick Sie wissen jetzt, wie Sie Daten mit Streams einlesen, Daten mit Streams schreiben und wie Sie Streams mithilfe von Piping kombinieren. Im nächsten Rezept möchte ich Ihnen nun zeigen, wie Sie eigene Streams implementieren.
Verwandte Rezepte 왘 Rezept 30: Daten mit Streams lesen 왘 Rezept 31: Daten mit Streams schreiben 왘 Rezept 63: Einen TCP-Server erstellen
5.6 Rezept 33: Eigene Streams implementieren Sie möchten einen eigenen Stream implementieren.
5.6.1 Lösung Die Node.js-API stellt für das Erstellen von Streams an verschiedenen Stellen entsprechende Methoden zur Verfügung. In den vorherigen Rezepten haben Sie bspw. gesehen, wie Sie mit entsprechenden Methoden aus dem »fs«-Modul Dateien unter Verwendung von Readable Streams lesen und unter Verwendung von Writable Streams schreiben können. Anhand des Moduls »zlib« habe ich Ihnen zudem gezeigt, wie sich Dateien unter Verwendung von Transform Streams komprimieren und dekomprimieren lassen. In diesem Rezept möchte ich Ihnen nun zeigen, wie Sie die verschiedenen Arten von Streams selbst implementieren: 왘 Readable Streams: In Abschnitt 5.6.2 implementieren wir einen Readable Stream,
der zufällige Sensorwerte zwischen –1 und 2.000 generiert, wobei der Wert –1 für einen fehlerhaften Sensorwert steht. 왘 Writable Streams: In Abschnitt 5.6.3 implementieren wir einen Writable Stream,
in den Sensorwerte geschrieben werden können und der bei fehlerhaften Sensorwerten einen Fehler ausgibt und die Verarbeitung abbricht.
190
5.6
Rezept 33: Eigene Streams implementieren
왘 Duplex Streams: In Abschnitt 5.6.4 implementieren wir einen Duplex Stream, der
die Funktionalität des Readable Streams und des Writable Streams aus den vorherigen beiden Abschnitten vereint. 왘 Transform Streams: In Abschnitt 5.6.5 schließlich implementieren wir einen
Transform Stream, in den Sensorwerte geschrieben werden können und der fehlerhafte Sensorwerte normalisiert und durch 0 ersetzt.
5.6.2 Lösung: Einen Readable Stream implementieren Für die Implementierung eigener Streams stellt die Node.js-API das Modul »stream« zur Verfügung. Die in diesem Modul enthaltene Klasse Readable bildet dabei die Basis für die Implementierung eigener Readable Streams. Um nun einen eigenen Stream zu implementieren, erstellen Sie von dieser Basisklasse eine Unterklasse und überschreiben dabei die Methode _read(). Innerhalb dieser Methode können Sie dann genau definieren, wann Daten in den Stream geschrieben werden sollen. Dazu wiederum stellen Readable Streams die Methode push() zur Verfügung. Wenn Sie, wie in Rezept 30 beschrieben, einen Readable Stream für das Lesen von Dateien erzeugt und gestartet haben, passiert nichts anderes, als dass der von fs.createReadStream() erzeugte Readable Stream intern die Methode push() aufruft, um Daten aus der Datei als einzelne Teile (sogenannte »Chunks«) in den Stream zu schreiben. In Listing 5.17 sehen Sie nun, wie dies konkret für eine eigene Implementierung aussehen könnte: Hier wird bspw. ein Sensor simuliert, der 100.000-mal hintereinander einen zufälligen Wert zwischen –1 und 2.000 ausgibt. Dazu wird innerhalb der Methode _read() eine entsprechende Schleife durchlaufen. Jeder Wert wird dabei zuerst in eine Zeichenkette und ausgehend davon in ein Buffer-Objekt umgewandelt. Der Aufruf der Methode push() sorgt dafür, dass der entsprechende Wert (in Form des Buffer-Objekts) in den Stream geschrieben wird. Ist das Ende der Schleife erreicht, wird die Methode push() mit dem Argument null aufgerufen, was wiederum dafür sorgt, dass der Stream beendet wird. const { Readable } = require('stream'); const random = (min, max) => { min = Math.ceil(min); max = Math.floor(max); return Math.floor(Math.random() * (max - min + 1)) + min; }; class SensorReadable extends Readable { constructor(opt) {
191
5
Dateisystem, Streams und Events
super(opt); this._maxValues = 100000; this._index = 1; } _read() { const i = this._index++; if (i > this._maxValues) { this.push(null); } else { const numberAsString = String(random(-1, 2000)); const buffer = Buffer.from(`${numberAsString}\n`, 'utf8'); this.push(buffer); } } } module.exports = SensorReadable; Listing 5.17 Implementierung eines eigenen Readable Streams
Listing 5.18 zeigt, wie Sie die oben implementierte SensorReadable-Klasse verwenden. Hier wird die Ausgabe des Readable Streams über Piping an die Standardausgabe (process.stdout) weitergeleitet (aus den in Rezept 32 genannten Gründen verwenden Sie für das Piping die Funktion pipeline() aus dem »stream«-Modul). Wenn Sie dieses Programm nun aufrufen, werden auf der Konsole insgesamt 100.000 zufällige Zahlen (»Sensorwerte«) im Wertebereich von –1 bis 2.000 ausgegeben. const { pipeline } = require('stream'); const SensorReadable = require('./SensorReadable'); const sensorReadable = new SensorReadable(); pipeline(sensorReadable, process.stdout, (error) => { if (error) { console.error('Pipeline failed.', error); } else { console.log('Pipeline succeeded.'); } }); Listing 5.18 Verwendung des eigenen Readable Streams
192
5.6
Rezept 33: Eigene Streams implementieren
Hinweis Sie können Readable Streams (und im Übrigen auch Writable Streams, Duplex Streams und Transform Streams) statt über die Implementierung einer Unterklasse auch in einer Kurzschreibweise implementieren, bei der Sie den jeweiligen Stream direkt über den Konstruktor der Basisklasse erstellen. Die Implementierung der zu überschreibenden Methoden übergeben Sie dabei in Form eines Konfigurationsobjekts: const { Readable } = require('stream'); const readable = new Readable({ read(size) { // ... } }); Listing 5.19 Verwendung der Kurzschreibweise für Readable Streams
5.6.3 Lösung: Einen Writable Stream implementieren Analog zu der Klasse Readable stellt das Modul »stream« für das Erstellen von Writable Streams die Klasse Writable zur Verfügung. Um einen eigenen Writable Stream zu implementieren, erstellen Sie von dieser Klasse eine Unterklasse und überschreiben dabei die Methode _write(). Diese Methode nimmt drei Parameter entgegen: den jeweiligen »Chunk«, also den Teil, der gerade vom Stream verarbeitet wird, das Encoding sowie als dritten Parameter eine Callback-Funktion, die aufzurufen ist, wenn der Writable Stream mit der Verarbeitung der Daten fertig ist. Die in Listing 5.20 gezeigte Klasse SensorWritable bspw. nimmt Daten entgegen, wandelt diese über parseInt() in Ganzzahlen um und prüft, ob diese nicht negativ sind. Für den Fall, dass eine Zahl negativ ist (der Sensorwert sozusagen fehlerhaft ist), wird die Callback-Funktion mit einem entsprechenden Fehlerobjekt aufgerufen, was wiederum dafür sorgt, dass die Verarbeitung weiterer Daten durch den Writable Stream abgebrochen wird. Ist die Zahl 0 oder größer als 0, wird sie einfach auf die Konsole ausgegeben und die Callback-Funktion entsprechend ohne Fehlerobjekt aufgerufen. const { Writable } = require('stream'); class SensorWritable extends Writable { _write(chunk, encoding, callback) { const string = chunk.toString(); const value = parseInt(string); if (value < 0) { callback(new Error(`Invalid: ${value}`));
193
5
Dateisystem, Streams und Events
} else { console.log(`Valid: ${value}`); callback(); } } } module.exports = SensorWritable; Listing 5.20 Implementierung eines eigenen Writable Streams
Listing 5.21 zeigt, wie die Klasse SensorWritable in Kombination mit der im vorherigen Abschnitt implementierten SensorReadable-Klasse verwendet werden kann. Zur Erinnerung: Diese Klasse schreibt 100.000 zufällige Zahlen in den Stream, wobei die Wahrscheinlichkeit 1:2.000 ist, dass die jeweilige Zahl negativ und damit der Sensorwert fehlerhaft ist. Die Kombination mit dem implementierten Writable Sensor sorgt dafür, dass bei fehlerhaften Sensorwerten ein entsprechender Fehler ausgegeben und die Stream-Verarbeitung abgebrochen wird. const { pipeline } = require('stream'); const SensorReadable = require('./SensorReadable'); const SensorWritable = require('./SensorWritable'); const sensorReadable = new SensorReadable(); const sensorWritable = new SensorWritable(); pipeline(sensorReadable, sensorWritable, (error) => { if (error) { console.error('Pipeline failed.', error); } else { console.log('Pipeline succeeded.'); } }); Listing 5.21 Verwendung des eigenen Writable Streams
5.6.4 Lösung: Einen Duplex Stream implementieren Bei Duplex Streams handelt es sich quasi um eine Kombination aus Readable Stream und Writable Stream, weil Daten sowohl aus Duplex Streams gelesen als auch in Duplex Streams geschrieben werden können. Die entsprechende Basisklasse Duplex aus dem »stream«-Modul stellt daher auch zwei Methoden bereit, die bei Implementierung eigener Duplex Streams zu überschreiben sind: die Methode _read() für das
194
5.6
Rezept 33: Eigene Streams implementieren
Verhalten als Readable Stream sowie die Methode _write() für das Verhalten als Writable Stream. Prominentestes Beispiel für einen Duplex Stream in der Node.js-API ist wahrscheinlich die Klasse Socket aus dem »net«-Package, mit deren Hilfe Socket-Kommunikation zwischen einem (Socket-)Server und einem (Socket-)Client aufgebaut werden kann. Auch bildlich kann man sich einen Duplex Stream anhand dieses Beispiels sehr schön vorstellen: Über eine (Socket-)Verbindung können Server und Client sowohl Daten schreiben (das wäre der Writable Teil) als auch Daten lesen (das wäre der Readable Teil). Das folgende Beispiel ist zugegeben nicht ganz so praxisnah, sondern etwas konstruiert und soll vielmehr nur das Vorgehen bei der Implementierung eines eigenen Duplex Streams veranschaulichen. Listing 5.22 zeigt einen Duplex Stream, der die Funktionalität des Readable Streams aus Abschnitt 5.6.2 und die des Writable Streams aus Abschnitt 5.6.3 in einer Klasse vereint. Mit anderen Worten: Der Duplex Stream generiert in der Methode _read() die zufälligen Sensorwerte und gibt sie in der Methode _write() entsprechend – sofern nicht fehlerhaft – auf die Konsole aus. Der Inhalt der beiden Methoden bleibt gegenüber den Einzelimplementierungen unverändert. const { Duplex } = require('stream'); const random = (min, max) => { min = Math.ceil(min); max = Math.floor(max); return Math.floor(Math.random() * (max - min + 1)) + min; }; class SensorDuplex extends Duplex { constructor(opt) { super(opt); this._maxValues = 100000; this._index = 1; } _read() { const i = this._index++; if (i > this._maxValues) { this.push(null); } else { const numberAsString = String(random(-1, 2000)); const buffer = Buffer.from(`${numberAsString}\n`, 'utf8'); this.push(buffer); }
195
5
Dateisystem, Streams und Events
} _write(chunk, encoding, callback) { const string = chunk.toString(); const value = parseInt(string); if (value < 0) { callback(new Error(`Invalid: ${value}`)); } else { console.log(`Valid: ${value}`); callback(); } } } module.exports = SensorDuplex; Listing 5.22 Implementierung eines eigenen Duplex Streams
In Listing 5.23 sehen Sie, wie sich dieser Duplex Stream verwenden lässt. Das Beispiel ist dabei analog zu Listing 5.21 aus dem Abschnitt 5.6.3, in dem der Writable Stream mit dem zuvor implementierten Readable Stream kombiniert wurde. Der Unterschied: Jetzt werden zwei Instanzen des Duplex Streams verwendet, wobei die eine Instanz als Readable Stream fungiert und die andere als Writable Stream. const { pipeline } = require('stream'); const SensorDuplex = require('./SensorDuplex'); const sensorReadable = new SensorDuplex(); const sensorWritable = new SensorDuplex(); pipeline(sensorReadable, sensorWritable, (error) => { if (error) { console.error('Pipeline failed.', error); } else { console.log('Pipeline succeeded.'); } }); Listing 5.23 Verwendung des eigenen Duplex Streams
Das Beispiel kann weiter vereinfacht werden, da natürlich eigentlich nicht zwei Instanzen des Duplex Streams benötigt werden, wenn eine Instanz ja schon beide Funktionalitäten bereitstellt. Folgendes würde also auch funktionieren:
196
5.6
Rezept 33: Eigene Streams implementieren
const { pipeline } = require('stream'); const SensorDuplex = require('./SensorDuplex'); const sensorDuplex = new SensorDuplex(); pipeline(sensorDuplex, sensorDuplex, (error) => { if (error) { console.error('Pipeline failed.', error); } else { console.log('Pipeline succeeded.'); } }); Listing 5.24 Verwendung des eigenen Duplex Streams
5.6.5 Lösung: Einen Transform Stream implementieren Für die Implementierung von Transform Streams stellt das Modul »stream« die Klasse Transform zur Verfügung. Transform Streams bauen auf Duplex Streams auf und sind immer dann sinnvoll, wenn Sie bei der Verwendung von Streams die Daten in irgendeiner Art und Weise transformieren, also verändern möchten. Wie schon für die anderen Stream-Klassen müssen Sie – um einen eigenen Transform Stream zu implementieren – von der Klasse Transform eine Unterklasse erstellen und dort die Methode _transform() überschreiben. Diese Methode nimmt – wie schon die Methode _write() der Klasse Writable – drei Parameter entgegen: den Teil, der gerade vom Stream verarbeitet wird (»Chunk«), das Encoding und eine Callback-Funktion, die aufzurufen ist, wenn der Transform Stream die Datenverarbeitung abgeschlossen hat, und der Sie den Wert übergeben können, der an den nächsten Stream weitergereicht wird. Als Beispiel wollen wir im Folgenden einen Transform Stream implementieren, der in Kombination mit dem in Abschnitt 5.6.2 implementierten Readable Stream und dem Writable Stream aus Abschnitt 5.6.3 verwendet werden kann. Zur Erinnerung: Der Readable Stream SensorReadable generiert zufällige Sensorwerte im Wertebereich von –1 und 2.000, wobei –1 für fehlerhafte Messungen steht. Der Writable Stream liest Sensorwerte ein und gibt diese auf die Konsole aus, wobei für fehlerhafte Werte (also –1) ein entsprechender Fehler ausgegeben wird und die Stream-Verarbeitung abbricht. Der im Folgenden zu implementierende Transform Stream soll jetzt die fehlerhaften Werte normalisieren, sprich den Wert -1 durch den Wert 0 ersetzen. Dazu bilden wir, wie in Listing 5.25 zu sehen, eine Unterklasse der Klasse Transform und implementie-
197
5
Dateisystem, Streams und Events
ren die Methode _transform() wie folgt: Zunächst wird der »Chunk« in eine Zeichenkette umgewandelt, dann in eine Ganzzahl geparst und dann geprüft, ob diese Zahl kleiner 0 ist. Ist dies der Fall, normalisieren wir diesen Wert, d. h., wir rufen die callback()-Funktion mit einer 0 auf. const { Transform } = require('stream'); class SensorTransform extends Transform { _transform(chunk, encoding, callback) { const string = chunk.toString(); const value = parseInt(string); if (value < 0) { const buffer = Buffer.from('0', 'utf8'); callback(null, buffer); } else { callback(null, chunk); } } } module.exports = SensorTransform; Listing 5.25 Implementierung eines eigenen Transform Streams
Hinweis Die Methode _transform() – Sie werden es vermuten – ist nur dazu gedacht, von innerhalb einer Transform-Stream-Klasse aufgerufen zu werden.
Die Verwendung des Transform Streams in Kombination mit dem vorher implementierten Readable Stream und dem Writable Stream sehen Sie in Listing 5.26. Wenn Sie dieses Programm laufen lassen, werden Sie feststellen, dass in der Ausgabe nicht mehr der Wert –1 auftaucht (da dieser Wert jeweils durch den Transform Stream durch 0 ersetzt wurde) und die Abarbeitung der vom Readable Stream erzeugten 100.000 Zahlen vollständig abgeschlossen wird (weil der Writable Stream nicht mehr mit einem Fehler abbricht). const { pipeline } = require('stream'); const SensorReadable = require('./SensorReadable'); const SensorTransform = require('./SensorTransform'); const SensorWritable = require('./SensorWritable'); const sensorReadable = new SensorReadable();
198
5.7
Rezept 34: Events versenden und empfangen
const sensorTransform = new SensorTransform(); const sensorWritable = new SensorWritable(); pipeline(sensorReadable, sensorTransform, sensorWritable, (error) => { if (error) { console.error('Pipeline failed.', error); } else { console.log('Pipeline succeeded.'); } }); Listing 5.26 Verwendung des eigenen Transform Streams
5.6.6 Ausblick In diesem Rezept haben Sie gesehen, wie Sie die verschiedenen Arten von Streams selbst implementieren können. In diesem Zusammenhang ebenfalls interessant sind die Packages »from2« (https://www.npmjs.com/package/from2) und »through2« (https://www.npmjs.com/package/through2). Ersteres ist ein Helfer-Package für das Erstellen von Readable Streams, letzteres ein Helfer-Package für das Erstellen von Transform Streams. Neben den in diesem und den vorangegangenen Rezepten vorgestellten Konzepten von Streams und Techniken gibt es natürlich noch viele weitere Dinge, die Sie mit Streams anstellen können, und auch verschiedene Patterns für den richtigen Umgang mit Streams. Wenn Sie sich eingehender damit beschäftigen möchten, empfehle ich Ihnen das »Stream Handbook«, das unter https://github.com/substack/streamhandbook zur Verfügung steht.
Verwandte Rezepte 왘 Rezept 30: Daten mit Streams lesen 왘 Rezept 31: Daten mit Streams schreiben 왘 Rezept 32: Mehrere Streams über Piping kombinieren
5.7 Rezept 34: Events versenden und empfangen Sie möchten zwischen verschiedenen Komponenten einer Node.js-Applikation über Events kommunizieren, bspw. um die einzelnen Komponenten voneinander zu entkoppeln.
199
5
Dateisystem, Streams und Events
5.7.1 Lösung In den vorherigen Rezepten haben Sie bereits einige Beispiele für die Verwendung von Events gesehen. Beispielsweise als wir in Rezept 28 mithilfe des Packages »klaw« ein Programm geschrieben haben, das über Verzeichnisse iteriert und für gefundene Unterverzeichnisse und Dateien jeweils ein Event auslöst. Auch bei der Verwendung von Streams, was Thema der vorherigen Rezepte war, haben Sie die Möglichkeit, auf verschiedene Events innerhalb von Event-Listenern zu reagieren. Im Folgenden möchte ich Ihnen nun zeigen, wie Sie unter Node.js selbst Komponenten erstellen, die Events versenden und wie an ihnen Event-Listener registriert werden können. Generell funktioniert das Senden und Empfangen von Events über das »events«Package, das Bestandteil der Standard-Node.js-API ist, bzw. über die in diesem Package enthaltene Klasse EventEmitter. Von dieser Klasse erstellen Sie zunächst, wie in Listing 5.27 zu sehen, eine Objektinstanz. Anschließend lassen sich über die Methode on() an dieser Instanz Event-Listener für bestimmte Events definieren. Die Methode on() kennen Sie bereits (sofern Sie die oben genannten Rezepte schon durchgearbeitet haben). Als Parameter erwartet diese Methode den Namen des Events als Zeichenkette sowie den jeweiligen Event-Listener in Form einer Funktion, die ausgeführt werden soll, wenn ein entsprechendes Event am Event-Emitter ausgelöst wird. Letzteres erreichen Sie über die Methode emit(), wobei hierbei der Name des Events sowie die zu verschickende Nachricht als Parameter zu übergeben sind. const { EventEmitter } = require('events'); // EventEmitter-Instanz zum Versenden // und Empfangen von Events const eventEmitter = new EventEmitter(); // Name des Events, was versendet wird const eventType = 'exampleEvent'; // Registrieren eines Event-Listeners für das Event eventEmitter.on(eventType, (message) => { console.log(message); console.log(message.topic); console.log(message.content); }); // Nachricht, die versendet werden soll const message = { topic: 'A message',
200
5.7
Rezept 34: Events versenden und empfangen
content: 'Some dummy content' } // Versenden der Nachricht eventEmitter.emit(eventType, message); Listing 5.27 Prinzipielle Verwendung von Events unter Node.js
Darüber hinaus stellt die EventEmitter-Klasse eine Reihe weiterer Methoden bereit, von denen Tabelle 5.5 eine Übersicht zeigt. So lassen sich z. B. über die Methode removeListener() Event-Listener auch wieder für ein Event entfernen (neben dem Event muss dabei der jeweilige Event-Listener als Parameter übergeben werden). Alternativ dazu können über die Methode removeAllListeners() auch direkt alle Event-Listener für ein Event entfernt werden. Ebenfalls praktisch: Über die Methode once() lassen sich Event-Listener definieren, die bei Auftreten eines Events genau einmal aufgerufen werden sollen. Tritt ein Event ein zweites Mal auf, wird der entsprechende Event-Listener nicht erneut aufgerufen. Methode
Beschreibung
emitter.addListener( eventName, listener )
Fügt einen Event-Listener zu einem bestimmten Event hinzu. Alias für die Methode on()
emitter.emit( eventName[, ...args] )
Löst ein Event aus.
emitter.eventNames()
Liefert ein Array der Event-Namen zurück, für die Event-Listener registriert sind.
emitter.getMaxListeners()
Gibt die maximale Anzahl an Event-Listenern zurück, die hinzugefügt werden können.
emitter.listenerCount( eventName )
Gibt die Anzahl der für ein Event registrierten Event-Listener zurück.
emitter.listeners( eventName )
Gibt die für ein Event registrierten Event-Listener zurück.
Tabelle 5.5 Methoden der »EventEmitter«-Klasse
201
5
Dateisystem, Streams und Events
Methode
Beschreibung
emitter.off( eventName, listener )
Entfernt einen Event-Listener für ein Event. Alias für die Methode removeListener()
emitter.on( eventName, listener )
Registriert einen Event-Listener für ein Event.
emitter.once( eventName, listener )
Registriert einen Event-Listener, der bei Auftreten des Events genau einmal aufgerufen wird.
emitter.prependListener( eventName, listener )
Registriert einen Event-Listener für ein Event und fügt diesen an den Anfang der für dieses Event registrierten Event-Listener hinzu.
emitter.prependOnceListener( eventName, listener )
Registriert einen Event-Listener, der bei Auftreten des Events genau einmal aufgerufen wird, und fügt diesen an den Anfang der für dieses Event registrierten Event-Listener hinzu.
emitter.removeAllListeners( [eventName] )
Entfernt alle Event-Listener für ein Event.
emitter.removeListener(eventName, listener)
Entfernt einen Event-Listener für ein Event.
emitter.setMaxListeners(n)
Setzt die maximale Anzahl an Event-Listenern, die registriert werden können.
emitter.rawListeners(eventName)
Gibt eine Kopie des EventListener-Arrays für das entsprechende Event zurück.
Tabelle 5.5 Methoden der »EventEmitter«-Klasse (Forts.)
202
5.7
Rezept 34: Events versenden und empfangen
Eigene »EventEmitter«-Klassen Bei der Implementierung eigener Event-Emitter haben Sie die Wahl: Zum einen können Sie eine neue Klasse erstellen, die von der EventEmitter-Klasse ableitet, zum anderen können Sie der neuen Klasse auch eine Eigenschaft hinzufügen, hinter der eine Instanz der EventEmitter-Klasse hinterlegt ist. Letzteres gilt in der objektorientierten Programmierung eigentlich als bessere Praxis (Stichwort Composition over Inheritance bzw. Komposition vor Vererbung), weswegen ich im folgenden Praxisbeispiel diese Technik verwende. Listing 5.28 zeigt die Klasse Converter, die einen Algorithmus zur Konvertierung von HTML-Dateien bzw. Webseiten in PDF-Dateien skizziert und bei den verschiedenen Zwischenschritten (Starten des Konvertierungsprozesses, Starten des Downloads, Beenden des Downloads, Starten der PDF-Konvertierung, Beenden der PDF-Konvertierung und Beenden des Konvertierungsprozesses) entsprechende Events verschickt. const EventEmitter = require('events'); const ConverterEvents = require('./ConverterEvents'); module.exports = class Converter { constructor() { this._emitter = new EventEmitter(); } async convert(url) { this.notify(ConverterEvents.STARTED_CONVERSION, { url }); await this._wait(); this.notify(ConverterEvents.STARTED_DOWNLOAD, { url }); await this._wait(); this.notify(ConverterEvents.FINISHED_DOWNLOAD, { url }); await this._wait(); this.notify(ConverterEvents.STARTED_PDF_CONVERSION, { url }); await this._wait(); this.notify(ConverterEvents.FINISHED_PDF_CONVERSION, { url }); await this._wait(); this.notify(ConverterEvents.FINISHED_CONVERSION, { url }); } /** * Helper method to wait for a given number * of milliseconds. */
203
5
Dateisystem, Streams und Events
_wait(milliseconds = 500) { return new Promise((resolve, reject) => { setTimeout(resolve, milliseconds); }); } notify(event, message) { this._emitter.emit(event, { ...message }); } on(event, callback) { this._emitter.on(event, callback); } off(event, callback) { this._emitter.removeListener(event, callback); } }; Listing 5.28 Einbinden eines Event-Emitters über Komposition
Die einzelnen Event-Namen werden der Übersicht halber als Konstanten an zentraler Stelle in einer eigenen Datei verwaltet (Listing 5.29). Dies ist insofern ein Best Practice, als dass Sie dann sowohl innerhalb der Klasse, welche die Events auslöst, als auch in dem Code, der für diese Events entsprechende Event-Listener registriert, auf die gleichen Konstanten zugreifen können. Sollte sich der Name eines Events dann im Laufe der Entwicklung ändern, können Sie dies an zentraler Stelle anpassen. module.exports = { STARTED_CONVERSION: 'started_conversion', STARTED_DOWNLOAD: 'started_download', FINISHED_DOWNLOAD: 'finished_download', STARTED_PDF_CONVERSION: 'started_pdf_conversion', FINISHED_PDF_CONVERSION: 'finished_pdf_conversion', FINISHED_CONVERSION: 'finished_conversion' } Listing 5.29 Event-Namen werden am besten in einer eigenen Datei verwaltet.
204
5.7
Rezept 34: Events versenden und empfangen
Listing 5.30 zeigt den Code, der die Converter-Klasse verwendet und sich für die definierten Events registriert: const Converter = require('./Converter'); const ConverterEvents = require('./ConverterEvents'); const converter = new Converter(); // Registrierung der Event-Listener converter.on(ConverterEvents.STARTED_CONVERSION, (message) => { console.log(`Started converting ${message.url}`); }); converter.on(ConverterEvents.STARTED_DOWNLOAD, (message) => { console.log(`Started downloading ${message.url}`); }); converter.on(ConverterEvents.FINISHED_DOWNLOAD, (message) => { console.log(`Finished downloading ${message.url}`); }); converter.on(ConverterEvents.STARTED_PDF_CONVERSION, (message) => { console.log(`Started PDF conversion for ${message.url}`); }); converter.on(ConverterEvents.FINISHED_PDF_CONVERSION, (message) => { console.log(`Finished PDF conversion for ${message.url}`); }); converter.on(ConverterEvents.FINISHED_CONVERSION, (message) => { console.log(`Finished conversion for ${message.url}`); }); // Starten der Konvertierung converter.convert('http://www.nodejskochbuch.de'); Listing 5.30 Registrieren von Event-Listenern
5.7.2 Ausblick In diesem Rezept haben Sie gesehen, wie Sie mithilfe der EventEmitter-Klasse eigene Events versenden und empfangen können. Im nächsten Rezept möchte ich Ihnen ein weiteres Package vorstellen, das Ihnen noch mehr Flexibilität für das Arbeiten mit Events bietet.
Verwandte Rezepte 왘 Rezept 35: Erweiterte Features beim Event-Handling verwenden
205
5
Dateisystem, Streams und Events
5.8 Rezept 35: Erweiterte Features beim Event-Handling verwenden Sie möchten zwischen verschiedenen Komponenten einer Node.js-Anwendung über Events kommunizieren und dabei fortgeschrittene Features wie Wildcards einsetzen.
5.8.1 Lösung Bei der Verwendung des »events«-Packages stoßen Sie je nach Anforderung an Grenzen. Wenn bspw. ein Event-Listener insgesamt fünfmal aufgerufen werden soll und danach nicht mehr, müssten Sie eine lokale Zählervariable vorhalten und den EventListener dann entsprechend manuell für das Event deregistrieren. Oder ein anderer Anwendungsfall, der noch aufwendiger umzusetzen wäre: Angenommen, Sie verschicken Events mit den Namen »player.started«, »player.paused« und »player.stopped« und möchten einen Event-Listener für alle drei Events registrieren. Wäre es da nicht praktisch, Wildcards einsetzen zu können und den Event-Listener für »player.*« zu registrieren? Auch das ist mit dem »events«-Package nicht möglich. Ein Package, das genau diese Anwendungsfälle abdeckt, ist das Package »eventemitter2« (https://github.com/EventEmitter2/EventEmitter2). Die in diesem Package enthaltene Klasse EventEmitter2 erweitert die API der im vorherigen Rezept gezeigten Klasse EventEmitter (nicht über Vererbung, sondern hinsichtlich der API) und stellt zusätzliche Methoden und Konzepte zur Verfügung. So ist es bspw. möglich, exakt zu definieren, wie häufig ein Event-Listener für ein bestimmtes Event aufgerufen werden soll. Außerdem lassen sich innerhalb von EventNamen Wildcard-Operatoren einsetzen, wodurch das ganze Event-Handling nochmal deutlich flexibler wird. In Tabelle 5.6 finden Sie eine Übersicht der Methoden, die das »eventemitter2«-Package zusätzlich zu den Methoden aus dem »eventemitter«Package zur Verfügung stellt. Listing 5.31 zeigt, wie das eingangs erwähnte Beispiel über Wildcards umgesetzt werden könnte. const { EventEmitter2 } = require('eventemitter2'); const emitter = new EventEmitter2({ // Verwenden von Wildcards an- und ausschalten // standardmäßig auf "false" gesetzt. wildcard: true, // Angabe des Trennzeichens zur Segmentierung // von Namespaces, standardmäßig auf "." gesetzt. delimiter: '.',
206
5.8 Rezept 35: Erweiterte Features beim Event-Handling verwenden
// Angabe darüber, ob ein Event ausgelöst werden soll, // wenn ein neuer Listener hinzugefügt wurde, // standardmäßig auf "false" gesetzt. newListener: false, // Angabe über die maximale Anzahl an erlaubten // Listenern, standardmäßig auf 10 gesetzt. maxListeners: 20 }); emitter.on('player.*', (value) => { console.log(value); }); emitter.emit('player.started', { artist: 'Ben Harper', song: 'Diamonds On the Inside' }); emitter.emit('player.paused', { artist: 'Ben Harper', song: 'Diamonds On the Inside', minute: 2, second: 25 }); emitter.emit('player.volumechanged', { volume: 11 }); emitter.emit('player.stopped', {}); Listing 5.31 Verwenden des Packages »eventemitter2«
Methode
Beschreibung
emitter.onAny(listener)
Registriert einen Event-Listener, der aufgerufen wird, wenn irgendein Event ausgelöst wird.
emitter.prependAny(listener)
Registriert einen Event-Listener und fügt diesen an den Anfang der Liste für die Event-Listener hinzu, die für alle Events registriert sind.
Tabelle 5.6 Zusätzliche Methoden der »EventEmitter2«-Klasse
207
5
Dateisystem, Streams und Events
Methode
Beschreibung
emitter.offAny(listener)
Entfernt einen Event-Listener, der auf alle Events hört.
emitter.many( event, timesToListen, listener )
Registriert einen Event-Listener, der bei Auftreten des Events insgesamt n-mal aufgerufen wird.
emitter.prependMany( event, timesToListen, listener )
Registriert einen Event-Listener und fügt diesen an den Anfang der Liste für die Event-Listener hinzu, die für ein Event n-mal aufgerufen werden sollen.
emitter.listenersAny()
Gibt die Event-Listener zurück, die bei Auslösen irgendeines Events aufgerufen werden.
emitter.emitAsync( event, [arg1], [arg2], [...] )
Löst ein Event aus und gibt das Ergebnis aller für das Event registrierten Event-Listener mithilfe von Promise.all() zurück. Eignet sich also gut dazu, um die Berechnungen aller Event-Listener einzusammeln.
Tabelle 5.6 Zusätzliche Methoden der »EventEmitter2«-Klasse (Forts.)
5.8.2 Ausblick In diesem und dem vorherigen Rezept haben Sie gesehen, wie Sie unter Node.js mithilfe von Events zwischen einzelnen Komponenten einer Applikation kommunizieren können. Wenn Sie Nachrichten zwischen unterschiedlichen Komponenten austauschen möchten, die nicht von einer einzelnen Node.js-Anwendung gesteuert werden, sondern die entweder in verschiedenen Prozessen oder sogar auf verschiedenen Rechnern laufen, verwenden Sie statt des nativen Event-Mechanismus besser einen Message Broker. Wie dies funktioniert und welche verschiedenen Message Broker mit Node.js verwendet werden können, erfahren Sie in Kapitel 9, »Sockets und Messaging«, in Rezept 70 bis Rezept 72.
208
5.9
Zusammenfassung
Verwandte Rezepte 왘 Rezept 34: Events versenden und empfangen 왘 Rezept 70: Über AMQP auf RabbitMQ zugreifen 왘 Rezept 71: Einen MQTT-Broker erstellen 왘 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
5.9 Zusammenfassung Node.js bietet in der Standard-API eine Reihe von nützlichen Funktionalitäten. In diesem Kapitel haben wir uns dabei auf die Themen »Dateisystem«, »Streams« und »Events« konzentriert. Sie wissen jetzt also, wie Sie 왘 mit Dateien und Verzeichnissen arbeiten (Rezept 28), 왘 Dateien und Verzeichnisse überwachen (Rezept 29), 왘 Daten mit Streams lesen (Rezept 30), 왘 Daten mit Streams schreiben (Rezept 31), 왘 mehrere Streams über Piping kombinieren (Rezept 32), 왘 eigene Streams implementieren (Rezept 33), 왘 Events versenden und empfangen (Rezept 34), 왘 erweiterte Features beim Event-Handling verwenden (Rezept 35).
209
Kapitel 6 Datenformate In diesem Kapitel lernen Sie, wie Sie verschiedene Datenformate verarbeiten, die für die Entwicklung von Node.js-Applikationen relevant sind.
Bei der Entwicklung von Node.js-Applikationen haben Sie es oft mit verschiedenen Datentypen zu tun. Beispiele hierfür gibt es viele: Für die Implementierung von Webservices oder deren Aufruf werden oftmals XML oder JSON als Austauschformat verwendet, bei der Implementierung von Webanwendungen muss in vielen Fällen serverseitig HTML oder CSS generiert werden, und für die Konfiguration von Applikationen kommen neben JSON auch Formate wie YAML, TOML oder INI zum Einsatz. In diesem Kapitel möchte ich Ihnen verschiedene Rezepte vorstellen, mit deren Hilfe Sie die gebräuchlichsten Formate bei der Implementierung von Node.js-Applikationen verarbeiten können: 왘 Rezept 36: XML verarbeiten 왘 Rezept 37: XML generieren 왘 Rezept 38: RSS und Atom generieren und verarbeiten 왘 Rezept 39: CSV verarbeiten 왘 Rezept 40: HTML mit Template-Engines generieren 왘 Rezept 41: HTML mit der DOM-API generieren 왘 Rezept 42: YAML verarbeiten und generieren 왘 Rezept 43: TOML verarbeiten 왘 Rezept 44: INI verarbeiten und generieren 왘 Rezept 45: JSON validieren 왘 Rezept 46: JavaScript verarbeiten und generieren 왘 Rezept 47: CSS verarbeiten und generieren
6.1 Rezept 36: XML verarbeiten Sie möchten Daten verarbeiten, die im XML-Format vorliegen.
211
6
Datenformate
6.1.1 Einführung: XML-Verarbeitung XML, die Extensible Markup Language, ist ein weit verbreitetes Datenaustauschformat. Auch wenn Sie bei der Entwicklung von JavaScript-Anwendungen in den meisten Fällen eher auf das JSON-Format zurückgreifen werden, haben Sie es mit Sicherheit (gerade bei der Integration von bestehenden Webservices) auch mit XML zu tun. Dies gilt sowohl für das Verarbeiten von Antworten eines Webservice als auch beim Erstellen von Anfragen an einen Webservice. In diesem Rezept zeige ich Ihnen, wie Sie XML mit JavaScript verarbeiten können, im anschließenden Rezept dann, wie Sie mit JavaScript XML generieren können. Prinzipiell unterscheidet man beim Parsen von XML-Daten zwischen zwei verschiedenen Ansätzen bzw. zwei verschiedenen Arten von Parsern. DOM-Parser erstellen beim Parsen eines XML-Dokuments ein baumbasiertes Modell des Dokuments, das sogenannte Document Object Model oder kurz DOM. Dieses Modell wird im Speicher vorgehalten und erlaubt es, jederzeit auf beliebige Knoten zuzugreifen. Dem gegenüber stehen sogenannte SAX-Parser (SAX für Simple API for XML), die ein XML-Dokument ereignisgesteuert parsen und dabei für verschiedene Komponenten des XML entsprechende Events auslösen, bspw. wenn der Parser auf ein Element, ein Attribut oder den Textinhalt eines Elements trifft. Für die Events lassen sich bei einem SAX-Parser entsprechende Event-Listener registrieren, die dann während des Parsens aufgerufen werden. Im Gegensatz zum DOM-Parsing wird beim SAX-Parsing also nicht das gesamte XMLDokument als Modell im Speicher gehalten, sondern immer nur der Teil, den der Parser gerade verarbeitet. Vergleicht man das DOM-Parsing mit dem SAX-Parsing, eignet sich Ersteres daher eher für überschaubar große XML-Dokumente (bzw. solche, die nicht zu groß für den Speicher sind), Letzteres dagegen auch für beliebig große XML-Dokumente. Neben DOM und SAX gibt es mit StAX (Streaming API for XML) noch einen dritten Ansatz, bei dem ein Mittelweg zwischen den beiden vorgenannten Arten eingeschlagen wird. Für Node.js stehen sowohl für DOM als auch für SAX entsprechende Parser-Bibliotheken zur Verfügung. Eine Bibliothek für das StAX-Parsing allerdings gibt es nach meinem Wissen für Node.js nicht. Im Folgenden stelle ich Ihnen daher nur Packages für das DOM- und SAX-Parsing vor. Damit sollten Sie eigentlich alle Anwendungsfälle für die XML-Verarbeitung abdecken können. Als einzulesende Beispieldaten werden für die nachfolgenden Beispiele jeweils die Daten des folgenden XML verwendet, das eine einfache Struktur für die Definition von Kalendern bzw. Terminen vorgibt.
212
6.1
Rezept 36: XML verarbeiten
Max Mustermann
Katze füttern 8:00 Küche
Mit Freundin Schuhe einkaufen 9:00 Schuhgeschäft
Computer spielen 20:00 Am Computer
Listing 6.1 XML-Daten für die folgenden Code-Beispiele
6.1.2 Lösung 1: XML mit einem DOM-Parser verarbeiten Für das DOM-Parsing empfiehlt sich das Package »cheerio« (https://github.com/cheeriojs/cheerio), das Sie wie folgt installieren: $ npm install cheerio
In Listing 6.2 sehen Sie die Verwendung des Packages. Dargestellt ist hier, wie sich das eben gezeigte XML-Beispiel mithilfe von »cheerio« einlesen lässt, um anschließend auf verschiedene Elemente des XML-Baums zuzugreifen. Um XML-Daten (und übrigens auch HTML-Daten) einzulesen, stellt das Package die Methode load() zur Verfügung. Ihr übergeben Sie den einzulesenden XML- bzw. HTML-Inhalt in Form einer Zeichenkette sowie optional ein Konfigurationsobjekt, über das sich verschiedene Einstellungen konfigurieren lassen. Das von load() zu-
213
6
Datenformate
rückgegebene Funktionsobjekt stellt dann eine API bereit, die ähnlich wie die API der bekannten Frontend-Bibliothek »jQuery« (https://jquery.com/) funktioniert (die Bibliothek »jQuery« wird standardmäßig über die Variable $ bereitgestellt, weswegen ich in Listing 6.2 auch für »cheerio« diese Konvention gewählt habe). Durch Angabe sogenannter Selektoren lassen sich Suchanfragen an den XML-Baum stellen: Der Selektor »appointments appointment« bspw. gibt ein Array aller Elemente mit dem Namen »appointment« zurück, die sich unterhalb eines Elements mit dem Namen »appointments« befinden. Als zweiten Parameter können Sie bei solchen Suchanfragen optional dasjenige Element übergeben, unterhalb dessen gesucht werden soll. Dadurch können Sie die Suche gezielt auf bestimmte Bereiche des XML-Baums eingrenzen. In Listing 6.2 wird dies bspw. innerhalb der Schleife dazu genutzt, um gezielt innerhalb eines -Elements nach den Elementen , und zu suchen. Um auf einzelne Attribute eines Elements zuzugreifen, verwenden Sie die Methode attr(). In Listing 6.2 wird auf diese Weise z. B. auf das Attribut »name« des -Elements zugegriffen und anschließend ausgegeben. Über die Methode text() wiederum können Sie den Textinhalt eines Elements ermitteln, was in Listing 6.2 bspw. dazu verwendet wird, um die Beschreibung, die Uhrzeit und den Ort eines Termins auszugeben. const fs = require('fs'); const path = require('path'); const cheerio = require('cheerio'); const XML_PATH = path.join(__dirname, '..', '..', 'xml', 'calendar.xml'); fs.readFile(XML_PATH, (error, content) => { const $ = cheerio.load(content.toString(), { normalizeWhitespace: true, xmlMode: true }); const calendar = $('calendar'); const calendarName = calendar.attr('name'); console.log(`Calendar: ${calendarName}`) const owner = $('calendar owner name'); console.log(`Owner: ${owner.text()}`) const appointments = $('appointments appointment'); appointments.each((index, element) => { const description = $('description', element);
214
6.1
Rezept 36: XML verarbeiten
const time = $('time', element); const location = $('location', element); console.log(`Task: ${description.text()}`); console.log(`Time: ${time.text()}`); console.log(`Location: ${location.text()}`); }); }); Listing 6.2 XML-Daten lesen mit »cheerio«
Prinzipiell können Sie mit »cheerio« auf sehr einfache Art und Weise XML-Daten verarbeiten und gezielt auf die entsprechenden Elemente, Attribute etc. zugreifen. Für größere XML-Dokumente eignen sich DOM-Parser wie »cheerio« allerdings nur bedingt, weil für das gesamte einzulesende XML-Dokument entsprechender Speicher reserviert werden muss. In Fällen, in denen Sie es also mit großen Daten zu tun haben oder die Größe der Daten nicht vorhersagen können, empfiehlt sich daher der Einsatz eines SAX-Parsers.
6.1.3 Lösung 2: XML mit einem SAX-Parser verarbeiten Für Node.js steht Ihnen für das SAX-Parsing bspw. das Package »sax-js« (https://github.com/isaacs/sax-js) zur Verfügung, das Sie wie folgt installieren: $ npm install sax
Am einfachsten lässt sich »sax-js« wie in Listing 6.3 in Kombination mit Streams verwenden (siehe Kapitel 5, »Dateisystem, Streams und Events«). Erstellen Sie dazu wie in Listing 6.3 über die Methode createStream() einen entsprechenden SAX-Stream, laden Sie anschließend das zu verarbeitende XML in einen Readable Stream, und übergeben Sie es durch Aufruf der Methode pipe() an den SAX-Stream (noch besser: Verwenden Sie die Methode pipeline() aus Rezept 32, wenn es die verwendete Node.js-Version erlaubt). Mithilfe der Methode on() können Sie für verschiedene Events entsprechende EventListener definieren (Tabelle 6.1), bspw. wenn der SAX-Parser auf ein Attribut oder ein öffnendes Tag trifft. const const const const
fs = require('fs'); path = require('path'); sax = require('sax'); saxStream = sax.createStream();
saxStream.on('attribute', (attribute) => { console.log(attribute);
215
6
Datenformate
}); saxStream.on('opentag', (node) => { console.log(node); }); saxStream.on('error', (error) => { console.error(error); this._parser.error = null; this._parser.resume(); }); const XML_PATH = path.join(__dirname, '..', '..', 'xml', 'calendar.xml'); fs .createReadStream(XML_PATH) .pipe(saxStream); Listing 6.3 XML-Daten lesen mit »sax-js«
Event
Beschreibung
error
Wird ausgelöst, wenn ein Fehler auftritt.
text
Wird ausgelöst, wenn der Parser auf einen Textknoten trifft.
doctype
Wird ausgelöst, wenn der Parser auf den Dokumenttyp trifft.
processinginstruction
Wird ausgelöst, wenn der Parser auf eine Processing Instruction trifft.
opentagstart
Wird ausgelöst, wenn der Parser auf ein öffnendes Tag trifft, ohne dabei die Attribute zu berücksichtigen.
opentag
Wird ausgelöst, nachdem der Parser auf ein öffnendes Tag getroffen ist. Im Unterschied zu dem Event »opentagstart« enthält dieses Event auch Angaben zu den Attributen des Tags.
closetag
Wird ausgelöst, wenn der Parser auf ein schließendes Tag trifft.
attribute
Wird ausgelöst, wenn der Parser auf ein Attribut trifft.
Tabelle 6.1 Wichtige Events beim SAX-Parsing mit dem »sax«-Package
216
6.1
Rezept 36: XML verarbeiten
Event
Beschreibung
comment
Wird ausgelöst, wenn der Parser auf einen Kommentar trifft.
opencdata
Wird ausgelöst, wenn der Parser auf einen ) eines h2 {\n margin: 25px;\n background-color: rgb(240, 240, 240);\n}\n", "id": "" }, "end": { "line": 2, "column": 15 } }, "prop": "margin", "value": "25px" }, { "raws": { "before": "\n ", "between": ": " }, "type": "decl",
280
6.12
Rezept 47: CSS verarbeiten und generieren
"source": { "start": { "line": 3, "column": 3 }, "input": { "css": "div.someClass > h2 {\n margin: 25px;\n background-color: rgb(240, 240, 240);\n}\n", "id": "" }, "end": { "line": 3, "column": 39 } }, "prop": "background-color", "value": "rgb(240, 240, 240)" } ], "source": { "start": { "line": 1, "column": 1 }, "input": { "css": "div.someClass > h2 {\n margin: 25px;\n background-color: rgb(240, 240, 240);\n}\n", "id": "" }, "end": { "line": 4, "column": 1 } }, "selector": "div.someClass > h2" } ], "source": { "input": { "css": "div.someClass > h2 {\n margin: 25px;\n background-color: rgb(240, 240, 240);\n}\n", "id": "" },
281
6
Datenformate
"start": { "line": 1, "column": 1 } } } Listing 6.50 Abstrakter Syntaxbaum für das CSS-Beispiel
6.12.2 Lösung: eigene Plugins für »PostCSS« schreiben »PostCSS« kann, wie gezeigt, als einfacher CSS-Parser verwendet werden, Sie können es aber auch dazu verwenden, um CSS zu transformieren. In diesem Fall kommt der eingangs erwähnte Plugin-Mechanismus zum Einsatz, der beliebig um eigene Plugins erweitert werden kann. Listing 6.51 zeigt ein Plugin, das alle Farbwerte der CSS-Eigenschaft »backgroundcolor« in Hexadezimal-Farbwerte umwandelt (unter Verwendung des Packages »tinycolor2«, das ich Ihnen empfehle, wenn Sie in irgendeiner Form Farbwerte verarbeiten oder von einem Farbsystem in ein anderes Farbsystem konvertieren möchten). Die Definition des Plugins geschieht über Methode plugin(). Als ersten Parameter übergeben Sie dabei den Namen des Plugins, als weiteren Parameter eine Funktion, die dem Initialisieren des Plugins dient und ihrerseits eine Funktion zurückgibt, die den eigentlichen Code für das Plugin enthält und im Rahmen der CSS-Prozessierung von »PostCSS« aufgerufen wird. Innerhalb dieser Funktion wiederum haben Sie über den Parameter root Zugriff auf den abstrakten Syntaxbaum und die Möglichkeit, diesen zu verändern und an das nächste Plugin weiterzureichen (Parameter result). const postcss = require('postcss'); const tinycolor = require('tinycolor2'); module.exports = postcss.plugin('color-converter-plugin', opts => { opts = opts || {}; return (root, result) => { root.walkRules(rule => { const { selector } = rule; rule.walk(node => { const { prop, value } = node; if (prop === 'background-color') { const color = tinycolor(value); node.value = #${color.toHex()}; }
282
6.12
Rezept 47: CSS verarbeiten und generieren
}); }); }; }); Listing 6.51 Implementierung eines Plugins für »PostCSS«
In Listing 6.52 sehen Sie, wie sich das Plugin anschließend anwenden lässt. Die Initialisierung von »PostCSS« geschieht über den Aufruf postcss(), wobei die Liste der Plugins zu übergeben ist. Anschließend lässt sich über process() die eigentliche CSSProzessierung anstoßen. Damit Plugins auch asynchron arbeiten können, liefert die Methode process() ein Promise-Objekt zurück, sodass Sie auf das Ergebnis im Callback von then() zugreifen können. const const const const
postcss = require('postcss'); fs = require('fs'); path = require('path'); colorConverterPlugin = require('./color-converter-plugin');
const inputCSS = fs .readFileSync(path.join(__dirname, '..', 'styles.css')) .toString(); console.log(inputCSS); // Ausgabe: // div.someClass > h2 { // margin: 25px; // background-color: rgb(240, 240, 240); // } postcss([colorConverterPlugin()]) .process(inputCSS, { from: 'styles.css', to: 'styles.out.css' }) .then(result => { console.log(result.css); // Ausgabe: // div.someClass > h2 { // margin: 25px; // background-color: #f0f0f0; // } }); Listing 6.52 Anwendung eines Plugins in »PostCSS«
283
6
Datenformate
6.12.3 Ausblick Das Verarbeiten (und Transformieren) von CSS ist insbesondere für den Build-Prozess von Webanwendungen interessant. Dank des Plugin-Systems von »PostCSS« können Sie neue Transformationen relativ einfach implementieren und in den Build-Prozess integrieren
6.13 Zusammenfassung In diesem Kapitel haben Sie gesehen, wie Sie unter Node.js die verschiedensten Datenformate verarbeiten und/oder generieren können. Seien es typische Webformate wie HTML, CSS und JavaScript selbst, Austauschformate wie XML und JSON, Newsfeed-Formate wie RSS und Atom oder Konfigurationsformate wie YAML, TOML und INI: Für jedes dieser Formate (und nahezu für jedes andere Format) gibt es für Node.js entsprechende Packages, die Ihnen die Arbeit erleichtern. Zusammenfassend haben Sie in diesem Kapitel gelernt, wie Sie 왘 XML verarbeiten (Rezept 36), 왘 XML generieren (Rezept 37), 왘 RSS und Atom generieren und verarbeiten (Rezept 38), 왘 CSV verarbeiten (Rezept 39), 왘 HTML mit Template-Engines generieren (Rezept 40), 왘 HTML mit der DOM-API generieren (Rezept 41), 왘 YAML verarbeiten und generieren (Rezept 42), 왘 TOML verarbeiten (Rezept 43), 왘 INI verarbeiten und generieren (Rezept 44), 왘 JSON validieren (Rezept 45), 왘 JavaScript verarbeiten und generieren (Rezept 46), 왘 CSS verarbeiten und generieren (Rezept 47).
284
Kapitel 7 Persistenz Ob relational oder nicht relational: Node.js macht in jeder Hinsicht eine gute Figur in Bezug auf die Integration von Datenbanken.
Für alle bekannten Datenbanksysteme stehen mittlerweile entsprechende Treiber für Node.js zur Verfügung. In diesem Kapitel zeige ich Ihnen anhand bekannter Datenbanksysteme, wie die Integration in eine Node.js-Anwendung funktioniert. Dabei gehe ich zunächst auf relationale Datenbanken (auch: SQL-Datenbanken) ein (Rezepte 48 bis 50), im Anschluss (Rezepte 51 bis 53) dann auf nicht relationale Datenbanken (auch: NoSQL-Datenbanken). In jedem Rezept zeige ich Ihnen dabei, wie Sie sich aus einer Node.js-Applikation mit der jeweiligen Datenbank verbinden und wie Sie die sogenannten CRUD-Methoden (Create, Read, Update, Delete) ausführen können. 왘 Rezept 48: Auf eine MySQL-Datenbank zugreifen 왘 Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen 왘 Rezept 50: Objektrelationale Mappings definieren 왘 Rezept 51: Auf eine MongoDB-Datenbank zugreifen 왘 Rezept 52: Auf eine Redis-Datenbank zugreifen 왘 Rezept 53: Auf eine Cassandra-Datenbank zugreifen
7.1 Rezept 48: Auf eine MySQL-Datenbank zugreifen Sie möchten auf eine MySQL-Datenbank zugreifen und Datensätze lesen, anlegen, aktualisieren oder löschen.
7.1.1 Lösung Auch wenn für die Neuentwicklung einer Node.js-Anwendung der Trend eher zu der Verwendung einer NoSQL-Datenbank geht, sind relationale Datenbanksysteme (RDBMS) wie MySQL nach wie vor weit verbreitet. Insbesondere hinsichtlich komplexer Anfragen und bspw. Transaktionsmanagement sind relationale Datenbanken NoSQL-Datenbanken vorzuziehen.
285
7
Persistenz
MySQL installieren Damit Sie ohne viel Aufwand lokal auf Ihrem Rechner eine MySQL-Installation zum Laufen bringen, habe ich Ihnen eine entsprechende Docker-Compose-Datei vorbereitet (Listing 7.1). Neben der eigentlichen Datenbank wird zudem das Datenbankverwaltungssystem Adminer (https://www.adminer.org/) gestartet, das Sie anschließend unter http://localhost:8082/ aufrufen können. Damit haben Sie direkt eine grafische (Web)Oberfläche, mit der Sie auf die MySQL-Datenbank zugreifen können. version: '3.1' services: db: image: mysql restart: always environment: MYSQL_ROOT_PASSWORD: 1234 ports: - 3306:3306 expose: - 3306 volumes: - ./init-db-sql:/docker-entrypoint-initdb.d adminer: image: adminer restart: always ports: - 8082:8080 Listing 7.1 Docker-Compose-Datei für MySQL
Das Schema für die im Folgenden verwendete Beispieldatenbank sowie die Beispieldaten, die wir im Folgenden verwenden wollen, finden Sie unter https://dev. mysql.com/doc/index-other.html. Nach erfolgreichem Download legen Sie die beiden entsprechenden Dateien sakila-schema.sql und sakila-data.sql einfach innerhalb Ihres Node.js-Projektes in das Verzeichnis init-db-sql (bzw. in das Verzeichnis, in dem sich die Docker-Compose-Datei befindet). Dieses Verzeichnis ist in der Konfiguration von Docker Compose auf den Ordner /docker-entrypoint-initdb.d innerhalb des resultierenden Docker-Containers gemountet. Alle Dateien mit den Endungen .sh, .sql und .sql.gz, die innerhalb dieses Verzeichnisses liegen (bzw. eben in dem Verzeichnis, das dorthin gemountet ist), werden beim Erstellen des Containers ausgeführt und dienen dazu, den initialen Aufbau der Datenbank zu konfigurieren. Beachten Sie dabei: Da das Ausführen der Dateien in alphabetischer Reihenfolge geschieht, müssen Sie die beiden heruntergeladenen Dateien so umbenennen, dass die Schema-Datei in dieser Reihenfolge vorn steht und die Daten-Datei hinten. Ansonsten kommt es bei
286
7.1
Rezept 48: Auf eine MySQL-Datenbank zugreifen
dem Ausführen der Dateien zu einem Fehler, weil beim Anlegen der Daten die durch das Schema definierte Struktur nicht gefunden wurde.
Client für MySQL installieren Der bekannteste und wahrscheinlich meistgenutzte MySQL-Client für Node.js ist das Package »mysql« (https://github.com/mysqljs/mysql), das Sie wie folgt für Ihr Projekt installieren können: $ npm install mysql
Verbindung herstellen Um über das Package »mysql« eine Verbindung zu der Datenbank herzustellen, erstellen Sie, wie in Listing 7.2 zu sehen, zunächst über die Methode createConnection() ein Objekt, das die Verbindung repräsentiert, wobei über ein Konfigurationsobjekt die Verbindungseinstellungen wie Nutzername und Passwort sowie der Host und der Name der Datenbank angegeben werden können. Auf dem Verbindungsobjekt rufen Sie anschließend die Methode connect() auf. Die Callback-Funktion, die Sie hierbei als Parameter übergeben, wird aufgerufen, sobald die Verbindung hergestellt wurde oder beim Herstellen der Verbindung ein Fehler auftrat. Ist Letzteres der Fall, haben Sie über den Parameter error die Möglichkeit, auf detaillierte Informationen zu dem jeweiligen Fehler zuzugreifen. Um die Verbindung zu der Datenbank wieder zu trennen, verwenden Sie die Methode end(). const mysql = require('mysql'); const connection = mysql.createConnection({ host : 'localhost', user : 'root', password : '1234', database : 'sakila' }); connection.connect((error) => { if (error) { console.error(error); } else { console.log('Connected'); } }); connection.end(); Listing 7.2 Herstellen einer Verbindung zu MySQL
287
7
Persistenz
Lesen von Datensätzen Für das Lesen von Datensätzen und generell das Ausführen von Datenbankanfragen (Queries) stellt das Verbindungsobjekt (hier: connection) die Methode query() zur Verfügung (Listing 7.3). Diese Methode kann mit einer unterschiedlichen Anzahl an Parametern aufgerufen werden: Bei zwei Parametern bezeichnet der erste Parameter die Datenbankanfrage und der zweite Parameter die Callback-Funktion, die aufgerufen wird, sobald die Anfrage abgeschlossen wurde. Optional lässt sich zwischen diesen beiden Parametern aber noch ein dritter Parameter verwenden, über den spezielle Werte definiert werden können, die im Rahmen der Datenbankanfrage benötigt werden, bspw. die einzusetzenden Werte für Platzhalter (ein Beispiel hierzu folgt weiter unten im nächsten Abschnitt beim Erstellen von Datensätzen). Beim Lesen von Datensätzen sind lediglich zwei Parameter zu übergeben: zum einen die Datenbankanfrage (in diesem Fall eine SELECT-Anfrage), zum anderen die Callback-Funktion. Die gefundenen Datensätze sind in entsprechender Callback-Funktion in Form eines Arrays als Parameter rows aufgeführt, über das sich mit forEach() iterieren lässt. Jedes in diesem Array enthaltene Objekt hat dabei Eigenschaften, die den Spaltennamen der entsprechenden Tabelle entsprechen (im Beispiel sind dies actor_id, first_name, last_name und last_update; siehe auch die Kommandozeilenausgabe des Programms weiter unten). Möchten Sie innerhalb Ihres JavaScript-Codes aber mit anders benannten Eigenschaften arbeiten (bspw. in üblicher Camel-CaseSchreibweise), können Sie, wie in Listing 7.3 zu sehen, dank Objekt-Destructuring relativ einfach ein entsprechendes Objekt erzeugen. const mysql = require('mysql'); const connection = mysql.createConnection({ host: 'localhost', user: 'root', password: '1234', database: 'sakila' }); connection.connect(error => { if (error) { console.error(error); } else { console.log('Connected'); } }); const QUERY = 'SELECT * FROM actor'; connection.query(QUERY, (error, rows, fields) => { if (error) { console.error(error); }
288
7.1
Rezept 48: Auf eine MySQL-Datenbank zugreifen
console.log(rows); rows.forEach(row => { const { first_name: firstName, last_name: lastName } = row; // ... }); }); connection.end(); Listing 7.3 Lesen von Datensätzen
Die Ausgabe des Programms lautet wie folgt: [ { actor_id: 1, first_name: 'PENELOPE', last_name: 'GUINESS', last_update: 2006-02-15T03:34:33.000Z }, { actor_id: 2, first_name: 'NICK', last_name: 'WAHLBERG', last_update: 2006-02-15T03:34:33.000Z }, { actor_id: 3, first_name: 'ED', last_name: 'CHASE', last_update: 2006-02-15T03:34:33.000Z }, { actor_id: 4, first_name: 'JENNIFER', last_name: 'DAVIS', last_update: 2006-02-15T03:34:33.000Z }, { actor_id: 5, first_name: 'JOHNNY', last_name: 'LOLLOBRIGIDA', last_update: 2006-02-15T03:34:33.000Z }, ... ]
Erstellen von Datensätzen Um einen Datensatz zu erstellen, übergeben Sie der Methode query(), wie in Listing 7.4 gezeigt, eine entsprechende INSERT-Query (INSERT INTO actor SET ?). Als zweiten
289
7
Persistenz
Parameter übergeben Sie außerdem ein Objekt, dessen Eigenschaften entsprechend für die gleichnamigen Datenbankfelder eingesetzt werden und das intern für den Platzhalter in der Anfrage verwendet wird. Der Vorteil: »mysql« nimmt Ihnen die Arbeit ab und bildet automatisch die Eigenschaften des Objekts auf die passenden Datenbankfelder ab. Darüber hinaus verhindert es durch Escaping, dass die Anfragen syntaktisch nicht korrekt sind. Wurde der Datensatz erfolgreich erstellt, erhält das result-Objekt in der CallbackMethode die entsprechende ID des neuen Datensatzes über die Eigenschaft insertId (im Beispiel der Wert 201, weil in der Beispieldatenbank zuvor genau 200 Datensätze in der Datenbank waren). const mysql = require('mysql'); // Erstellen der Verbindung wie zuvor // ... const QUERY = 'INSERT INTO actor SET ?'; const actor = { first_name: 'MAX', last_name: 'MUSTERMANN', last_update: new Date() }; connection.query(QUERY, actor, (error, result) => { if (error) { console.error(error); } }); connection.end(); Listing 7.4 Erstellen von Datensätzen
Aktualisieren von Datensätzen Das Aktualisieren von Datensätzen funktioniert in MySQL über die UPDATE-Query. Über das ?-Zeichen können Sie dabei wieder Platzhalter definieren. Die konkret einzusetzenden Werte übergeben Sie der Methode query() in Form eines Arrays als zweiten Parameter. In Listing 7.5 wird auf diese Weise bspw. eine UPDATE-Query definiert, über die der Vorname des Schauspielers mit der ID 201 auf den Wert »MORITZ« gesetzt wird. Da von einer UPDATE-Query prinzipiell auch mehrere Datensätze betroffen sein können, enthält das result-Objekt in der Callback-Funktion die Eigenschaft changedRows, über die genau die Anzahl an geänderten Datensätzen ermittelt werden kann. const mysql = require('mysql'); // Erstellen der Verbindung wie zuvor // ...
290
7.1
Rezept 48: Auf eine MySQL-Datenbank zugreifen
const QUERY = 'UPDATE actor SET first_name = ? WHERE actor_id = ?'; const updateData = ['MORITZ', 201]; connection.query(QUERY, updateData, (error, result) => { if (error) { console.error(error); } console.log(`Changed ${result.changedRows} row(s)`); }); connection.end(); Listing 7.5 Aktualisieren von Datensätzen
Löschen von Datensätzen Für das Löschen von Datensätzen verwenden Sie die DELETE-Query. Eventuelle Platzhalter in der Query können Sie wie gewohnt in Form eines Arrays als zweiten Parameter für die query()-Methode übergeben. In Listing 7.6 bspw. wird der Datensatz mit der ID 201 aus der Datenbank gelöscht. Da auch beim Löschen von Datensätzen mehrere Datensätze betroffen sein können, lässt sich die genaue Anzahl in der Callback-Funktion über die Eigenschaft affectedRows des result-Objekts ermitteln. const mysql = require('mysql'); // Erstellen der Verbindung wie zuvor // ... const QUERY = 'DELETE FROM actor WHERE actor_id = ?'; const deleteData = [201]; connection.query(QUERY, deleteData, (error, result) => { if (error) { console.error(error); } console.log(`Deleted ${result.affectedRows} row(s)`); }); connection.end(); Listing 7.6 Löschen von Datensätzen
7.1.2 Ausblick In diesem Rezept haben Sie gesehen, wie Sie mithilfe des »mqysql«-Packages auf MySQL-Datenbanken zugreifen und Datensätze erstellen, lesen, aktualisieren und löschen können (mit anderen Worten: wie Sie die CRUD-Operationen durchführen können). Im nächsten Rezept zeige ich Ihnen, wie Sie Gleiches in Verbindung mit einer PostgreSQL-Datenbank machen. Im daran anschließenden Rezept 50 werde ich Ihnen schließlich zeigen, wie Sie den Zugriff auf relationale Datenbanken über sogenanntes objektrelationales Mapping vereinfachen.
291
7
Persistenz
Verwandte Rezepte 왘 Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen 왘 Rezept 50: Objektrelationale Mappings definieren
7.2 Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen Sie möchten auf eine PostgreSQL-Datenbank zugreifen.
7.2.1 Lösung Bei PostgreSQL (https://www.postgresql.org/) handelt es sich um ein objektrelationales Datenbankmanagementsystem (ORDBMS), dessen Entwicklung bereits in den 80er-Jahren begann und das somit schon über 30 Jahre alt ist.
PostgreSQL installieren PostgreSQL steht u. a. für Linux, macOS und Windows zur Verfügung, entsprechende Installationsanleitungen finden sich auf der offiziellen Website unter https://www. postgresql.org/download/. Alternativ dazu bietet es sich an, PostgreSQL über Docker zu starten. Dazu rufen Sie folgende Datei mit Docker Compose über den Befehl docker-compose up auf: version: '3.1' services: db: image: postgres restart: always environment: POSTGRES_USER: example_user POSTGRES_PASSWORD: example_password ports: - 5432:5432 volumes: - ./init-db-sql:/docker-entrypoint-initdb.d adminer: image: adminer restart: always ports: - 8080:8080 Listing 7.7 Docker-Compose-Datei für PostgreSQL
292
7.2
Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen
Neben der PostgreSQL-Installation wird Ihnen – wie schon im vorherigen Rezept – die Weboberfläche Adminer (https://www.adminer.org/) zur Verfügung gestellt, über die Sie auf die Datenbank zugreifen können. Öffnen Sie die Weboberfläche unter http://localhost:8080, und erstellen Sie über folgende Anweisung eine Tabelle, die Sie als Basis für die Beispiele verwenden: CREATE TABLE users ( id bigserial primary key, first_name varchar(20) NOT NULL, last_name varchar(20) NOT NULL, age integer NOT NULL ); Listing 7.8 SQL-Befehl für das Erstellen der Beispieltabelle
Client für PostgreSQL installieren Für Node.js stehen verschiedene Client-Bibliotheken für PostgreSQL zur Verfügung, wobei »node-postgres« (https://github.com/brianc/node-postgres) das bekannteste und am häufigsten verwendete Package sein dürfte. Installieren können Sie das Package über folgenden Befehl: $ npm install pg
Verbindung herstellen Nach erfolgreicher Installation binden Sie das Package wie gewohnt über require ('pg') ein (Listing 7.9). Die gesamte Kommunikation findet anschließend über die Klasse Client statt. Dem Konstruktor übergeben Sie dabei ein Konfigurationsobjekt, über das die Verbindungseinstellungen wie Nutzername, Passwort, Datenbank-Host und Datenbank-Port sowie der Name der Datenbank konfiguriert werden können. Alternativ können Sie dies auch über die Umgebungsvariablen PGUSER, PGPASSWORD, PGHOST, PGPORT und PGDATABASE festlegen oder dem Konfigurationsobjekt direkt in Form einer Connection URI (mit folgendem Aufbau postgresql://user:password@ host:port/database) als Eigenschaft connectionString übergeben. Die eigentliche Verbindung stellen Sie anschließend über die Methode connect() her. Diese Methode liefert ein Promise-Objekt als Rückgabewert und kann somit auch, wie in Listing 7.9 zu sehen, in Kombination mit await verwendet werden. Nachdem die Verbindung hergestellt wurde, können Sie Anfragen an die Datenbank stellen (die verschiedenen Arten der Anfragen schauen wir uns dabei in den folgenden Abschnitten an). Um die Verbindung zu einer Datenbank wieder zu trennen, verwenden Sie die Methode end().
293
7
Persistenz
const { Client } = require('pg'); const client = new Client({ user: 'example_user', password: 'example_password', host: 'localhost', port: 5432, database: 'tests' }); (async () => { try { await client.connect(); // ... await client.end(); } catch (error) { console.error(error); } })(); Listing 7.9 Herstellen einer Verbindung zu PostgreSQL
Erstellen von Datensätzen Das Ausführen von Datenbankanfragen und damit das Erstellen von neuen Datensätzen erfolgt über die generische Methode query(), der Sie einfach die entsprechende Datenbankanfrage in Form einer Zeichenkette als ersten Parameter übergeben. Innerhalb der Zeichenkette können Sie über $1, $2, $3 etc. Platzhalter definieren. Die einzusetzenden Werte werden der Methode query() dann in Form eines Arrays als zweiter Parameter übergeben. Im Beispiel in Listing 7.10 wird auf diese Weise ein Datenbankeintrag erzeugt, der in der Spalte first_name den Wert aus der Eigenschaft user.firstName, in der Spalte last_name den Wert aus der Eigenschaft user.lastName und in der Spalte age den Wert aus der Eigenschaft age enthält. const { Client } = require('pg'); const client = new Client({ user: 'example_user', password: 'example_password', host: 'localhost', port: 5432, database: 'tests' }); (async () => { try { await client.connect(); const user = {
294
7.2
Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen
firstName: 'Max', lastName: 'Mustermann', age: 45 }; const query = 'INSERT INTO users(first_name, last_name, age) values($1, $2, $3)' const result = await client.query( query, [user.firstName, user.lastName, user.age] ); await client.end(); } catch (error) { console.error(error); } })(); Listing 7.10 Erstellen von Datensätzen
Hinweis Die Methode query() kann sowohl in Kombination mit Callbacks verwendet werden als auch in Kombination mit Promises bzw. await. Soweit es Ihnen die Projektgegebenheiten erlauben (Stichwort: verwendete ECMAScript-Version), empfehle ich Ihnen der Übersichtlichkeit halber den Einsatz von Letzterem. Durch Promises und insbesondere durch die Kombination mit async und await ist der Code viel aufgeräumter und um einiges besser zu lesen.
Lesen von Datensätzen Auch das Lesen von Datensätzen geschieht über die Methode query(), wobei hierbei eine entsprechende SELECT-Anfrage zu übergeben ist (Listing 7.11). Das Ergebnis der Anfrage bzw. die gefundenen Datensätze sind als Array-Eigenschaft rows in dem zurückgegebenen Objekt enthalten, über das wie gewohnt iteriert werden kann. Zu beachten ist dabei, dass die Namen der Eigenschaften der einzelnen Ergebnisobjekte den Namen der Spalten in der jeweiligen Tabelle entsprechen. Um innerhalb Ihrer Applikation mit Eigenschaften in Camel-Case-Schreibweise weiterarbeiten zu können, müssen Sie die Eigenschaften, wie in Listing 7.11 zu sehen, von Hand mappen (hier konkret mithilfe von Object Destructuring). const { Client } = require('pg'); // Erstellen der Verbindung wie zuvor // ...
295
7
Persistenz
(async () => { try { await client.connect(); const query = 'SELECT * FROM users ORDER BY id ASC'; const result = await client.query(query); const { rows } = result; rows.forEach(row => { const { first_name: firstName, last_name: lastName } = row; // ... }); await client.end(); } catch (error) { console.error(error); } })(); Listing 7.11 Lesen von Datensätzen
Aktualisieren von Datensätzen Um Datensätze zu aktualisieren, verwenden Sie ebenfalls die Methode query(), der Sie dieses Mal jedoch eine entsprechende UPDATE-Anfrage übergeben. Folgendes Beispiel aktualisiert das Alter für den Eintrag, der für die Spalte first_name den Wert »Max« hat: const { Client } = require('pg'); // Erstellen der Verbindung wie zuvor // ... (async () => { try { await client.connect(); const user = { firstName: 'Max', lastName: 'Mustermann', age: 46 }; const query = 'UPDATE users SET age=($1) WHERE first_name=($2)'; await client.query(query, [ user.age, user.firstName ]); await client.end(); } catch (error) {
296
7.2
Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen
console.error(error); } })(); Listing 7.12 Aktualisieren von Datensätzen
Löschen von Datensätzen Für das Löschen von Datensätzen übergeben Sie der Methode query() eine DELETEAnfrage. Folgendes Beispiel löscht alle Datensätze aus der Tabelle users, für die first_ name den Wert »Max« hat: const { Client } = require('pg'); // Erstellen der Verbindung wie zuvor // ... (async () => { try { await client.connect(); const user = { firstName: 'Moritz', lastName: 'Mustermann', age: 45 }; const query = 'DELETE FROM users WHERE first_name=($1)'; await client.query(query, [ user.firstName ]); await client.end(); } catch (error) { console.error(error); } })(); Listing 7.13 Löschen von Datensätzen
Connection Pools verwenden Das Herstellen neuer Datenbankverbindungen ist nicht kostenlos: Zum einen kostet es Ressourcen, zum anderen kostet es Zeit. Letzteres spielt sich zwar im Millisekundenbereich ab, summiert sich bei vielen Anfragen aber merkbar. Hinzu kommt, dass Datenbankserver nur eine begrenzte Anzahl an Verbindungen aufrechterhalten können und somit bei zu vielen Verbindungen Probleme machen. Wenn Sie in einer Applikation also mehrere Anfragen an eine Datenbank stellen, ist es sinnvoll, einzelne Datenbankverbindungen wiederzuverwenden, anstatt für jede
297
7
Persistenz
Anfrage eine neue Verbindung herzustellen. Datenbank-Clients stellen dazu oftmals einen sogenannten Connection Pool bereit: Dabei handelt es sich um einen lokalen Cache von bestehenden Datenbankverbindungen, die dann für Anfragen (wieder) verwendet werden. Dies verbessert zum einen die Performance, zum anderen reduziert es den Ressourcenverbrauch. Listing 7.14 zeigt, wie Sie einen Connection Pool mit dem Node.js-Client verwenden. Statt wie zuvor die Client-Klasse importieren Sie nun die Pool-Klasse aus dem »pg«Package. Die Verwendung ist dabei analog, d. h., Sie übergeben dem Konstruktor der Pool-Klasse wie schon zuvor dem Konstruktor der Client-Klasse ein Konfigurationsobjekt mit entsprechenden Verbindungsinformationen und rufen für das Ausführen von Datenbankanfragen die Methode query() auf. Was wegfällt, ist ein explizites Verbinden zur Datenbank, weil dies intern durch den Connection Pool gehandhabt wird (zur Erinnerung: Bei Verwendung der Client-Klasse mussten Sie dies über einen Aufruf der Methode connect() machen). const { Pool } = require('pg'); const pool = new Pool({ user: 'example_user', password: 'example_password', host: 'localhost', port: 5432, database: 'tests' }); (async () => { try { const query = 'SELECT * FROM users ORDER BY id ASC'; const result = await pool.query(query); const { rows } = result; rows.forEach(row => { const { first_name: firstName, last_name: lastName } = row; console.log(${firstName} ${lastName}); }); await pool.end(); } catch (error) { console.error(error); } })(); Listing 7.14 Verwenden eines Connection Pools
298
7.3
Rezept 50: Objektrelationale Mappings definieren
7.2.2 Ausblick Sie haben in diesem und dem vorherigen Rezept gesehen, wie Sie mit Node.js auf zwei der prominentesten relationalen Datenbanksysteme zugreifen können. Hinsichtlich des Mappings von Datensätzen auf JavaScript-Objekte ist dabei aber (vor allem, wenn man Daten aus verschiedenen Tabellen kombiniert) mitunter einiges an Handarbeit notwendig. Aus diesem Grund ist in den vergangenen Jahren die Idee von sogenannten objektrelationalen Mappings (kurz ORMs) immer beliebter geworden. Was es damit auf sich hat und wie Sie ORMs unter Node.js verwenden können, zeige ich Ihnen im folgenden Rezept.
Verwandte Rezepte 왘 Rezept 48: Auf eine MySQL-Datenbank zugreifen 왘 Rezept 50: Objektrelationale Mappings definieren
7.3 Rezept 50: Objektrelationale Mappings definieren Sie möchten auf eine Datenbank zugreifen, dabei aber nicht direkt mit den Anfragen der jeweiligen Query Language in Berührung kommen und sich nicht von Hand um das Mapping von Tabellendaten zu JavaScript-Objekten kümmern.
7.3.1 Exkurs: Objektrelationale Mappings Object-Relational Mapping (kurz ORM) sorgt dafür, dass Objekte auf relationale Datenbanken abgebildet (gemappt) werden und umgekehrt die Daten aus relationalen Datenbanken zurück in Objekte (siehe Abbildung 7.1). ORMs stellen damit eine zusätzliche Abstraktionsschicht für den Zugriff auf die in Datenbanken gespeicherten Daten dar. Mit anderen Worten: Innerhalb des Codes arbeitet man nicht direkt mit Statements der jeweiligen Datenbankanfragensprache (bspw. wie in den vorherigen beiden Rezepten mit SQL-Statements), sondern mit Objekten, die den Zugriff auf die Datenbank abstrahieren.
Hinweis Durch diese Abstraktion ist es in der Regel auch ohne großen Aufwand möglich, ein bestimmtes Datenbanksystem durch ein anderes zu ersetzen. Lediglich der vom ORM verwendete Datenbanktreiber muss dazu ausgetauscht werden. Einen Nachteil haben ORMs allerdings auch: Insgesamt stellen sie einen zusätzlichen Overhead dar und können die Applikation an sich dadurch langsamer machen.
299
Persistenz
MappingLogik
7
Relationale Datenbank
Objekte
Abbildung 7.1 Das Prinzip des objektrelationalen Mappings
Prinzipiell gibt es verschiedene Techniken, wie das Mapping von Objekten auf Tabellen realisiert wird: 왘 Tabelle pro Vererbungshierarchie: Hierbei werden die Eigenschaften einer Klasse
zusammen mit den Eigenschaften aller Unterklassen in einer einzigen Tabelle gespeichert (Abbildung 7.2). Damit festgestellt werden kann, welche Klasse einem Datensatz in der Tabelle zugrunde liegt, und um ausgehend davon in der Lage sein zu können, aus einem Datensatz entsprechende Objektinstanzen zu erzeugen, wird darüber hinaus zusätzlich der Typ (bzw. der Klassenname) in einer weiteren Spalte gespeichert. Person
Persons
name
name address id
Customer address
type
Employee id Klassenhierarchie
→
Tabelle
Abbildung 7.2 Eine Tabelle pro Vererbungshierarchie 왘 Tabelle pro Unterklasse: Hierbei wird für jede Klasse, also sowohl für die Basis-
klasse als auch für alle ableitenden Unterklassen, eine eigene Tabelle verwendet, wobei in jeder Tabelle nur die direkten Eigenschaften der jeweiligen Klasse gespeichert werden (Abbildung 7.3). Beim Erzeugen von Objektinstanzen ausgehend von einzelnen Datensätzen ergibt sich der Typ direkt aus der jeweiligen Tabelle.
300
7.3
Rezept 50: Objektrelationale Mappings definieren
Person
Persons
name
name
Customer
Customers
Employee
address
address
id
Employees id Klassenhierarchie
→
Tabelle
Abbildung 7.3 Eine Tabelle pro Unterklasse 왘 Tabelle pro konkrete Klasse: ähnlich wie der zuvor beschriebene Ansatz, aber mit
dem Unterschied, dass es keine Tabelle für die Basisklasse gibt. Stattdessen werden die Eigenschaften der Basisklasse in jeder Tabelle für die entsprechenden Unterklassen mit aufgeführt (Abbildung 7.4).
Person
Customers
name
Customer address
name address Employee Employees
id
name id Klassenhierarchie
→
Tabelle
Abbildung 7.4 Eine Tabelle pro konkrete Klasse
7.3.2 Lösung Eine bekannte ORM-Bibliothek für Node.js ist »Sequelize.js« (http://docs.sequelizejs.com/), die direkt in Kombination mit mehreren Datenbanksystemen verwendet werden kann: So werden momentan bspw. MySQL, PostgreSQL, SQLite und MSSQL unterstützt.
301
7
Persistenz
Installieren können Sie »Sequelize.js« für Ihr Projekt wie folgt: $ npm install sequelize
Hinweis Die in diesem Rezept gezeigten Code-Beispiele setzen eine laufende MySQL-Datenbank voraus. Um diese zu starten, verwenden Sie bitte die entsprechende Konfigurationsdatei für Docker Compose aus Rezept 48.
Verbindung herstellen Listing 7.15 zeigt die notwendigen Schritte für die Konfiguration einer neuen Sequelize-Objektinstanz. Dem Konstruktor übergibt man dabei ein Konfigurationsobjekt, über dessen Eigenschaften sich das jeweils verwendete Datenbanksystem konfigurieren lässt. Im Fall von SQL (egal ob MySQL oder PostgreSQL) sind dies, wie im Beispiel gezeigt, Einstellungen wie Hostname und optional Benutzername, Passwort und die verwendete Datenbank. Je nach verwendetem Datenbanksystem können sich die Eigenschaften aber auch unterscheiden. Die Eigenschaft dialect ist allerdings in allen Fällen zwingend anzugeben: Anhand des hier definierten Wertes wählt »Sequelize.js« intern den passenden Treiber für das jeweilige Datenbanksystem aus. const Sequelize = require('sequelize'); const sequelize = new Sequelize({ host: 'localhost', dialect: 'mysql', database: 'sakila', username: 'root', password: '1234' }); Listing 7.15 Erstellen einer »Sequelize«-Instanz
Nach der Konfiguration der Datenbank ist es anschließend möglich, sogenannte Models zu definieren, welche die Tabellen in der entsprechenden Datenbank abstrahieren (Listing 7.16). Die Definition eines Models geschieht dabei über die Methode define() der eben erzeugten Sequelize-Objektinstanz. Der Methode übergeben Sie dabei zum einen den Namen der Tabelle sowie zum anderen ein Objekt, das den Aufbau dieser Tabelle bzw. das Mapping zu dieser Tabelle beschreibt. Als dritten, optionalen Parameter lässt sich ein weiteres Konfigurationsobjekt übergeben, über das sich zusätzliche Aspekte konfigurieren lassen: Beispielsweise werden standardmäßig die Tabellennamen als Plural des angegebenen Namens erzeugt, im Beispiel wäre dies standardmäßig »actors«. Über freezeTableName: true können Sie
302
7.3
Rezept 50: Objektrelationale Mappings definieren
dem entgegenwirken und erzwingen, dass »Sequelize.js« stattdessen exakt den angegebenen Namen verwendet (im Beispiel: »actor«). Über timestamps: false sorgen Sie außerdem dafür, dass »Sequelize.js« nicht automatisch die beiden Eigenschaften createdAt und updatedAt für jeden Datensatz erzeugt. Der Aufruf von sequelize. sync() sorgt schließlich dafür, dass die Datenbank mit dem definierten Model synchronisiert wird. const Actor = sequelize.define( 'actor', { actor_id: { type: Sequelize.INTEGER, primaryKey: true, autoIncrement: true }, first_name: Sequelize.STRING, last_name: Sequelize.STRING }, { // Standardmäßig werden die Tabellennamen als Plural des // angegebenen Namens erzeugt, im Beispiel "actors". Möchte // man dies verhindern, muss die Eigenschaft "freezeTableName" // auf "true" gesetzt werden. freezeTableName: true, timestamps: false } ); (async() => { await sequelize.sync(); })(); Listing 7.16 Definieren eines Models
Standardmäßig entsprechen die Namen der Eigenschaften eines Models den Namen der jeweiligen Felder in der Datenbank. Über die Eigenschaft field haben Sie jedoch die Möglichkeit, ein Mapping anzugeben, sodass Sie bei der Wahl der Eigenschaftsnamen völlig frei sind (Listing 7.17). const Actor = sequelize.define( 'actor', { id: { field: 'actor_id', type: Sequelize.INTEGER,
303
7
Persistenz
primaryKey: true, autoIncrement: true }, firstName: { field: 'first_name', type: Sequelize.STRING }, lastName: { field: 'last_name', type: Sequelize.STRING } }, { freezeTableName: true, timestamps: false } ); Listing 7.17 Mapping von Eigenschaften des Models auf Datenbankfelder
Lesen von Datensätzen Ausgehend von dem im vorherigen Abschnitt definierten Model, können Sie nun Anfragen an die Datenbank ausführen, indem Sie einfach Methoden der erzeugten Model-Instanz aufrufen. Über Actor.findAll() können Sie, wie in Listing 7.18 gezeigt, bspw. alle Datensätze aus der Tabelle »actor« (bzw. »actors«) auslesen. Im Beispiel wird auch direkt der Vorteil von »Sequelize.js« deutlich: Dank des im Model definierten Mappings enthalten die zurückgegebenen Objekte direkt die richtig benannten Eigenschaften. Sie müssen sich also nicht wie beim direkten Zugriff (Rezept 48 und Rezept 49) selbst darum kümmern, die Eigenschaften entsprechend umzubenennen. ... (async () => { await sequelize.sync(); const actors = await Actor.findAll(); actors.forEach(actor => { console.log(actor.id); console.log(actor.firstName); console.log(actor.lastName); }); })(); Listing 7.18 Lesen von Datensätzen
304
7.3
Rezept 50: Objektrelationale Mappings definieren
Um die Suche weiter einzugrenzen, können Sie der Methode findAll() zudem ein Konfigurationsobjekt übergeben, mit dessen Hilfe Sie bestimmte Suchkriterien definieren können. Um bspw. alle Datensätze zurückzugeben, für die das Feld last_name den Wert »MUSTERMANN« hat, würden Sie wie folgt vorgehen: (async () => { await sequelize.sync(); const actors = await Actor.findAll({ where: { lastName: 'MUSTERMANN' } }); console.log('--------'); actors.forEach(actor => { console.log(actor.id); console.log(actor.firstName); console.log(actor.lastName); }); })(); Listing 7.19 Angabe von Suchkriterien beim Lesen von Datensätzen
Erstellen von Datensätzen Um neue Datensätze zu erstellen, verwenden Sie die Methode create(). Ihr übergeben Sie das zu speichernde Objekt basierend auf dem definierten Model. Auch hierbei wird wieder deutlich, wie bequem es ist, wenn Sie sich innerhalb Ihres Applikations-Codes nicht um das Mapping kümmern müssen und Objekte aus Ihrer Applikationslogik direkt speichern können. … (async () => { await sequelize.sync(); const result = await Actor.create({ firstName: 'MAX', lastName: 'MUSTERMANN' }); console.log(result); })(); Listing 7.20 Erstellen von Datensätzen
305
7
Persistenz
Aktualisieren von Datensätzen Für das Aktualisieren von Datensätzen steht die Methode update() zur Verfügung. Ihr übergeben Sie als ersten Parameter die aktuellen Daten und als zweiten Parameter ein Konfigurationsobjekt, über das der zu aktualisierende Datensatz spezifiziert werden kann. In Listing 7.21 bspw. wird über die Eigenschaft where definiert, dass alle Personen, die den Vornamen »MAX« und den Nachnamen »MUSTERMANN« haben, fortan den Vornamen »MORITZ« erhalten. ... (async () => { await sequelize.sync(); await Actor.update( { firstName: 'MORITZ' }, { where: { firstName: 'MAX', lastName: 'MUSTERMANN' } } ); })(); Listing 7.21 Aktualisieren von Datensätzen
Löschen von Datensätzen Zu guter Letzt lassen sich einzelne Datensätze über die Methode destroy() wieder löschen. Wie schon bei der Methode update() definieren Sie über ein Konfigurationsobjekt, welche Datensätze gelöscht werden sollen. In Listing 7.22 bspw. werden alle Einträge gelöscht, deren Vorname »MAX« und deren Nachname »MUSTERMANN« lautet. ... (async () => { await sequelize.sync(); await Actor.destroy({ where: { firstName: 'MAX', lastName: 'MUSTERMANN' }
306
7.4
Rezept 51: Auf eine MongoDB-Datenbank zugreifen
}); })(); Listing 7.22 Löschen von Datensätzen
Hinweis Durch die Abstraktion von der konkret verwendeten Datenbank stellt »Sequelize.js« in gewisser Weise eine Art Adapter-Package dar, dessen Prinzip Sie schon in Kapitel 3, »Logging und Debugging«, in Rezept 18 kennengelernt haben. Durch die Verwendung von Sequelize bleiben Sie unabhängig von der verwendeten Datenbank, genauso wie Sie dies in Kapitel 3 dank Adapter-Package auch für Logging-Bibliotheken erreicht haben.
7.3.3 Ausblick Neben den gezeigten Methoden für das Anlegen, Lesen, Aktualisieren und Löschen von Datensätzen stellt »Sequelize.js« viele weitere Methoden zur Verfügung, die das Arbeiten mit relationalen Datenbanken vereinfachen. Weitere Informationen diesbezüglich finden Sie in der offiziellen Dokumentation unter http://docs.sequelizejs.com/. Sollten die von einem Sequelize-Modell zur Verfügung gestellten Methoden einen bestimmten Anwendungsfall nicht abdecken, haben Sie zudem über die Methode sequelize.query('') immer die Möglichkeit, direkt Anfragen an das jeweilige Datenbanksystem zu formulieren. Neben »Sequelize.js« gibt es für Node.js noch eine Reihe weitere ORMs, die einen Blick wert sind: Zu den bekannteren zählen »Bookshelf.js« (https://bookshelfjs.org/), »TypeORM« (http://typeorm.io/), »waterline.js« (http://waterlinejs.org/) und »nodeorm2« (https://github.com/dresende/node-orm2).
Verwandte Rezepte 왘 Rezept 48: Auf eine MySQL-Datenbank zugreifen 왘 Rezept 49: Auf eine PostgreSQL-Datenbank zugreifen
7.4 Rezept 51: Auf eine MongoDB-Datenbank zugreifen Sie möchten auf die Daten in einer MongoDB-Datenbank zugreifen.
307
7
Persistenz
7.4.1 Lösung Bei MongoDB handelt es sich um eine in C++ geschriebene, verteilte NoSQL-Datenbank. Im Gegensatz zu relationalen DBMS ist MongoDB dokumentenbasiert, wobei die Dokumente in Form einer JSON-Struktur gespeichert werden. Gegenüber relationalen Datenbanken bietet eine NoSQL-Datenbank wie MongoDB verschiedene Vorteile hinsichtlich Performance, Skalierbarkeit und Verfügbarkeit.
MongoDB installieren Bevor Sie mit dem Zugriff per Node.js loslegen können, benötigen Sie zunächst einen MongoDB-Server, entsprechende Installationsdateien können Sie sich unter https:// www.mongodb.com/download-center#atlas herunterladen. Ich empfehle allerdings die Verwendung von Docker bzw. Docker Compose und habe Ihnen eine entsprechende Konfigurationsdatei vorbereitet, die Sie wie gewohnt über den Befehl dockercompose up starten können: version: '3.7' services: mongodb: image: mongo:latest environment: - MONGO_DATA_DIR=/data/db - MONGO_LOG_DIR=/dev/null volumes: - ./data/db:/data/db ports: - 27017:27017 Listing 7.23 Docker-Compose-Datei für MongoDB
Client für MongoDB installieren Um auf eine MongoDB aus JavaScript heraus unter Node.js zugreifen zu können, benötigen Sie einen entsprechenden Treiber, der in Form des Packages »mongodb« (https://mongodb.github.io/node-mongodb-native/) daherkommt und durch folgenden Befehl installiert werden kann: $ npm install mongodb
Verbindung herstellen Das Package »mongodb« exportiert das Objekt MongoClient, über das die gesamte Kommunikation mit einer MongoDB stattfindet. Um eine Verbindung zur Datenbank herzustellen, verwenden Sie, wie in Listing 7.24 zu sehen, die Methode connect(), die als ersten Parameter die URL erwartet, unter der die Datenbank zu er-
308
7.4
Rezept 51: Auf eine MongoDB-Datenbank zugreifen
reichen ist (siehe auch Hinweiskasten »Aufbau Verbindungs-URL«) und als zweiten Parameter eine Callback-Funktion, die aufgerufen werden soll, wenn die Verbindung erfolgreich hergestellt wurde, oder auch dann, wenn die Verbindung nicht hergestellt werden konnte. Ist Ersteres der Fall, hat das Fehlerobjekt error im Callback den Wert null, andernfalls erhält man hierüber Informationen zu den genauen Fehlerursachen. Über client.close() lässt sich die Verbindung vom MongoDB-Server wieder trennen. const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; MongoClient.connect(URL, (error, client) => { if (error) { throw error; } console.log('Connected successfully to server'); client.close(); }); Listing 7.24 Verbindung herstellen zu einer MongoDB
Aufbau Verbindungs-URL Die URL für die Verbindung zur MongoDB hat den folgenden Aufbau: mongodb: //[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]] [/[database][?options]]. Über das Präfix mongodb:// definieren Sie dabei das MongoDB-Protokoll, anschließend können optional Nutzername und Passwort angegeben werden, gefolgt von dem Host und – ebenfalls optional – dem Port (standardmäßig 27017). Darauf folgen der Name der Datenbank, zu der die Verbindung aufgebaut werden soll, und – wieder optional – weitere Optionen. Weitere Informationen hierzu finden Sie unter der URL https://docs.mongodb.com/manual/reference/connectionstring/.
Erstellen von Collections MongoDB speichert Datensätze in sogenannten Collections, die mehr oder weniger das Äquivalent zu Tabellen in relationalen Datenbanken sind. Um eine neue Collection zu erstellen, führen Sie, wie in Listing 7.25 zu sehen, die Methode createCollection() auf dem Datenbankobjekt aus, das Sie über den Aufruf client.db() ermitteln. Dabei übergeben Sie den Namen der zu erstellenden Collection sowie eine CallbackFunktion, die aufgerufen wird, wenn die Collection erstellt wurde oder es dabei zu einem Fehler kam. In ersterem Fall erhält man ein Objekt, das die Collection repräsentiert (hier: collection), in letzterem das Fehler-Objekt mit detaillierten Informationen zu dem Fehler (hier: error).
309
7
Persistenz
const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); db.createCollection(COLLECTION, (error, collection) => { if (error) { return error; } console.log('Collection created'); client.close(); }); }); Listing 7.25 Erstellen einer Collection
Erstellen von Datensätzen Für das Speichern von Objekten steht am Objekt, das eine Collection repräsentiert, die Methode insert() zur Verfügung. Ein Beispiel hierzu sehen Sie in Listing 7.26: Hier wird nach dem Verbinden zur Datenbank und dem Zugriff auf die Collection über die Methode collection() ein Objekt contact erstellt und über insert() der Collection hinzugefügt. const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); const collection = db.collection(COLLECTION); const contact = { firstName: 'Max', lastName: 'Mustermann', age: 45 } collection.insert(contact, (error, result) => { if (error) { throw error; }
310
7.4
Rezept 51: Auf eine MongoDB-Datenbank zugreifen
}); client.close(); }); Listing 7.26 Erstellen von Datensätzen
Möchten Sie direkt auf einen Schlag mehrere Datensätze einfügen, verwenden Sie, wie in Listing 7.27 zu sehen, die Methode insertMany() und übergeben dabei die Datensätze in Form eines Arrays. const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); const collection = db.collection(COLLECTION); const contacts = [ { firstName: 'Moritz', lastName: 'Mustermann', age: 45 }, { firstName: 'Peter', lastName: 'Mustermann', age: 68 }, { firstName: 'Petra', lastName: 'Mustermann', age: 66 } ]; collection.insertMany(contacts, (error, result) => { if (error) { throw error; } }); client.close(); }); Listing 7.27 Erstellen von mehreren Datensätzen
311
7
Persistenz
Hinweis Um sich einen Überblick über die in einer MongoDB gespeicherten Daten zu verschaffen, empfiehlt sich das Tool Robo 3T (https://robomongo.org/download), das Ihnen eine grafische Oberfläche zur Verfügung stellt (Abbildung 7.5). Hierüber können Sie bspw. Anfragen an die Datenbank formulieren, Daten ändern, löschen und vieles mehr.
Abbildung 7.5 Die Oberfläche von Robo 3T
Lesen von Datensätzen Um ein Objekt aus einer Collection zu lesen, verwenden Sie die Methode find(). Ohne Parameter liefert diese alle in der jeweiligen Collection enthaltenen Objekte zurück. In Listing 7.28 lassen wir uns bspw. alle Datensätze der Collection »contacts« ausgeben: const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); const collection = db.collection(COLLECTION); collection.find().toArray((error, contacts) => {
312
7.4
Rezept 51: Auf eine MongoDB-Datenbank zugreifen
if (error) { throw error; } console.log(contacts); }); client.close(); }); /* [ { _id: 5c750a2fa46586e02fb7a9ea, firstName: 'Max', lastName: 'Mustermann', age: 45 }, { _id: 5c750a547f3eb3e076c38653, firstName: 'Moritz', lastName: 'Mustermann', age: 45 }, { _id: 5c750a547f3eb3e076c38654, firstName: 'Peter', lastName: 'Mustermann', age: 68 }, { _id: 5c750a547f3eb3e076c38655, firstName: 'Petra', lastName: 'Mustermann', age: 66 } ] */ Listing 7.28 Lesen von Datensätzen
Möchten Sie nur solche Objekte auswählen, die einem bestimmten Kriterium entsprechen, haben Sie zudem die Möglichkeit, der Methode find() ein entsprechendes Konfigurationsobjekt zu übergeben. In Listing 7.29 bspw. wird eine Suche ausgeführt, die als Ergebnis nur die Objekte enthält, deren Eigenschaft age den Wert »45« hat. const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); const collection = db.collection(COLLECTION); collection .find({ age: 45
313
7
Persistenz
}) .toArray((error, contacts) => { if (error) { throw error; } console.log(contacts); }); client.close(); }); /* [ { _id: 5c750a2fa46586e02fb7a9ea, firstName: 'Max', lastName: 'Mustermann', age: 45 }, { _id: 5c750a547f3eb3e076c38653, firstName: 'Moritz', lastName: 'Mustermann', age: 45 } ] */ Listing 7.29 Lesen von Datensätzen nach Kriterium
Aktualisieren von Datensätzen Collections stellen drei verschiedene Methoden bereit, um Objekte zu aktualisieren: Über updateOne() lässt sich ein einzelnes Objekt aktualisieren, über updateMany() mehrere Objekte, und über replaceOne() können Objekte komplett ersetzt werden. Alle drei Methoden erwarten dabei drei Parameter: ein Konfigurationsobjekt, das die zu aktualisierenden Objekte beschreibt, ein Konfigurationsobjekt (wie schon bei der Methode find()), das die vorzunehmenden Änderungen beschreibt, sowie eine Callback-Funktion, die nach Aktualisieren der Objekte oder bei einem Fehler aufgerufen wird. Ein Beispiel für die Verwendung von updateOne() zeigt Listing 7.30: const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); const collection = db.collection(COLLECTION); collection.updateOne( { firstName: 'Max',
314
7.4
Rezept 51: Auf eine MongoDB-Datenbank zugreifen
lastName: 'Mustermann' }, { $set: { age: 46 } }, (error, result) => { if (error) { throw error; } console.log('Updated document'); } ); client.close(); }); Listing 7.30 Aktualisieren von Datensätzen
Löschen von Datensätzen Für das Löschen von Objekten aus einer Collection stehen Ihnen zwei Methoden zur Verfügung: Die Methode deleteOne() löscht ein einzelnes Objekt, die Methode deleteMany() dagegen mehrere. Beide Methoden erwarten als Parameter ein Konfigurationsobjekt, über das Sie anhand von Kriterien definieren können, welche Objekte gelöscht werden sollen. In Listing 7.31 bspw. werden durch den Aufruf von deleteMany() alle Einträge der Collection »contacts« gelöscht, deren Eigenschaft age den Wert »45« hat. const { MongoClient } = require('mongodb'); const URL = 'mongodb://localhost:27017'; const DATABASE = 'example'; const COLLECTION = 'contacts'; MongoClient.connect(URL, (error, client) => { console.log('Connected successfully to server'); const db = client.db(DATABASE); const collection = db.collection(COLLECTION); collection.deleteMany( { age: 45 }, (error, result) => { if (error) { throw error; } console.log('Removed documents');
315
7
Persistenz
} ); client.close(); }); Listing 7.31 Löschen von Datensätzen
7.4.2 Ausblick In diesem Rezept haben Sie gesehen, wie Sie unter Node.js auf die nicht relationale MongoDB zugreifen können. Eine Bibliothek, die Sie sich in diesem Zusammenhang auch näher anschauen können, ist Mongoose (https://mongoosejs.com/), das für MongoDB in etwa das darstellt, was Sequelize für MySQL und PostgreSQL darstellt: Mongoose abstrahiert von dem konkreten Zugriff auf eine MongoDB und stellt verschiedene Funktionalitäten bereit, um Objekte ohne MongoDB-spezifischen Code direkt aus einer Node.js-Applikation zu speichern. Im nächsten Rezept möchte ich Ihnen eine weitere nicht relationale Datenbank vorstellen, die im Unterschied zu MongoDB keine dokumentenbasierte Datenbank ist, sondern ein sogenannter Key Value Store.
7.5 Rezept 52: Auf eine Redis-Datenbank zugreifen Sie möchten auf eine Redis-Datenbank zugreifen.
7.5.1 Lösung Bei Redis (https://redis.io/) handelt es sich um einen Key Value Store (auch Key Value Database oder im Deutschen eine Schlüssel-Wert-Datenbank), d. h., Werte (Values) innerhalb der Datenbank werden über Schlüssel (Keys) eindeutig identifiziert. Redis unterscheidet sich zudem von gleichartigen Persistenzlösungen insofern, als dass die Daten vollständig im Speicher vorgehalten werden. Als Einschränkung hat dies natürlich zur Folge, dass nur solche Daten gespeichert werden können, die nicht größer als der zur Verfügung stehende Speicher sind (es sei allerdings angemerkt, dass Redis mit entsprechenden Konfigurationen durchaus Daten auch dauerhaft persistieren kann, wodurch diese Einschränkung umgangen werden kann). Zudem eignet sich Redis in der Regel für solche Anwendungsfälle, in denen das zu persistierende Datenmodell relativ einfach gehalten ist. Vorteil ist jedoch die sehr hohe Geschwindigkeit, weswegen Redis auch gern für die Implementierung von CachingLösungen eingesetzt wird.
316
7.5
Rezept 52: Auf eine Redis-Datenbank zugreifen
Redis installieren Um Redis lokal zu starten, verwenden Sie am besten folgende Konfigurationsdatei für Docker Compose, die Sie mit dem Befehl docker-compose up starten (alternativ können Sie Redis natürlich auch direkt installieren, Informationen dazu finden Sie unter https://redis.io/topics/quickstart): version: '3.1' services: redis: image: redis:4.0.8-alpine command: ["redis-server", "--appendonly", "yes"] hostname: redis networks: - redis-net volumes: - redis-data:/data ports: - 6379:6379 redis-commander: container_name: redis-commander hostname: redis-commander image: rediscommander/redis-commander:latest restart: always environment: - REDIS_HOSTS=local:redis:6379 ports: - 8083:8081 networks: - redis-net depends_on: - redis networks: redis-net: volumes: redis-data: Listing 7.32 Docker-Compose-Datei für Redis
Durch diesen Aufruf wird zum einen eine lokale Instanz von Redis gestartet, zum anderen eine Instanz von »Redis Commander« (https://github.com/joeferner/rediscommander, siehe Abbildung 7.6), einer auf Node.js basierenden Webanwendung für das Management von Redis-Datenbanken (alternativ können Sie »Redis Commander« auch über npm installieren: npm install -g redis-commander).
317
7
Persistenz
Abbildung 7.6 Die Weboberfläche von »Redis Commander«
Client für Redis installieren Um von Node.js aus auf Redis zuzugreifen, empfiehlt sich das »redis«-Package, das Sie wie folgt installieren: $ npm install redis
Nach Einbinden des Packages erzeugen Sie über die Methode createClient() eine neue Client-Instanz (Listing 7.33). Als Parameter können Sie dabei optional ein Konfigurationsobjekt übergeben, über das Sie bspw. den Host und den Port des RedisServers definieren. Mithilfe der Methode on() lassen sich anschließend an der ClientInstanz Event-Listener registrieren, wie z. B. in Listing 7.33 für das »connect«-Event, das dann ausgelöst wird, wenn die Verbindung erfolgreich hergestellt wurde (Tabelle 7.1 listet weitere Events auf, für die entsprechende Listener registriert werden können). const redis = require('redis'); const options = { host: '127.0.0.1', port: 6379 } const client = redis.createClient(options);
318
7.5
Rezept 52: Auf eine Redis-Datenbank zugreifen
client.on('connect', () => { console.log('Connected to Redis database'); }); Listing 7.33 Herstellen einer Verbindung zu Redis
Event
Event-Beschreibung
ready
Wird ausgelöst, wenn die Verbindung zum Redis-Server hergestellt wurde und der Server bereit ist, Anfragen entgegenzunehmen. Anfragen, die vorher an den Server gesendet wurden, werden gecacht und ausgeführt, bevor dieses Event ausgelöst wird.
connect
Wird wie ready dann ausgelöst, wenn die Verbindung zum RedisServer hergestellt wurde und der Server bereit ist, Anfragen entgegenzunehmen.
reconnecting
Wird ausgelöst, wenn die Verbindung zum Redis-Server zuvor unterbrochen war und jetzt wieder hergestellt wurde.
error
Wird im Fehlerfall ausgelöst, bspw. wenn eine Verbindung zum Redis-Server nicht hergestellt werden konnte.
end
Wird ausgelöst, wenn die Verbindung zum Redis-Server geschlossen wurde.
warning
Wird ausgelöst, um auf Warnungen reagieren zu können.
Tabelle 7.1 Events für die Arbeit mit dem Redis-Client
Arbeiten mit Strings Redis unterstützt folgende fünf verschiedene Datentypen, die als Werte bei einem Key/Value-Paar verwendet werden können: Strings, Hashes, Listen, Sets und Sorted Sets. Je nachdem, mit welchem Typ Sie arbeiten, verwenden Sie sowohl für den lesenden als auch für den schreibenden Zugriff unterschiedliche Methoden. Die Namen der Methoden leiten sich dabei von den Befehlen ab, die auch über das Command Line Interface (CLI) von Redis zur Verfügung stehen.
Redis-CLI Über das Redis-CLI (und auch über »Redis Commander«) können Sie auf Redis auch per Kommandozeile zugreifen. Eine gute Übersicht der zur Verfügung stehenden Befehle finden Sie bspw. unter https://redis.io/commands.
319
7
Persistenz
Für das Speichern von Strings (Zeichenketten) steht über das Redis-CLI bspw. der Befehl SET, für das Lesen von Strings die Befehle GET und KEYS zur Verfügung. Analog verwenden Sie unter Node.js also die Methoden set(), get() und keys(). Optional können Sie den Methoden als letzten Parameter eine Callback-Funktion übergeben, die aufgerufen wird, wenn der entsprechende Befehl ausgeführt wurde oder es dabei zu einem Fehler kam. Die in Listing 7.34 als Parameter übergebene Funktion redis.print macht dabei nichts anderes, als eine entsprechende Meldung auszugeben (siehe auch die Konsolenausgabe weiter unten in Listing 7.34). const redis = require('redis'); const client = redis.createClient(); client.on('error', error => { console.log('Error ' + error); }); // Falls vorhanden, dann löschen: // client.del('username'); client.set('username', 'maxmustermann', redis.print); client.get('username', redis.print); client.keys('username', (error, replies) => { replies.forEach((reply, i) => { console.log(`${i}: ${reply}`); }); client.quit(); }); // Ausgabe: /* Reply: OK Reply: maxmustermann 0: username */ Listing 7.34 Verwenden von String-Keys
Arbeiten mit Hashes Hashes in Redis können in etwa mit Maps verglichen werden: Innerhalb eines Hashes lassen sich Schlüssel/Wert-Paare speichern, sodass sie sich z. B. gut dazu eignen, um Objektstrukturen zu speichern. In Listing 7.35 bspw. wird ein Hash mit dem Key »maxmustermann« erzeugt, unter dem dann die Schlüssel/Wert-Paare »firstName«/ »Max«, »lastName«/»Mustermann« und »age«/45 gespeichert werden. const redis = require('redis'); const client = redis.createClient(); client.on('error', error => {
320
7.5
Rezept 52: Auf eine Redis-Datenbank zugreifen
console.log('Error ' + error); }); // Falls vorhanden, dann löschen: // client.del('maxmustermann'); client.hset('maxmustermann', 'firstName', 'Max'); client.hset('maxmustermann', 'lastName', 'Mustermann'); client.hset('maxmustermann', 'age', 45); client.hkeys('maxmustermann', (error, replies) => { replies.forEach((reply, i) => { console.log(`${i}: ${reply}`); }); client.quit(); }); // Ausgabe: /* 0: firstName 1: lastName 2: age */ Listing 7.35 Verwenden von Hash-Keys
Arbeiten mit Listen Bei Listen in Redis handelt es sich um einfache Listen von Strings, die in der Reihenfolge des Hinzufügens sortiert sind. Neue Elemente lassen sich über die Methode lpush() an den Beginn der Liste oder über die Methode rpush() an das Ende der Liste anfügen. Die Methoden lpushx() und rpushx() funktionieren analog, fügen Elemente aber nur dann hinzu, falls die Liste schon existiert: const redis = require('redis'); const client = redis.createClient(); client.on('error', error => { console.log('Error ' + error); }); // Falls vorhanden, dann löschen: // client.del('topics'); // Einfügen an den Beginn der Liste: client.lpush('topics', 'JavaScript is awesome', redis.print); // Einfügen an das Ende der Liste: client.rpush('topics', 'Node.js Best Practices', redis.print); // Einfügen an den Beginn der Liste:
321
7
Persistenz
client.lpush('topics', 'Docker set up', redis.print); client.lrange('topics', 0, -1, (error, replies) => { replies.forEach((reply, i) => { console.log(`${i}: ${reply}`); }); client.quit(); }); // Ausgabe: /* Reply: 1 Reply: 2 Reply: 3 0: Docker set up 1: JavaScript is awesome 2: Node.js Best Practices */ Listing 7.36 Verwenden von Listen
Arbeiten mit Sets Bei Sets handelt es sich um unsortierte Mengen von String, wobei jede Zeichenkette eindeutig sein muss. Über die Methode sadd() lassen sich einzelne Strings zu einem Set hinzufügen, wobei als erster Parameter der Name des jeweiligen Sets und als zweiter Parameter die entsprechende Zeichenkette zu übergeben ist. Über die Methode smembers() lassen sich die in einem Set enthaltenen Werte ermitteln. In Listing 7.37 bspw. werden zunächst die Werte »javascript«, »nodejs« und »docker« zu dem Set »tags« hinzugefügt. Der Versuch, die Zeichenkette »docker« ein zweites Mal hinzuzufügen, schlägt fehl, wie anhand der Ausgabe des Programms zu erkennen ist. const redis = require('redis'); const client = redis.createClient(); client.on('error', error => { console.log('Error ' + error); }); // Falls vorhanden, dann löschen: // client.del('tags'); client.sadd('tags', 'javascript', redis.print); client.sadd('tags', 'nodejs', redis.print); client.sadd('tags', 'docker', redis.print); client.sadd('tags', 'docker', redis.print); client.smembers('tags', (error, replies) => { replies.forEach((reply, i) => {
322
7.5
Rezept 52: Auf eine Redis-Datenbank zugreifen
console.log(${i}: ${reply}); }); client.quit(); }); // Ausgabe /* Reply: 1 Reply: 1 Reply: 1 Reply: 0 0: docker 1: javascript 2: nodejs /* Listing 7.37 Verwenden von Sets
Arbeiten mit Sorted Sets Bei Sorted Sets (sortierte Sets) handelt es sich um sortierte Mengen von Strings, wobei wie bei normalen unsortierten Mengen jede Zeichenkette eindeutig sein muss. Um Strings zu einem Sorted Set hinzuzufügen, verwenden Sie die Methode zadd(), der Sie neben dem Namen des Sets die Position der Zeichenkette und die Zeichenkette selbst als Parameter übergeben. In Listing 7.38 wird das Sorted Set »tags« angelegt und jeweils an unterschiedlichen Positionen die Werte »javascript«, »nodejs« und »docker« eingefügt, wobei letzterer aufgrund der geforderten Eindeutigkeit von Werten faktisch nur einmal hinzugefügt wird. const redis = require('redis'); const client = redis.createClient(); client.on('error', error => { console.log('Error ' + error); }); // Falls vorhanden, dann löschen: // client.del('tags'); client.zadd('tags', 3, 'javascript', redis.print); client.zadd('tags', 4, 'nodejs', redis.print); client.zadd('tags', 1, 'docker', redis.print); client.zadd('tags', 2, 'docker', redis.print); client.zrange('tags', 0, -1, (error, replies) => { replies.forEach((reply, i) => { console.log(${i}: ${reply}); });
323
7
Persistenz
client.quit(); }); // Ausgabe: /* Reply: 1 Reply: 1 Reply: 1 Reply: 0 0: docker 1: javascript 2: nodejs /* Listing 7.38 Verwenden von sortierten Sets
7.5.2 Redis als Pub/Sub Redis kann nicht nur als Datenspeicher verwendet werden, sondern implementiert auch das sogenannte Pub/Sub-Pattern: Dabei handelt es sich um ein Pattern für den Nachrichtenaustausch zwischen zwei Komponenten (Stichwort Messaging, siehe auch Kapitel 9, »Sockets und Messaging«). Im Gegensatz zum Observer-Pattern (einem der bekannten Entwurfsmuster der sogenannten Gang of Four) sind die nachrichtensendende Komponente und die nachrichtenempfangende Komponente nicht direkt aneinandergekoppelt, sondern über einen Nachrichtenkanal (Message Channel) voneinander entkoppelt. Der Nachrichtensender (auch Publisher) verschickt Nachrichten an den Nachrichtenkanal unter Verwendung sogenannter Topics bzw. Channels. Andere Komponenten können an dem Nachrichtenkanal diese Topics abonnieren und werden damit zum Subscriber bzw. Nachrichtenempfänger (Abbildung 7.7).
Publisher
Message Channel
Subscriber
Abbildung 7.7 Das Prinzip von Pub/Sub
Der Client, der durch das »redis«-Package bereitgestellt wird, lässt sich über entsprechende Methoden sowohl als Subscriber als auch als Publisher verwenden. Lis-
324
7.5
Rezept 52: Auf eine Redis-Datenbank zugreifen
ting 7.39 und Listing 7.40 zeigen hierfür entsprechende Code-Beispiele. Subscriber können sich mithilfe der Methode subscribe() für ein bestimmtes Topic registrieren, Publisher senden über die Methode publish() Nachrichten (in Form von Zeichenketten) an ein bestimmtes Topic. Über die Methode on() lassen sich zudem Event-Handler registrieren: Das Event »subscribe« wird bspw. aufgerufen, wenn die Subscription für ein Topic erfolgreich war, das Event »message« immer dann, wenn zu dem Topic eine Nachricht eingeht. const redis = require('redis'); const subscriber = redis.createClient(); subscriber.on('subscribe', (channel, count) => { console.log(`Subscriber subscribed to channel "${channel}"`); }); subscriber.on('message', (channel, message) => { const parsedMessage = JSON.parse(message); console.log(parsedMessage.content); }); subscriber.subscribe('example-channel'); Listing 7.39 Implementierung eines Subscribers mit Redis const redis = require('redis'); const publisher = redis.createClient(); const message = { content: 'Hello World' } publisher.publish('example-channel', JSON.stringify(message)); Listing 7.40 Implementierung eines Publishers mit Redis
7.5.3 Ausblick In diesem Rezept haben Sie gesehen, wie Sie unter Node.js auf Redis-Datenbanken zugreifen können. Im nächsten Rezept werde ich Ihnen mit Apache Cassandra eine weitere bekannte nicht relationale Datenbank vorstellen, die sich insbesondere durch ihre Skalierbarkeit und Hochverfügbarkeit auszeichnet. In Kapitel 9, »Sockets und Messaging«, werde ich zudem detaillierter auf das Thema Messaging eingehen, das ich in dem vorherigen Abschnitt 7.5.2 nur gestreift habe.
Verwandte Rezepte 왘 Rezept 70: Über AMQP auf RabbitMQ zugreifen 왘 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
325
7
Persistenz
7.6 Rezept 53: Auf eine Cassandra-Datenbank zugreifen Sie möchten auf eine Cassandra-Datenbank zugreifen.
7.6.1 Lösung Apache Cassandra (http://cassandra.apache.org/) ist ein in Java geschriebenes NoSQL-Datenbanksystem, das ursprünglich von Facebook entwickelt wurde, seit 2009 aber von der Apache Software Foundation (AFS) weiterentwickelt wird und seitdem unter einer Open-Source-Lizenz steht. Es zeichnet sich vor allem durch eine hohe Skalierbarkeit und Ausfallsicherheit aus und eignet sich insbesondere für den Einsatz in Big-Data-Szenarien. Die Struktur von Cassandra zeigt Abbildung 7.8. Daten werden dabei innerhalb sogenannter Keyspaces gespeichert, die wiederum sogenannte Column Families enthalten. Innerhalb einer Column Family werden die Daten in Form von Key Value Stores gespeichert. Für einen Key (auch als Column Key bezeichnet, im Beispiel bspw. »Max«) kann es mehrere Daten geben, die in Form sogenannter Columns gespeichert werden. Keyspace
Column Family age
email
gender
38
[email protected]
M
email
gender
[email protected]
F
Joe
Jane
Abbildung 7.8 Struktur von Cassandra
Für den Zugriff auf die Daten stellt Cassandra eine eigene Anfragesprache, die sogenannte Cassandra Query Language (CQL), zur Verfügung, die sich in etwa an der Syn-
326
7.6
Rezept 53: Auf eine Cassandra-Datenbank zugreifen
tax von SQL orientiert (siehe http://cassandra.apache.org/doc/latest/cql/). So lassen sich, wie Sie gleich sehen werden, bspw. aus SQL bekannte Anfragen wie CREATE, SELECT, UPDATE und DELETE ausführen, um die entsprechenden CRUD-Operationen anwenden zu können.
Hinweis Als Administrationstool für Cassandra bietet sich DevCenter von DataStax an, das nach einer Registrierung unter https://academy.datastax.com/quick-downloads kostenfrei heruntergeladen werden kann (siehe Abbildung 7.9).
Abbildung 7.9 Die Oberfläche von DevCenter
Apache Cassandra installieren Da Apache Cassandra in Java implementiert ist, lässt es sich prinzipiell auf jedem Betriebssystem installieren, auf dem eine Laufzeitumgebung für Java installiert ist. Details zur Installation finden Sie unter http://cassandra.apache.org/doc/latest/getting_started/installing.html, der Einfachheit halber habe ich Ihnen aber auch hier wieder eine Konfigurationsdatei für Docker Compose vorbereitet, die Sie einfach über docker-compose up starten können: version: '3.1' services: cassandra-seed: container_name: cassandra-seed-node image: cassandra:3.11.0 ports: - "9042:9042" # Native transport
327
7
Persistenz
- "7199:7199" - "9160:9160"
# JMX # Thrift-Clients
Listing 7.41 Docker-Compose-Datei für Cassandra
Hinweis Alternativ zu der Konfigurationsdatei aus Listing 7.41 finden Sie im GitHub-Repository von DataStax (https://github.com/datastax/docker-images) auch weitere Konfigurationsdateien, um eine etwas angepasste Version von Cassandra inklusive Weboberfläche zur Administration starten zu können.
Client für Cassandra installieren Neben dem eingangs erwähnten Administrationstool DevCenter stellt DataStax auch Client-Bibliotheken für verschiedene Programmiersprachen und Laufzeitumgebungen zur Verfügung. So auch für Node.js in Form des Packages »cassandradriver«, das sich über folgenden Befehl installieren lässt: $ npm install cassandra-driver
Anlegen von Keyspaces und Column Families Bevor Sie Daten speichern können, müssen Sie zunächst sicherstellen, dass es in der verbundenen Cassandra-Instanz einen entsprechenden Keyspace und eine entsprechende Column Family gibt. Dies erreichen Sie entweder über eine der genannten Administrationsoberflächen oder über das in Listing 7.42 gezeigte Initialisierungsskript: const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'] }); const queryKeyspace = "CREATE KEYSPACE IF NOT EXISTS userdata WITH REPLICATION = { 'class' : ¿ 'SimpleStrategy', 'replication_factor' : 1 }"; const queryTable = 'CREATE TABLE IF NOT EXISTS userdata.users(key text ¿ PRIMARY KEY, firstName text, lastName text, email text, birthdate timestamp);'; (async () => { await client.execute(queryKeyspace); await client.execute(queryTable); })(); Listing 7.42 Anlegen von Keyspaces und Column Families
328
7.6
Rezept 53: Auf eine Cassandra-Datenbank zugreifen
Das Erzeugen des Keyspaces geschieht über den Befehl CREATE KEYSPACE, wobei Sie über die zusätzliche Angabe von IF NOT EXISTS sicherstellen können, dass der Keyspace nur dann angelegt wird, wenn er noch nicht existiert (würden Sie diese Angabe weglassen und den Befehl ein zweites Mal ausführen, käme es zu einer entsprechenden Fehlermeldung). Über die dem Namen des Keyspaces gefolgte Angabe WITH REPLICATION können Sie zudem die Replikationsstrategie definieren, sprich die Strategie, nach der eine Cassandra-Datenbank innerhalb eines Clusters repliziert werden soll. Nachdem der Keyspace erfolgreich angelegt ist, können Sie über den Befehl CREATE TABLE Column Families hinzufügen. Auch hier stellt die zusätzliche Angabe von IF NOT EXISTS sicher, dass eine Column Family nur dann angelegt wird, wenn diese noch nicht existiert. Dem Namen der Column Family stellen Sie den Namen des Keyspaces voran, in Klammern folgen die Namen und Typen der einzelnen Columns, wobei über PRIMARY KEY die Column »key« als Primärschlüssel definiert wird. Beide Anfragen (zum Anlegen des Keyspaces und zum Anlegen der Column Family) werden anschließend über den Aufruf der Methode client.execute() ausgeführt, die generell für das Ausführen von CQL-Anfragen verwendet werden kann.
Erstellen von Datensätzen Neue Datensätze lassen sich über den CQL-Befehl INSERT INTO anlegen, gefolgt von dem Namen der Column Family sowie einem Mapping von Columns zu den einzusetzenden Werten (Listing 7.43). Hierbei können Sie innerhalb der Anfrage über das ?-Zeichen zusätzlich Platzhalter definieren. Übergibt man dann dem Aufruf von query() als zweiten Parameter ein Array, werden die darin enthaltenen Werte entsprechend ihrer Position eingesetzt. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'], keyspace: 'userdata' }); const query = 'INSERT INTO users (key, firstname, lastname, email, birthdate) VALUES (?, ?, ?, ?, ?)'; const params = [ 'maxmustermann', 'Max', 'Mustermann', '[email protected]', new Date(1979, 5, 25) ];
329
7
Persistenz
(async () => { const result = await client.execute(query, params); })(); Listing 7.43 Erstellen von Datensätzen
Lesen von Datensätzen Das Lesen von Datensätzen geschieht über den CQL-Befehl SELECT. In Listing 7.44 bspw. werden auf diese Weise alle Datensätze aus der Column Family »users« selektiert. Über die Eigenschaft rows des von execute() zurückgegebenen Ergebnisobjekts kann anschließend auf die gefundenen Datensätze zugegriffen werden. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'], keyspace: 'userdata' }); const query = 'SELECT * FROM users'; (async () => { const result = await client.execute(query); const first = result.rows[0]; console.log(first); // Ausgabe: // Row { // key: 'maxmustermann', // birthdate: 1979-06-24T23:00:00.000Z, // email: '[email protected]', // firstname: 'Max', // lastname: 'Mustermann' } })(); Listing 7.44 Lesen von Datensätzen
Aktualisieren von Datensätzen Um Datensätze zu aktualisieren, verwenden Sie den CQL-Befehl UPDATE (Listing 7.45). Das Prinzip ist dabei das gleiche wie für die anderen Anfragearten: Über das ?-Zeichen können Sie innerhalb des Anfrage-Strings Platzhalter definieren und entsprechende konkrete Werte in Form eines Arrays der Methode execute() übergeben. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'], keyspace: 'userdata' });
330
7.6
Rezept 53: Auf eine Cassandra-Datenbank zugreifen
const queryUpdate = "UPDATE users SET email = ? WHERE key = ?"; const querySelect = 'SELECT * FROM users WHERE key = ?'; (async () => { const key = 'maxmustermann'; const newEmail = '[email protected]'; await client.execute(queryUpdate, [newEmail, key]); const result = await client.execute(querySelect, [key]); const first = result.rows[0]; console.log(first); // Ausgabe: // Row { // key: 'maxmustermann', // birthdate: 1979-06-24T23:00:00.000Z, // email: '[email protected]', // firstname: 'Max', // lastname: 'Mustermann' } })(); Listing 7.45 Aktualisieren von Datensätzen
Löschen von Datensätzen Um Datensätze zu löschen, verwenden Sie den CQL-Befehl DELETE, wie in Listing 7.46 zu sehen. Auch hierbei ist es möglich, über das ?-Zeichen Platzhalter innerhalb der Anfrage zu definieren, die dann beim Ausführen durch die entsprechenden Werte ersetzt werden. Im Beispiel wird auf diese Weise der Datensatz gelöscht, der den Schlüssel »maxmustermann« hat. const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'], keyspace: 'userdata' }); const queryDelete = 'DELETE FROM users WHERE key = ?'; const querySelect = 'SELECT * FROM users WHERE key = ?'; (async () => { const key = 'maxmustermann'; await client.execute(queryDelete, [key]); const result = await client.execute(querySelect, [key]); console.log(result.rows.length); // Ausgabe: 0 })(); Listing 7.46 Löschen von Datensätzen
331
7
Persistenz
7.6.2 Ausblick In diesem Rezept haben Sie gesehen, wie Sie unter Node.js auf eine Apache-Cassandra-Datenbank zugreifen können. Sie kennen jetzt den prinzipiellen Aufbau einer solchen Datenbank und wissen, wie Sie die CRUD-Operationen anwenden können. Apache Cassandra ist allerdings (wie auch die anderen in diesem Kapitel beschriebenen Datenbanken) so komplex, dass man es auf wenigen Seiten selbstverständlich nicht mit allen seinen Features zusammenfassen kann und ich an dieser Stelle auf entsprechende Literatur verweisen möchte (bspw. auf das Buch »Cassandra: The Definitive Guide« von Jeff Carpenter und Eben Hewitt, das bei O’Reilly erschienen ist).
7.7 Zusammenfassung In diesem Kapitel haben Sie gesehen, wie Sie unter Node.js sowohl auf relationale als auch auf nicht relationale Datenbanken zugreifen können. Dabei haben Sie jeweils nur eine kleine Auswahl an Datenbanken betrachtet. Konkret wissen Sie jetzt, wie Sie 왘 auf eine MySQL-Datenbank zugreifen (Rezept 48), 왘 auf eine PostgreSQL-Datenbank zugreifen (Rezept 49), 왘 objektrelationale Mappings definieren (Rezept 50), 왘 auf eine MongoDB-Datenbank zugreifen (Rezept 51), 왘 auf eine Redis-Datenbank zugreifen (Rezept 52), 왘 auf eine Cassandra-Datenbank zugreifen (Rezept 53).
Neben den beschriebenen gibt es natürlich noch eine ganze Reihe weiterer Datenbanken inklusive entsprechender Client-Packages für Node.js. Beispiele für Datenbanken, die Sie problemlos unter Node.js verwenden können sind PouchDB (https:// pouchdb.com/), LevelDB (https://github.com/google/leveldb) oder SQLite (https:// www.sqlite.org).
332
Kapitel 8 Webanwendungen und Webservices In diesem Kapitel zeige ich Ihnen, wie Sie Node.js dazu verwenden, Webanwendungen und Webservices zu erstellen.
Node.js ist geradezu prädestiniert für die Entwicklung von Webanwendungen und stellt mit dem »http«-Modul bereits entsprechende Funktionalität bereit. Neben diesem Standard-Modul lernen Sie in diesem Kapitel verschiedene weitere Packages und Frameworks kennen, welche die Implementierung von Webanwendungen und Webservices bzw. REST-APIs weiter vereinfachen. In diesem Zusammenhang schauen wir uns ebenfalls an, wie Sie von Client-Seite auf REST-APIs zugreifen können und wie Sie Webanwendungen durch Authentifizierungsmechanismen absichern. Im letzten Drittel des Kapitels gehe ich dann auf das Thema GraphQL ein und zeige Ihnen, wie Sie eine GraphQL-API implementieren und anschließend über einen entsprechenden Client darauf zugreifen. 왘 Rezept 54: Einen HTTP-Server implementieren 왘 Rezept 55: Eine Webanwendung über HTTPS betreiben 왘 Rezept 56: Eine REST-API implementieren 왘 Rezept 57: Einen HTTP-Client implementieren 왘 Rezept 58: Authentifizierung implementieren 왘 Rezept 59: Authentifizierung mit »Passport.js« implementieren 왘 Rezept 60: Eine GraphQL-API implementieren 왘 Rezept 61: Anfragen an eine GraphQL-API stellen 왘 Rezept 62: Eine GraphQL-API über HTTP betreiben
8.1 Rezept 54: Einen HTTP-Server implementieren Sie möchten unter Node.js einen HTTP-Server implementieren.
8.1.1 Lösung: einen Webserver mit der Standard-Node.js-API erstellen Node.js stellt Ihnen als Teil der Standard-API für das Erstellen von Webservern das »http«-Modul zur Verfügung, sodass Sie prinzipiell keine zusätzlichen Packages be-
333
8
Webanwendungen und Webservices
nötigen. Ein einfaches Beispiel für die Verwendung dieses Moduls sehen Sie in Listing 8.1. Nachdem Sie das Modul »http« über require() importiert haben, erstellen Sie mithilfe der Funktion createServer() ein Serverobjekt. Die hierbei übergebene Callback-Funktion wird immer dann aufgerufen, wenn bei dem Webserver eine Anfrage von einem Client eingeht, und Sie haben hier die Möglichkeit zu definieren, welche Antwort zurück an den Client geschickt werden soll. Innerhalb der Callback-Funktion haben Sie Zugriff auf ein Objekt, das die Anfrage an den Webserver repräsentiert (Parameter request), und ein Objekt, das die Antwort des Servers repräsentiert (Parameter response). Um nun eine Antwort zu generieren, reicht es, wie im Beispiel gezeigt, auf das response-Objekt mithilfe der Methode writeHead() einen entsprechenden ContentType-Header zu setzen und mithilfe der Methode end() die Daten zu definieren, die in der Antwort enthalten sein sollen. Im Beispiel wird einfach unabhängig von der eingegangenen Anfrage immer die Zeichenkette »Hello World« als Antwort zurückgegeben. Prinzipiell haben Sie hier natürlich alle Freiheiten und können die Antwort auch dynamischer gestalten – bspw. abhängig von den im Request-Objekt enthaltenen Daten (URL-Pfad, Query-Parameter etc.). Um den Webserver zu starten, rufen Sie auf dem Serverobjekt die Methode listen() auf. Hierbei übergeben Sie den Port, unter dem der Webserver erreichbar sein soll, sowie optional eine Callback-Funktion, die aufgerufen wird, wenn der Webserver gestartet wurde. const http = require('http'); const PORT = 3000; function handleRequest(request, response) { response.writeHead(200, { 'Content-Type': 'text/plain' }); response.end('Hello World'); } const server = http.createServer(handleRequest); server.listen(PORT, () => { console.log(`Server started at: http://localhost:${PORT}`); }); Listing 8.1 Ein einfacher HTTP-Server mit dem »http«-Modul
Speichern Sie den obigen Code in einer Datei server-http.js, und rufen Sie ihn wie folgt auf: $ node server-http.js Server started at: http://localhost:3000
334
8.1
Rezept 54: Einen HTTP-Server implementieren
Wenn Sie nun die URL http://localhost:3000 in einem Browser aufrufen, erhalten Sie die Ausgabe »Hallo Welt«. Sie sehen also: Bereits mit wenigen Code-Zeilen ist es möglich, unter Node.js einen Webserver zu implementieren. Für einfache Szenarien ist das »http«-Modul durchaus auch in Erwägung zu ziehen. Für komplexere Einsatzgebiete empfehle ich Ihnen jedoch den Einsatz eines professionellen Frameworks wie des im Folgenden vorgestellten »Express«.
8.1.2 Lösung: einen Webserver mit »Express« implementieren Frameworks wie »Express« (https://expressjs.com) bieten Ihnen gegenüber dem »http«-Modul zusätzliche Funktionalitäten, bspw. vereinfachtes Routing (siehe Rezept 56), Erweiterung durch sogenannte Middlewares, Authentifizierung (beides Rezept 58), Templating (siehe Rezept 40) und vieles andere mehr. In Folgenden möchte ich Ihnen zeigen, wie Sie den im vorherigen Abschnitt implementierten Webserver mit »Express« umsetzen können. Das Beispiel ist dabei nach wie vor bewusst einfach gehalten – auf die Details von »Express« komme ich im Laufe dieses Kapitels noch in den anderen Rezepten zu sprechen.
Installation und Verwendung Installieren können Sie »Express« wie gewohnt über npm: $ npm install express
Den analogen Code für das Beispiel aus Listing 8.1 sehen Sie in Listing 8.2. Nach Einbinden des Packages erstellen Sie über die Funktion express() zunächst ein Objekt, das den Webserver repräsentiert und mit dessen Hilfe Sie die genauen Eigenschaften des Webservers konfigurieren können. Eine Übersicht darüber, welche Methoden dazu zur Verfügung stehen, finden Sie unter der https://expressjs.com/de/api.html# app. Über die in Listing 8.2 verwendete Methode get() bspw. ist es möglich, eine Route zu definieren, über die HTTP-Anfragen bearbeitet werden können, die als HTTPMethode GET verwenden. Als ersten Parameter übergeben Sie dabei den Pfad und als zweiten Parameter die Callback-Funktion, die immer dann aufgerufen wird, wenn eine (GET-)Anfrage vom Client an den entsprechenden Endpoint gestellt wird. Innerhalb der Callback-Funktion haben Sie (wie schon bei Verwendung des »http«Moduls) zum einen Zugriff auf ein Objekt, das die Anfrage vom Client repräsentiert (https://expressjs.com/de/api.html#req), und zum anderen auf ein Objekt, das die Antwort an den Client repräsentiert (https://expressjs.com/de/api.html#res).
335
8
Webanwendungen und Webservices
Analog zu get() stehen auch für alle anderen HTTP-Methoden entsprechende Methoden an dem app-Objekt zur Verfügung, d. h., über post() können Sie Routen für POST-Anfragen definieren, über put() Routen für PUT-Anfragen usw. (eine vollständige Auflistung der unterstützten HTTP-Methoden finden Sie unter https://expressjs.com/de/api.html#routing-methods). Um den Webserver schlussendlich zu starten, verwenden Sie die Methode listen(), der Sie den entsprechenden Port übergeben sowie eine Callback-Funktion, die aufgerufen wird, wenn der Webserver gestartet wurde oder es dabei zu einem Fehler kam. const express = require('express'); const app = express(); const PORT = 3000; app.get('/', (request, response) => { response.send('Hello World'); }); app.listen(PORT, (error) => { if (error) { console.error(error); } else { console.log(`Server started at: http://localhost:${PORT}`); } }); Listing 8.2 Ein einfacher HTTP-Server mit dem »Express«-Package
8.1.3 Ausblick Node.js bringt mit dem »http«-Modul bereits alles mit, was Sie für die Implementierung von Webservern bzw. Webanwendungen benötigen. In vielen Fällen ergibt es aber Sinn, wenn Sie von Anfang an auf ein Webframework wie das in diesem Rezept vorgestellte »Express« zurückgreifen, das klassische Anforderungen wie die Implementierung von REST-APIs oder die Integration von Authentifizierungsmethoden erheblich vereinfacht und beschleunigt (wie Sie in folgenden Rezepten noch sehen werden). Hilfreich ist in diesem Zusammenhang auch der offizielle »Express Generator« (https://www.npmjs.com/package/express-generator), mit dessen Hilfe Sie sich das Grundgerüst für eine »Express«-basierte Webanwendung automatisch generieren können.
336
8.2
Rezept 55: Eine Webanwendung über HTTPS betreiben
Verwandte Rezepte 왘 Rezept 40: HTML mit Template-Engines generieren 왘 Rezept 55: Eine Webanwendung über HTTPS betreiben 왘 Rezept 56: Eine REST-API implementieren 왘 Rezept 57: Einen HTTP-Client implementieren 왘 Rezept 58: Authentifizierung implementieren 왘 Rezept 59: Authentifizierung mit »Passport.js« implementieren
8.2 Rezept 55: Eine Webanwendung über HTTPS betreiben Sie möchten eine Webanwendung über HTTPS betreiben.
8.2.1 Lösung Wenn Sie eine Webanwendung entwickeln, in der sensible Daten wie bspw. Nutzerdaten, Bankdaten oder Passwörter übertragen werden, sollten Sie nicht HTTP als Protokoll verwenden, weil hier die gesamte Kommunikation unverschlüsselt stattfindet. Stattdessen sollten Sie Ihre Anwendung auf HTTPS (Hypertext Transfer Protocol Secure) umstellen. Die im Folgenden beschriebenen Schritte bauen auf den aus dem vorherigen Rezept bekannten Webanwendungen auf. Wie Sie gleich sehen werden, ist die Umstellung von einer Anwendung, die auf HTTP basiert, zu einer Anwendung, die auf HTTPS basiert, relativ einfach.
Exkurs: HTTPS Bei HTTPS handelt es sich um die sichere Version des HTTP-Protokolls, bei der die Daten in beide Richtungen, d. h. vom Client zum Server und vom Server zum Client, verschlüsselt übertragen werden (Abbildung 8.1). Dabei ist der Ablauf der folgende: Stellt der Client eine Anfrage an den Server, schickt dieser zunächst seinen öffentlichen Schlüssel und ein Zertifikat an den Client. Der Client (bzw. der Browser) stellt daraufhin sicher, dass das Zertifikat zum einen gültig ist und zum anderen von einer vertrauenswürdigen Zertifizierungsstelle stammt. Ist beides der Fall, erstellt der Client selbst ebenfalls einen Schlüssel (den Symmetric Key) und schickt diesen an den Server, der den Schlüssel wiederum mit seinem privaten Schlüssel entschlüsselt. Anschließend verschlüsselt der Server die an den Client zurückgesendeten Daten mit dem Symmetric Key, der sie dann wieder entschlüsseln kann.
337
8
Webanwendungen und Webservices
Client Client
1 Anfrage über HTTPS 2 Public Key und Zertifikat
Server Server
3 Browser prüft Zertifikat auf Gültigkeit 4 Browser erstellt Symmetric Key Client
5 Symmetric Key
Server
6 Server entschlüsselt Symmetric Key Client
7 Inhalt, verschlüsselt mit Symmetric Key
Server
8 Browser entschlüsselt Inhalt mit Symmetric Key
Abbildung 8.1 Das Prinzip von HTTPS
Die Zertifikate erstellen Bevor Sie die Änderungen am Node.js-Code vornehmen, müssen Sie zunächst ein Zertifikat erstellen. Dazu können Sie bspw. das Tool »openssl« verwenden. Das damit erstellte Zertifikat ist dann zwar nicht von einer offiziellen und vertrauenswürdigen Zertifizierungsstelle erstellt und der Client (bzw. der Browser) wird Sie später beim Zugriff auf den Server entsprechend darauf hinweisen, allerdings ist das für den Testaufbau und das Verständnis irrelevant.
HTTPS im Produktivsystem Für die Nutzung von HTTPS im Produktivsystem müssen Sie sich entsprechende Zertifikate von einer offiziellen Zertifizierungsstelle erstellen lassen, bspw. dem immer beliebter werdenden Let’s Encrypt (https://letsencrypt.org/).
Die Befehle für das Erstellen eines Schlüssels und eines Zertifikats lauten wie folgt: $ openssl genrsa -out localhost.key 2048 $ openssl req \ -new \ -x509 \ -key localhost.key \ -out localhost.cert \ -days 365
338
8.2
Rezept 55: Eine Webanwendung über HTTPS betreiben
Daraufhin werden zwei Dateien erstellt: localhost.key enthält den Schlüssel und localhost.cert das Zertifikat. Beide Dateien werden Sie gleich noch benötigen.
Webserver über HTTPS erstellen Für das Erstellen von HTTPS-basierten Webanwendungen stellt die Node.js-API das Modul »https« zur Verfügung. Den angepassten Code, der auf dem Beispiel aus dem vorherigen Rezept basiert, sehen Sie in Listing 8.3. Das Grundgerüst bleibt mehr oder weniger das gleiche. Statt des Moduls »http« verwenden Sie nun das Modul »https«; den zuvor erzeugten Schlüssel und die zuvor erzeugte Zertifikatsdatei lesen Sie über readFileSync() aus den entsprechenden Dateien ein und hinterlegen den Inhalt in einem Konfigurationsobjekt mit den Eigenschaften key und cert. Wie das Modul »http« stellt auch das »https«-Modul eine Methode createServer() zur Verfügung, über die sich ein entsprechendes Webserver-Objekt instanziieren lässt. Der Unterschied: Als ersten Parameter übergeben Sie jetzt das oben beschriebene Konfigurationsobjekt, das den Schlüssel und das Zertifikat enthält. const https = require('https'); const fs = require('fs'); const options = { key: fs.readFileSync('./localhost.key'), cert: fs.readFileSync('./localhost.cert') }; const PORT = 3000; function handleRequest(request, response) { response.writeHead(200, { 'Content-Type': 'text/plain' }); response.end('Hallo Welt'); } const server = https.createServer(options, handleRequest); server.listen(PORT, () => { console.log(`Server started at: https://localhost: ${PORT}`); }); Listing 8.3 Erstellen eines Webservers über HTTPS
Wenn Sie den Code aus Listing 8.3 starten, können Sie die Webanwendung anschließend unter https://localhost:3000 aufrufen (beachten Sie das »https« in der URL). Wie eingangs erwähnt, wird der Browser Sie darauf hinweisen, dass das Zertifikat nicht von einer offiziellen Zertifizierungsstelle stammt. Diese Warnung können Sie ignorieren und entsprechend bestätigen, dass Sie wissen, was Sie tun.
339
8
Webanwendungen und Webservices
Webserver mit »Express« über HTTPS erstellen In diesem Abschnitt wollen wir uns noch kurz anschauen, wie die Integration von HTTPS bei »Express« funktioniert. Dazu sehen Sie in Listing 8.4 den angepassten Code basierend auf dem im vorherigen Rezept gezeigten Beispiel. Auch hier bleibt das Grundgerüst der Applikation fast unverändert. Statt des Moduls »http« verwenden Sie nun das Modul »https«, Schlüssel und Zertifikatsdatei lesen Sie wieder über readFileSync() aus den entsprechenden Dateien ein und hinterlegend den Inhalt in den entsprechenden Eigenschaften des Konfigurationsobjekts. Den eigentlichen Webserver starten Sie allerdings nicht mehr wie in Listing 8.2 über die Methoden des app-Objekts. Stattdessen erstellen Sie, wie im vorherigen Abschnitt beschrieben, über die Methode createServer() eine Webserver-Objektinstanz, übergeben dabei aber – anders als in Listing 8.3 – keine Callback-Funktion, sondern direkt das app-Objekt. Der anschließende Aufruf listen() sorgt dafür, dass der Webserver startet und unter dem angegebenen Port 3000 zu erreichen ist. Wenn Sie die Webanwendung nun unter https://localhost:3000 aufrufen, können Sie die Warnung bezüglich des nicht verifizierten Zertifikats wieder ignorieren. const const const const const
https = require('https'); fs = require('fs'); express = require('express'); app = express(); PORT = 3000;
const options = { key: fs.readFileSync('./localhost.key'), cert: fs.readFileSync('./localhost.cert') }; app.get('/', (request, response) => { response.send('Hello World'); }); const server = https.createServer(options, app); server.listen(PORT, () => { console.log(`Server started at: https://localhost: ${PORT}`); }); Listing 8.4 Erstellen eines Webservers mit »Express« über HTTPS
340
8.3
Rezept 56: Eine REST-API implementieren
Merke Für die Integration von HTTPS verwenden Sie eine Kombination aus dem Modul »https« und dem »Express«-Framework.
Hinweis Das Modul »https« stellt mit der Methode request() auch eine Methode zur Verfügung, um Anfragen an einen HTTPS-basierten Webserver zu stellen.
8.2.2 Ausblick Wie Sie in diesem Rezept gesehen haben, ist es relativ einfach, eine Webanwendung über HTTPS auszuliefern. Die Änderungen, die Sie an dem Code vornehmen müssen, sind minimal, die Auswirkungen bezüglich der Sicherheit jedoch enorm.
8.3 Rezept 56: Eine REST-API implementieren Sie möchten eine REST-API implementieren.
8.3.1 Exkurs: REST-APIs Bevor Sie an die Implementierung einer REST-API gehen, möchte ich in diesem Abschnitt zunächst einen (sehr) kurzen Überblick über die wichtigsten Prinzipien von REST gebe. REST steht für Representational State Transfer und bezeichnet ein Programmierparadigma, das insbesondere bei der Implementierung von Webservices zum Einsatz kommt. REST hat im Wesentlichen folgende fünf Prinzipien: 1. Prinzip 1: Alles wird als Ressource betrachtet. Der Name der Ressource sollte dabei ein Nomen sein (und nicht etwa ein Verb o. Ä.). 2. Prinzip 2: Jede Ressource ist durch Identifier eindeutig identifizierbar. Als Identifier werden dabei URIs (Uniform Resource Identifiers) verwendet, bspw. https:// philipackermann.de/api/books/nodejscookbook). 3. Prinzip 3: Es werden die Standard-HTTP-Methoden verwendet. Mit GET bspw. kann eine Ressource abgerufen, mit POST erstellt und mit DELETE gelöscht werden. Wichtig: Die ID bleibt unverändert (Prinzip 2). Eine URL wie z. B. https://philipackermann.de/api/books/nodejscookbook/update folgt nicht den Prinzipien von REST.
341
8
Webanwendungen und Webservices
4. Prinzip 4: Ressourcen können verschiedene Repräsentationen haben. Beispielsweise könnte eine Ressource sowohl in XML als auch in JSON abgerufen werden können. Die ID (Prinzip 2) bleibt dabei aber gleich – die Repräsentation (bzw. das Format) wird durch den MIME-Type (Multipurpose Internet Mail Extensions) definiert. 5. Prinzip 5: Die Kommunikation ist zustandslos. Jede HTTP-Anfrage, die an den Webserver geschickt wird, wird komplett isoliert betrachtet und bearbeitet. Mit anderen Worten: Auf Server-Seite werden keine Informationen (kein Zustand) zur Client-Session gespeichert. Stefan Tilkov, Martin Eigenbrodt, Silvia Schreier und Oliver Wolf haben ein ganzes (hervorragendes) Buch zu diesem Thema geschrieben: Wenn Sie also tiefer in diese Materie eintauchen möchten, lohnt sich ein Blick in ihr Buch »REST und HTTP: Entwicklung und Integration nach dem Architekturstil des Web«.
8.3.2 Lösung: eine REST-API mit »Express« implementieren Prinzipiell können Sie unter Node.js eine REST-API auch mit dem »http«-Modul der Standard-API implementieren (siehe Rezept 54). Allerdings empfehle ich Ihnen aus den in Rezept 54 genannten Gründen, auf Frameworks zurückzugreifen, die für die Entwicklung von REST-APIs spezialisiert sind. Beispiele hierfür gibt es viele. Ich möchte mich im Folgenden jedoch auf »Express« (https://expressjs.com) konzentrieren, das Sie ebenfalls schon aus den vorangegangenen Rezepten kennen. Falls noch nicht geschehen, installieren Sie »Express« wie folgt: $ npm install express
In Rezept 54 haben Sie bereits gesehen, wie sich grundsätzlich ein HTTP-Server mit »Express« implementieren lässt. Listing 8.5 zeigt den entsprechenden grundlegenden Aufbau noch einmal. const express = require('express'); const app = express(); const PORT = 3000; app.get('/', (request, response) => { response.send('Hello World'); }); app.listen(PORT, (error) => { if (error) { console.error(error); } else {
342
8.3
Rezept 56: Eine REST-API implementieren
console.log(Server started at: http://localhost:${PORT}); } }); Listing 8.5 Genereller einfacher Aufbau einer »Express«-Anwendung
Dieses Beispiel passen Sie nun im ersten Schritt etwas an, sodass Anfragen an den Pfad »/api/v1« an einen eigenen Router weitergeleitet werden. Dies ergibt Sinn, wenn Sie den gleichen »Express«-basierten Webserver bspw. sowohl für das Implementieren einer REST-API als auch für das Bereitstellen einer »normalen« Webanwendung (bzw. des Frontends) verwenden wollen, oder auch, um einfacher verschiedene Versionen einer API hinzufügen zu können (siehe auch Abschnitt 8.3.3). const const const const
express = APIRouter app = new apiRouter
require('express'); = require('./APIRouter'); express(); = new APIRouter();
const PORT = 3000; app.use('/api/v1', apiRouter); app.listen(PORT, (error) => { if (error) { console.error(error); } else { console.log(Server started at: http://localhost:${PORT}); } }); Listing 8.6 Integration eines API-Routers in eine »Express«-Anwendung
Prinzipiell besteht die folgende Implementierung neben dem oben gezeigten Code aus drei Klassen: 1. APIRouter: Die Klasse APIRouter definiert die konkreten Routen unterhalb von »/api/v1« und mappt diese Routen auf Funktionen aus der Klasse ContactRoute (Listing 8.9). APIRouter leitet von der Express-Klasse Router ab (Listing 8.7). 2. ContactModel: Die Klasse ContactModel enthält das Objektmodell für die Kontakte sowie Helferfunktionen, um auf das Objektmodell zugreifen zu können (Listing 8.8). Diese speichert aus Demonstrationszwecken die Kontakte lediglich lokal in einer Map. Für den Produktiveinsatz ergibt das natürlich keinen Sinn. Hier sollten Sie auf Persistenz-Lösungen zurückgreifen, die ich in Kapitel 7, »Persistenz«, besprochen habe.
343
8
Webanwendungen und Webservices
3. ContactRoute: Die Klasse ContactRoute enthält Funktionen, die aus den vom APIRouter weitergeleiteten HTTP-Anfragen die Parameter etc. extrahieren und mit den entsprechenden Daten die Funktionen aus dem ContactModel aufrufen (Listing 8.9). Im Folgenden zeige ich Ihnen im Detail, wie Sie diese drei Klassen ausbauen, um Datensätze auszulesen, anzulegen, zu aktualisieren und zu löschen. Im Detail sind dies folgende Routen: HTTP-Methode
Route
Beschreibung
GET
/api/1/contacts
Liefert alle Kontakte zurück.
GET
/api/1/contacts/
Gibt einen Kontakt anhand seiner ID zurück.
POST
/api/1/contacts
Erstellt einen neuen Kontakt.
PUT
/api/1/contacts/
Aktualisiert einen bestehenden Kontakt.
DELETE
/api/1/contacts/
Löscht einen bestehenden Kontakt.
Tabelle 8.1 Die für das Beispiel zu erstellenden Routen
Datensätze auslesen Das einfachste Beispiel ist das Auslesen von Datensätzen. Im APIRouter (Listing 8.7) definieren Sie die Mappings über die Methode get(), wobei Sie als ersten Parameter den Pfad angeben und als zweiten Parameter die aufzurufende (statische) Methode von ContactRoute. Die Route »/contacts« wird also auf die Methode ContactRoute. getContacts() gemappt und die Route »/contacts/:id« auf die Methode ContactRoute.findContact(). Bei der letzten Route sehen Sie auch, dass Sie mithilfe des Doppelpunkts Platzhalter definieren können. Diese Platzhalter werden durch »Express« bei einer eingehenden Anfrage entsprechend aus der URL extrahiert und sind dann im request-Objekt der jeweiligen Callback-Funktion enthalten (dazu gleich mehr). const { Router } = require('express'); const ContactRoute = require('./routes/ContactRoute'); module.exports = class APIRouter extends Router { constructor(opts = APIRouter.defaultOptions()) { super(opts); this.get( '/', (request, response) => response.json({
344
8.3
Rezept 56: Eine REST-API implementieren
name: 'Contact API', version: '1' }) ); this.get( '/contacts', ContactRoute.getContacts ); this.get( '/contacts/:id', ContactRoute.findContact ); /* ... */ } static defaultOptions() { return { caseSensitive: true, strict: true }; } }; Listing 8.7 Aufbau der Klasse »APIRouter«
Die Klasse ContactModel (Listing 8.8) bietet für das Auslesen von Kontakten zwei Methoden an: getContacts() liefert ein Array mit allen Kontakten zurück, findContact() sucht zu einer gegebenen ID den entsprechenden Eintrag und gibt diesen zurück. const contacts = new Map(); contacts.set('1', { firstName: 'Max', lastName: 'Mustermann' }); contacts.set('2', { firstName: 'Moritz', lastName: 'Mustermann' }); module.exports = class ContactModel { static getContacts() { const contactsArray = []; for (let [id, contact] of contacts) { contactsArray.push({
345
8
Webanwendungen und Webservices
...contact, id }); } return contactsArray; } static findContact(id) { const contact = contacts.get(id); return contact; } static addContact(id, newContact) { /* ... */ } static updateContact(id, updatedContact) { /* ... */ } static deleteContact(id) { /* ... */ } }; Listing 8.8 Aufbau der Klasse »ContactModel«
Die Aufgabe der Klasse ContactRoute (Listing 8.9) ist es, HTTP-Anfragen vom APIRouter entgegenzunehmen und eine entsprechende HTTP-Antwort zu generieren. Für das Auslesen aller Kontakte wird einfach der Rückgabewert von ContactModel.getContacts() über die Methode send() weitergegeben. Für das Auslesen eines einzelnen Kontakts anhand der ID muss die ID zunächst aus dem URI-Pfad extrahiert werden. Praktischerweise enthält das Objekt request eine Eigenschaft params, die sämtlich Pfadparameter als Eigenschaften bereitstellt. Mit dieser ID rufen Sie ContactModel.findContact() auf und geben – sofern gefunden – das entsprechende Objekt zurück. Falls zu der ID kein Kontakt gefunden wurde, definieren Sie über die Methode status() den Status-Code 404 (»Not Found«) und haben zusätzlich über send() die Möglichkeit, eine detaillierte Fehlermeldung an den Client zurückzuschicken. const ContactModel = require('../model/ContactModel'); module.exports = class ContactRoute {
346
8.3
Rezept 56: Eine REST-API implementieren
static getContacts(request, response) { const contactsArray = ContactModel.getContacts(); response.send(contactsArray); } static findContact(request, response) { const { id } = request.params; const contact = ContactModel.findContact(id); if (contact) { response.send(contact); } else { response.status(404).send('Contact not found.'); } } static addContact(request, response) { /* ... */ } static updateContact(request, response) { /* ... */ } static deleteContact(request, response) { /* ... */ } }; Listing 8.9 Aufbau der Klasse »ContactRoute«
Wenn Sie den Server starten und anschließend im Browser die URL http://localhost:3000/api/v1/contacts öffnen, sollten Sie folgendes JSON als Ausgabe erhalten: [{"firstName":"Max","lastName":"Mustermann","id":"1"},{"firstName":"Moritz", "lastName":"Mustermann","id":"2"}]
HTTP-Clients Beim Entwickeln von REST-Schnittstellen ist ein guter HTTP-Client für das Testen unerlässlich. Empfehlenswert ist diesbezüglich das Tool Postman (https://www.getpostman.com/). Einzelne HTTP-Anfragen lassen sich über eine grafische Oberfläche relativ einfach konfigurieren, ausführen und übersichtlich speichern. Wer auf eine grafische Oberfläche verzichten kann und sich in der Kommandozeile heimischer fühlt, dem sei HTTPie (https://httpie.org/) empfohlen, das für macOS,
347
8
Webanwendungen und Webservices
Linux und Windows installiert werden kann (siehe https://httpie.org/doc#installation). Nach der Installation steht der Befehl http zur Verfügung, mit dessen Hilfe sich HTTP-Anfragen formulieren lassen. Eine ausführliche Dokumentation aller Unterbefehle und Flags finden Sie unter https://httpie.org/doc.
Datensätze anlegen Laut REST-Prinzipien können neue Datensätze über das Stellen einer POST-Anfrage angelegt werden. Um das entsprechende Mapping zu definieren, stellt Ihnen die Router-Klasse die Methode post() zur Verfügung. Als ersten Parameter definieren Sie, wie in Listing 8.10 zu sehen, wieder die entsprechende Route (»/contacts«) und als zweiten Parameter die aufrufende Methode aus der ContactRoute. const { Router } = require('express'); const ContactRoute = require('./routes/ContactRoute'); module.exports = class APIRouter extends Router { constructor(opts = APIRouter.defaultOptions()) { super(opts); /* ... */ this.post( '/contacts', ContactRoute.addContact ); /* ... */ } /* ... */ }; Listing 8.10 Mapping einer POST-Route
Um Daten, die per POST an den Server geschickt werden, als JSON zu parsen, müssen Sie zudem die Express-Middleware »body-parser« einbinden und, wie in Listing 8.11 gezeigt, aktivieren: const const const const const
express = require('express'); APIRouter = require('./APIRouter'); bodyParser = require('body-parser'); app = new express(); apiRouter = new APIRouter();
const PORT = 3000;
348
8.3
Rezept 56: Eine REST-API implementieren
app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); app.use('/api/v1', apiRouter); app.listen(PORT, (error) => { if (error) { console.error(error); } else { console.log(`Server started at: http://localhost:${PORT}`); } }); Listing 8.11 Einbinden der »body-parser«-Middleware
Danach wird der Body von HTTP-Anfragen (der Payload) durch die Middleware als JSON geparst, und Sie können anschließend über die Eigenschaft body des requestObjekts darauf zugreifen, bspw., wie in Listing 8.12 zu sehen, um die Daten für den neu anzulegenden Kontakt zu extrahieren. const ContactModel = require('../model/ContactModel'); module.exports = class ContactRoute { /* ... */ static addContact(request, response) { const { id } = request.body; const newContact = { ...request.body }; delete newContact.id; try { ContactModel.addContact(id, newContact); response.send(newContact); } catch (error) { response.status(409).send(error); } } /* ... */ }; Listing 8.12 Anlegen eines neuen Kontakts
Listing 8.13 zeigt die Implementierung der Methode addContact() der Klasse ContactModel. Hier passiert nichts Ungewöhnliches: Zunächst wird geprüft, ob es für die
349
8
Webanwendungen und Webservices
übergebene ID schon einen Kontakt gibt, und gegebenenfalls ein entsprechender Fehler erzeugt. Gibt es keinen Kontakt für die ID, wird der Kontakt in der Map gespeichert. const contacts = new Map(); contacts.set('1', { firstName: 'Max', lastName: 'Mustermann' }); contacts.set('2', { firstName: 'Moritz', lastName: 'Mustermann' }); module.exports = class ContactModel { /* ... */ static addContact(id, newContact) { const contains = contacts.get(id); if (!contains) { contacts.set(id, newContact); return newContact; } else { throw new Error('Contact already exists.'); } } /* ... */ }; Listing 8.13 Anlegen eines neuen Kontakts in »ContactModel«
Datensätze aktualisieren Für das Aktualisieren von Datensätzen sieht REST die HTTP-Methode PUT vor. Analog dazu stellt die Router-Klasse die Methode put() zur Verfügung, um ein entsprechendes Mapping zu definieren. Listing 8.14 zeigt den hierfür relevanten Code aus der APIRouter-Klasse. const { Router } = require('express'); const ContactRoute = require('./routes/ContactRoute'); module.exports = class APIRouter extends Router { constructor(opts = APIRouter.defaultOptions()) { super(opts);
350
8.3
Rezept 56: Eine REST-API implementieren
/* ... */ this.put( '/contacts/:id', ContactRoute.updateContact ); /* ... */ } /* ... */ }; Listing 8.14 Mapping einer PUT-Route
Die Klasse ContactRoute wird um die Methode updateContact() erweitert (Listing 8.15), bei der die ID des Kontakts wieder aus den Pfadparametern ausgelesen wird und die eigentlichen Kontaktdaten aus dem Request-Body extrahiert werden. const ContactModel = require('../model/ContactModel'); module.exports = class ContactRoute { /* ... */ static updateContact(request, response) { const { id } = request.params; const updatedContact = { ...request.body }; delete updatedContact.id; try { ContactModel.updateContact(id, updatedContact); response.send(updatedContact); } catch (error) { response.status(404).send(error); } } /* ... */ }; Listing 8.15 Kontakte aktualisieren in der »ContactRoute«
Die Klasse ContactModel wird, wie in Listing 8.16 gezeigt, ebenfalls um eine Methode updateContact() erweitert. /* ... */ module.exports = class ContactModel {
351
8
Webanwendungen und Webservices
/* ... */ static updateContact(id, updatedContact) { const contains = contacts.get(id); if (contains) { contacts.set(id, updatedContact); return updatedContact; } else { throw new Error('Contact does not exist.'); } } /* ... */ }; Listing 8.16 Kontakte aktualisieren im »ContactModel«
Datensätze löschen Um Datensätze zu löschen, verwenden Sie als Mapping-Funktion die Methode delete() wie folgt: const { Router } = require('express'); const ContactRoute = require('./routes/ContactRoute'); module.exports = class APIRouter extends Router { constructor(opts = APIRouter.defaultOptions()) { super(opts); /* ... */ this.delete( '/contacts/:id', ContactRoute.deleteContact ); } /* ... */ }; Listing 8.17 Mapping einer DELETE-Route
In der Klasse ContactRoute kommt die Methode deleteContact() hinzu, in welcher der ID-Parameter aus dem Request extrahiert und der Aufruf an die entsprechende Methode im ContactModel delegiert wird:
352
8.3
Rezept 56: Eine REST-API implementieren
const ContactModel = require('../model/ContactModel'); module.exports = class ContactRoute { /* ... */ static deleteContact(request, response) { const { id } = request.params; const deleted = ContactModel.deleteContact(id); if (deleted) { response.send(contact); } else { response.status(404).send('Contact not found.'); } } }; Listing 8.18 Kontakte löschen in der »ContactRoute«
Der Code für das ContactModel wird ebenfalls um eine Methode deleteContact() ergänzt, die den Kontakt anhand der ID aus der Map löscht: /* ... */ module.exports = class ContactModel { /* ... */ static deleteContact(id) { const deleted = contacts.delete(id); if (deleted) { return contact; } else { throw new Error('Contact not deleted.'); } } }; Listing 8.19 Kontakte löschen im »ContactModel«
8.3.3 Versionierung Ein Punkt, den Sie bei der Planung einer REST-API berücksichtigen sollten, ist die Versionierung der API. Insbesondere wenn eine API von externen Diensten genutzt wird, die auf die definierten Endpoints, Formate etc. angewiesen sind, sollten Sie
353
8
Webanwendungen und Webservices
sicherstellen, dass die API abwärtskompatibel bleibt. Am einfachsten ist dies, wenn Sie innerhalb der URIs eine Versionsnummer vorsehen, entweder als Teil des Pfades (https://philipackermann.de/api/v1/books/nodejscookbook) oder als Query-StringParameter (https://philipackermann.de/api/books/nodejscookbook?version=1). Alternativ dazu können Sie die Versionsnummer auch als zusätzlichen HTTP-Header vorsehen. Letzteres empfehle ich Ihnen allerdings nur dann, wenn Sie es erstens mit einer bestehenden API zu tun haben, die noch keine Versionsnummer in den URIs enthält, und Sie zweitens diese URIs um keinen Preis ändern bzw. durch neue URIs ergänzen wollen. Der Detailgrad der Versionsnummer (Major, Minor, Patch) richtet sich danach, wie feingliedrig Sie Änderungen an der API vornehmen wollen. In der Regel sollte die Versionsnummer bei einer REST-API nur die Major-Version enthalten, in Ausnahmefällen zusätzlich die Minor-Version. Die Patch-Version mit aufzunehmen ergibt in keinem Fall Sinn (wenn sich eine API so häufig ändert und sie so häufig publiziert werden sollte, sollten Sie stattdessen den Release-Zyklus bzw. die Versionierung überdenken).
8.3.4 Ausblick Sie wissen nun, wie Sie mithilfe des Frameworks »Express« eine einfache REST-API erstellen können. Im nächsten Rezept zeige ich Ihnen, wie Sie unter Node.js HTTPAnfragen stellen können, z. B. um Anfragen an die in diesem Rezept implementierte REST-API zu stellen. In Kapitel 10, »Testing und TypeScript«, lernen Sie zudem, wie Sie REST-APIs mithilfe von Unit-Tests automatisiert testen können (Rezept 77). Eine interessante Alternative zu REST, das sogenannte GraphQL, schauen wir uns in den Rezepten 60 bis 62 an. Webframeworks für die Entwicklung von REST-APIs gibt es im Node.js-Universum ziemlich viele: Neben dem vorgestellten »Express« sind bspw. »Restify« (http:// restify.com/), »Koa« (https://koajs.com/), »Hapi.js« (https://hapijs.com/), »Sails.js« (https://sailsjs.com/), »Loopback« (https://loopback.io/) und »Nest.js« (https://nestjs.com/) recht bekannt. Wenn Sie besonders auf die Performance Ihrer API Wert legen, lohnt zudem ein Blick auf »Fastify« (https://github.com/fastify/fastify), das in verschiedenen Benchmarkingtests im Vergleich zu den anderen Frameworks am besten abschneidet. Schneller ist nur der reine Einsatz des »http«-Moduls ohne jeglichen »Framework-Ballast«.
Verwandte Rezepte 왘 Rezept 54: Einen HTTP-Server implementieren 왘 Rezept 55: Eine Webanwendung über HTTPS betreiben
354
8.4
Rezept 57: Einen HTTP-Client implementieren
왘 Rezept 57: Einen HTTP-Client implementieren 왘 Rezept 60: Eine GraphQL-API implementieren 왘 Rezept 77: Unit-Tests für REST-APIs implementieren 왘 Rezept 103: Microservice-Architekturen aufsetzen mit Docker Compose
8.4 Rezept 57: Einen HTTP-Client implementieren Sie möchten einen HTTP-Client implementieren, bspw., um auf eine REST-API zuzugreifen.
8.4.1 Lösung: einen HTTP-Client mit der Standard-Node.js-API implementieren In Rezept 54 haben Sie gesehen, wie Sie mithilfe des Moduls »http« einen HTTP-Server implementieren können. Neben dieser Funktionalität bietet das Modul »http« auch die Möglichkeit, einen HTTP-Client zu implementieren. Dazu verwenden Sie, wie in Listing 8.20 gezeigt, die Funktion request() (als Grundlage dient die REST-API aus Rezept 56). Über ein Konfigurationsobjekt definieren Sie den anzufragenden Webserver bzw. dessen Host, Port und die Pfadangabe. Als zweiten Parameter übergeben Sie der Funktion eine Callback-Funktion, über die sich die Antwort vom Server verarbeiten lässt. Das entsprechende Objekt response leitet von der Klasse EventEmitter ab, d. h., Sie können über die Methode on() Event-Listener registrieren (siehe auch Rezept 34). Um die komplette Antwort zu erhalten, müssen Sie einen Event-Listener für das »data«-Event registrieren, innerhalb dessen Sie jeweils einen Teil der Daten erhalten. Wenn alle Teile übertragen wurden, wird das Event »end« ausgelöst. Mit anderen Worten: Sie müssen sich zunächst in dem Event-Listener für das »data«-Event die einzelnen Teile in einer Variable (hier: body) merken und können erst anschließend in dem Event-Listener für das »end«-Event auf die gesamten Daten zugreifen, bspw. um – wie in Listing 8.20 gezeigt – die Daten als JSON zu verarbeiten. const http = require('http'); const options = { host: 'localhost', port: '3000', path: '/api/v1/contacts' };
355
8
Webanwendungen und Webservices
const request = http.request(options, (response) => { let body = ''; response.on('data', (data) => { body += data; }); response.on('end', () => { const contacts = JSON.parse(body); contacts.forEach((contact) => { console.log(contact); }); }); }); request.end(); Listing 8.20 Ein einfacher Client mit dem »http«-Modul
Das »http«-Modul bietet bereits alle Möglichkeiten, HTTP-Anfragen zu stellen. Trotzdem empfehle ich Ihnen, für den Praxiseinsatz auf alternative Packages zurückzugreifen, die das ganze Prozedere des Erstellens von Anfragen und das Verarbeiten von Antworten um einiges vereinfachen.
8.4.2 Lösung: einen HTTP-Client mit »superagent« implementieren In meinem persönlichen Werkzeugkasten greife ich mittlerweile (vor allem seitdem die Weiterentwicklung des populären »request«-Packages eingestellt wurde, siehe auch Kasten weiter unten in diesem Rezept) in den meisten Fällen auf das Package »superagent« (https://github.com/visionmedia/superagent) zurück. Installieren können Sie das Package über folgenden Befehl: $ npm install superagent
Einer der wesentlichen Vorteile von »superagent« ist es, dass Sie sich nicht selbst um das Zusammenbauen der HTTP-Antwort kümmern müssen. Das nimmt das Package praktischerweise intern selbst in die Hand. Folglich sieht der entsprechende Code, der das Gleiche macht wie der Code aus Listing 8.20 wesentlich schlanker und lesbarer aus: const superagent = require('superagent'); superagent .get('http://localhost:3000/api/v1/contacts')
356
8.4
Rezept 57: Einen HTTP-Client implementieren
.end((error, response) => { if (error) { console.error(error); } else { const contacts = response.body; contacts.forEach((contact) => { console.log(contact); }); } }); Listing 8.21 Ein einfacher Client mit dem »superagent«-Package
Sowohl das Stellen der Anfragen als auch das Verarbeiten der Antwort ist um einiges einfacher als bei Verwendung des »http«-Moduls. Neben der im Listing verwendeten Methode get() für das Erstellen einer GET-Anfrage stellt »superagent« für die HTTP-Methoden DELETE, HEAD, PATCH, POST und PUT ebenfalls entsprechend benannte Methoden zur Verfügung. Um bspw. einen neuen Kontakt zu der Kontaktliste hinzuzufügen, rufen Sie einfach die Methode post() wie folgt auf: const superagent = require('superagent'); const body = { id: '4', firstName: 'Petra', lastName: 'Mustermann' }; superagent .post('http://localhost:3000/api/v1/contacts') .send(body) .then((response) => { console.log(response.body); }); Listing 8.22 Versenden einer POST-Anfrage
Neben den gezeigten Methoden stellt die API von »superagent« viele weitere Methoden zur Verfügung, die bei dem Erstellen von HTTP-Anfragen hilfreich sind. So ist es bspw. möglich, über die Methode set() HTTP-Header zu definieren, über den Shortcut type() direkt den Content-Type-Header zu setzen, über accept() den AcceptHeader, über query() Query-String-Parameter zu definieren, über key() und cert()
357
8
Webanwendungen und Webservices
Schlüssel und Zertifikat für Anfragen über HTTPS und über auth() Authentifizierungsinformationen, die dann entsprechend als Header-Information mit der Anfrage übertragen werden. Einen guten Überblick über die zur Verfügung stehenden Methoden finden Sie in der offiziellen Dokumentation unter http://visionmedia.github.io/superagent.
Hinweis Ursprünglich wollte ich Ihnen in diesem Rezept ein anderes Package vorstellen (und hatte das Rezept tatsächlich schon fertiggestellt). Das Package »request« war jahrelang meine erste Wahl, wenn es um die Implementierung eines HTTP-Clients ging. Seit März 2019 befindet sich das Package allerdings im »Maintenance mode«, d. h., Bugs werden weiterhin entfernt, aber es werden keine neuen Features mehr eingebaut. Die genauen Beweggründe für diese Entscheidung hat der Entwickler Mikeal Rogers in einer GitHub-Issue unter https://github.com/request/request/issues/3142 dargelegt.
8.4.3 Ausblick Neben dem vorgestellten Package »superagent« gibt es viele verschiedene alternative HTTP-Clients für Node.js. Einen guten Einstiegspunkt bietet bspw. die Liste unter https://github.com/zeke/npm-collection-http-clients. Erwähnenswert sind hier besonders das Package »axios« (https://www.npmjs.com/package/axios), ein Promise-basierter HTTP-Client sowie »whatwg-fetch« (https://www.npmjs.com/package/whatwg-fetch), ein Polyfill für Node.js, der die Fetch API der Web Hypertext Application Technology Working Group implementiert (siehe auch den entsprechenden Artikel in meinem Blog »Tales from the Web Side« bei Heise Developer unter https://www. heise.de/developer/artikel/AJAX-aber-einfacher-Die-neue-Fetch-API-2642427.html). In Rezept 77 werde ich Ihnen das Package »supertest« vorstellen, das – der Name lässt es bereits vermuten – auf dem Package »superagent« aufbaut und – dies wiederum lässt der Name des Rezepts vermuten – für das Testen von REST-APIs verwendet werden kann.
Verwandte Rezepte 왘 Rezept 54: Einen HTTP-Server implementieren 왘 Rezept 55: Eine Webanwendung über HTTPS betreiben 왘 Rezept 56: Eine REST-API implementieren 왘 Rezept 77: Unit-Tests für REST-APIs implementieren
358
8.5
Rezept 58: Authentifizierung implementieren
8.5 Rezept 58: Authentifizierung implementieren Sie möchten eine Webanwendung oder eine REST-API durch einen Authentifizierungsmechanismus vor öffentlichem Zugang schützen.
8.5.1 Lösung Wenn Sie verhindern möchten, dass eine Webanwendung oder REST-API öffentlich zugänglich ist, sollten Sie diese durch einen entsprechenden Authentifizierungsmechanismus absichern. In diesem Rezept möchte ich Ihnen zunächst zeigen, wie Sie die in Rezept 56 entwickelte REST-API mithilfe sogenannter Basic Authentication absichern. In dem hieran anschließenden Rezept stelle ich Ihnen dann ein Package vor, das Ihnen über entsprechende Plugins mehrere Hundert alternative Authentifizierungsmechanismen bereitstellt.
Exkurs: Basic Authentication Basic Authentication ist einer der populärsten Authentifizierungsmechanismen. Der Ablauf besteht dabei aus den in Abbildung 8.2 gezeigten vier Schritten.
Client
Server
1 GET / api / 1 / contacts 401 Unauthorized WWW-Authenticate: Basic
2
3 GET / api / 1 / contacts Authorization: Basic YWRtaW46cGFzc3dvcmQ= 200 OK
4
Abbildung 8.2 Prinzip der Basic Authentication
Im ersten Schritt 1 sendet der Client eine gewöhnliche HTTP-Anfrage an den Webserver. Der Webserver prüft dann, ob die angefragte Ressource (bspw. ein API-Endpoint, eine Webseite etc.) öffentlich zugänglich ist oder aber erst nach durchgeführter Authentifizierung. Ist Letzteres der Fall, schickt der Webserver im zweiten Schritt 2 eine entsprechende HTTP-Antwort an den Client, die als Status-Code den Wert 401 (»Unauthorized«) und zudem den Header »WWW-Authenticate« enthält.
359
8
Webanwendungen und Webservices
Auf Client-Seite sorgt dies dafür, dass die entsprechenden Credentials (also Nutzername und Passwort) abgefragt werden. Handelt es sich bei dem Client um einen Browser, wird dem Nutzer dazu ein entsprechender Dialog angezeigt. Anschließend sendet der Client im dritten Schritt 3 eine erneute Anfrage an den Webserver, welche die Credentials in Form des »Authorization«-Header enthält. Im vierten und letzten Schritt 4 gewährt der Webserver dem Client (nach erfolgreicher Authentifizierung versteht sich!) den Zugang zu der angefragten Ressource und schickt diese an den Client.
Per HTTP auf die API zugreifen Bevor wir uns im nächsten Schritt konkret der Implementierung der Basic Authentication zuwenden, lassen Sie uns zunächst unter Verwendung von HTTPie (siehe Rezept 56) die REST-API für den Endpoint http://localhost:3000/api/1/contacts aufrufen. Alternativ dazu können Sie natürlich auch Postman (ebenfalls Rezept 56) oder einen anderen HTTP-Client verwenden, wichtig ist nur, dass Sie – das ist gleich noch relevant – die HTTP-Anfrage einfach konfigurieren können. Listing 8.23 zeigt die Kommunikation zwischen Client und Server beim Zugriff auf den Endpoint http://localhost:3000/api/1/contacts (der Parameter --verbose bewirkt, dass HTTPie nicht nur Details zu der HTTP-Antwort auf die Konsole ausgibt, sondern auch Details zu der HTTP-Anfrage). $ http GET http://localhost:3000/api/v1/contacts --verbose GET /api/v1/contacts HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Connection: keep-alive Host: localhost:3000 User-Agent: HTTPie/0.9.3 HTTP/1.1 200 OK Connection: keep-alive Content-Length: 110 Content-Type: application/json; charset=utf-8 Date: Mon, 18 Feb 2019 12:17:46 GMTETag: W/"6e-Knhc8UM07I/O2WVoeeVgitY5gG8" X-Powered-By: Express [ { "firstName": "Max", "id": "1", "lastName": "Mustermann" },
360
8.5
Rezept 58: Authentifizierung implementieren
{ "firstName": "Moritz", "id": "2", "lastName": "Mustermann" } ] Listing 8.23 HTTP-Anfrage und HTTP-Antwort
Wie Sie anhand der Ausgabe sehen können, antwortet der Webserver direkt mit dem Status-Code 200, was bedeutet, dass der angefragte Endpoint direkt ohne Authentifizierung zugänglich ist. Das wollen wir im Folgenden ändern.
Basic Authentication über Middleware einrichten Über Middlewares bietet »Express« ein Plugin-artiges System, um HTTP-Anfragen und HTTP-Antworten abfangen und verarbeiten zu können. In Rezept 56 hatten Sie bspw. die Middleware »body-parser« verwendet, um den Inhalt einer POST-Anfrage automatisch in JSON umzuwandeln. Middlewares lassen sich beliebig zu einer »Middleware-Kette« hintereinanderschalten, sodass Sie einzelne Features (wie bspw. Authentifizierung) sehr modular entwickeln und für verschiedene Projekte wiederverwenden können. Um den Endpoint durch Basic Authentication zu schützen, implementieren Sie im Folgenden eine eigene Middleware, anhand derer sich der prinzipielle Ablauf der Basic Authentication gut nachvollziehen lässt. Dabei dient das Package »basic-auth« als Grundlage, das – ausgehend von dem in Rezept 56 verwendeten Projekt – wie folgt zu installieren ist: $ npm install basic-auth
Listing 8.24 zeigt den Code für die Middleware-Funktionen, die bezüglich der Parameter immer den gleichen Aufbau haben: Der erste Parameter enthält die HTTP-Anfrage, der zweite die HTTP-Antwort und der dritte einen Verweis auf die nächste Middleware in der Middleware-Kette. Die Authentifizierungs-Middleware an sich ist sehr einfach aufgebaut: Über die von »basic-auth« zur Verfügung gestellte Methode auth() extrahieren Sie zunächst die Credentials aus der HTTP-Anfrage. Wenn keine Credentials übergeben wurden oder die Credentials falsch sind, antwortet die Middleware mit einem entsprechenden Fehler (und ruft auch die nächste Middleware nicht mehr auf). Der Einfachheit halber prüfen Sie dabei in der Funktion authenticate() lediglich, ob der Nutzername »admin« und das Passwort »password« lautet. In Produktivsys-
361
8
Webanwendungen und Webservices
temen sollten Sie die Nutzerdaten natürlich nicht auf diese Weise »hart kodieren«, sondern beides entsprechend (verschlüsselt) in einer Datenbank vorhalten (für weitere Details dazu sei an dieser Stelle auf das Kapitel 7, »Persistenz«, verwiesen). Wurde die Authentifizierung dagegen erfolgreich durchgeführt, macht die Middleware ansonsten nichts, außer die nächste Middleware über next() aufzurufen. const auth = require('basic-auth'); // Dummy Authentifizierung const authenticate = (username, password) => username === 'admin' && password === 'password'; const authenticationMiddleware = async (request, response, next) => { const credentials = auth(request); if (credentials === undefined) { response.statusCode = 401; response.setHeader('WWW-Authenticate', 'Basic'); response.end('No credentials'); } else { const authenticated = await authenticate( credentials.name, credentials.pass ); if (!authenticated) { response.statusCode = 401; response.end('Wrong credentials'); } else { next(); } } }; module.exports = authenticationMiddleware; Listing 8.24 Eine eigene Middleware für Basic Authentication
Diese Middleware können Sie jetzt in der »Express«-Applikation, wie in Listing 8.25 gezeigt, über die Methode use() am app-Objekt integrieren. Damit werden alle Anfragen an die Applikation an die Middleware weitergeleitet und wie beschrieben hinsichtlich der Credentials überprüft. const express = require('express'); const APIRouter = require('./APIRouter'); const bodyParser = require('body-parser');
362
8.5
Rezept 58: Authentifizierung implementieren
const authenticationMiddleware = require('./authenticate'); const app = new express(); const apiRouter = new APIRouter(); const PORT = 3000; app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); app.use(authenticationMiddleware); app.use('/api/v1', apiRouter); app.listen(PORT, (error) => { if (error) { console.error(error); } else { console.log(`Server started at: http://localhost:${PORT}`); } }); module.exports = app; Listing 8.25 Basic Authentication in »Express«
Per HTTP auf die geschützte API zugreifen Um die Authentifizierung zu testen, rufen Sie nun erneut den HTTPie-Befehl von eben auf. Wie Sie der folgenden Ausgabe entnehmen können, antwortet der Server jetzt wie erwartet mit einem 401-Status-Code und der Nachricht »No Credentials«. $ http GET http://localhost:3000/api/v1/contacts --verbose GET /api/v1/contacts HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Connection: keep-alive Host: localhost:3000 User-Agent: HTTPie/0.9.3 HTTP/1.1 401 Unauthorized Connection: keep-alive Content-Length: 14 Date: Mon, 18 Feb 2019 12:21:58 GMT WWW-Authenticate: Basic
363
8
Webanwendungen und Webservices
X-Powered-By: Express No credentials Listing 8.26 HTTP-Kommunikation bei fehlgeschlagener Authentifizierung
Diese Anfrage des Clients und die Antwort des Webservers stellen also die in der Einführung beschriebenen ersten beiden Schritte des Workflows dar. Um nun die Schritte drei und vier durchzuführen und erfolgreich auf die API zugreifen zu können, müssen Sie bei der nächsten HTTP-Anfrage vom Client einfach die entsprechenden Credentials im »Authorization«-Header mitgeben. Die Credentials sind dabei nicht im Klartext zu übergeben, sondern entsprechend kodiert. Da Sie die Anfrage manuell – also ohne Browser – durchführen, müssen Sie die Kodierung selbst vornehmen (also genau das, was der Browser nach Eingabe von Nutzername und Passwort intern auch macht). Ein Online-Tool, über das sich direkt ein entsprechender Header generieren lässt, finden Sie bspw. unter https://www.blitter.se/utils/basic-authentication-header-generator/. Für den Nutzernamen »admin« und das Passwort »password« ergibt sich dabei folgender Header: »Authorization: Basic YWRtaW46cGFzc3dvcmQ=«. Übergeben Sie diesen nun der HTTP-Anfrage, ist die Authentifizierung auf Server-Seite erfolgreich, und der Server antwortet mit dem eigentlichen Inhalt der angefragten Seite: $ http GET \ http://localhost:3000/api/v1/contacts \ 'Authorization:Basic YWRtaW46cGFzc3dvcmQ=' \ --verbose GET /api/v1/contacts HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Authorization: Basic YWRtaW46cGFzc3dvcmQ= Connection: keep-alive Host: localhost:3000 User-Agent: HTTPie/0.9.3 HTTP/1.1 200 OK Connection: keep-alive Content-Length: 110Content-Type: application/json; charset=utf-8 Date: Mon, 18 Feb 2019 12:35:26 GMT ETag: W/"6e-Knhc8UM07I/O2WVoeeVgitY5gG8" X-Powered-By: Express [
364
8.5
Rezept 58: Authentifizierung implementieren
{ "firstName": "Max", "id": "1", "lastName": "Mustermann" }, { "firstName": "Moritz", "id": "2", "lastName": "Mustermann" } ] Listing 8.27 HTTP-Kommunikation bei erfolgreicher Authentifizierung
Hinweis Der auf dem Package »superagent« basierende HTTP-Client aus Rezept 57 lässt sich übrigens relativ einfach anpassen, damit der Zugriff auf die nun abgesicherte RESTAPI funktioniert. Das Einzige, was Sie hierfür machen müssen, ist, über die Methode auth() Nutzername und Passwort zu übergeben. Intern erstellt »superagent« dann einen entsprechend kodierten »Authorization«-Header. const superagent = require('superagent'); superagent .get('http://localhost:3000/api/v1/contacts') .auth('admin', 'password') .end((error, response) => { if (error) { console.error(error); } else { const contacts = response.body; contacts.forEach((contact) => { console.log(contact); }); } }); Listing 8.28 Basic Authentication mit dem »superagent«-Package
8.5.2 Ausblick Basic Authentication ist nur einer von vielen Authentifizierungsmechanismen, die Sie für das Absichern von Ressourcen verwenden können. Im nächsten Rezept möch-
365
8
Webanwendungen und Webservices
te ich Ihnen ein Package (genauer gesagt: eine weitere Middleware für »Express«) vorstellen, das Ihnen dabei hilft, mit relativ wenig Aufwand verschiedenste Authentifizierungsmechanismen zu integrieren.
Verwandte Rezepte 왘 Rezept 54: Einen HTTP-Server implementieren 왘 Rezept 56: Eine REST-API implementieren 왘 Rezept 57: Einen HTTP-Client implementieren 왘 Rezept 59: Authentifizierung mit »Passport.js« implementieren
8.6 Rezept 59: Authentifizierung mit »Passport.js« implementieren Sie möchten sich nicht selbst um die Implementierung eines Authentifizierungsmechanismus kümmern, sondern eine Middleware verwenden, mit der sich verschiedenste existierende Authentifizierungsmechanismen verwenden lassen.
8.6.1 Lösung In den Beispielen aus dem vorherigen Rezept haben Sie die Authentifizierung mit einer eigenen Middleware implementiert. Auch wenn Sie dabei auf das bestehende Package »basic-auth« zurückgegriffen haben, können Sie sich die Arbeit noch etwas einfacher machen und eine der existierenden Authentifizierungs-Middlewares verwenden. Die bekannteste in diesem Zusammenhang ist »Passport.js« (http://www.passportjs.org/). Das Package stellt dabei nicht nur die Basic Authentication zur Verfügung, sondern insgesamt über 500 verschiedene Authentifizierungsmechanismen, darunter JSON Web Tokens (kurz JWT), OAuth 2.0, die Authentifizierung über Facebook, Twitter oder LinkedIn, die Authentifizierung über LDAP und viele andere mehr. Im Folgenden möchte ich Ihnen zeigen, wie einfach sich die Basic Authentication aus dem vorherigen Rezept unter Verwendung von »Passport.js« realisieren lässt. Installieren Sie dazu (auf Basis des Projekts aus Rezept 56) wie folgt zunächst »Passport.js« sowie das entsprechende Plugin, das die Basic Authentication implementiert. $ npm install passport $ npm install passport-http
»Passport.js« implementiert das bekannte Strategy-Entwurfsmuster der »Gang of Four«: Jeder Authentifizierungsmechanismus ist dabei als Strategy-Klasse imple-
366
8.6
Rezept 59: Authentifizierung mit »Passport.js« implementieren
mentiert und kann entsprechend einfach eingebunden bzw. ausgetauscht werden. Das Plugin »passport-http« stellt – wie Sie in Listing 8.29 sehen können – eine Klasse BasicStrategy zur Verfügung, welche die Basic Authentication implementiert (die genaue Beschreibung dessen, was hier passiert, folgt unterhalb des Listings). const express = require('express'); const APIRouter = require('./APIRouter'); const bodyParser = require('body-parser'); // 1.) Passport.js und entsprechendes Plugin importieren const passport = require('passport'); const { BasicStrategy } = require('passport-http'); const app = new express(); const apiRouter = new APIRouter(); const PORT = 3000; app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); // 2.) Passport.js als Middleware registrieren app.use(passport.initialize()); // 3.) Authentifizierung für Route aktivieren app.use( '/api/v1', passport.authenticate('basic', { session: false }), apiRouter ); // Dummy Authentifizierung const authenticate = (username, password) => username === 'admin' && password === 'password'; // 4.) Strategy instanziieren const strategy = new BasicStrategy(async (username, password, done) => { const authenticated = await authenticate(username, password); if (!authenticated) { done('Wrong credentials'); } else { done(null, { username }); } });
367
8
Webanwendungen und Webservices
// 5.) Strategy in Passport.js registrieren passport.use(strategy); app.listen(PORT, (error) => { if (error) { console.error(error); } else { console.log(`Server started at: http://localhost:${PORT}`); } }); module.exports = app; Listing 8.29 Basic-Authentication mit »Passport.js«
Insgesamt besteht das Einbinden und Konfigurieren aus folgenden fünf Schritten, die im Listing entsprechend durch Kommentare gekennzeichnet sind. 1. Zunächst importieren Sie »Passport.js« und die entsprechende Strategy-Klasse aus dem verwendeten Plugin. 2. Anschließend wird »Passport.js« über die Methode use() als Middleware an der jeweiligen »Express«-Applikation registriert. 3. Im Gegensatz zu der Middleware, die Sie im vorherigen Rezept selbst implementiert hatten, wird »Passport.js« bzw. der definierte Authentifizierungsmechanismus nicht automatisch für alle Routen angewendet. Dies müssen Sie daher manuell an entsprechender Stelle konfigurieren. 4. Den konkreten Authentifizierungsmechanismus definieren Sie über die eingangs erwähnte Strategy-Klasse, in unserem Fall über die Klasse BasicStrategy. Dem Konstruktor übergeben Sie dabei eine Funktion mit drei Parametern: dem Nutzernamen, dem Passwort sowie einer Callback-Funktion. Innerhalb dieser Funktion haben Sie nun die Möglichkeit, die Authentifizierung durchzuführen. Aus Demonstrationszwecken greifen Sie hier wie schon im vorherigen Rezept auf unsere hart kodierte Lösung zurück. Schlägt die Authentifizierung fehl, rufen Sie die genannte Callback-Funktion mit einem entsprechenden Fehler als Parameter auf. Ist die Authentifizierung dagegen erfolgreich, lassen Sie beim Aufruf der CallbackFunktion den ersten Parameter einfach weg. 5. Anschließend muss die entsprechende Strategy bei »Passport.js« registriert werden. Wenn Sie die Applikation starten, können Sie nun, wie im vorherigen Rezept gezeigt, per HTTPie (oder einem anderen HTTP-Client) unter Angabe eines »Authorization«Headers auf die REST-API zugreifen.
368
8.6
Rezept 59: Authentifizierung mit »Passport.js« implementieren
Weitere Authentifizierungsmechanismen Wie eingangs erwähnt, gibt es für »Passport.js« eine Unmenge von Plugins, über die Sie sehr einfach weitere Authentifizierungsmechanismen in Ihre Applikation integrieren können. Die Plugins stehen dabei jeweils als separate Packages zur Verfügung und müssen entsprechend über npm installiert werden (bspw. npm install passportfacebook). Anschließend müssen Sie innerhalb Ihrer Applikation, wie in Listing 8.30 exemplarisch für die Authentifizierung über Facebook gezeigt, drei Stellen anpassen. Zunächst müssen Sie die entsprechende Strategy-Klasse aus dem jeweiligen Plugin importieren, dann die abzusichernden Routen so anpassen, dass passport.authenticate() das Plugin verwendet, und des Weiteren eine Instanz der Strategy-Klasse erstellen, um Sie der Methode passport.use() zu übergeben. const express = require('express'); const APIRouter = require('./APIRouter'); const bodyParser = require('body-parser'); // 1.) Passport.js und entsprechendes Plugin importieren const passport = require('passport'); const FacebookStrategy = require('passport-facebook').Strategy; const app = new express(); const apiRouter = new APIRouter(); const PORT = 3000; app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); // 2.) Passport.js als Middleware registrieren app.use(passport.initialize()); // 3.) Authentifizierung für Route aktivieren app.use( '/api/v1', passport.authenticate('facebook'), apiRouter ); // 4.) Strategy instanziieren const strategy = new FacebookStrategy({ clientID: '', clientSecret: '', callbackURL: 'http://localhost:3000/auth/facebook/callback' },
369
8
Webanwendungen und Webservices
(accessToken, refreshToken, profile, done) => { // ... } ); // 5.) Strategy in Passport.js registrieren passport.use(strategy); app.listen(PORT, (error) => { if (error) { console.error(error); } else { console.log(`Server started at: http://localhost:${PORT}`); } }); module.exports = app; Listing 8.30 Authentifizierung über Facebook
Hinweis Um die Authentifizierung über Facebook zu verwenden, müssen Sie zunächst bei Facebook eine entsprechende App erzeugen. Details dazu finden Sie unter http:// www.passportjs.org/docs/facebook/ und https://developers.facebook.com/docs/apps/. Anschließend erhalten Sie eine App ID und ein App Secret, die in dem obigen Listing für die entsprechenden Platzhalter einzutragen sind. Darüber hinaus müssen Sie innerhalb Ihrer Applikation eine Callback URL vorsehen, die immer dann aufgerufen wird, wenn die Authentifizierung über Facebook abgeschlossen wurde.
8.6.2 Ausblick Auch wenn es prinzipiell, wie in dem vorherigen Rezept gezeigt, möglich ist, Authentifizierungsmechanismen manuell in Form eigener Middleware für »Express« zu implementieren, rate ich Ihnen dazu, von Anfang an »Passport.js« zu verwenden. Zumindest, wenn Sie eine Webanwendung auf Basis von »Express« implementieren, denn »Passport.js« kann nur in Kombination mit diesem Webframework verwendet werden.
Verwandte Rezepte 왘 Rezept 54: Einen HTTP-Server implementieren 왘 Rezept 56: Eine REST-API implementieren
370
8.7
Rezept 60: Eine GraphQL-API implementieren
왘 Rezept 57: Einen HTTP-Client implementieren 왘 Rezept 58: Authentifizierung implementieren
8.7 Rezept 60: Eine GraphQL-API implementieren Sie möchten eine GraphQL-API implementieren, um anschließend flexible Anfragen an diese API stellen zu können.
8.7.1 Exkurs: das Problem von REST In Rezept 56 haben Sie gesehen, wie Sie unter Node.js eine REST-API erstellen können. Je nach Anwendungsfall stellen REST-APIs aber nicht die beste Form einer API für Webservices dar, weil hierbei letztendlich der Server den Aufbau und die Struktur der Antworten bestimmt (dazu gleich mehr im nächsten Abschnitt). Mit GraphQL (http:// facebook.github.io/graphql/) hat Facebook daher eine Anfragesprache geschaffen, über die sich auf Client-Seite die Struktur der Daten formulieren lässt, die von einem Webservice zurückgegeben werden sollen. Wie das funktioniert, zeigen dieses Rezept und das daran anschließende Rezept. Zunächst lernen Sie, wie Sie prinzipiell eine GraphQL-API (unabhängig von HTTP) erstellen, anschließend im folgenden Rezept, wie Sie diese API über HTTP betreiben.
REST vs. GraphQL Der Unterschied zu REST lässt sich dabei am besten an einem konkreten Szenario nachvollziehen: Stellen Sie sich vor, Sie sollen eine API erstellen, über die sich Informationen zu Musikkünstlern abrufen lassen. Das Objektmodell soll der Einfachheit halber relativ schmal gehalten sein: Einzelne Künstler haben einen Namen und eine Liste von Alben, jedes Album hat wiederum einen Titel, ein Erscheinungsjahr und eine Liste von Songs. Einzelne Songs wiederum haben einen Titel und eine Angabe über die Dauer. Wie dieses Objektmodell aussehen könnte, zeigt der JSON-Code in Listing 8.31 (wobei hier aus Platzgründen nur ein Ausschnitt des Modells abgedruckt ist). { "artists": [ { "id": "artist-1", "name": "Ben Harper", "albums": [ { "id": "album-1",
371
8
Webanwendungen und Webservices
"title": "Welcome to the Cruel World", "year": 1994, "tracks": [ { "id": "title-1", "title": "The Three of Us", "length": "2:35" }, ... ] }, ... ] }, { "id": "artist-2", "name": "DJ Shadow", "albums": [ { "id": "album-21", "title": "Endtroducing.....", "year": 1996 }, ... ] } ] } Listing 8.31 Objektmodell für das Beispiel (gekürzt)
Geht man dieses Szenario mithilfe von REST an, würde das vermutlich in den folgenden Endpoints resultieren: 왘 /api/artists – Zugriff auf alle Künstler 왘 /api/artists/:id – Zugriff auf einen bestimmten Künstler 왘 /api/artists/:id/albums – Zugriff auf die Alben eines Künstlers 왘 /api/artists/:id/albums/:aid – Zugriff auf ein bestimmtes Album 왘 /api/artists/:id/albums/:aid/tracks – Zugriff auf die Songs eines Albums 왘 /api/artists/:id/albums/:aid/tracks/:tid – Zugriff auf einen bestimmten Song
Für jeden Endpoint müssten außerdem verschiedene HTTP-Methoden unterstützt werden: GET für die Anfrage von Daten, POST für das Anlegen, PUT für das Aktualisie-
372
8.7
Rezept 60: Eine GraphQL-API implementieren
ren, DELETE für das Löschen usw. Der Vorteil dieser Herangehensweise: APIs, die nach den Prinzipien und Best Practices von REST entworfen sind, sind für jeden Entwickler relativ schnell zu verstehen und zu verwenden. So weit, so gut. Allerdings sind REST-APIs auch relativ unflexibel: Da der Server derjenige ist, der über die Endpoints festlegt, welche Daten an den Client geschickt werden bzw. wie diese Daten strukturiert sind, hat der Client nur begrenzte Möglichkeiten, individuell zu bestimmen, in welcher Form er die Daten erhalten möchte. Dazu ein Beispiel: Angenommen, auf Client-Seite soll eine Übersicht aller Künstler inklusive einer Auflistung der jeweiligen Alben dargestellt werden. Mit den oben gelisteten Endpoints wären hierzu mehrere Anfragen an die REST-API notwendig: zum einen eine Anfrage an den Endpoint /api/artists, um eine Liste aller Künstler zu erhalten 1, und zum anderen für jeden Künstler eine Anfrage an /api/artists/:id/albums, um jeweils eine Liste aller Alben für den jeweiligen Künstler zu erhalten 2 (Abbildung 8.3).
Client 1 GET / api / artists
Server (REST-API)
[{ "id": "artist-1", "name": "Ben Harper" }, { "id": "artist-2", "name": "DJ Shadow" }, ... ]
2 GET / api / artists / artist-1 / albums
[ {...} ] GET / api / artists / artist-2 / albums
[ {...} ] ... (für jeden weiteren Musikkünstler)
Abbildung 8.3 Bei REST sind gegebenenfalls mehrere Aufrufe notwendig.
373
8
Webanwendungen und Webservices
Abhängig von der Anzahl der Künstler erhöht sich also auch die Anzahl der Anfragen, die notwendig sind, um das gewünschte Ergebnis zu erhalten. Mit anderen Worten: Dieser Ansatz skaliert sehr schlecht. Um nun die mehrfachen Aufrufe (und damit unnötigen HTTP-Traffic) zu vermeiden, hat man in REST die folgenden zwei Möglichkeiten: 1. Zusätzlicher Endpoint: Hierbei wird ein weiterer Endpoint implementiert, der die geforderten Daten direkt den Anforderungen entsprechend in einer einzelnen HTTP-Antwort bereitstellt (bspw. api/artists-and-albums). 2. Parametrisierter Endpoint: Hierbei wird ein bestehender Endpoint um zusätzliche Parameter erweitert, anhand derer die zurückgegebene Antwort zusammengebaut wird, bspw. /api/artists?includeAlbums=true oder /api/artists?include= artist.albums. Beide Vorgehensweisen würden das Problem zwar fürs Erste lösen, widersprechen aber zum einen den Prinzipien von REST und würden zum anderen nur so lange ausreichen, bis sich auf Client-Seite eine neue Anforderung für die Struktur der Daten ergibt: Dann nämlich müssten Sie entweder mehrere HTTP-Anfragen in Kauf nehmen oder erneut weitere Änderungen bezüglich der Endpoints vornehmen.
8.7.2 Lösung: dynamische APIs mit GraphQL Die beschriebene Problematik ist genau der Punkt, an dem GraphQL ansetzt. Im Gegensatz zu REST, bei dem der Server definiert, in welcher Struktur Daten an den Client zurückgesendet werden, entscheidet bei GraphQL der Client, der die API anfragt, in welcher Struktur er die Daten benötigt. Dazu formuliert der Client eine sogenannte GraphQL-Query, die dann auf ServerSeite gegen ein graphenbasiertes Schema ausgeführt wird. Die entsprechenden Daten werden anschließend in der angefragten Struktur zurück an den Client gesendet (Abbildung 8.4).
GraphQL unter Node.js Bibliotheken für GraphQL gibt es für verschiedene Programmiersprachen, bspw. für Ruby, Python, Java, Scala, Clojure, Go, PHP und C#. Für JavaScript bzw. Node.js bildet das Package »graphql« die Referenzimplementierung. Installiert werden kann das Package wie gewohnt über npm mithilfe des folgenden Befehls: $ npm install graphql
374
8.7
Client
Rezept 60: Eine GraphQL-API implementieren
Server (GraphQl-API) POST query{ artists{ name, albums{ title, year } } }
{ "data": { "artists": [ { "name": "Ben Harper" "albums": [ . . . ] }, { "name": "DJ Shadow" "albums": [ . . . ] ] } }
Abbildung 8.4 Bei GraphQL lassen sich Anfragen dynamisch anpassen.
GraphQL-Schemas definieren Anschließend lässt sich das »graphql«-Package per require() einbinden und stellt verschiedene Typen zur Verfügung, über die sich ein GraphQL-Schema (GraphQL Schema Definition Language (SDL)) definieren lässt. Wie solch ein Schema für das eingangs geschilderte Beispiel aussehen könnte, sehen Sie in Listing 8.32. Den Einstiegspunkt bildet dabei der Typ GraphQLSchema, dem Sie als Konfigurationsobjekt die Wurzeltypdefinition übergeben und darüber das Schema instanziieren. Die Wurzeltypdefinition (im Beispiel RootType genannt) wiederum bezeichnet den Einstiegspunkt für die GraphQL-Anfrage, dem hierarchisch weitere Typen untergeordnet werden. Für das Beispiel sind dies ArtistType, AlbumType sowie TrackType: Ein Künstler hat mehrere Alben, die wiederum aus mehreren Tracks bestehen.
375
8
Webanwendungen und Webservices
const { GraphQLSchema, GraphQLObjectType, GraphQLString, GraphQLInt, GraphQLList, GraphQLID, GraphQLNonNull } = require('graphql'); const data = require('./artists-data.json'); const TrackType = new GraphQLObjectType({ name: 'TrackType', fields: { id: { type: GraphQLString }, title: { type: GraphQLString }, length: { type: GraphQLString } } }); const AlbumType = new GraphQLObjectType({ name: 'AlbumType', fields: { id: { type: GraphQLString }, title: { type: GraphQLString }, year: { type: GraphQLInt }, tracks: { type: new GraphQLList(TrackType), resolve(album) { return album.tracks; }
376
8.7
Rezept 60: Eine GraphQL-API implementieren
} } }); const ArtistType = new GraphQLObjectType({ name: 'ArtistType', fields: { id: { type: GraphQLString }, name: { type: GraphQLString }, albums: { type: new GraphQLList(AlbumType), resolve(artist) { let storedArtist = data.artists.find( storedArtist => storedArtist.id === artist.id || storedArtist.name === name ); return storedArtist.albums; } } } }); const RootType = new GraphQLObjectType({ name: 'RootType', fields: { artists: { type: new GraphQLList(ArtistType), resolve() { return data.artists; } }, artist: { type: ArtistType, args: { id: { type: GraphQLString }, name: { type: GraphQLString
377
8
Webanwendungen und Webservices
} }, resolve(parent, { id, name }) { let storedArtist = data.artists.find( storedArtist => storedArtist.id === id || storedArtist.name === name ); return storedArtist; } } } }); const schema = new GraphQLSchema({ query: RootType }); module.exports = schema; Listing 8.32 Schema-Definition in GraphQL
Über die Eigenschaft fields des Konfigurationsobjekts, das Sie dem Konstruktor GraphQLObjectType übergeben, lässt sich für jeden Typ definieren, welche Anfragen erlaubt sind bzw. welche Anfragen auf den jeweiligen Typ zutreffen. Jede Eigenschaft in dem hinterlegten Objekt definiert dabei eine mögliche Anfrage. Der Typ der Antwort wiederum wird durch die Eigenschaft type dieses Objekts definiert, die eigentlichen Werte durch den Rückgabewert der Methode resolve(). Ein Beispiel: Der Code artists: { type: new GraphQLList(ArtistType), resolve() { return data.artists; } }
besagt, dass für Anfragen an »artists« eine Liste von Objekten vom Typ ArtistType zurückgegeben wird, wobei die konkreten Instanzen aus data.artists ermittelt werden. Der Code artist: { type: ArtistType, args: {
378
8.8
Rezept 61: Anfragen an eine GraphQL-API stellen
id: { type: GraphQLString }, name: { type: GraphQLString } }, resolve(parent, { id, name }) { let storedArtist = data.artists.find( storedArtist => storedArtist.id === id || storedArtist.name === name ); return storedArtist; } }
wiederum definiert, dass für Anfragen an »artist« ein einzelnes Objekt vom Typ ArtistType zurückgegeben wird und die konkrete Instanz aus dem Objekt data.artists anhand der ID oder des Namens zurückgegeben wird.
8.7.3 Ausblick Mit der Definition eines GraphQL-Schemas haben Sie die Grundlage für eine GraphQL-API geschaffen (denn die API wird letztendlich durch das jeweilige Schema definiert). Im nächsten Rezept schauen wir uns an, wie sich an diese API Anfragen stellen lassen. Da GraphQL unabhängig von einem konkreten Protokoll wie HTTP ist, werden wir die Anfragen dabei zunächst direkt an die API stellen. Im daran anschließenden Rezept wiederum zeige ich Ihnen, wie Sie eine GraphQL-API über HTTP betreiben.
Verwandte Rezepte 왘 Rezept 56: Eine REST-API implementieren 왘 Rezept 61: Anfragen an eine GraphQL-API stellen 왘 Rezept 62: Eine GraphQL-API über HTTP betreiben
8.8 Rezept 61: Anfragen an eine GraphQL-API stellen Sie möchten Anfragen an ein GraphQL-API stellen.
379
8
Webanwendungen und Webservices
8.8.1 Lösung Sie haben die Möglichkeit, an das im vorherigen Rezept implementierte Schema und die dahinterliegenden Daten Anfragen zu stellen. Listing 8.33 zeigt bspw., wie Sie eine Anfrage stellen, um lediglich die IDs und Namen aller Musikkünstler zu erhalten, nicht aber die detaillierten Informationen zu den Alben. Die Anfrage sieht auf den ersten Blick zwar aus wie JSON, bei genauerem Hinsehen sollte aber auffallen: Die Syntax ist eine andere! (async () => { const query = `{ artists { id, name } }`; const result = await graphql(schema, query); console.log(JSON.stringify(result, null, 2)); // { // "data": { // "artists": [ // { // "id": "artist-1", // "name": "Ben Harper" // }, // { // "id": "artist-2", // "name": "DJ Shadow" // } // ] // } // } })(); Listing 8.33 GraphQL-Anfrage an ein Schema
Um dagegen nur den Namen (also nicht die ID) und zusätzlich alle Informationen zu den Alben eines Künstlers zu erhalten, würden Sie folgende Anfrage verwenden: const query = `{ artists { name, albums { title,
380
8.8
Rezept 61: Anfragen an eine GraphQL-API stellen
year } } }`;
Innerhalb von Anfragen können Sie zudem mithilfe von Argumenten weiter eingrenzen, welche Daten des Objektmodells in der Antwort enthalten sein sollen. Um z. B. einen Musikkünstler anhand des Namens zu ermitteln, übergeben Sie diesen einfach, wie in Listing 8.34 zu sehen, der Anfrage artist als Argument. Intern wird dann die in Listing 8.32 (siehe vorheriges Rezept) definierte resolve()-Methode aufgerufen und der entsprechende Künstler anhand des Namens ermittelt: ... (async () => { const query = `{ artist(name: "Ben Harper") { name, albums { title, year } } }`; const result = await graphql(schema, query); console.log(JSON.stringify(result, null, 2)); // { // "data": { // "artist": { // "name": "Ben Harper", // "albums": [ // { // "title": "Welcome to the Cruel World", // "year": 1994 // }, // { // "title": "Fight for Your Mind", // "year": 1995 // }, // { // "title": "The Will to Live", // "year": 1997 // }, // {
381
8
Webanwendungen und Webservices
// "title": "Burn to Shine", // "year": 1999 // }, // { // "title": "Diamonds on the Inside", // "year": 2003 // } // ] // } // } // } })(); Listing 8.34 Verwendung von Argumenten
Ebenfalls nützlich: Möchten Sie in dem zurückgegebenen Ergebnis andere Eigenschaftsnamen erhalten, als im Schema definiert, können Sie dies innerhalb einer GraphQL-Anfrage über sogenannte Aliasse definieren. Dazu schreiben Sie einfach, wie in Listing 8.35 zu sehen, den Aliasnamen getrennt durch einen Doppelpunkt vor den eigentlichen Namen der Eigenschaft. In der Ausgabe wird dann der Aliasname statt des Originalnamens verwendet. In dem Beispiel wird also aus der Eigenschaft name die Eigenschaft artistName, aus (dem ersten) title wird albumName, aus tracks wird songs und aus (dem zweiten) title wird songName. (async () => { const query = `{ artist(name: "Ben Harper") { artistName: name albums { albumName: title songs: tracks { songName: title } } } }`; const result = await graphql(schema, query); console.log(JSON.stringify(result, null, 2)); // { // "data": { // "artist": { // "artistName": "Ben Harper",
382
8.9 Rezept 62: Eine GraphQL-API über HTTP betreiben
// "albums": [ // { // "albumName": "Welcome to the Cruel World", // "songs": [ // { // "songName": "The Three of Us" // }, // ... // ] // }, // ... // ] // } // } // } })(); Listing 8.35 Verwendung von Aliassen
8.8.2 Ausblick Die Anfragesprache von GraphQL bietet Ihnen ein mächtiges Werkzeug, um Antworten, die von einer API zurückgegeben werden, dynamisch den Anforderungen auf Client-Seite anzupassen. Für weitergehende Informationen zu der Anfragesprache wie bspw. Mutations (für das Ändern von Daten auf Server-Seite), Fragments (für das Wiederverwenden von einzelnen Bestandteilen einer Anfrage) und Directives (Beeinflussen der Ausgabe von Anfragen) empfehle ich Ihnen die Dokumentation unter https://graphql.org/learn/queries/. Im nächsten Rezept zeige ich Ihnen, wie Sie eine GraphQL-API über HTTP betreiben können.
Verwandte Rezepte 왘 Rezept 56: Eine REST-API implementieren 왘 Rezept 60: Eine GraphQL-API implementieren 왘 Rezept 62: Eine GraphQL-API über HTTP betreiben
8.9 Rezept 62: Eine GraphQL-API über HTTP betreiben Sie möchten eine GraphQL-API über HTTP betreiben.
383
8
Webanwendungen und Webservices
8.9.1 Lösung: GraphQL über HTTP betreiben Wie Sie im vorherigen Rezept gesehen haben, kann GraphQL prinzipiell unabhängig von HTTP oder anderen Protokollen verwendet werden. Am häufigsten kommt GraphQL allerdings in Kombination mit HTTP zum Einsatz. Welche Anforderungen ein GraphQL-Server, der über http betrieben wird, erfüllen muss, ist unter https://graphql.org/learn/serving-over-http/ beschrieben. Demnach muss der Server bspw. GET- und POST-Anfragen unterstützen: Bei GET wird die GraphQL-Anfrage über den Parameter »query« übergeben, bspw. http://localhost: 400/api/artists?query="artists{ name, albums { title } }", bei POST-Anfragen dagegen wird die GraphQL-Anfrage im Body übergeben. Dabei kann entweder der »Content-Type«-Header auf den Wert »application/json« gesetzt und die GraphQL-Anfrage als Wert der Eigenschaft query des übergebenen JSON-Objekts definiert werden. Oder der »Content-Type«-Header wird auf den Wert »application/graphql« gesetzt und die GraphQL-Anfrage direkt als Body übergeben. Das Format der HTTP-Antwort, die man vom Server erhält, ist standardmäßig JSON, wobei zwei Eigenschaften enthalten sein können: Die Eigenschaft data enthält die Daten, die der GraphQL-Server als Ergebnis für die jeweilige GraphQL-Anfrage liefert, die Eigenschaft errors enthält im Fehlerfall weitere Details zu den aufgetretenen Fehlern. In Rezept 54 haben Sie gesehen, wie Sie mit dem Modul »http« aus der Standard-API von Node.js einen HTTP-Server erstellen können. Es spricht also nichts dagegen, selbst einen HTTP-Server für GraphQL zu implementieren, wenn Sie Rezept 54 und Rezept 60 miteinander kombinieren. Ich möchte Ihnen im Folgenden allerdings zwei komfortablere Lösungen vorstellen, die auch in der Praxis am häufigsten verwendet werden: die Integration von GraphQL mit »Express« sowie mit dem Apollo Server, der sich auf die Arbeit mit GraphQL spezialisiert hat.
8.9.2 Lösung: GraphQL über »Express« betreiben Viele Webframeworks wie z. B. »Express« bieten über Plugins eine Integration von GraphQL an. Um das aus Rezept 60 bekannte Schema mithilfe eines Express-Servers für HTTP-Anfragen zur Verfügung zu stellen, installieren Sie – sofern noch nicht geschehen – zunächst die Packages »graphql«, »express« und »express-graphql«: $ npm install graphql express express-graphql
Letzteres übernimmt die komplette Integration von GraphQL, sodass Sie sich um nichts weiter kümmern müssen. Lediglich das Schema und einen Endpoint müssen Sie, wie in Listing 8.36 zu sehen, definieren. Wenn Sie dieses Beispielprogramm star-
384
8.9 Rezept 62: Eine GraphQL-API über HTTP betreiben
ten, steht die GraphQL-API unter http://localhost:4000/api/artists über HTTP zur Verfügung: // express-graphql/src/start.js const schema = require('./graphql-schema'); const express = require('express'); const graphqlHTTP = require('express-graphql'); const app = express(); app.use( '/api/artists', graphqlHTTP({ schema: schema }) ); app.listen(4000, () => { console.log('GraphQL-Server gestartet'); }); Listing 8.36 GraphQL-Integration mit »Express«
GraphQL-Anfragen über HTTP stellen Das Absenden einer GraphQL-Anfrage von Client-Seite kann anschließend mit jedem beliebigen HTTP-Client geschehen, für das schnelle Testen bietet sich Postman an (https://www.getpostman.com/) oder Kommandozeilentools wie curl bzw. das im Folgenden verwendete HTTPie (https://httpie.org). Eine Beispielanfrage, um in der Antwort nur die Namen der Musikkünstler zu enthalten (die Sie bereits aus dem vorherigen Rezept kennen), ist in Listing 8.37 zu sehen. $ http POST http://localhost:4000/api/artists query="{ artists { name } }" HTTP/1.1 200 OK Connection: keep-alive Content-Length: 65 Content-Type: application/json; charset=utf-8 Date: Sat, 08 Sep 2018 18:36:25 GMT ETag: W/"41-1GHj71hzxAtFI6zvgOpybFnuAN0" X-Powered-By: Express { "data": { "artists": [ {
385
8
Webanwendungen und Webservices
"name": "Ben Harper" }, { "name": "DJ Shadow" } ] } } Listing 8.37 HTTP-Anfrage an einen GraphQL-Server
Listing 8.38 dagegen zeigt eine Anfrage, um neben den Namen auch die Titel der Alben des jeweiligen Musikers zu enthalten. Den Aufbau der Query kennen Sie dabei ebenfalls schon aus dem vorherigen Rezept. $ http POST http://localhost:4000/api/artists query= "{ artists { name, albums { title } } }" HTTP/1.1 200 OK Connection: keep-alive Content-Length: 410 Content-Type: application/json; charset=utf-8 Date: Sat, 08 Sep 2018 18:38:09 GMT ETag: W/"19a-YFpM4HwkX/RNbsSHkKX9ps5l9BY" X-Powered-By: Express { "data": { "artists": [ { "albums": [ { "title": "Welcome to the Cruel World" }, { "title": "Fight for Your Mind" }, { "title": "The Will to Live" }, { "title": "Burn to Shine" }, { "title": "Diamonds on the Inside" } ],
386
8.9 Rezept 62: Eine GraphQL-API über HTTP betreiben
"name": "Ben Harper" }, { "albums": [ { "title": "Endtroducing....." }, { "title": "The Private Press" }, { "title": "The Outsider" }, { "title": "The Less You Know, the Better" }, { "title": "The Mountain Will Fall" } ], "name": "DJ Shadow" } ] } } Listing 8.38 HTTP-Anfrage an einen GraphQL-Server
Tipp: GraphiQL Alternativ zu Postman, curl oder HTTPie können Sie auch auf die Browser-IDE GraphiQL (https://github.com/graphql/graphiql) zurückgreifen, um Anfragen an einen GraphQLServer zu stellen. Dazu müssen Sie auf Server-Seite das entsprechende Flag setzen: app.use( '/api/artists', graphqlHTTP({ schema: schema, graphiql: true }) );
GraphiQL eignet sich besonders gut dazu, Anfragen zu testen, sollte im Produktivsystem allerdings nicht verwendet und somit in diesem Fall wieder deaktiviert werden.
387
8
Webanwendungen und Webservices
8.9.3 Lösung: GraphQL über den Apollo Server betreiben Eine Alternative zu »express-graphql« stellt der Apollo Server (https://www.apollographql.com/) dar, der gegenüber der erstgenannten Lösung einige Vorteile mit sich bringt. Beispielsweise lässt er sich nicht nur in Kombination mit »Express« verwenden, sondern integriert sich auch mit anderen Frameworks wie Hapi (https://hapijs.com/) und Koa (https://koajs.com/). Um den Apollo Server (und gegebenenfalls GraphQL) zu installieren, verwenden Sie folgenden Befehl: $ npm install graphql apollo-server
Anschließend binden Sie das Package, wie in Listing 8.39 zu sehen, ein und erzeugen eine Instanz von ApolloServer, wobei Sie zum einen die Typdefinitionen und zum anderen sogenannte Resolver übergeben. Diese definieren, welche Daten für die jeweiligen GraphQL-Anfragen zurückgegeben werden, und übernehmen damit die Aufgabe der resolve()-Funktionen aus Rezept 60. Für die Definition der Typen stellt Apollo den Tagged Template-String gql zur Verfügung, mit dessen Hilfe Sie direkt die GraphQL Schema Definition Language verwenden können, was gegenüber der Verwendung von Objektinstanzen (wie in Rezept 60) um einiges bequemer ist. // apollo/src/start.js const { ApolloServer, gql } = require('apollo-server'); const data = require('./artists-data.json'); const typeDefs = gql` type Artist { id: String name: String albums: [Album] } type Album { id: String title: String year: Int tracks: [Track] } type Track { id: String title: String
388
8.9 Rezept 62: Eine GraphQL-API über HTTP betreiben
length: String } type Query { artists: [Artist] artist: Artist } `; const resolvers = { Query: { artists: () => data.artists, artist: ({ id, name }) => { let storedArtist = data.artists.find( storedArtist => storedArtist.id === id || storedArtist.name === name ); return storedArtist; } } }; const server = new ApolloServer({ typeDefs, resolvers }); server.listen().then(({ url }) => { console.log(`GraphQL gestartet unter ${url}`); }); Listing 8.39 GraphQL-Integration über den Apollo Server
Anschließend lassen sich, wie in dem vorherigen Abschnitt für »Express« gezeigt, HTTP-Anfragen an den Server stellen. In diesem Zusammenhang sei auf das Package »apollo-client« (https://github.com/apollographql/apollo-client) hingewiesen, das einen entsprechenden Client zur Verfügung stellt, der das Absenden von GraphQL-Anfragen weiter vereinfacht.
8.9.4 Ausblick GraphQL eignet sich für solche Anwendungsfälle, in denen Sie auf Client-Seite möglichst flexibel entscheiden möchten, in welcher Struktur Sie die Daten vom Server benötigen. Insbesondere im Zusammenspiel mit Webapplikationen, die das »React«Framework nutzen (das wie GraphQL ebenfalls von Facebook entwickelt wird), werden GraphQL-basierte APIs häufig verwendet.
389
8
Webanwendungen und Webservices
8.10 Zusammenfassung In diesem Kapitel habe ich Ihnen verschiedene Rezepte bezüglich der Implementierung von Webanwendungen und Webservices vorgestellt. Sie wissen jetzt, wie Sie 왘 einen HTTP-Server erstellen (Rezept 54), 왘 eine Webanwendung über HTTPS betreiben (Rezept 55), 왘 eine REST-API erstellen (Rezept 56), 왘 einen HTTP-Client erstellen (Rezept 57), 왘 Authentifizierung für eine Webanwendung implementieren (Rezept 58), 왘 Authentifizierung für eine Webanwendung mit »Passport.js« implementieren
(Rezept 59), 왘 eine GraphQL-API erstellen (Rezept 60), 왘 Anfragen an eine GraphQL-API stellen (Rezept 61), 왘 eine GraphQL-API über HTTP betreiben (Rezept 62).
390
Kapitel 9 Sockets und Messaging In diesem Kapitel stelle ich Ihnen verschiedene Rezepte rund um die Themen Socket-Kommunikation und Messaging vor, mit deren Hilfe Sie zum einen eine bidirektionale Kommunikation zwischen Client und Server realisieren und zum anderen einzelne Komponenten einer Node.js-Applikation voneinander entkoppeln können.
Für die Kommunikation zwischen Client und Server ist HTTP nicht immer die geeignete Wahl. Sobald Sie in (mehr oder weniger) Echtzeit Daten sowohl vom Client an den Server als auch in die andere Richtung schicken wollen und daher eine dauerhafte Verbindung zwischen Client und Server benötigen, müssen Sie auf andere Technologien zurückgreifen. In diesem Kapitel zeige ich Ihnen, wie Sie Client-ServerKommunikation über TCP (Rezepte 63 und 64), WebSockets (Rezepte 65 bis 68), Server-Sent Events (Rezept 69) und über die Messaging-Protokolle AMQP (Rezept 70) und MQTT (Rezepte 71 und 72) realisieren. Darüber hinaus schauen wir uns als Randthema zum Thema Messaging das Versenden von E-Mails an (Rezept 73). 왘 Rezept 63: Einen TCP-Server erstellen 왘 Rezept 64: Einen TCP-Client erstellen 왘 Rezept 65: Einen WebSocket-Server erstellen 왘 Rezept 66: Einen WebSocket-Client erstellen 왘 Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren 왘 Rezept 68: Subprotokolle für WebSocket-Kommunikation definieren 왘 Rezept 69: Server-Sent Events generieren 왘 Rezept 70: Über AMQP auf RabbitMQ zugreifen 왘 Rezept 71: Einen MQTT-Broker erstellen 왘 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen 왘 Rezept 73: E-Mails versenden
391
9
Sockets und Messaging
9.1 Rezept 63: Einen TCP-Server erstellen Sie möchten einen Server erstellen, um Verbindungen über TCP entgegenzunehmen und zu verarbeiten.
9.1.1 Lösung Für die Arbeit mit TCP (Transmission Control Protocol) stellt Node.js über die Standard-API das Package »net« (https://nodejs.org/api/net.html) zur Verfügung. Um einen TCP-Server zu erstellen, gehen Sie prinzipiell vor, wie in Listing 9.1 zu sehen. Zunächst erstellen Sie über die Methode createServer() ein Objekt (vom Typ net. Server), das den Server repräsentiert. Über die Methode on() dieses Objekts können Sie anschließend Event-Listener für verschiedene Events registrieren. Das Event »listening« wird bspw. ausgelöst, wenn der Server erfolgreich gestartet wurde und auf neue Verbindungen hört. Wird eine Verbindung von einem TCP-Client hergestellt, wird das Event »connection« ausgelöst. Der entsprechende Event-Listener erhält dabei als Parameter ein Objekt (socket), das die Verbindung zum jeweiligen TCP-Client repräsentiert. Auch auf diesem Objekt lassen sich (ebenfalls über eine Methode on()) erneut Event-Listener registrieren, bspw., wie im Beispiel zu sehen, für das »data«-Event, das ausgelöst wird, wenn vom Client Daten empfangen wurden, oder für das »end«-Event, das beim Beenden der Verbindung durch den Client ausgelöst wird. Über die Methode write() können Sie zudem Nachrichten vom Server an den Client schicken. Um die Anzahl der verbundenen Clients zu ermitteln, verwenden Sie in die Methode getConnections() des Server-Objekts (Achtung: Die Eigenschaft connections ist ver-
waltet und sollte nicht verwendet werden). Im Beispiel wird der ermittelte Wert jeweils bei neuen Verbindungen und bei Verbindungsabbrüchen durch den Client auf der Konsole ausgegeben. Nachdem alle Event-Listener registriert wurden, starten Sie den Server über den Aufruf von listen(), wobei Sie als Parameter den Port und den Host übergeben, unter dem der Server erreichbar sein soll. const net = require('net'); const PORT = 1337; const HOST = '127.0.0.1'; const server = net.createServer((socket) => { socket.write('Example server\n'); });
392
9.1
Rezept 63: Einen TCP-Server erstellen
server.on('listening', () => { const address = server.address(); const port = address.port; const family = address.family; const ipaddress = address.address; console.log(`Server is listening at port: ${port}`); console.log(`Server ip: ${ipaddress}`); console.log(`Server is IP4/IP6: ${family}`); }); server.on('connection', (socket) => { socket.write('Hello client\n'); const { localAddress, localPort } = socket; console.log(`Server is listening at local port: ${localPort}`); console.log(`Server local ip: ${localAddress}`); const { remotePort, remoteAddress, remoteFamily } = socket; console.log(`Remote socket is listening at port: ${remotePort}`); console.log(`Remote socket ip; ${remoteAddress}`); console.log(`Remote socket is IP4/IP6: ${remoteFamily}`); socket.on('data', (data) => { socket.write(data); const { bytesRead, bytesWritten } = socket; console.log(`Bytes read: ${bytesRead}`); console.log(`Bytes written: ${bytesWritten}`); console.log(`Data sent to server: ${data.toString()}`); }); socket.on('end', (data) => { console.log('Socket ended from client'); server.getConnections((error, count) => { console.log(`Number of concurrent connections to the server: ${count}`); }); }); server.getConnections((error, count) => { console.log(`Number of concurrent connections to the server: ${count}`); }); }); server.on('error', (error) => { console.error(error);
393
9
Sockets und Messaging
}); server.listen(PORT, HOST); Listing 9.1 Erstellen eines TCP-Servers
Starten des TCP-Servers Speichern Sie den Code aus Listing 9.1 in eine Datei server.js, und starten Sie die Applikation über folgenden Befehl (da keine externen Packages als Abhängigkeit verwendet werden, müssen Sie nicht einmal ein npm install ausführen): $ node Server Server Server
server.js is listening at port: 1337 ip: 127.0.0.1 is IP4/IP6: IPv4
Alternativ dazu finden Sie den Code aus Listing 9.1 wie immer im Downloadbereich zum Buch. Dort habe ich Ihnen zum Starten des Servers auch ein entsprechendes npm-Script in die package.json hinzugefügt. Der Aufruf lautet dann entsprechend: $ npm start node ./src/server.js Server is listening at port: 1337 Server ip: 127.0.0.1 Server is IP4/IP6: IPv4
Zugriff auf den TCP-Server Für einen schnellen Test, ob der Server so funktioniert, wie wir uns das vorstellen, bietet sich der telnet-Befehl an. Bei Telnet (Kurzform für Teletype Network) handelt es sich um ein Netzwerkprotokoll, bei dem der Datenaustausch über eine TCP-Verbindung läuft. Um sich per Telnet mit dem gerade gestarteten TCP-Server zu verbinden, können Sie folgenden Befehl verwenden, wobei Sie als ersten Parameter den Host und als zweiten Parameter den Port des TCP-Servers angeben: $ telnet 127.0.0.1 1337
Anschließend müsste beim Server folgende Ausgabe erscheinen, weil dort jetzt das »connection«-Event ausgelöst wird. Server is listening at local port: 1337 Server LOCAL ip: 127.0.0.1 Remote socket is listening at port: 51670
394
9.1
Rezept 63: Einen TCP-Server erstellen
Remote socket ip; 127.0.0.1 Remote socket is IP4/IP6: IPv4 Number of concurrent connections to the server: 1
Die Ausgabe auf Client-Seite, also unterhalb des eingegebenen telnet-Befehls, müsste dagegen so aussehen: Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. Echo server Hello client
Jetzt können Sie testweise beliebig viele weitere Verbindungen aufbauen, indem Sie verschiedene Terminals öffnen und jeweils erneut den folgenden Befehl ausführen: $ telnet 127.0.0.1 1337
Dies führt auf Server-Seite zu einer neuen Konsolenausgabe und erhöht entsprechend die Anzahl der Verbindungen: Server Server Remote Remote Remote Number
is listening at local port: 1337 local ip: 127.0.0.1 Socket is listening at port: 51858 Socket ip; 127.0.0.1 Socket is IP4/IP6: IPv4 of concurrent connections to the server: 2
Wenn Sie nun auf Client-Seite eine Nachricht an den Server schicken, kommt die Nachricht wieder zurück an den Client (tippen Sie die entsprechende Nachricht einfach in das Terminal, in dem Sie telnet aufgerufen haben, und drücken Sie anschließend die (¢)-Taste). Hello World Hello World
Die Ausgabe auf Server-Seite lautet dann wie folgt: Bytes read: 26 Bytes written: 39 Data sent to server: Hello World
9.1.2 Ausblick Sie wissen jetzt, wie Sie mithilfe der Node.js-Standard-API einen TCP-Server erstellen sowie Nachrichten von einem Client empfangen und Nachrichten an einen Client senden können. Im folgenden Rezept zeige ich Ihnen, wie Sie unter Node.js einen
395
9
Sockets und Messaging
TCP-Client erstellen und mit diesem auf den in diesem Rezept implementierten TCPServer zugreifen können.
Verwandte Rezepte 왘 Rezept 64: Einen TCP-Client erstellen
9.2 Rezept 64: Einen TCP-Client erstellen Sie möchten einen TCP-Client erstellen, um auf einen TCP-Server zugreifen zu können.
9.2.1 Lösung Auch für das Erstellen von TCP-Clients bietet sich die Verwendung des Packages »net« aus der Node.js-Standard-API an. Um eine entsprechende Objektinstanz zu erzeugen, rufen Sie, wie in Listing 9.2 gezeigt, die Methode createConnection() (bzw. deren Alias connect()) auf, die Ihnen ein Objekt vom Typ net.Socket zurückgibt. Als Parameter übergeben Sie dabei den Port und den Host, unter dem der TCP-Server erreichbar ist. Anschließend haben Sie über den Aufruf der Methode on() wieder die Möglichkeit, Event-Listener zu registrieren (siehe auch Tabelle 9.1). Über die Methode write() können Sie zudem Daten an den TCP-Server schicken. Im Beispiel wird im Event-Listener für das »connect«-Event, mit anderen Worten dann, wenn die Verbindung hergestellt wurde, direkt die Meldung »Hello World« an den Server geschickt. const net = require('net'); const PORT = 1337; const HOST = '127.0.0.1'; const client = net.createConnection(PORT, HOST); client.on('connect', () => { client.write('Hello World'); }); client.on('data', (data) => { console.log(`Data received from server: ${data.toString()}`); }); client.on('close', () => { console.log('Connection closed'); });
396
9.2
Rezept 64: Einen TCP-Client erstellen
client.on('error', (error) => { console.error(error); }); Listing 9.2 Erstellen eines TCP-Clients
Event
Beschreibung
close
Wird ausgelöst, wenn die Socket-Verbindung geschlossen wurde.
connect
Wird ausgelöst, wenn die Socket-Verbindung hergestellt wurde.
data
Wird ausgelöst, wenn Daten über die Socket-Verbindung empfangen wurden.
error
Wird ausgelöst, wenn ein Fehler aufgetreten ist.
ready
Wird ausgelöst, wenn die Socket-Verbindung verwendet werden kann.
end
Wird ausgelöst, wenn das Übertragen von Daten abgeschlossen wurde.
timeout
Wird ausgelöst, wenn aufgrund von Inaktivität ein Timeout auftritt.
Tabelle 9.1 Wichtige Events für die Arbeit mit TCP-Clients
Starten des TCP-Clients Den Code aus Listing 9.2 kopieren Sie in eine Datei client.js und starten ihn über folgenden Befehl: $ node client.js
Alternativ dazu finden Sie den Code auch im Downloadbereich zum Buch. Dort habe ich Ihnen zum Starten des Servers wieder ein entsprechendes npm-Script in die package.json hinzugefügt. Der Aufruf lautet dann: $ npm start node ./src/client.js
Auf Client-Seite wird die Begrüßungsnachricht des Servers ausgegeben sowie die Nachricht, die vom Client an den Server und dann wieder vom Server an den Client zurückgeschickt wird: Data received from server: Echo server Hello World
Auf Server-Seite sollten zudem wieder entsprechende Meldungen bezüglich der neuen Verbindung ausgegeben werden:
397
9
Sockets und Messaging
Server is listening at local port: 1337 Server local ip: 127.0.0.1 Remote Socket is listening at port: 55865 Remote Socket ip; 127.0.0.1 Remote Socket is IP4/IP6: IPv4 Number of concurrent connections to the server: 1 Bytes read: 11 Bytes written: 23 Data sent to server: Hello World
So weit, so einfach. In dem nächsten Abschnitt möchte ich Ihnen nun ein etwas praxisnäheres Beispiel für die Verwendung eines TCP-Clients vorstellen, und zwar die Kommunikation mit dem TCP-Server von Docker.
Praxis-Beispiel: mit Docker über TCP kommunizieren Docker stellt seine API über einen TCP-Server bereit, der als Hintergrundprozess in Form eines Daemons läuft. Über diesen TCP-Server können Sie REST-ähnliche Anfragen an die sogenannte Docker Engine API stellen (siehe auch https://docs.docker. com/develop/sdk/), wobei die Anfragen nicht über HTTP, sondern über Sockets gestellt werden. Der String GET http:/containers/json HTTP/1.0 besagt bspw., dass eine Liste der aktuell gestarteten Docker-Container aufgelistet werden soll. Mit dem Parameter ?all=1 ("GET http:/containers/json HTTP/1.0"?all=1) werden entsprechend alle Docker-Container aufgelistet, also auch die, die momentan nicht gestartet sind. Den Code für das Herstellen einer Verbindung und das Absenden von Anfragen sehen Sie in Listing 9.3 (damit das Beispiel funktioniert, muss logischerweise Docker installiert sein, wovon ich an dieser Stelle ausgehe). Das Beispiel zeigt eine Helferfunktion getContainers(), die asynchron arbeitet und intern die entsprechenden Informationen über die Socket-Verbindung ermittelt. Innerhalb der Helferfunktion wird zunächst über den Aufruf createConnection() wie gewohnt eine Verbindung zu dem TCP-Server hergestellt. Wurde die Verbindung erfolgreich aufgebaut, wird über write(), abhängig vom booleschen Parameter all, eine der beiden oben beschriebenen Anfragen an den Server geschickt. Die vom Server gesendeten Daten der Antwort werden im Event-Listener für das »data«-Event gesammelt und in das Array parts zwischengespeichert. Wurden alle Daten übertragen, d. h. das »end«-Event ausgelöst, werden im entsprechenden Event-Listener die im Array gesammelten Daten über den Aufruf von join() zusammengefügt, dann über substring() der JSON-Teil der Antwort extrahiert und anschließend über JSON.parse() in ein JSON-Objekt geparst.
398
9.2
Rezept 64: Einen TCP-Client erstellen
const net = require('net'); const isWindows = require('os').type() === 'Windows_NT'; const socketPath = isWindows ? '//./pipe/docker_engine' : '/var/run/docker.sock'; const getContainers = (all) => { return new Promise((resolve, reject) => { const socket = net.createConnection({ path: socketPath }); const parts = []; socket.on('connect', () => { socket.write( GET http:/containers/json${all ? '?all=1' : ''} HTTP/1.0\r\n\r\n ); }); socket.on('data', (data) => { parts.push(data.toString()); }); socket.on('error', () => { reject({}); }); socket.on('end', () => { let allData = parts.join(''); const startIndex = allData.indexOf('['); const endIndex = allData.length; allData = allData.substring(startIndex, endIndex); try { const result = JSON.parse(allData); resolve(result); } catch (err) { reject({}); } }); }); }; Listing 9.3 Zugriff auf Docker über TCP-Sockets
399
9
Sockets und Messaging
Die Helferfunktion kann anschließend wie folgt verwendet werden: (async () => { const containers = await getContainers(true); containers.forEach((container) => { console.log(`Id: ${container.Id}`); console.log(`Names: ${container.Names.join('')} `); }); })();
Auf diese Weise können Sie nun verschiedene weitere Helferfunktionen für den Zugriff auf die Docker Engine API implementieren (https://docs.docker.com/develop/ sdk/), bspw. um alle Docker Images aufzulisten, Docker-Container zu starten und vieles mehr. Alternativ dazu könnten Sie die entsprechenden Docker-Befehle wie docker images natürlich auch im Rahmen eines Kindprozesses ausführen (siehe Rezept 80) und die entsprechende Ausgabe des Befehls verarbeiten. Dank der Docker Engine API ist die Lösung über eine Socket-Verbindung allerdings eleganter, weil Sie hier als Antwortformat direkt JSON erhalten, das ja relativ einfach zu parsen ist.
9.2.2 Ausblick In diesem und dem vorherigen Rezept haben Sie gesehen, wie Sie unter Node.js Server und Client für TCP-Kommunikation implementieren. In den folgenden Rezepten zeige ich Ihnen, wie Sie Server und Client für die Kommunikation über WebSockets implementieren.
Verwandte Rezepte 왘 Rezept 63: Einen TCP-Server erstellen 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen
9.3 Rezept 65: Einen WebSocket-Server erstellen Sie möchten einen Server erstellen, um Anfragen über das WebSocket-Protokoll entgegenzunehmen.
9.3.1 Lösung Bei dem WebSocket-Protokoll handelt es sich um ein Netzwerkprotokoll, das auf TCP basiert und eine bidirektionale Kommunikation zwischen einer Webanwendung
400
9.3
Rezept 65: Einen WebSocket-Server erstellen
und einem Webserver ermöglicht.Node.js bietet standardmäßig kein Package an, um mit WebSockets arbeiten zu können. Es gibt allerdings zahlreiche frei verfügbare Packages, die hier Abhilfe schaffen. Eines davon ist das Package »ws« (https://github.com/websockets/ws), das Sie wie folgt installieren: $ npm install ws
Erstellen der WebSocket-Server-Instanz Nach erfolgreicher Installation des Packages binden Sie es wie gewohnt über require(), wie in Listing 9.4 zu sehen, ein. Das Erstellen eines WebSocket-Servers ist anschließend schnell gemacht, und zwar, indem Sie über den Konstruktor der Klasse WebSocket.Server eine entsprechende Objektinstanz erstellen. Den Port, unter dem der WebSocket-Server verfügbar sein soll, können Sie dabei über das Konfigurationsobjekt definieren, das Sie dem Konstruktor als Parameter übergeben: const WebSocket = require('ws'); const wss = new WebSocket.Server({ port: 8080 }); Listing 9.4 Erstellen einer WebSocket-Server-Instanz
Diese wenigen Zeilen an Code reichen bereits aus, um den WebSocket-Server unter Port 8080 zu starten. Allerdings macht er noch nicht viel, reagiert z. B. nicht auf Nachrichten von WebSocket-Clients und versendet auch selbst keine Nachrichten.
Auf Client-Verbindungen reagieren Nachdem der WebSocket-Server instanziiert ist, können Sie über die Methode on() Event-Listener für verschiedene Events registrieren (siehe Tabelle 9.2). Um bspw. darauf zu reagieren, wenn sich ein neuer Client erfolgreich zu dem Server verbunden hat, registrieren Sie einfach einen entsprechenden Event-Listener für das »connection«-Event: wss.on('connection', (ws) => { console.log('New client connected.'); }); Listing 9.5 Reagieren auf Client-Verbindungen
Der Event-Listener für das Event »connection« wird dabei mit einem Objekt vom Typ WebSocket (https://github.com/websockets/ws/blob/master/doc/ws.md#classwebsocket) aufgerufen, das die Verbindung zwischen Client und Server repräsentiert.
401
9
Sockets und Messaging
Dieses Objekt können Sie im Folgenden sowohl dazu verwenden, Nachrichten vom Server an den jeweiligen Client zu senden, als auch dazu, auf Nachrichten von dem jeweiligen Client an den Server zu reagieren. Event
Beschreibung
close
Wird ausgelöst, wenn der Server geschlossen wurde.
connection
Wird ausgelöst, wenn sich ein neuer Client erfolgreich zu dem Server verbunden hat.
error
Wird ausgelöst, wenn ein Fehler auftritt.
headers
Wird ausgelöst, bevor die Response-Header im Zuge des Handshakes zwischen Client und Server in den Socket geschrieben werden.
listening
Wird ausgelöst, wenn der Server bereit ist, auf Verbindungen zu hören.
Tabelle 9.2 Mögliche Events für WebSocket-Server
Nachrichten von einem Client empfangen An dem Objekt vom Typ WebSocket wiederum können Sie erneut über die Methode on() Event-Listener für verschiedene Events registrieren (siehe Tabelle 9.3). Um auf Nachrichten reagieren zu können, die vom Client an den Server geschickt werden, registrieren Sie bspw. einen Event-Listener für das Event »message«. Um erkennen zu können, dass ein Client die Verbindung zum Server beendet hat, registrieren Sie dagegen einen Event-Listener für das Event »close«: const WebSocket = require('ws'); const wss = new WebSocket.Server({ port: 8080 }); wss.on('connection', (ws) => { console.log('New client connected.'); ws.on('message', (message) => { console.log(`received: ${message}`); }); ws.on('close', () => { console.log('Client closed connection."); }); }); Listing 9.6 Nachrichten vom Client empfangen und Verbindungsabbrüche erkennen
402
9.3
Rezept 65: Einen WebSocket-Server erstellen
Event
Beschreibung
close
Wird ausgelöst, wenn die Verbindung geschlossen wurde.
error
Wird ausgelöst, wenn ein Fehler auftritt.
message
Wird ausgelöst, wenn eine vom Client versendete Nachricht empfangen wurde.
open
Wird ausgelöst, wenn die Verbindung zwischen Client und Server hergestellt wurde.
ping
Wird ausgelöst, wenn ein vom Client ausgehendes »Ping« empfangen wurde.
pong
Wird ausgelöst, wenn ein vom Client ausgehendes »Pong« empfangen wurde.
unexpected-response
Wird bei unerwarteten Antworten ausgelöst.
upgrade
Wird ausgelöst, wenn die Response-Header im Zuge des Handshakes zwischen Client und Server empfangen wurden.
Tabelle 9.3 Mögliche Events für WebSocket-Verbindungen
Nachrichten an einen Client schicken Über das Objekt vom Typ WebSocket können Sie nicht nur auf Nachrichten vom Client reagieren, sondern auch Nachrichten vom Server an den jeweiligen Client schicken. Dazu stellt das Objekt die Methode send() zur Verfügung, der Sie entweder eine Zeichenkette übergeben (um Textdaten zu versenden) oder ein Objekt vom Typ Float32Array (um binäre Daten zu versenden). const WebSocket = require('ws'); const wss = new WebSocket.Server({ port: 8080 }); wss.on('connection', (ws) => { console.log('New client connected.'); ws.send('Hello client'); ws.on('message', (message) => { console.log(`received: ${message}`); ws.send('Message received'); }); ws.on('close', () => {
403
9
Sockets und Messaging
console.log('Client closed connection."); }); }); Listing 9.7 Nachrichten an Clients versenden
Nachrichten an mehrere Clients schicken Innerhalb des Event-Listeners für das »connection«-Event können Sie über das Objekt ws lediglich eine Nachricht an den jeweiligen Client am anderen Ende dieser einen WebSocket-Verbindung schicken. Für Anwendungsfälle, bei denen Sie eine Nachricht an alle verbundenen Clients versenden möchten, z. B. um bei einer Chatanwendung die Nutzer eines Chatraums über neue Nutzer zu informieren, müssen Sie dagegen anders vorgehen. Das Objekt wss, welches den WebSocket-Server repräsentiert, verfügt über eine Eigenschaft clients, in der die WebSocket-Verbindungen zu allen Clients als Array hinterlegt sind. Um nun an alle Clients eine Nachricht zu schicken, iterieren Sie einfach über die Verbindungsobjekte in diesem Array und rufen die Methode send() auf. In Listing 9.8 bspw. wird auf diese Weise beim Verbinden neuer Clients eine Nachricht an alle anderen Clients versendet (die Überprüfung client !== ws sorgt dafür, dass an den neu verbundenen Client keine Nachricht geschickt wird). const WebSocket = require('ws'); const wss = new WebSocket.Server({ port: 8080 }); wss.on('connection', (ws) => { wss.clients.forEach((client) => { if (client !== ws && client.readyState === WebSocket.OPEN) { client.send('New client connected.'); } }); }); Listing 9.8 Nachrichten an mehrere Clients versenden
Hinweis Beachten Sie: Wenn Sie JSON-Objekte über WebSockets übertragen möchten, müssen Sie diese beim Versenden zunächst über JSON.stringify() in eine Zeichenkette umwandeln und später beim Empfangen über JSON.parse() wieder in ein Objekt umwandeln.
404
9.4
Rezept 66: Einen WebSocket-Client erstellen
9.3.2 Ausblick Sie wissen jetzt, wie Sie unter Node.js einen WebSocket-Server implementieren, wie Sie auf neue Verbindungen reagieren, wie Sie Nachrichten von Clients empfangen und wie Sie umgekehrt Nachrichten an Clients versenden. Im nächsten Rezept zeige ich Ihnen, wie Sie einen solchen WebSocket-Client implementieren.
Verwandte Rezepte 왘 Rezept 66: Einen WebSocket-Client erstellen 왘 Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren
9.4 Rezept 66: Einen WebSocket-Client erstellen Sie möchten einen WebSocket-Client erstellen, um eine Verbindung zu einem WebSocket-Server herzustellen.
9.4.1 Lösung Im vorherigen Rezept haben Sie gesehen, wie Sie mithilfe des Packages »ws« einen WebSocket-Server erstellen können. In dem vorliegenden Rezept zeige ich Ihnen nun, wie Sie über dasselbe Package einen WebSocket-Client erstellen und dann eine Verbindung zu dem eben implementierten WebSocket-Server herstellen. Wenn Sie den Code für den WebSocket-Client in dem gleichen Package implementieren, in dem auch der Code für den WebSocket-Server liegt, brauchen Sie das Package »ws« natürlich nicht erneut installieren. Für den Fall, dass Sie den Code für Server und Client in separaten Packages implementieren (was sinnvoll ist), installieren Sie das Package wie gewohnt auch für den Client über folgenden Befehl: $ npm install ws
Anschließend binden Sie das Package, wie in Listing 9.9 zu sehen, auch über require('ws') ein, erzeugen dieses Mal aber keine Server-Instanz, sondern eine Instanz von WebSocket, also genau der Klasse, die Sie schon im vorherigen Rezept kennengelernt haben und die eine WebSocket-Verbindung zwischen Server und Client repräsentiert, dieses Mal allerdings aus Sicht des Clients. Als Parameter übergeben Sie der Konstruktorfunktion die URL, unter der der WebSocket-Server läuft, im Beispiel also ws://localhost:8080 (unter der Voraussetzung, versteht sich, dass Sie den Server zuvor entsprechend gestartet haben).
405
9
Sockets und Messaging
const WebSocket = require('ws'); const ws = new WebSocket('ws://localhost:8080'); ws.on('open', () => { ws.send('Hello server'); }); ws.on('message', (data) => { console.log(data); }); Listing 9.9 Erstellen eines WebSocket-Clients
Über die Methode on() haben Sie nun wieder die Möglichkeit, für die bekannten Events (siehe Tabelle 9.3 aus Rezept 65) entsprechende Event-Listener zu registrieren. Mithilfe der Methode send() haben Sie zudem die Möglichkeit, Nachrichten (als Text oder in Binärform) vom Client an den Server zu schicken.
WebSocket-Client im Browser Wenn Sie aus einer Webanwendung heraus eine WebSocket-Verbindung zu einem WebSocket-Server herstellen möchten, müssen Sie in der Regel überhaupt keine Bibliothek einbinden. Alle modernen Browser implementieren die WebSocket-API aus dem HTML5-Standard (https://html.spec.whatwg.org/multipage/web-sockets.html# network). Um eine WebSocket-Verbindung herzustellen, verwenden Sie, wie in Listing 9.10 zu sehen, die Klasse WebSocket. Diese Klasse ist allerdings trotz des gleichen Namens nicht zu verwechseln mit der Klasse aus dem »ws«-Package. Statt einer Methode on() für das Registrieren von Event-Listenern stellt sie verschiedene Event-Handler zur Verfügung: onopen wird aufgerufen, wenn die WebSocket-Verbindung geöffnet wurde, onerror wenn beim Verbindungsaufbau ein Fehler aufgetreten ist, onclose wenn die Verbindung wieder geschlossen wurde und onmessage bei eingehenden Nachrichten. const ws = new WebSocket('ws://localhost:8080'); ws.onopen = () => { ws.send('Hello server'); }); ws.onerror = (error) => { console.error(error);
406
9.5
Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren
}; ws.onclose = () => { console.log('Connection closed.'); }; ws.onmessage = (data) => { console.log(data); }); Listing 9.10 Erstellen eines WebSocket-Clients im Browser
9.4.2 Ausblick Mit diesem und dem vorherigen Rezept haben Sie alle Zutaten, um unter Node.js eine WebSocket-Kommunikation zwischen Client und Server zu implementieren. Im nächsten Rezept gebe ich Ihnen noch ein paar Tipps, was Sie bezüglich des Aufbaus von Nachrichten und der Implementierung eigener Protokolle auf Basis von WebSockets beachten sollten.
Verwandte Rezepte 왘 Rezept 65: Einen WebSocket-Server erstellen 왘 Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren
9.5 Rezept 67: Nachrichtenformate für WebSocketKommunikation definieren Sie möchten zwischen WebSocket-Client und WebSocket-Server ein einheitliches Protokoll- und Nachrichtenformat definieren.
9.5.1 Lösung Im Unterschied zu einer REST-API, in der über HTTP-Verben (bzw. HTTP-Methoden) und Header serverseitig gesteuert werden kann, wie eine Anfrage behandelt (und geroutet) werden soll, müssen Sie dies bei der Kommunikation über WebSockets selbst in die Hand nehmen. Metainformationen einer Nachricht, die bei HTTP durch die Methoden, Header und Query-String-Parameter vorgegeben sind, müssen Sie bei WebSockets in der Nachricht selbst vorhalten. Bevor Sie sich also konkret an die Implementierung einer WebSocket-API machen, sollten Sie sich im Vorfeld ein einheitliches Format für die Nachrichten überlegen:
407
9
Sockets und Messaging
Dazu zählt bspw., welche verschiedenen Typen von Nachrichten es gibt, wie diese Nachrichten zu erkennen sind sowie deren Aufbau.
Nachrichtentypen definieren Als Format für die Nachrichten bietet sich in vielen Fällen JSON an, auch wenn über WebSockets selbstverständlich andere Datenformate und auch binäre Daten übertragen werden können. Bei Verwendung von JSON ergibt es außerdem Sinn, die Nachricht in einen Teil mit Metainformationen (bzw. Header-Informationen) und einen Teil mit der eigentlichen Payload (bzw. dem Body) einzuteilen: const message = { meta: {} body: {} }
Um sowohl auf Server-Seite als auch auf Client-Seite empfangene Nachrichten unterscheiden zu können, wird in der Regel der Typ der Nachricht als Metaeigenschaft definiert: const message = { meta: { type: 'some_message_type' } body: {} }
Protokolldefinitionen Um die zur Verfügung stehenden Nachrichtentypen einheitlich auf Server-Seite und auf Client-Seite verwenden zu können, bietet es sich zudem an, diese in einem separaten JavaScript-Modul als Protokolldefinition zu speichern. Für die Implementierung eines Musikplayers bspw., der über WebSockets gesteuert werden soll, könnte eine Protokolldefinition wie in Listing 9.11 aussehen. Das Objekt REQUESTS enthält dabei die Typen von Anfragenachrichten (in diesem Fall Nachrichten, die vom Client an den Server geschickt werden), das Objekt EVENTS enthält die Typen von Ereignisnachrichten (in diesem Fall Nachrichten, die vom Server an den Client geschickt werden). const EVENTS = { STARTED_SONG: 'started_song', PAUSED_SONG: 'paused_song', STOPPED_SONG: 'stopped_song' };
408
9.5
Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren
const REQUESTS = { START_SONG: 'start_song', PAUSE_SONG: 'pause_song', STOP_SONG: 'stop_song' }; module.exports = { EVENTS, REQUESTS }; Listing 9.11 Protokolldefinition
Diese Protokolldefinition können Sie nun sowohl auf Server-Seite für die Implementierung eines WebSocket-Servers als auch auf Client-Seite für die Implementierung eines WebSocket-Clients als Basis für das Erstellen von Nachrichten und das Reagieren auf Nachrichten verwenden (dazu jeweils gleich mehr Details).
Factory für Nachrichten Neben der zentralen Verwaltung der Nachrichtentypen bietet es sich an, das Erstellen von Nachrichten ebenfalls an zentraler Stelle zu steuern, wobei sich die Verwendung des Factory-Entwurfsmusters anbietet (Listing 9.12). Damit stellen Sie sicher, dass bei Änderungen am Aufbau einer Nachricht dies nur an einer Stelle angepasst werden muss. const { EVENTS, REQUESTS } = require('./Protocol'); module.exports = class MessageFactory { static createStartRequest(artist, song) { return { meta: { type: REQUESTS.START_SONG }, body: { artist, song } }; } static createStartedEvent(artist, song) { return { meta: {
409
9
Sockets und Messaging
type: EVENTS.STARTED_SONG }, body: { artist, song } }; } }; Listing 9.12 Helferklasse für das Erstellen von Nachrichten
Nachrichten auf Server-Seite Im Code für den WebSocket-Server binden Sie nun die Protokolldefinition und die Message-Factory ein (Listing 9.13). Erstere, um Nachrichten vom Client gegen die in der Protokolldefinition definierten Typen zu überprüfen. Letztere, um entsprechende Nachrichten zu generieren, die vom Server an die Clients geschickt werden. Abhängig vom empfangenen Nachrichtentyp können Sie dann anhand des in der Nachricht definierten Typs Ihre Programmlogik implementieren.
Hinweis Beachten Sie, dass die Nachrichten, die Sie über die WebSocket-Verbindung auf dem Server empfangen, zunächst in JSON geparst werden müssen, damit Sie den Typ korrekt ermitteln können. const WebSocket = require('ws'); const MessageFactory = require('./MessageFactory'); const Protocol = require('./Protocol'); const wss = new WebSocket.Server({ port: 8089 }); wss.on('connection', (ws) => { ws.on('message', (message) => { const parsedMessage = JSON.parse(message); switch (parsedMessage.meta.type) { case Protocol.REQUESTS.START_SONG: console.log('Start song request.'); const event = MessageFactory.createStartedEvent( parsedMessage.artist, parsedMessage.song
410
9.5
Rezept 67: Nachrichtenformate für WebSocket-Kommunikation definieren
); ws.send(JSON.stringify(event)); break; } }); }); wss.on('error', (error) => { console.error(error); }); wss.on('listening', () => { console.log(`WebSocket server started on port ${wss.options.port}`); }); Listing 9.13 WebSocket-Server in Node.js
Nachrichten auf Client-Seite Auf Client-Seite verwenden Sie die Protokolldefinition und die Message-Factory auf die gleiche Weise. Den entsprechenden Code dazu sehen Sie in Listing 9.14: Hier wird über createStartRequest() eine Nachricht für das Starten eines Songs erstellt und dann an den Server geschickt. Im Event-Listener für das »message«-Event wird das bestätigte Starten des Songs auf die Konsole ausgegeben. const WebSocket = require('ws'); const MessageFactory = require('./MessageFactory'); const Protocol = require('./Protocol'); const ws = new WebSocket('ws://localhost:8089'); ws.on('open', () => { const message = MessageFactory.createStartRequest( 'The Doors', 'Strange Days' ); ws.send(JSON.stringify(message)); }); ws.on('message', (message) => { const parsedMessage = JSON.parse(message); switch (parsedMessage.meta.type) { case Protocol.EVENTS.STARTED_SONG: console.log('Server started song.');
411
9
Sockets und Messaging
break; } }); Listing 9.14 WebSocket-Client
9.5.2 Ausblick Über eine gemeinsame Protokolldefinition und einen vereinbarten Aufbau von Nachrichten stellen Sie sicher, dass Server und Client korrekt miteinander kommunizieren können. Zumindest theoretisch. Denn auch obiger Code verhindert nicht, dass sich ein Client mit dem Server verbindet, der sich nicht an das vereinbarte Protokoll hält. Wie können Sie also sicherstellen, dass ein Client, der sich über WebSockets zu einem Server verbindet, das gleiche Protokoll verwendet wie dieser? Die Antwort auf diese Fragen liefern sogenannte Subprotokolle, die ich Ihnen im nächsten Rezept vorstelle.
9.6 Rezept 68: Subprotokolle für WebSocket-Kommunikation definieren Sie möchten sicherstellen, dass bei einer Kommunikation über WebSockets der Server und die Clients das gleiche Subprotokoll verwenden.
9.6.1 Lösung Über Subprotokolle können Sie definieren, welche Art der Kommunikation ein WebSocket-Server oder ein WebSocket-Client unterstützen. Ein Beispiel für ein solches Subprotokoll ist das WebSocket Application Messaging Protocol, kurz WAMP (http:// wamp.ws), das auf Basis von WebSockets RPC (Remote Procedure Call) und PubSub (Publish/Subscribe) Messaging Patterns zur Verfügung stellt. WAMP verwendet WebSockets als Transport-Protokoll und JSON als Austauschformat. Andere Beispiele für Subprotokolle sind SOAP (Simple Object Access Protocol), STOMP (Simple Text Orientated Messaging Protocol, https://stomp.github.io/) oder XMPP (Extensible Messaging and Presence Protocol, https://tools.ietf.org/html/rfc7395). Für unser Beispiel des Musikplayers aus dem vorherigen Rezept erweitern Sie zunächst die Protokolldefinition um eine entsprechende Konstante NAME und legen als Namen für das Subprotokoll »musicplayer« fest (Listing 9.15). const NAME = 'musicplayer'; const EVENTS = {
412
9.6
Rezept 68: Subprotokolle für WebSocket-Kommunikation definieren
STARTED_SONG: 'started_song', PAUSED_SONG: 'paused_song', STOPPED_SONG: 'stopped_song' }; const REQUESTS = { START_SONG: 'start_song', PAUSE_SONG: 'pause_song', STOP_SONG: 'stop_song' }; module.exports = { NAME, EVENTS, REQUESTS }; Listing 9.15 Erweiterung der Protokolldefinition um Namen
Beim Verbinden mit einem WebSocket-Server kann der Client, wie in Listing 9.16 zu sehen, über den zweiten Parameter des WebSocket-Konstruktors ein Subprotokoll angeben, das er unterstützt (bzw. in Form eines Arrays sogar mehrere Subprotokolle). Nur wenn der Server eines der angegebenen Subprotokolle ebenfalls unterstützt, wird die Verbindung erfolgreich hergestellt und das »open«-Event ausgelöst. Unterstützt der Server dagegen keines der übergebenen Subprotokolle, schlägt der Verbindungsaufbau mit einem entsprechenden »error«-Event fehl. const WebSocket = require('ws'); const MessageFactory = require('./MessageFactory'); const Protocol = require('./Protocol'); const ws = new WebSocket('ws://localhost:8089', Protocol.NAME); ws.on('open', () => { const message = MessageFactory.createStartRequest( 'The Doors', 'Strange Days' ); ws.send(JSON.stringify(message)); }); ws.on('message', (message) => { const parsedMessage = JSON.parse(message); switch (parsedMessage.meta.type) {
413
9
Sockets und Messaging
case Protocol.EVENTS.STARTED_SONG: console.log('Server started song.'); break; } }); Listing 9.16 Angabe des Subprotokolls bei einem WebSocket-Client
Auf Server-Seite wiederum können Sie anhand der Eigenschaft protocol des jeweiligen Verbindungsobjekts den Namen des Subprotokolls einsehen und abhängig davon Ihre Programmlogik implementieren. In Listing 9.17 bspw. stellen Sie über die if-Bedingung zunächst sicher, dass der Client das Subprotokoll »musicplayer« übergeben hat. Ist dies der Fall, wird die Nachricht wie aus dem vorherigen Rezept bekannt weiterverarbeitet. Entspricht das Subprotokoll allerdings nicht dem erwarteten Wert, gibt der Server eine entsprechende Fehlermeldung aus (hier würde es in der Praxis sicherlich Sinn ergeben, eine entsprechende Fehlermeldung an den Client zurückzusenden). const WebSocket = require('ws'); const MessageFactory = require('./MessageFactory'); const Protocol = require('./Protocol'); const wss = new WebSocket.Server({ port: 8089 }); wss.on('connection', (ws) => { if (ws.protocol === Protocol.NAME) { ws.on('message', (message) => { const parsedMessage = JSON.parse(message); switch (parsedMessage.meta.type) { case Protocol.REQUESTS.START_SONG: console.log('Start song request.'); const event = MessageFactory.createStartedEvent( parsedMessage.artist, parsedMessage.song ); ws.send(JSON.stringify(event)); break; } }); } else { console.error('Protocol not supported.');
414
9.7
Rezept 69: Server-Sent Events generieren
} }); wss.on('error', (error) => { console.error(error); }); wss.on('listening', () => { console.log(WebSocket server started on port ${wss.options.port}); }); Listing 9.17 Subprotokolle für WebSockets
Hinweis Die Subprotokolle werden nur beim initialen Verbindungsaufbau benötigt. Nach erfolgreichem Verbindungsaufbau spielen die Subprotokolle keine Rolle mehr.
9.6.2 Ausblick In den vorherigen vier Rezepten haben Sie gesehen, wie Sie eine WebSocket-Kommunikation zwischen Server und Client unter Node.js implementieren können und was Sie dabei beachten sollten. WebSockets bilden eine wichtige Grundlage für echtzeitfähige Applikationen, in denen Daten vom Server an den Client geschickt werden (beispielsweise Online-Chats etc.). Doch es gibt auch noch eine andere Möglichkeit, Daten vom Server an den Client zu schicken. Welche dies ist und wie die entsprechende Integration in Node.js-Applikationen aussieht, erfahren Sie im nächsten Rezept.
9.7 Rezept 69: Server-Sent Events generieren Sie möchten vom Server Events an den Client schicken, benötigen dabei aber keine bidirektionale Kommunikation zwischen Server und Client.
9.7.1 Lösung: die Server-Seite implementieren In den vorherigen Rezepten haben Sie gesehen, wie Sie mithilfe von WebSockets eine bidirektionale Kommunikation zwischen Client und Server realisieren können. In vielen Fällen ist es aber gar nicht notwendig, dass Clients Daten an den Server schicken. Ein klassisches Beispiel hierfür wäre ein Börsen-Ticker, der den Kurs einer Aktie an den Client überträgt. In solchen Fällen ist es daher sinnvoll, alternativ zu WebSockets auch andere Technologien in Betracht zu ziehen: Die Rede ist von sogenannten Server-Sent Events (siehe http://www.w3.org/TR/eventsource/ bzw. im »Living Standard« unter https://html.spec.whatwg.org/multipage/comms.html#server-sent-
415
9
Sockets und Messaging
events). Mithilfe von Server-Sent Events ist es – wie der Name schon andeutet – möglich, vom Server aktiv Nachrichten an Clients zu versenden (siehe Abbildung 9.1). Zeit
Neue Daten
Server
Antwort mit neuen Daten
Neue Daten
Antwort mit neuen Daten
Client
Abbildung 9.1 Prinzip von Server-Sent Events
Um Server-Sent Events zu verwenden, benötigen Sie kein zusätzliches Package, sondern können alles mit Modulen aus der Standard-API von Node.js realisieren. Listing 9.18 zeigt den serverseitigen Code für eine Anwendung, die alle fünf Sekunden eine Zufallszahl zwischen 1 und 20 generiert und diese über den Event-Stream unter http:// localhost:8000/events an den Client schickt. const fs = require('fs'); const http = require('http'); const MIN = 1; const MAX = 20; const server = http.createServer((request, response) => { if ( request.headers.accept && request.headers.accept === 'text/event-stream' ) { if (request.url === '/events') { sendEvent(request, response); } else { response.writeHead(404); response.end(); } } else { response.writeHead(200, { 'Content-Type': 'text/html'
416
9.7
Rezept 69: Server-Sent Events generieren
}); response.write(fs.readFileSync(__dirname + '/index.html')); response.end(); } }); server.listen(8000); function sendEvent(request, response) { response.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' }); const id = (new Date()).toLocaleTimeString(); setInterval(() => { createServerSendEvent(response, id); }, 5000); createServerSendEvent(response, id); } function createServerSendEvent(response, id) { const number = createRandomNumber(); response.write(`id: ${id}\n`); response.write(`data: ${number}\n\n`); } function createRandomNumber() { let number = Math.floor(Math.random() * MAX) + MIN; return number; } Listing 9.18 Implementierung eines Webservers für Server-Sent Events
Zunächst werden in den ersten beiden Zeilen zwei Node.js-Standard-Module importiert, die Sie bereits aus vorherigen Rezepten kennen: Das Modul »fs«, das verschiedene Funktionen rund um das Arbeiten mit dem Dateisystem bereitstellt, und das Modul »http«, über das sich ein Webserver starten lässt. Im Callback-Handler für HTTP-Anfragen implementieren Sie dann die Logik für den Aufbau der Verbindung für die Server-Sent Events. Der erste Teil der Verzweigung prüft über den »Accept«-Header, ob der Client eine Verbindung zu dem Event-Stream aufbauen möchte (der Header hat in diesem Fall den Wert »text/event-stream«). Ist
417
9
Sockets und Messaging
dies der Fall, wird über eine weitere if-Anweisung geprüft, ob der Client die URL »/events« aufgerufen hat. Ist dies ebenfalls der Fall, wird die eigentliche Verbindung zwischen Client und Server über den Event-Stream aufgebaut, was der Übersichtlichkeit halber in der separaten Funktion sendEvent() ausgelagert ist: In dieser Funktion wiederum wird alle fünf Sekunden unter Verwendung der Funktion createServerSendEvent() ein serverseitiges Event erzeugt. Der Code für die Erzeugung der Zufallszahl wiederum befindet sich in der Funktion createRandomNumber(). Der zweite Teil der Verzweigung im Callback bewirkt zudem, dass für alle anderen Anfragen die HTML-Datei index.html zurückgeliefert werden soll, sprich der Inhalt aus Listing 9.20 (weiter unten im nächsten Abschnitt).
9.7.2 Lösung: die Client-Seite implementieren Server-Sent Events bzw. das damit einhergehende EventSource-Interface werden von (fast) allen größeren Browsern unterstützt. Eine Ausnahme bilden derzeit der Internet Explorer und Microsoft Edge (siehe https://caniuse.com/#feat=eventsource). Das EventSource-Interface repräsentiert eine serverseitige Quelle, die Events generiert bzw. Nachrichten verschickt. Um eine solche Eventquelle zu definieren, übergeben Sie, wie in Listing 9.19 zu sehen, der entsprechenden Konstruktorfunktion die URL der Eventquelle, und definieren Sie einen Event-Handler, um auf die Nachrichten vom Server reagieren zu können. const source = new EventSource('/events'); source.onmessage = (event) => { // gesendete Nachricht console.log(event.data); // Quelle console.log(event.origin); // ID des zuletzt gesendeten Events console.log(event.lastEventId); }; Listing 9.19 Festlegen einer Datenquelle für serverseitige Events
Hinweis Neben dem Event-Handler onmessage stehen noch die Event-Handler onopen und onerror zur Verfügung. Ersterer wird aufgerufen, wenn die Verbindung zum Server geöffnet wurde, letzterer, wenn ein Fehler aufgetreten ist.
418
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
Diesen Code bringen Sie einfach in einer HTML-Datei unter (Listing 9.20), die Sie anschließend im Browser aufrufen können.
Listing 9.20 HTML-Code für das Empfangen der serverseitigen Events
9.7.3 Ausblick Server-Sent Events bieten sich immer dann an, wenn Sie aktiv vom Server Nachrichten an den Client schicken möchten. Wenn Sie dagegen eine bidirektionale Kommunikation benötigen, in der auch der Client über die gleiche Verbindung Daten an den Server schickt, greifen Sie eher auf WebSockets zurück.
Verwandte Rezepte 왘 Rezept 65: Einen WebSocket-Server erstellen 왘 Rezept 66: Einen WebSocket-Client erstellen
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen Sie möchten über AMQP auf das Messaging-System RabbitMQ zugreifen.
9.8.1 Exkurs: Messaging Bei der Implementierung komplexer Softwaresysteme, bei denen verschiedene Komponenten bzw. Anwendungen miteinander interagieren, helfen Messaging-Systeme
419
9
Sockets und Messaging
bzw. Message-Broker dabei, eine Kopplung zwischen den einzelnen Komponenten zu vermeiden. Statt einer direkten Kommunikation zwischen einzelnen Komponenten (Abbildung 9.2) erfolgt die gesamte Kommunikation über den Message-Broker (Abbildung 9.3). Einzelne Komponenten können dazu Nachrichten an den Message-Broker schicken oder von dort abrufen. Der Message-Broker übernimmt dabei verschiedene Aufgaben: Zum einen können eingehende Nachrichten nach bestimmten Regeln verteilt werden, sodass diese von anderen Komponenten abgerufen werden können (Stichwort Message-Routing), zum anderen können Message-Broker dafür sorgen, Nachrichten zwischen verschiedenen Messaging-Protokollen zu übersetzen. In diesem und den folgenden Rezepten zeige ich Ihnen, wie Sie Messaging auch für Ihre Node.js-Applikationen verwenden können.
Komponente A
Komponente B
Service A1
Service B1
Service B2
Service A2
Service C1
Service C2 Komponente C
Abbildung 9.2 Direkte Kommunikation zwischen Komponenten
420
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
Komponente A
Komponente B
Service A1
Service B1
Service B2
Service A2
Message System
Service C1
Service C2 Komponente C
Abbildung 9.3 Kommunikation über Message-Broker
9.8.2 Einführung: AMQP Bei AMQP (Advanced Messaging Queuing Protocol) handelt es sich um einen offenen Standard, der ein Protokoll für den Austausch von Nachrichten beschreibt, ein sogenanntes Messaging-Protokoll. Die wesentlichen Komponenten von AMQP sind: Producer bzw. Publisher, Consumer bzw. Subscriber, Exchanges, Queues sowie Bindings (siehe Abbildung 9.4). Außerdem wird zwischen Connections und Channels unterschieden. Als Producer bzw. Publisher bezeichnet man beim Messaging diejenigen Komponenten, die Nachrichten an den Message-Broker schicken. Als Consumer bzw. Subscriber hingegen werden diejenigen Komponenten bezeichnet, die am Message-Broker eingehende Nachrichten verarbeiten.
421
9
Sockets und Messaging
Producer
Message-Broker Exchanges
Bindings
Consumer Queues …
Nachricht
…
Nachricht
…
Abbildung 9.4 Komponenten bei AMQP
Producer senden die Nachrichten bei AMQP an sogenannte Exchanges, von denen es verschiedene Typen gibt und die dafür sorgen, dass Nachrichten nach bestimmten Regeln an Message Queues verteilt (»geroutet«) werden. Subscriber können dann die Nachrichten aus diesen Message Queues abrufen. Innerhalb von Queues werden die Nachrichten nach dem FIFO-Prinzip (First In First Out) verwaltet: Nachrichten, die zuerst in eine Queue weitergeleitet werden, werden auch zuerst bearbeitet (Abbildung 9.5).
Message Queue Nachricht
Nachricht
Abbildung 9.5 Prinzip von Message Queues
Sowohl Producer als auch Consumer müssen – bevor sie Nachrichten senden bzw. empfangen können – eine (TCP-)Verbindung (Connection) zu dem Message-Broker herstellen. Um dann auf Exchanges bzw. Queues zugreifen zu können, werden sogenannte Channels – virtuelle Verbindungen innerhalb der TCP-Verbindung – aufgebaut.
422
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
Exchanges Insgesamt gibt es bei AMQP (standardmäßig) vier verschiedene Typen von Exchanges: Direct Exchanges, Fanout Exchanges, Topic Exchanges und Headers Exchanges. Zusätzlich haben Sie die Möglichkeit, über eine entsprechende Plugin-Schnittstelle sogenannte Custom Exchanges und damit eigene Routing-Mechanismen zu implementieren (bspw. geobasiertes Routing o. Ä.). Fanout Exchanges Der einfachste Fall der vier genannten Exchanges ist ein Fanout Exchange: Hierbei werden die eingehenden Nachrichten an alle an diesen Exchange gebundenen Queues weitergeleitet (siehe Abbildung 9.6). Ein typischer Anwendungsfall für die Verwendung von Fanout Exchanges ist die Umsetzung des Publish/Subscribe-Entwurfsmusters: Eine oder mehrere Komponenten registrieren sich für ein bestimmtes Event und werden alle bei Auftreten des Events benachrichtigt. Producer
Message-Broker Exchanges
Bindings
Consumer Queues
Nachricht
… Consumer Nachricht
Fanout Exchange
…
Nachricht
… Consumer Nachricht
Abbildung 9.6 Prinzip von Fanout Exchanges
Direct Exchanges Beim Direct Exchange (Abbildung 9.7) wird anhand eines Routing Keys, der vom Publisher als Metainformation einer Nachricht mitgesendet wird, entschieden, an welche Queue die Nachricht weitergeleitet wird. Nur wenn der Routing Key der Nachricht dem Routing Key entspricht, der in dem Binding zwischen einem Exchange und einer Queue definiert ist, wird die Nachricht an die entsprechende Queue weitergeleitet.
423
9
Sockets und Messaging
Producer
Message-Broker Exchanges
Bindings
Queues
error
Error Queue
warn
Warning Queue
Nachricht 1 info Nachricht 2 error
Consumer Nachricht 2 error Consumer
Direct Exchange
info
Nachricht 3 warn
Info Queue
Nachricht 3
Consumer
warn
Nachricht 1 info
Abbildung 9.7 Prinzip von Direct Exchanges
Topic Exchanges Etwas flexibler als Direct Exchanges sind die Topic Exchanges (Abbildung 9.8). Vom Prinzip her arbeiten sie ähnlich wie Direct Exchanges, da auch hier anhand des Routing Keys entschieden wird, auf welche Queues die Nachrichten verteilt werden sollen. Im Unterschied jedoch zum Direct Exchange, bei dem der Routing Key exakt mit dem am Binding zwischen Queue und Exchange definierten Key übereinstimmen muss, haben Sie beim Topic Exchange die Möglichkeit, am Binding auch Wildcards bzw. Routing Patterns zu definieren. Producer Nachricht 1
Message-Broker Exchanges
Consumer
Bindings
Queues
*.error.*
Error Queue
*.warn.*
Warning Queue
*.info.*
Info Queue
some.info Nachricht 2 error.severe Nachricht 3 some.error
Topic Exchange
Nachricht 4 info.result Nachricht 5 xyz.warn
Nachricht 3
Nachricht 2
Consumer Nachricht 5
Consumer Nachricht 4
Nachricht 1
Abbildung 9.8 Prinzip von Topic Exchanges
Headers Exchanges Wenn Ihnen die drei genannten Exchange-Typen nicht ausreichen, können Sie auf Headers Exchanges zurückgreifen, welche die flexibelste Variante eines Exchanges
424
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
darstellen (Abbildung 9.9). Anstatt das Routing auf Basis eines einzelnen Routing Keys durchzuführen, geschieht dieses auf Basis von Header-Informationen, die einer Nachricht mitgesendet werden. Headers Exchanges eignen sich also immer dann, wenn man das Routing anhand mehrerer Parameter vornehmen möchte und diese nicht alle in einem Routing Key unterbringen kann oder möchte. Producer log = info Nachricht 1
Message-Broker Exchanges
Bindings
Consumer Queues
Nachricht 2
level = 2 log = info level = 1
log = info Nachricht 2 level = 1 log = info Nachricht 3
Headers Exchange
level = 3 log = info
log = info level = 2 log = info level = 3
Info Level 1 Consumer Info Level 2
Nachricht 4
Nachricht 1
Info Level 3
Nachricht 4 level = 2 log = info Nachricht 5
Consumer Nachricht 5
Nachricht 3
level = 3
Abbildung 9.9 Prinzip von Headers Exchanges
9.8.3 Installation eines Message-Brokers für AMQP Einer der bekanntesten Message-Broker für AMQP ist das in der Programmiersprache Erlang implementierte RabbitMQ (https://www.rabbitmq.com/). RabbitMQ steht Ihnen für alle gängigen Betriebssysteme zur Verfügung. Entsprechende Installationsdateien können Sie auf der Website unter https://www.rabbitmq.com/download. html herunterladen. Alternativ dazu steht ein Docker Image zur Verfügung (Details siehe https://hub. docker.com/r/library/rabbitmq/), für das ich Ihnen der Einfachheit halber wieder eine Konfigurationsdatei vorbereitet habe, die Sie mit Docker Compose über den Befehl docker-compose up starten können: version: '3.5' services: broker: image: rabbitmq:3 container_name: rabbitmq
425
9
Sockets und Messaging
ports: - 5672:5672 expose: - 5672 Listing 9.21 Docker-Compose-Datei für RabbitMQ
9.8.4 Lösung Für JavaScript bzw. Node.js dürfte das Package »amqplib« (https://github.com/squaremo/amqp.node) einer der bekanntesten AMQP-Clients sein. Über das Package lassen sich Producer und Consumer implementieren, Exchanges und Queues verwalten, Verbindungen herstellen, Channels aufbauen und vieles andere mehr. Installieren können Sie das Package über folgenden Befehl: $ npm install amqplib
Die API von »amqplib« gibt es in zwei Varianten: als Callback-API und als PromiseAPI. Je nachdem, welche Variante Sie verwenden möchten, binden Sie das Package entweder über require('amqplib/callback_api') (bei Verwendung der Callback-API) oder über require('amqplib') (bei Verwendung der Promise-API) ein. Für die nachfolgenden Beispiele verwenden Sie letztere Variante, weil der Code insbesondere in Kombination mit async und await um einiges lesbarer ist.
Kommunikation über Queues Der einfachste Fall einer Kommunikation zwischen Producer und Consumer verzichtet ganz auf Exchanges und läuft direkt über Queues: Der Producer schickt eine Nachricht direkt an eine Queue, der Consumer holt diese Nachricht aus der Queue ab und verarbeitet sie. Den Code dafür sehen Sie in Listing 9.22 (Producer) und Listing 9.23 (Consumer). Sowohl Producer als auch Consumer müssen zunächst über den Aufruf der Methode connect() eine (TCP-)Verbindung zum Message-Broker herstellen und innerhalb dieser wiederum über den Aufruf von createChannel() eine virtuelle Verbindung aufbauen. Der anschließende Aufruf von assertQueue() ist optional: Wurde die Queue bereits vorher erstellt – entweder programmatisch oder über die Management-Oberfläche von RabbitMQ (https://www.rabbitmq.com/management.html) –, wird die Queue nicht erneut erzeugt. Um eine Nachricht an die Queue zu schicken, rufen Sie aufseiten des Producers die Methode sendToQueue() auf. Ihr übergeben Sie den Namen der Queue sowie den Inhalt der Nachricht in Form eines Buffers. Auf der Seite des Publishers registrieren Sie über die Methode consume() eine Callback-Funktion an dem Channel, die immer
426
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
dann aufgerufen wird, wenn eine neue Nachricht für den Consumer in der Queue bereitgestellt wird (registrieren Sie auf diese Weise mehrere Consumer an einer Queue, werden die Nachrichten nach dem Round-Robin-Verfahren nacheinander an die Consumer verteilt). const amqp = require('amqplib'); const configuration = { hostname: 'localhost', connectionTimeout: 10000, authMechanism: 'AMQPLAIN', vhost: '/', noDelay: true, ssl: { enabled: true } }; const queue = 'example-queue'; (async () => { try { const connection = await amqp.connect(configuration); const channel = await connection.createChannel(); await channel.assertQueue(queue); await channel.sendToQueue(queue, Buffer.from('Hello World!')); } catch (error) { console.error(error); } })(); Listing 9.22 Producer in AMQP const amqp = require('amqplib'); const configuration = { hostname: 'localhost', connectionTimeout: 10000, authMechanism: 'AMQPLAIN', vhost: '/', noDelay: true, ssl: { enabled: true }
427
9
Sockets und Messaging
}; const queue = 'example-queue'; (async () => { try { const connection = await amqp.connect(configuration); const channel = await connection.createChannel(); await channel.assertQueue(queue); await channel.consume(queue, (message) => { if (message !== null) { console.log(message.content.toString()); channel.ack(message); } }); } catch (error) { console.error(error); } })(); Listing 9.23 Consumer in AMQP
Kommunikation über Exchanges Flexibler als die direkte Verwendung von Queues ist es, die Nachrichten an Exchanges zu schicken. Der Vorteil: Das Routing können Sie dann, wie eingangs beschrieben, über die Einstellungen am jeweiligen Exchange vornehmen. In Listing 9.24 sehen Sie, wie Sie mit dem Package »amqplib« ein Fanout Exchange erstellen und anschließend zwei Queues daran binden. Für das Erstellen des Exchanges verwenden Sie die Methode assertExchange(), der Sie den Namen und den Typ des Exchanges übergeben und die sicherstellt – ähnlich wie zuvor –, dass es einen entsprechenden Exchange gibt, und gegebenenfalls einen neuen anlegt. Über die Methode bindQueue() binden Sie eine Queue an einen Exchange. Um eine Nachricht an einen Exchange zu versenden, verwenden Sie anschließend die Methode publish(), der Sie den Namen des Exchanges und die Nachricht in Form eines Buffers übergeben. const amqp = require('amqplib'); const configuration = { hostname: 'localhost', connectionTimeout: 10000, authMechanism: 'AMQPLAIN',
428
9.8 Rezept 70: Über AMQP auf RabbitMQ zugreifen
vhost: '/', noDelay: true, ssl: { enabled: true } }; const exchange = 'example-fanout-exchange'; const queue1 = 'example-queue'; const queue2 = 'example-queue-2'; (async () => { try { const connection = await amqp.connect(configuration); const channel = await connection.createChannel(); await channel.assertExchange(exchange, 'fanout'); await channel.assertQueue(queue1); await channel.assertQueue(queue2); await channel.bindQueue(queue1, exchange, ''); await channel.bindQueue(queue2, exchange, ''); await channel.publish(exchange, '', Buffer.from('Hello World!')); } catch (error) { console.error(error); } })(); Listing 9.24 Producer über Exchanges
In Listing 9.25 sehen Sie den gegenüber Listing 9.23 etwas angepassten ConsumerCode, wobei sich der Consumer an beiden definierten Queues registriert. Starten Sie diesen Code, und rufen Sie anschließend mehrmals den Code aus Listing 9.24 auf, sehen Sie, dass die Nachrichten abwechselnd an den Queues ankommen, d. h., die erste Nachricht geht an Queue 1, die zweite Nachricht an Queue 2, die dritte Nachricht wieder an Queue 1 usw. const amqp = require('amqplib'); const configuration = { hostname: 'localhost', connectionTimeout: 10000, authMechanism: 'AMQPLAIN', vhost: '/', noDelay: true, ssl: {
429
9
Sockets und Messaging
enabled: true } }; const queue1 = 'example-queue'; const queue2 = 'example-queue'; (async () => { try { const connection = await amqp.connect(configuration); const channel = await connection.createChannel(); await channel.assertQueue(queue1); await channel.assertQueue(queue2); await channel.consume(queue1, (message) => { if (message !== null) { console.log('Message from queue 1'); console.log(message.content.toString()); channel.ack(message); } }); await channel.consume(queue2, (message) => { if (message !== null) { console.log('Message from queue 2'); console.log(message.content.toString()); channel.ack(message); } }); } catch (error) { console.error(error); } })(); Listing 9.25 Consumer für mehrere Queues
9.8.5 Ausblick In diesem Rezept haben Sie gesehen, wie Sie unter Node.js das AMQP-Protokoll in Kombination mit RabbitMQ für die Kommunikation verwenden. Dank der verschiedenen Exchanges lassen sich in AMQP unterschiedliche Mechanismen der Nachrichtenzustellung (Message-Routing) implementieren. Ein anderes Messaging-Protokoll, das als Mechanismus »nur« Publish/Subscribe ermöglicht, dafür aber gegenüber AMQP sehr leichtgewichtig und besonders im IoT-
430
9.9
Rezept 71: Einen MQTT-Broker erstellen
Umfeld (Internet of Things) eine starke Verbreitung hat, ist MQTT. Wie Sie dieses Protokoll unter Node.js einsetzen können, zeige ich Ihnen in den beiden folgenden Rezepten.
9.9 Rezept 71: Einen MQTT-Broker erstellen Sie möchten über das MQTT-Protokoll auf einen Message-Broker zugreifen, entweder um Nachrichten an den Broker zu senden oder um Nachrichten von dem Broker zu empfangen.
9.9.1 Exkurs: das Nachrichtenprotokoll MQTT MQTT (Message Queuing Telemetry Transport) ist ein Nachrichtenprotokoll, das hauptsächlich für die sogenannte M2M-Kommunikation, also für die Machine-toMachine-Kommunikation zum Einsatz kommt. Das Protokoll wurde ursprünglich von den Firmen IBM und Arcom Control Systems im Rahmen eines gemeinsamen Projekts zur Überwachung einer Ölpipeline entwickelt, wobei der Fokus auf folgenden Anforderungen lag: 왘 Unterstützung von Geräten mit eingeschränkten Ressourcen (viele Sensoren mit
wenig Rechenleistung) 왘 Unterstützung unterschiedlicher Qualitäts-Level bezüglich der Übertragung der
Daten (Betrieb auch in instabilen Netzwerken) 왘 effiziente Nutzung der Bandbreite (Betrieb auch in Netzwerken mit niedriger Band-
breite) 왘 Übertragung unterschiedlicher Datentypen
Publish/Subscribe MQTT implementiert das sogenannte Publish/Subscribe Messaging Pattern, kurz Pub/Sub: Publisher versenden Nachrichten an Topics, ein oder mehrere Subscriber registrieren sich für Topics, um darüber die Nachrichten zu empfangen. Dabei kommunizieren Publisher und Subscriber nicht direkt miteinander, sondern sind über einen Broker voneinander entkoppelt (siehe Abbildung 9.10). Der Broker sorgt anhand der Topics dafür, dass Nachrichten an den oder die richtigen Empfänger gelangen. Topics sind im Wesentlichen einfache Zeichenketten, die ähnlich wie eine URL hierarchisch aufgebaut sein können und aus mehreren Topic-Ebenen bestehen, bspw. »factory/hall1/temperatureSensor« oder »factory/hall2/lightSensor«.
431
9
Sockets und Messaging
MQTT-Broker
Publisher
1. Subscribe für ein Topic
Consumer
2. Publish für ein Topic
3. Nachricht weiterleiten
Abbildung 9.10 Prinzip eines MQTT-Brokers
Subscriber registrieren sich beim Broker für ein oder mehrere Topics und können darüber festlegen, an welchen Nachrichten sie interessiert sind. Empfängt der Broker dann eine Nachricht zu einem bestimmten Topic, leitet er die Nachricht an alle für das Topic registrierten Subscriber weiter (siehe Abbildung 9.11). MQTT-Broker /home/garage/lightSensor Publisher
/home/groundfloor/bathroom/lightSensor
Subscribe Subscribe
Consumer Consumer
/home/groundfloor/kitchen/lightSensor
Abbildung 9.11 Prinzip von Topics in MQTT
9.9.2 Lösung: einen MQTT-Broker installieren Auf dem Markt gibt es verschiedene MQTT-Broker, von denen Mosquitto (https:// mosquitto.org/), HiveMQ (https://www.hivemq.com/) und VerneMQ (https://vernemq.com/) die bekanntesten sind. Welchen dieser Broker Sie im Einzelfall verwenden, müssen Sie natürlich selbst entscheiden. Für alle drei Broker habe ich Ihnen entsprechende Dateien für Docker Compose vorbereitet (docker-compose.mosquitto.yml (Listing 9.26), docker-compose.hivemq.yml (Listing 9.27) und docker-compose.vernemq.yml (Listing 9.28), die Sie über docker-compose up unter Angabe des entsprechenden Dateinamens wie folgt starten können: # Starten von Mosquitto $ docker-compose -f docker-compose.mosquitto.yml up
432
9.9
Rezept 71: Einen MQTT-Broker erstellen
# Starten von HiveMQ $ docker-compose -f docker-compose.hivemq.yml up # Starten von VerneMQ $ docker-compose -f docker-compose.vernemq.yml up
Hinweis Beachten Sie, dass Sie die Port-Mappings anpassen müssen, wenn Sie alle Broker parallel starten möchten, da es ansonsten zu Konflikten für den Port 1883 kommt. version: '3.5' services: broker: image: eclipse-mosquitto container_name: mosquitto ports: - 1883:1883 expose: - 1883 Listing 9.26 Docker-Compose-Datei für Mosquitto version: '3.5' services: broker: image: hivemq/hivemq3 container_name: hivemq ports: - 1883:1883 expose: - 1883 Listing 9.27 Docker-Compose-Datei für HiveMQ version: '3.5' services: broker-vernemq: image: erlio/docker-vernemq container_name: vernemq environment:
433
9
Sockets und Messaging
# DOCKER_VERNEMQ_USER_ADMIN: "secret" DOCKER_VERNEMQ_ALLOW_ANONYMOUS: "on" ports: - 1883:1883 expose: - 1883 Listing 9.28 Docker-Compose-Datei für VerneMQ
9.9.3 Lösung: einen MQTT-Broker über Node.js starten Eine interessante Alternative zu den vorgenannten MQTT-Brokern ist »mosca« (https://github.com/mcollina/mosca), ein in Node.js geschriebener MQTT-Broker, den Sie über folgenden Befehl global installieren und anschließend über den Befehl mosca starten können. $ npm install -g mosca
Alternativ dazu steht auch ein Docker Image zur Verfügung, eine entsprechende Konfigurationsdatei (docker-compose.mosca.yml) habe ich Ihnen wieder vorbereitet: version: '3.5' services: broker-mosca: image: matteocollina/mosca container_name: mosca ports: - 1883:1883 - 80:80 expose: - 1883 - 80 Listing 9.29 Docker-Compose-Datei für mosca
Starten können Sie diese Datei über folgenden Befehl: $ docker-compose -f docker-compose.mosca.yml up
Hinweis Beachten Sie aber, dass Sie, je nachdem, welche MQTT-Features Sie verwenden, für »mosca« eine entsprechende Datenbank konfigurieren müssen (bspw. für Retained Messages, siehe Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen).
434
9.9
Rezept 71: Einen MQTT-Broker erstellen
Einbinden von mosca in Node.js-Applikation Besonders interessant ist die Tatsache, dass »mosca« auch programmatisch verwendet werden kann, z. B. um es in eine eigene Node.js-Applikation zu integrieren und so gezielt auf Anfragen von Clients reagieren zu können. Dazu installieren Sie das Package über folgenden Befehl als lokale Abhängigkeit: $ npm install mosca
Anschließend können Sie das Package wie gewohnt über require() einbinden und über die Klasse Server eine neue Server-Instanz erstellen (Listing 9.30). Diese Klasse leitet praktischerweise von EventEmitter aus der Node.js-Standard-API ab und stellt daher die Methode on() für das Registrieren von Event-Listenern zur Verfügung. So können Sie bspw. über entsprechende Listener innerhalb Ihrer Applikation darauf reagieren, wenn eine Verbindung von einem Client hergestellt wurde (Event »clientConnected«), wieder unterbrochen wurde (Event »clientDisconnected«) oder wenn eine neue Nachricht publiziert wurde (Event »published«). const mosca = require('mosca'); const settings = { port: 1883 }; const server = new mosca.Server(settings); server.on('clientConnected', (client) => { console.log(`Client connected: ${client.id}`); console.log('********************'); }); server.on('clientDisconnected', (client) => { console.log(Client disconnected: ${client.id}); console.log('********************'); }); server.on('published', (packet, client) => { console.log('New message received'); console.log(`Topic: ${packet.topic}`); console.log(`Payload: ${packet.payload}`); console.log(`Message ID: ${packet.messageId}`); console.log(`QoS Level: ${packet.qos}`); console.log(`Retained Message: ${packet.retain}`); console.log('********************');
435
9
Sockets und Messaging
}); server.on('ready', () => { console.log(`Mosca server started at port: ${settings.port}`); }); Listing 9.30 Programmatisches Starten des MQTT-Brokers »mosca«
9.9.4 Ausblick Unabhängig davon, welchen der in diesem Rezept vorgestellten MQTT-Broker Sie verwenden: Interessant ist jetzt, wie Sie per MQTT auf den jeweiligen Broker zugreifen können. Wie das unter Node.js funktioniert, schauen Sie sich im nächsten Rezept an.
Verwandte Rezepte 왘 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
9.10 Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen Sie möchten über das MQTT-Protokoll auf einen Message-Broker zugreifen, entweder um Nachrichten an den Broker zu senden oder um Nachrichten von dem Broker zu empfangen.
9.10.1 Lösung: einen MQTT-Client verwenden Haben Sie sich für einen MQTT-Broker entschieden, stellt sich noch die Frage nach einem geeigneten MQTT-Client. Für Node.js bzw. JavaScript empfehle ich Ihnen das Package »MQTT.js« (https://github.com/mqttjs/MQTT.js), das Sie über folgenden Befehl installieren: $ npm install mqtt
Ein Beispiel für die Verwendung des Packages ist in Listing 9.31 und Listing 9.32 zu sehen. Ersteres zeigt den Code für einen Sender (Publisher) von Nachrichten, letzteres den Code für einen Empfänger (Consumer) von Nachrichten. In beiden Fällen erzeugen Sie zunächst über einen Aufruf von mqtt.connect() ein Client-Objekt, wobei Sie als Parameter die URL des MQTT-Brokers und über ein Konfigurationsobjekt die ID des Clients übergeben.
436
9.10
Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
Nach erfolgreicher Verbindung können Sie den jeweiligen Client über subscribe() für ein Topic registrieren oder über publish() Nachrichten zu einem Topic veröffentlichen. Darüber hinaus stehen Ihnen über die Client-API eine Reihe weiterer Methoden zur Verfügung (siehe Tabelle 9.4), bspw. unsubscribe(), um einen Client wieder von einem Topic zu deregistrieren, oder end(), um die Verbindung zum Broker zu beenden. const mqtt = require('mqtt'); const HOSTNAME = 'localhost'; const PORT = 1883; const CLIENT_ID = 'MQTT.js Node.js Client Publisher'; const client = mqtt.connect(`mqtt://${HOSTNAME}:${PORT}'`, { clientId: CLIENT_ID }); client.on('connect', () => { console.log('Publisher connected to MQTT broker'); client.publish('factory/hall2/lightSensor', '12.2'); }); Listing 9.31 Versenden von Nachrichten über MQTT
Auf Consumer-Seite können Sie eingehende Nachrichten zudem über das Event »message« abfangen und darauf innerhalb einer Callback-Funktion reagieren. Diese Funktion wird mit zwei Parametern aufgerufen: zum einen mit dem Topic, über das die Nachricht empfangen wurde, zum anderen mit der Nachricht selbst. const mqtt = require('mqtt'); const HOSTNAME = 'localhost'; const PORT = 1883; const CLIENT_ID = 'MQTT.js Node.js Client Consumer'; const client = mqtt.connect(`mqtt://${HOSTNAME}:${PORT}'`, { clientId: CLIENT_ID }); client.on('connect', () => { console.log('Consumer connected to MQTT broker'); client.subscribe('factory/hall2/lightSensor'); }); client.on('message', (topic, message) => { console.log(message.toString()); }); Listing 9.32 Empfangen von Nachrichten über MQTT
437
9
Sockets und Messaging
Methode/Eigenschaft
Beschreibung
mqtt.connect()
Herstellen einer Verbindung zu einem MQTTBroker.
mqtt.Client()
Repräsentiert eine Verbindung zu einem MQTTBroker.
mqtt.Client#on()
Registrieren eines Event-Listeners für verschiedene Events.
mqtt.Client#publish()
Veröffentlichen einer Nachricht.
mqtt.Client#subscribe()
Abonnieren eines Topics.
mqtt.Client#unsubscribe()
Kündigen eines Topic-Abonnements.
mqtt.Client#end()
Schließen der Verbindung.
mqtt.Client#handleMessage()
Reagieren auf Nachrichten.
mqtt.Client#connected
Boolesche Angabe darüber, ob der Client verbunden ist oder nicht.
mqtt.Client#reconnecting
Boolesche Angabe darüber, ob der Client gerade versucht, sich erneut zum MQTT-Broker zu verbinden.
mqtt.Client#getLastMessageId()
Liefert die ID der zuletzt gesendeten Nachricht.
mqtt.Store()
Repräsentiert einen In-Memory-Nachrichtenspeicher.
mqtt.Store#put()
Fügt dem Nachrichtenspeicher eine neue Nachricht hinzu.
mqtt.Store#del()
Löscht eine Nachricht aus dem Nachrichtenspeicher.
mqtt.Store#createStream()
Erzeugt einen Stream mit allen Nachrichten aus dem Nachrichtenspeicher.
mqtt.Store#close()
Schließt den Nachrichtenspeicher.
Tabelle 9.4 Methoden der »MQTT.js«-Bibliothek
Wildcards Bei der Angabe von Topics auf Subscriber-Seite haben Sie die Möglichkeit, über Wildcards relativ flexibel zu definieren, an welchen Topics man interessiert ist: »factory/#« bspw. informiert den Subscriber über alle Topics, die mit »factory/« beginnen (im Bei-
438
9.10
Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
spiel: über alle Sensordaten in der gesamten Fabrik), »factory/hall2/#« dagegen lediglich über alle Topics, die mit »factory/hall2/« beginnen (sprich über alle Sensordaten in Halle 2). const mqtt = require('mqtt'); const HOSTNAME = 'localhost'; const PORT = 1883; const CLIENT_ID = 'MQTT.js Node.js Client Consumer'; const client = mqtt.connect(`mqtt://${HOSTNAME}:${PORT}'`, { clientId: CLIENT_ID }); client.on('connect', () => { console.log('Consumer connected to MQTT broker'); client.subscribe('factory/hall2/#'); }); client.on('message', (topic, message) => { console.log(message.toString()); }); Listing 9.33 Consumer für alle Sensoren in Halle 2
Wildcards können Sie nicht nur am Ende eines Topic-Strings verwenden, sondern an beliebiger Stelle bzw. anstelle beliebiger Topic-Ebenen. Möchten Sie bspw. über alle Lichtsensoren in der gesamten Fabrik informiert werden, registrieren Sie sich einfach für das Topic »factory/#/lightSensor«. Der Wildcard-Operator # deckt mehrere Topic-Ebenen ab, im Beispiel also sowohl »factory/hall2/lightSensor« als auch »factory/hall3/floor2/lightSensor«. Alternativ steht Ihnen der Wildcard-Operator + zur Verfügung, der nur eine Topic-Ebene abdeckt: »factory/+/lightSensor« würde demnach »factory/hall2/lightSensor« abdecken, nicht aber »factory/hall3/floor2/lightSensor«.
Quality of Service Bezüglich der Zuverlässigkeit der Nachrichtenübertragung stehen in MQTT drei Qualitäts-Level zur Verfügung. Konkret sind dies folgende: 왘 Level 0: keine Garantie dafür, dass eine Nachricht bei den Subscribern ankommt
(Abbildung 9.12). Nachrichten werden weder vom Empfänger bestätigt noch vom Sender gespeichert. 왘 Level 1: Garantie dafür, dass eine Nachricht mindestens einmal ankommt (Abbil-
dung 9.13). Der Sender speichert die Nachricht so lange, bis er vom Empfänger eine Bestätigung erhält. Geschieht dies nicht innerhalb eines bestimmten Zeitfensters, wird die Nachricht erneut gesendet.
439
9
Sockets und Messaging
Client
PUBLISH QoS 0
MQTT-Broker
Abbildung 9.12 Quality of Service Level 0
Client
PUBLISH QoS 1
MQTT-Broker Store
PUBACK
Abbildung 9.13 Quality of Service Level 1 왘 Level 2: Garantiert über eine mehrstufige Kommunikation zwischen Sender und
Empfänger, dass eine Nachricht genau einmal beim Empfänger ankommt (Abbildung 9.14).
Client
PUBLISH QoS 2
MQTT-Broker Store
PUBREC PUBREL PUBCOMP
Abbildung 9.14 Quality of Service Level 2
Welches Level Sie wählen, hängt von dem konkreten Anwendungsfall ab: Bei einem Temperatursensor, der alle paar Sekunden einen aktuellen Temperaturwert liefert, ist es unter Umständen nicht wichtig, dass jeder dieser Werte bei den Empfängern ankommt. Bei einer Anwendung, die zeitkritische Informationen liefert, anhand derer Aktuatoren gesteuert werden sollen, ist es dagegen wichtig, dass jede Nachricht ankommt.
440
9.10
Rezept 72: Über MQTT auf einen MQTT-Broker zugreifen
Mit »MQTT.js« definieren Sie das QoS-Level (Quality of Service) über ein Konfigurationsobjekt, das Sie der Methode publish() übergeben: const mqtt = require('mqtt'); const HOSTNAME = 'localhost'; const PORT = 1883; const CLIENT_ID = 'MQTT.js Node.js Client Publisher'; const client = mqtt.connect(`mqtt://${HOSTNAME}:${PORT}'`, { clientId: CLIENT_ID }); client.on('connect', () => { console.log('Publisher connected to MQTT broker'); client.publish('home/garage/lightSensor', '12.2', { qos: 2 }); }); Listing 9.34 Publishing von Nachrichten mit QoS-Level 2
Retained Messages Unter Retained Messages (auch: persistente Nachrichten) werden solche Nachrichten verstanden, die für ein bestimmtes Topic vom MQTT-Broker gespeichert und an alle Clients, die sich für das jeweilige Topic registrieren, gesendet werden, auch an die Clients, die sich erst nach Eingang der entsprechenden Nachricht registrieren. Wird bspw. unter dem Topic »/factory/hall1/temperatureSensor« jede volle Stunde der gemessene Temperaturwert publiziert, können Sie über Retained Messages sicherstellen, dass alle Subscriber, die sich für das Topic registrieren, direkt den zuletzt gemessenen Wert erhalten und nicht bis zur nächsten vollen Stunde warten müssen. Mit anderen Worten: Auch wenn ein Subscriber zum eigentlichen Zeitpunkt, an dem die Nachricht gesendet wurde, noch nicht für das Topic registriert war, verpasst er die Nachricht nicht. const mqtt = require('mqtt'); const HOSTNAME = 'localhost'; const PORT = 1883; const CLIENT_ID = 'MQTT.js Node.js Client Publisher'; const client = mqtt.connect(`mqtt://${HOSTNAME}:${PORT}'`, { clientId: CLIENT_ID }); client.on('connect', () => { console.log('Publisher connected to MQTT broker'); client.publish('home/garage/lightSensor', '12.2', {
441
9
Sockets und Messaging
retain: true }); }); Listing 9.35 Publishing von persistenten Nachrichten
Last Will and Testament Für den Fall, dass sich ein Client vom Broker abmeldet oder die Verbindung unerwartet abbricht, haben Sie die Möglichkeit, eine Nachricht zu definieren, die in solch einem Fall an ein bestimmtes Topic geschickt werden soll. Solche Last-Will-and-Testament-Nachrichten eignen sich bspw. dazu, den Status von Sensoren oder anderen Komponenten in Ihrem System zu überwachen: Wird die Verbindung zu einem Sensor unterbrochen, können Sie auf die jeweilige Nachricht reagieren und entsprechende Maßnahmen treffen. Last-Will-and-Testament-Nachrichten definieren Sie direkt beim Aufbau der Verbindung zum Broker, indem Sie im entsprechenden Konfigurationsobjekt die Eigenschaft will definieren (Listing 9.36). Im folgenden Beispiel wird im Fall eines Verbindungsabbruchs zwischen Client und Broker eine Nachricht an das Topic »factory/ monitoring/clients/12345« geschickt, die den Inhalt aus dem Objekt lastWillPayload enthält. const mqtt = require('mqtt'); const HOSTNAME = 'localhost'; const PORT = 1883; const CLIENT_ID = '12345'; const lastWillPayload = { clientID: CLIENT_ID, status: 'disconnected' } const client = mqtt.connect(`mqtt://${HOSTNAME}:${PORT}'`, { clientId: CLIENT_ID, will: { topic: `factory/monitoring/clients/${CLIENT_ID}`, payload: JSON.stringify(lastWillPayload, null, 2), qos: 2, retain: true } }); Listing 9.36 Definition von Last-Will-Messages
442
9.11
Rezept 73: E-Mails versenden
9.10.2 Ausblick Sie wissen jetzt, wie Sie unter Node.js auf einen MQTT-Broker zugreifen können, wie Sie Nachrichten über Producer verschicken und über Consumer empfangen können. Neben dem Einsatz in IoT-Szenarien eignet sich MQTT auch für den Einsatz in Microservice-Architekturen, bspw. um die Kommunikation zwischen einzelnen Microservices zu steuern. In Kapitel 13, »Publishing, Deployment und Microservices«, werde ich auf dieses Thema noch einmal zu sprechen kommen.
Verwandte Rezepte 왘 Rezept 70: Über AMQP auf RabbitMQ zugreifen 왘 Rezept 102: Microservice-Architekturen verstehen
9.11 Rezept 73: E-Mails versenden Sie möchten über Node.js E-Mails versenden.
9.11.1 Lösung Das programmatische Versenden von E-Mails gehört in das Standard-Repertoire, und jeder Entwickler dürfte wohl früher oder später mit dieser Aufgabe konfrontiert sein. Sei es, um die Anmeldung für einen Newsletter zu bestätigen (oder einen Newsletter selbst zu verschicken), um bei auftretenden Fehlern oder Instabilitäten in einem System eine Nachricht an den Administrator zu versenden oder BestätigungsE-Mails bei Beenden lang andauernder serverseitiger Abläufe wie etwa Build-Prozessen: Einsatzgebiete für den automatische E-Mail-Versand gibt es viele. Das populärste Package für das Versenden von E-Mails ist »nodemailer« (https://github.com/nodemailer/nodemailer), das sich über den folgenden Befehl installieren lässt: $ npm install nodemailer
In Listing 9.37 sehen Sie ein Beispiel für das Versenden einer E-Mail. Prinzipiell besteht die Vorgehensweise aus drei Schritten: Über createTransport() konfigurieren Sie zunächst, über welchen sogenannten Transport die E-Mail versendet werden soll. Hierbei übergeben Sie Host und Port sowie die Credentials für die Authentifizierung. Im zweiten Schritt definieren Sie die E-Mail selbst, geben bspw. Sender und Empfänger, Betreffzeile und den eigentlichen Nachrichteninhalt an (siehe auch Tabelle 9.5 und https://nodemailer.com/message/). Ist die Nachricht konfiguriert, können Sie im dritten Schritt über die Methode sendMail() des Transport-Objekts die E-Mail versenden.
443
9
Sockets und Messaging
const nodemailer = require('nodemailer'); // 1.) Transport definieren const transporter = nodemailer.createTransport({ host: 'smtp.ethereal.email', port: 587, auth: { user: '', // entsprechend ersetzen pass: '' // entsprechend ersetzen } }); // 2.) E-Mail konfigurieren const email = { from: '[email protected]', to: '[email protected]', subject: 'Hello World', text: 'Hello World', html: 'Hello world' }; // 3.) E-Mail versenden transporter.sendMail(email, (error, info) => { if (error) { console.error(error); } else { console.log('Message sent: %s', info.messageId); } }); Listing 9.37 Senden von E-Mails unter Node.js
Tipp Um die prinzipielle Funktionsweise des E-Mail-Versands und den Code aus Listing 9.37 zu testen, bietet es sich an, unter https://ethereal.email einen entsprechenden Test-Account zu erstellen. Die Zugangsdaten lassen sich dann im CVS-Format, als SMTP-, IMAP- oder POP3-Konfiguration oder direkt als Code-Snippet für Node.js (und PHP) herunterladen. Wenn Sie in Listing 9.37 entsprechend die Platzhalter und ersetzen und das Programm aufrufen, können Sie anschließend unter https://ethereal.email/messages die versendeten E-Mails einsehen.
444
9.11
Rezept 73: E-Mails versenden
Eigenschaft
Beschreibung
from
E-Mail-Adresse des Absenders, bspw. »[email protected]« oder »Max Mustermann [email protected]«
to
kommaseparierte Liste von Empfängeradressen
cc
kommaseparierte Liste von Empfängeradressen, die in Kopie (CC) gesetzt werden sollen
bcc
kommaseparierte Liste von Empfängeradressen, die in Blindkopie (BCC) gesetzt werden sollen
subject
Betreffzeile der E-Mail
text
Textversion der E-Mail als Unicode-Zeichenkette, Buffer, Stream oder Anhang.
html
HTML-Version der E-Mail als Unicode-Zeichenkette, Buffer, Stream oder Anhang
attachments
Liste von E-Mail-Anhängen
Tabelle 9.5 Konfiguration von E-Mails
E-Mails mit Anhängen versenden Um eine E-Mail mit Anhängen zu versenden, gehen Sie wie in Listing 9.38 vor. Die Konfiguration des Transports und das Versenden der E-Mail unterscheiden sich dabei nicht von dem eben gezeigten Beispiel. Das Einzige, was sich unterscheidet, ist die Konfiguration der E-Mail selbst. Hier können Sie Anhänge über die Eigenschaft attachments definieren, entweder, indem Sie den Dateinamen und den Inhalt im Code selbst definieren (über filname und content), oder die zu versendende Datei direkt über den Pfad (path). const nodemailer = require('nodemailer'); const path = require('path'); const attachmentPath = path.join(__dirname, '..', 'data', 'attachment.txt'); const transporter = nodemailer.createTransport({ host: 'smtp.ethereal.email', port: 587, auth: { user: '', // entsprechend ersetzen pass: '' // entsprechend ersetzen }
445
9
Sockets und Messaging
}); const email = { from: '[email protected]', to: '[email protected]', subject: 'Hello World', text: 'Hello World', html: 'Hello world', attachments: [ { filename: 'attachment.txt', content: 'Hello World' }, { path: attachmentPath } ] }; transporter.sendMail(email, (error, info) => { if (error) { console.error(error); } else { console.log('Message sent: %s', info.messageId); } }); Listing 9.38 E-Mail mit Anhängen versenden
9.11.2 Ausblick Neben dem Versenden von E-Mails stellt das Entwicklerteam hinter »nodemailer« auch einen SMTP-Server für das Empfangen von E-Mails bereit. Diese Funktionalität wird man zwar in der Regel nicht so häufig benötigen wie das Versenden von E-Mails, falls Sie aber trotzdem einmal vor dieser Aufgabe stehen, lohnt sich ein Blick auf die entsprechende Dokumentation unter https://nodemailer.com/extras/smtp-server/.
9.12 Zusammenfassung Mit den Rezepten aus diesem Kapitel sind Sie bestens gerüstet, um echtzeitfähige Applikationen in Node.js zu implementieren. In diesem Kapitel haben Sie gelernt, wie Sie
446
9.12 Zusammenfassung
왘 einen TCP-Server implementieren (Rezept 63), 왘 einen TCP-Client implementieren (Rezept 64), 왘 einen WebSocket-Server implementieren (Rezept 65), 왘 einen WebSocket-Client implementieren (Rezept 66), 왘 Nachrichtenformate für WebSocket-Kommunikation definieren (Rezept 67), 왘 Subprotokolle für WebSocket-Kommunikation definieren (Rezept 68), 왘 Server-Sent Events verwenden (Rezept 69), 왘 über AMQP auf RabbitMQ zugreifen (Rezept 70), 왘 einen MQTT-Broker erstellen (Rezept 71), 왘 über MQTT auf einen MQTT-Broker zugreifen (Rezept 72), 왘 E-Mails versenden (Rezept 73).
447
Kapitel 10 Testing und TypeScript In diesem Kapitel stelle ich Ihnen zwei Ansätze vor, mit deren Hilfe Sie Fehler im Code vermeiden. Über Unit-Tests sichern Sie Ihren Code durch automatisierte Tests ab. Mithilfe von TypeScript machen Sie Ihren Code typsicherer.
In diesem Kapitel möchte ich Ihnen verschiedene Rezepte vorstellen, die Ihnen dabei helfen, Ihren Code robuster gegen Fehler zu machen. Dies ist zum einen das automatisierte Testen von Node.js-Applikationen (Rezepte 74 bis 77) und zum anderen die Verwendung von TypeScript (Rezepte 78 und 79). 왘 Rezept 74: Unit-Tests schreiben 왘 Rezept 75: Unit-Tests automatisch neu ausführen 왘 Rezept 76: Die Testabdeckung ermitteln 왘 Rezept 77: Unit-Tests für REST-APIs implementieren 왘 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren 왘 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
10.1 Rezept 74: Unit-Tests schreiben Sie möchten einen Unit-Test erstellen, um die Funktionalität Ihrer Anwendung automatisiert testen zu können.
10.1.1 Exkurs: Unit-Tests und testgetriebene Entwicklung Wenn Sie professionell Software entwickeln, führt kein Weg daran vorbei, den Code automatisiert zu testen. Über sogenannte Unit-Tests (auch Modultests) stellen Sie sicher, dass der eigentliche Anwendungs-Code, den Sie programmieren, auch so funktioniert, wie Sie sich das vorstellen. Zugleich beugen Sie durch Unit-Tests vor, dass bei Änderungen am Anwendungs-Code (bspw. bei vermeintlichen Bug-Fixes) nicht versehentlich neue Bugs in den Code gelangen. Oft wird im Zusammenhang mit Unit-Tests auch der Begriff der testgetriebenen Entwicklung genannt (kurz TDD für Test Driven Development). Ihren Ursprung hat die
449
10
Testing und TypeScript
testgetriebene Entwicklung im sogenannten Extreme Programming, einer Methode der agilen Softwareentwicklung. Die grundlegende Idee von TDD ist es, bei der Entwicklung iterativ vorzugehen: Bevor Sie mit der Implementierung einer neuen Komponente beginnen, legen Sie zunächst über Unit-Tests die Anforderungen an diese Komponente fest. Dieses Vorgehen ist auch unter dem Begriff Red, Green, Refactor bekannt und besteht aus folgenden drei gleichnamigen Phasen (siehe auch Abbildung 10.1): 1. In der Red-Phase definiert man, was genau entwickelt bzw. welche Funktionalität einer Komponente entwickelt werden soll. Diese Anforderungen schreibt man in Form eines Unit-Tests nieder, der in dieser Phase zunächst fehlschlägt (den Namen hat diese Phase aufgrund der Tatsache, dass fehlschlagende Unit-Tests üblicherweise durch die Farbe Rot gekennzeichnet werden). 2. In der Green-Phase implementiert man nun die entsprechende Komponente, sodass sie die im Test definierten Anforderungen erfüllt und der Test nicht mehr fehlschlägt (nicht fehlschlagende Tests werden in der Regel mit der Farbe Grün gekennzeichnet, daher der Name dieser Phase). 3. In der Refactor-Phase hat man die Möglichkeit, die Implementierung der Komponente zu optimieren, gegebenenfalls unter Verwendung der Refactoring-Techniken, die Martin Fowler in seinem Buch »Refactoring: Improving the Design of Existing Code« beschreibt.
Test schreiben Red
Refactor
Green
Implementierung optimieren
Test schlägt fehl
Implementierung, Test besteht
sodass Test besteht
Abbildung 10.1 Workflow der testgetriebenen Entwicklung
450
10.1
Rezept 74: Unit-Tests schreiben
Hinweis Das Buch »Refactoring: Improving the Design of Existing Code« von Martin Fowler gilt als einer der Klassiker der Softwareliteratur. Interessante Randnotiz: Während die erste Ausgabe von 1999 die Refactoring-Techniken noch in Java beschreibt, setzt die zweite Ausgabe von 2018 vollständig auf JavaScript. Ein weiterer Beleg dafür, wie wichtig die Sprache JavaScript in den vergangenen Jahren geworden ist.
Ein einzelner Unit-Test wiederum ist aus einem oder mehreren Testfällen (Test Cases) aufgebaut. Testfälle können außerdem über sogenannte Test-Suites zusammengefasst werden. Innerhalb eines Test Cases formulieren Sie über sogenannte Assertions die Anforderungen an die zu implementierende Komponente. Hierüber können Sie bestimmte Aspekte prüfen, bspw., welches Ergebnis eine Funktion für gegebene Parameter zurückgeben soll. Genauer gesagt, bestehen einzelne Test Cases aus drei verschiedenen Phasen: der Arrange-Phase, der Act-Phase und der Assert-Phase (auf diese Phasen komme ich gleich in dem Praxisbeispiel noch mal zu sprechen).
Test-Frameworks für Node.js Für die Implementierung von Tests unter Node.js steht Ihnen eine ganze Reihe von Tools und Frameworks zur Verfügung. Zu den bekanntesten zählen »Jest« (https:// jestjs.io/), »mocha« (https://mochajs.org/) »Jasmine« (https://jasmine.github.io/), »node-tap« (http://www.node-tap.org/), AVA (https://github.com/avajs/ava) und »tape« (https://github.com/substack/tape). In der Praxis verwende ich persönlich in den meisten Fällen »Jest«, weil es zum einen sehr schnell ist und zum anderen auch Support für die Ermittlung der Testabdeckung mit sich bringt (siehe auch Rezept 76). Da ich außerdem frontendseitig hauptsächlich mit »React« arbeite (»React« und »Jest« werden beide von Facebook entwickelt), gehört »Jest« quasi sowieso zu meinem Werkzeugkasten.
10.1.2 Lösung: Unit-Test mit »Jest« schreiben Um »Jest« in Aktion zu sehen, legen Sie ein Beispielprojekt an, und installieren Sie das Package als Entwicklungsabhängigkeit: $ $ $ $
mkdir testing-example cd testing-example npm init -y npm i -D jest
Legen Sie außerdem ein separates Verzeichnis für die Testdateien an. Üblicherweise sollte sich das Verzeichnis auf gleicher Ebene wie das src-Verzeichnis befinden und den Namen test verwenden:
451
10
Testing und TypeScript
$ mkdir test $ mkdir src
Speicherort von Testdateien Bezüglich des Speicherorts von Testdateien sind vor allem zwei Ansätze populär. Der eine Ansatz sieht – wie oben beschrieben – vor, dass die Tests in einem separaten Verzeichnis gespeichert werden und dabei die Verzeichnisstruktur von dem entsprechenden Quelltextverzeichnis eingehalten wird. Ein Test für eine Datei ConnectionManager.js, die in dem Verzeichnis src/services/connection liegt, würde also in dem Verzeichnis test/services/connection gespeichert. Der zweite Ansatz dagegen sieht vor, die Testdateien in dem gleichen Verzeichnis wie die jeweils getestete Datei zu speichern. Im obigen Beispiel würde die Testdatei also in das Verzeichnis src/service/ connection gelegt.
Einen Test erstellen Wenn Sie so diszipliniert sind und strikt der testgetriebenen Entwicklung folgen, müssen Sie vor der Implementierung einer neuen Komponente den Unit-Test schreiben (zugegeben, auch ich mache das nicht immer). Wenn Sie also bspw. die Aufgabe haben, eine Klasse zu implementieren, über die Nutzer verwaltet werden können, könnte ein Unit-Test in »Jest« etwa wie in Listing 10.1 aussehen. const UserRepository = require('../src/UserRepository'); describe('UserRepository', () => { describe('#add()', () => { it('should add the user and increase the numer of all users', () => { const userRepository = new UserRepository(); userRepository.add({ name: 'Max' }); userRepository.add({ name: 'Moritz' }); expect(userRepository.getAll().length).toBe(2); }); it('should add the user only if it is not already there', () => { const userRepository = new UserRepository(); userRepository.add({ name: 'Max' }); userRepository.add({ name: 'Max' }); expect(userRepository.getAll().length).toBe(1); }); });
452
10.1
Rezept 74: Unit-Tests schreiben
describe('#clearAll()', () => { it('should clear all users', () => { const userRepository = new UserRepository(); userRepository.add({ name: 'Moritz' }); expect(userRepository.getAll().length).toBe(1); userRepository.clearAll(); expect(userRepository.getAll().length).toBe(0); }); }); }); Listing 10.1 Unit-Test in »Jest«
Über die von »Jest« zur Verfügung gestellte Funktion describe() können Sie zusammengehörige Tests sinnvoll zu Test Suites zusammenfassen (beim späteren Ausführen der Tests werden entsprechende Tests zusammen gruppiert und entsprechend eingerückt). Gruppierungen können dabei beliebig geschachtelt werden, was hilfreich ist, um eine gewisse Struktur in die definierten Tests zu bekommen. Einzelne Tests Cases dagegen definieren Sie über die Methode it(). Hierbei übergeben Sie eine entsprechende Beschreibung des Tests in Form einer Zeichenkette und den eigentlichen Test in Form einer Funktion. Prinzipiell bestehen Test Cases, wie eingangs erwähnt, aus drei Phasen, auch bezeichnet als Arrange, Act, Assert (kurz AAA). In der Arrange-Phase werden Initialisierungen durchgeführt und das Test-Setup aufgebaut, bspw.: it('should add the user and increase the numer of all users', () => { // 1.) Arrange-Phase const userRepository = new UserRepository(); // ... });
In der Act-Phase werden die zu testenden Methoden aufgerufen: it('should add the user and increase the numer of all users', () => { // ... // 2.) Act-Phase userRepository.add({ name: 'Max' }); userRepository.add({ name: 'Moritz' }); });
In der Assert-Phase wird schließlich das zu erwartende Ergebnis bzw. der zu erwartende Zustand überprüft:
453
10
Testing und TypeScript
it('should add the user and increase the numer of all users', () => { // ... // 3.) Assert-Phase expect(userRepository.getAll().length).toBe(2); });
Insgesamt werden auf diese Weise im Beispiel drei Tests definiert: 왘 Test 1: Die Klasse UserRepository soll über eine Methode add() verfügen, über die
Nutzerobjekte hinzugefügt werden können. Über die Methode getAll() soll eine Liste dieser Nutzer zurückgegeben werden. Fügt man über die Methode add() zwei Nutzerobjekte hinzu, soll getAll() genau diese Objekte als Liste zurückgeben. 왘 Test 2: Die Methode add() soll doppelte Nutzer ignorieren. Fügt man über die Me-
thode add() zweimal einen Nutzer mit gleichem Namen hinzu, soll die Liste anschließend nur einmal den Nutzer enthalten. 왘 Test 3: Über die Methode clearAll() soll es möglich sein, alle Nutzer aus dem Re-
pository zu löschen.
Tipp Lassen Sie zwischen den einzelnen Phasen Arrange, Act und Assert jeweils eine Leerzeile. Auf diese Weise können Sie beim späteren Durchsehen der Tests schneller zuordnen, welche Code-Zeile zu welcher Phase gehört.
Hinweis Übrigens müssen Sie »Jest«, wie Sie in Listing 10.1 sehen konnten, nicht explizit als Abhängigkeit über require() einbinden, um die Funktionen describe(), it() und expect() nutzen zu können. Beim Ausführen von »Jest« werden diese Bibliotheksfunktionen implizit geladen und stehen daher innerhalb des Tests zur Verfügung.
Speichern Sie den Test in einer Datei UserRepository.test.js in dem eben angelegten Verzeichnis test.
Einen Test ausführen Fügen Sie nun in das src-Verzeichnis die Klasse UserRepository als Datei UserRepository.js hinzu, und ergänzen Sie folgenden Code (die konkrete Implementierung der Klasse bleibt dabei zunächst noch bewusst leer): module.exports = class UserRepository {};
Um nun den oben erstellten Test mit »Jest« auszuführen, verwenden Sie folgenden Befehl (dazu muss »Jest« global installiert sein):
454
10.1
Rezept 74: Unit-Tests schreiben
$ jest -verbose
Oder alternativ – wenn Sie wie ich npx nutzen – folgenden Befehl: $ npx jest --verbose
Die Angabe --verbose sorgt dabei dafür, dass die Konsolenausgabe von »Jest« etwas umfangreicher ist und mehr Informationen zu den ausgeführten Tests liefert. Wie Sie anhand dieser Konsolenausgabe in Listing 10.2 sehen, schlagen momentan alle Tests fehl. Das ist nicht weiter verwunderlich, denn es gibt ja auch noch keine Implementierung der Klasse UserRepository bzw. keine Methode add(). Sie befinden sich also gerade in der Red-Phase. FAIL test/UserRepository.test.js UserRepository #add() × should add the user and increase the numer of all users (12ms) × should add the user only if it is not already there (1ms) #clearAll() × should clear all users (1ms) ● UserRepository › #add() › should add the user and increase the numer #of all users TypeError: userRepository.add is not a function 5 6 7 > 8 9 10 11 12
| | | | | | | |
it('should add the user and increase the numer of all users', () => { const userRepository = new UserRepository(); userRepository.add({ name: 'Max' }); userRepository.add({ name: 'Moritz' }); expect(userRepository.getAll().length).toBe(2); });
at Object.add (test/UserRepository.test.js:7:22) ... Test Suites: 1 failed, 1 total Tests: 3 failed, 3 total Snapshots: 0 total Time: 2.166s Ran all test suites. Listing 10.2 Ausgabe der fehlgeschlagenen Tests
455
10
Testing und TypeScript
Erweitern Sie daher – im Rahmen der Green-Phase – die Klasse UserRepository wie folgt um die Methoden add(), contains(), getAll() und clearAll() (die alle selbsterklärend sein dürften, weswegen ich auf eine detaillierte Beschreibung an dieser Stelle verzichte). module.exports = class UserRepository { constructor() { this.users = []; } add(user) { if (!this.contains(user)) { if (user && user.name) { this.users.push(user); } else { throw new Error('Wrong user format.'); } } } contains(newUser) { return this.users.filter((user) => user.name === newUser.name).length > 0; } getAll(user) { return this.users; } clearAll() { this.users = []; } }; Listing 10.3 Implementierung der »UserRepository«-Klasse
Führen Sie nun die Tests erneut aus, schlägt keiner der definierten Tests fehl: $ npx jest --verbose PASS test/UserRepository.test.js UserRepository #add() ✓ should add the user and increase the numer of all users (5ms) ✓ should add the user only if it is not already there (1ms)
456
10.1
Rezept 74: Unit-Tests schreiben
#clearAll() ✓ should clear all users (2ms) Test Suites: Tests: Snapshots: Time: Ran all test
1 passed, 1 total 3 passed, 3 total 0 total 1.785s suites.
Tipp Wenn Sie den Testbefehl unter dem Skript test in die package.json-Konfiguration übernehmen, lassen sich die Tests anschließend sowohl über npm run test als auch über die Kurzform npm test ausführen. { "name": "testing-example", "version": "1.0.0", "main": "./src/start.js", "scripts": { "test": "npx jest --verbose" }, "keywords": [ "javascript", "nodejs" ], "author": "Philip Ackermann", "license": "MIT", "devDependencies": { "jest": "^23.6.0" } }
10.1.3 Ausblick Sie haben jetzt in aller Kürze gesehen, welche Vorteile das Implementieren von UnitTests mit sich bringt und wie Sie Unit-Tests unter Node.js erstellen. Damit sind die Voraussetzungen für die nächsten beiden Rezepte geschaffen, in denen ich Ihnen zeige, wie Sie den Workflow rund um das Testen optimieren, indem Sie Tests während der Entwicklung automatisch neu ausführen (Rezept 75) und ermitteln, welche Stellen Ihres Applikations-Codes durch Tests abgedeckt werden und welche noch nicht (Rezept 76).
457
10
Testing und TypeScript
10.2 Rezept 75: Unit-Tests automatisch neu ausführen Sie möchten Ihre Unit-Tests automatisch ausführen, wenn sich entweder der getestete Applikations-Code oder die Tests selbst ändern.
10.2.1 Lösung In Rezept 29 haben Sie bereits gesehen, wie Sie Dateien und Verzeichnisse auf Änderungen überwachen können. Neben den dort genannten Anwendungsfällen wie dem automatischen Neustart von Entwicklungsservern oder dem Synchronisieren von Dateien und Verzeichnissen können Sie die beschriebenen Techniken natürlich auch dazu verwenden, um bei Änderungen am Quelltext die jeweiligen Unit-Tests neu auszuführen und auf diese Weise unmittelbares Feedback zu erhalten. Praktischerweise nimmt Ihnen das im vorherigen Rezept vorgestellte Test-Framework »Jest« diese Arbeit bereits ab und bietet von Haus aus schon eine entsprechende Möglichkeit an. Über den Parameter --watch nämlich lässt sich »Jest« im sogenannten Watch-Modus ausführen, sprich »Jest« beobachtet Änderungen sowohl an Testdateien als auch an den von einem Test eingebundenen Dateien und führt dann die von Änderungen betroffene Tests erneut aus. Fügen Sie also (ausgehend von dem Projekt aus dem vorherigen Rezept) der package. json-Datei das Skript test:watch mit dem Befehl npx jest --watch hinzu: { ... "scripts": { "test": "npx jest --verbose", "test:watch": "npx jest --watch" }, ... }
Starten Sie anschließend das Skript wie folgt: $ npm run test:watch
Jest führt dann zunächst einmal alle Tests aus und fragt Sie anschließend nach dem gewünschten Watch-Verhalten. Hier haben Sie die Wahl: Beispielsweise können Sie bei Änderungen an den Quelltextdateien alle Tests ausführen, nur die fehlgeschlagenen Tests ausführen oder nur die Tests, die einem bestimmten Muster des Dateioder Testnamens entsprechen: Watch Usage › Press a to run all tests. › Press f to run only failed tests.
458
10.3 Rezept 76: Die Testabdeckung ermitteln
› › › ›
Press Press Press Press
p to filter by a filename regex pattern. t to filter by a test name regex pattern. q to quit watch mode. Enter to trigger a test run.
Ändern Sie nun z. B. etwas an der Implementierung der UserRepository-Klasse (etwa den Inhalt der add()-Methode), werden die Tests direkt ausgeführt, und Sie können sofort sehen, ob durch die Änderungen bestimmte Tests fehlschlagen oder noch alles so funktioniert wie zuvor.
Hinweis Eigene npm-Skripts, zu denen npm keinen Shortcut anbietet, müssen Sie übrigens immer über den Unterbefehl run ausführen. Der Befehl npm test:watch kann von npm nicht aufgelöst werden und ist damit ungültig.
Tipp Wenn Sie mehrere inhaltlich verwandte npm-Skripts definieren möchten, gilt es als guter Stil, zusammengehörige Skripts mit einem gemeinsamen Präfix zu versehen, bspw. wie in den vorangegangenen Beispielen die Skripts test und test:watch.
10.2.2 Ausblick Sie wissen jetzt, wie Sie unter Node.js mithilfe von »Jest« Unit-Tests schreiben und Ihren Code dadurch absichern können, und Sie haben in diesem Rezept gesehen, wie Sie den Zyklus zwischen Implementieren einer Komponente und Ausführen eines Unit-Tests durch das Watch-Feature von »Jest« minimieren können. Doch wie können Sie ermitteln, welcher Code durch Tests überhaupt ausgeführt bzw. abgedeckt wird? Die Antwort darauf finden Sie im nächsten Rezept.
Verwandte Rezepte 왘 Rezept 29: Dateien und Verzeichnisse überwachen 왘 Rezept 76: Die Testabdeckung ermitteln 왘 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
10.3 Rezept 76: Die Testabdeckung ermitteln Sie möchten die Testabdeckung ermitteln, um festzustellen, welche Stellen Ihres Quelltextes durch automatisierte Tests ausgeführt werden und welche nicht.
459
10
Testing und TypeScript
10.3.1 Lösung Das bekannteste Tool für die Ermittlung der Testabdeckung (Code Coverage) unter Node.js ist Istanbul (https://istanbul.js.org/). Es kann in Kombination mit verschiedenen Test-Frameworks verwendet werden und ist praktischerweise bereits als fester Bestandteil in »Jest« enthalten, sodass Sie – vorausgesetzt Sie verwenden dieses in den vorherigen Rezepten vorgestellte Test-Framework – nichts zusätzlich installieren oder groß konfigurieren müssen. Die Testabdeckung können Sie mit »Jest«/Istanbul ermitteln, indem Sie dem jestBefehl den Parameter --coverage anhängen (als Ausgangspunkt verwenden Sie den Code aus den vorherigen beiden Rezepten). $ npx jest --coverage
»Jest« führt daraufhin die Tests wie gewohnt aus, instrumentiert intern aber auch den getesteten Anwendungs-Code und ermittelt dadurch, welche Zeilen des Codes durch die Tests ausgeführt werden.
Instrumentierung Unter dem Begriff Instrumentierung versteht man in der Softwareentwicklung das Hinzufügen von zusätzlichen Informationen zu bestehendem Quelltext. Um zu ermitteln, welche Code-Zeilen durch Unit-Tests ausgeführt werden, muss der Code durch das entsprechende Coverage-Tool zuvor entsprechend verändert, sprich instrumentiert werden.
Abbildung 10.2 zeigt die entsprechende tabellarische Ausgabe für die Beispieltests. Folgende Daten sind in dieser Tabelle enthalten: 왘 Name der im Rahmen des Testdurchlaufs aufgerufenen Quelltextdatei 왘 prozentuelle Angabe darüber, wie viele der in der jeweiligen Datei enthaltenen
Statements ausgeführt wurden 왘 prozentuelle Angabe darüber, wie viele der Code-Verzweigungen ausgeführt
wurden 왘 prozentuelle Angabe darüber, wie viele der Funktionen ausgeführt wurden 왘 prozentuelle Angabe darüber, wie viele Zeilen ausgeführt wurden 왘 prozentuelle Angabe darüber, wie viele Zeilen nicht ausgeführt wurden
Neben der tabellarischen Konsolenausgabe generiert »Jest« unter dem Verzeichnis coverage zusätzlich einen detaillierteren Report im HTML-Format. Dort finden Sie neben einer Übersicht auch detaillierte Informationen darüber, welche Code-Zeilen, Verzweigungen etc. durch die Tests abgedeckt und welche nicht abgedeckt sind (Abbildung 10.3).
460
10.3 Rezept 76: Die Testabdeckung ermitteln
Abbildung 10.2 Tabellarische Konsolenausgabe für die Testabdeckung
Abbildung 10.3 Detaillierte Informationen für die Testabdeckung einer einzelnen Quelltextdatei
461
10
Testing und TypeScript
Wie Sie Abbildung 10.3 entnehmen können, decken die bisherigen Tests die Zeile 11 der Klasse UserRepository nicht ab. Mit anderen Worten: Durch die Tests ist nicht sichergestellt, dass die Methode add() bei Hinzufügen eines Objekts ohne name-Eigenschaft einen Fehler ausgibt.
Die Testabdeckung verbessern Ergänzen Sie nun die Testdatei um den in Listing 10.4 gezeigten Unit-Test. Über die Methode toThrow() ermöglicht es »Jest« zu definieren, dass ein bestimmter Aufruf eine Exception liefern soll. Welcher Aufruf dies ist, definieren Sie über den Body einer anonymen Funktion, die Sie wiederum der Funktion expect() übergeben: expect (testFunction).toThrow(). Der Test sagt also: Wenn die Methode add() von UserRepository mit einem Objekt aufgerufen wird, das zwar über eine Eigenschaft firstName verfügt, aber nicht über eine Eigenschaft name, dann soll dieser Aufruf eine Exception liefern. const UserRepository = require('../src/UserRepository'); describe('UserRepository', () => { describe('#add()', () => { // ... it('should not allow objects with wrong user format', () => { const userRepository = new UserRepository(); expect(() => { userRepository.add( { firstName: 'Max' } ); }).toThrow(); }); }); // ... }); Listing 10.4 Unit-Test für das Testen von Exceptions
Rufen Sie nun den Befehl zur Ermittlung der Testabdeckung erneut auf, sollte diese bei 100 % liegen, weil durch den zusätzlichen Test auch der Teil des Codes aufgerufen wird, der vorher noch nicht abgedeckt war.
462
10.4
Rezept 77: Unit-Tests für REST-APIs implementieren
10.3.2 Ausblick Eine hohe Testabdeckung ist natürlich erstrebenswert, und eine Testabdeckung von 100 % sorgt für ein beruhigendes Gefühl. Allerdings sollten Sie sich immer die Frage stellen, welcher Code wirklich durch Tests automatisiert getestet und damit abgedeckt werden soll. Für einfache Getter- und Setter-Methoden bspw. müssen Sie nicht extra Unit-Tests schreiben.
Verwandte Rezepte 왘 Rezept 74: Unit-Tests schreiben 왘 Rezept 77: Unit-Tests für REST-APIs implementieren 왘 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
10.4 Rezept 77: Unit-Tests für REST-APIs implementieren Sie möchten einen Unit-Test erstellen, um die Funktionalität einer REST-API automatisiert testen zu können.
10.4.1 Lösung In Rezept 56 haben Sie gesehen, wie Sie unter Node.js eine REST-API erstellen können. In dem vorliegenden Rezept möchte ich Ihnen nun zeigen, wie Sie für diese REST-API Unit-Tests erstellen können. Prinzipiell können Sie die in Rezept 57 vorgestellten Tools für das Testen von RESTAPIs bzw. zum Testen von HTTP im Allgemeinen verwenden. Nur eine von vielen Möglichkeiten: das »superagent«-Package (https://www.npmjs.com/package/superagent) innerhalb eines Unit-Tests mit »Jest« integrieren, innerhalb eines Tests eine HTTP-Anfrage stellen und im entsprechenden Callback die HTTP-Antwort überprüfen. Ein Tool, das ich trotzdem noch zusätzlich in meinem Werkzeugkasten habe, sowohl für das Testen von REST-APIs als auch für das Testen von »Express«-Anwendungen und HTTP-Anfragen im Allgemeinen, ist »supertest« (https://www.npmjs.com/ package/supertest). Es basiert auf dem Package »superagent« und erweitert dieses um eine zusätzliche Abstraktionsschicht, die viele nützliche Helferfunktionen rund um das Testen von HTTP-Kommunikation anbietet. Es ist unabhängig von dem tatsächlich verwendeten Test-Framework und kann problemlos in »Jest« oder »mocha« integriert werden.
463
10
Testing und TypeScript
Vorbereitungen und Installation Ausgehend von dem Code für die REST-API aus Rezept 56, möchte ich Ihnen im Folgenden die Integration in »Jest« und die prinzipielle Verwendung von »superagent« zeigen. Machen Sie sich daher am besten eine Kopie des Projekts aus Rezept 56 (oder laden Sie sich einfach den Quelltext für das aktuelle Rezept herunter), und installieren Sie in dem entsprechenden Projekt zunächst »superagent« als Test-Abhängigkeit: $ npm i -D supertest
Ergänzen Sie außerdem in der package.json-Datei ein Skript für das Ausführen der Tests: ... "scripts": { "start": "node ./src/start.js", "test": "npx jest --verbose" }, ...
Tipp Natürlich können Sie auch für Tests von REST-APIs die Testabdeckung ermitteln, wie Sie es in Rezept 76 gesehen haben. Fügen Sie dazu einfach den Parameter --coverage an oben genannten Befehl an, oder erstellen Sie ein separates, entsprechend benanntes npm-Skript (bspw. test:coverage).
Anlegen eines Unit-Tests Dateien, die Unit-Tests enthalten, sollten Sie, wie eingangs in dem Kapitel erwähnt, auf gleicher Ebene wie das src-Verzeichnis in ein Verzeichnis mit dem Namen test legen. Erzeugen Sie also dieses Verzeichnis, und erstellen Sie eine Datei ContactAPI.test.js mit dem folgenden Inhalt: const supertest = require('supertest'); const app = require('../src/start'); describe('Contact API', () => { describe('GET /api/v1/contacts', () => { it('should respond with JSON', (done) => { // (1) Arrange-Phase supertest(app)
464
10.4
Rezept 77: Unit-Tests für REST-APIs implementieren
// (2) Act-Phase .get('/api/v1/contacts') // (3) Assert-Phase .expect('Content-Type', /json/) .expect(200) .end((error, response) => { if (error) { throw error; } done(); }); }); }); }); Listing 10.5 Unit-Test für das Testen einer HTTP-Anfrage
Den geschachtelten Teil mit den Aufrufen von describe() und it(), die beide über das Test-Framework »Jest« bereitgestellt werden, kennen Sie schon aus Rezept 74. Entscheidend sind an dieser Stelle der Teil innerhalb des it()-Callbacks und die Importe zu Beginn des Skripts. Das Package »supertest« (bzw. die von dort exportierte Funktion) binden Sie unter dem Namen supertest ein. Der Funktion können Sie praktischerweise die Objektinstanz übergeben, die Ihre »Express«-Anwendung enthält. Anschließend können Sie mit der von »supertest« angebotenen Fluent API den genauen Testablauf definieren (die drei Phasen Arrange, Act und Assert sind durch die Fluent API nicht so leicht zu unterscheiden, weswegen ich der Übersichtlichkeit halber entsprechende Kommentare eingefügt habe). Der Aufruf get('/api/v1/contacts') sorgt für eine GET-Anfrage an den API-Endpoint »/api/v1/contacts«. Die einzelnen Assertions definieren Sie anschließend über die Methode expect() (übrigens nicht zu verwechseln mit der gleichnamigen Funktion von »Jest«). Über diese Methode können Sie die gebräuchlichsten Aspekte bezüglich der HTTP-Antworten testen, bspw. Header, Status-Codes etc. (siehe Tabelle 10.1). In Listing 10.5 wird auf diese Weise überprüft, dass der »Content-Type«-Header der HTTP-Antwort den Wert »json« enthält und der Status-Code den Wert 200 hat. Über die Methode end() haben Sie zudem die Möglichkeit, Fehler, die während des Überprüfens einer Assertion auftreten, abzufangen bzw. gesondert darauf zu reagieren. Im Beispiel leiten Sie – falls ein Fehler vorhanden ist – diesen einfach weiter, was dazu führt, dass »Jest« entsprechend den Test mit einem Fehler abbricht. Für den Fall,
465
10
Testing und TypeScript
dass kein Fehler auftritt, müssen Sie den done()-Callback von »Jest« aufrufen, um den Test normal zu beenden.
Hinweis Verwenden Sie dagegen keinen Aufruf von end(), wird bei einem Fehlschlagen einer Assertion der entsprechende Fehler direkt an »Jest« weitergeleitet. Der Inhalt des it()-Callbacks würde dann wie folgt aussehen: supertest(app) .get('/api/v1/contacts') .expect('Content-Type', /json/) .expect(200, done);
Am flexibelsten können Sie testen, indem Sie der Methode expect() eine CallbackFunktion übergeben, die dann mit dem vollständigen Response-Objekt aufgerufen wird. Ein Beispiel dazu zeigt Listing 10.6: Hier wird ebenfalls der Endpoint »/api/1/ contacts« getestet, allerdings dieses Mal der Body der HTTP-Antwort dahingehend überprüft, dass die Kontaktliste zwei Einträge enthält (nur um Verwirrung zu vermeiden: diese Überprüfung wiederum wird mit der expect()-Funktion von »Jest« durchgeführt). const supertest = require('supertest'); const app = require('../src/start'); describe('Contact API', () => { describe('GET /api/v1/contacts', () => { /* ... */ it('should get a list of all contacts', (done) => { supertest(app) .get('/api/v1/contacts') .expect((response) => { expect(response.body.length).toBe(2); }) .expect(200, done); }); }); }); Listing 10.6 Testen einer HTTP-Antwort mit eigener Callback-Funktion
466
10.4
Rezept 77: Unit-Tests für REST-APIs implementieren
Methode
Beschreibung
expect(status[, fn])
Testen des Status-Codes einer HTTPAntwort.
expect(status, body[, fn])
Testen des Status-Codes und des Bodys einer HTTP-Antwort.
expect(body[, fn])
Testen des Bodys einer HTTP-Antwort gegen einen String, einen regulären Ausdruck oder ein JSON-Objekt.
expect(field, value[, fn])
Testen eines HTTP-Headers einer HTTPAntwort gegen einen String oder einen regulären Ausdruck.
expect(assertionFunction(response))
Testen einer HTTP-Antwort mit eigener Testfunktion, die als Parameter die vollständige HTTP-Antwort erhält.
Tabelle 10.1 Die wichtigsten Test-Methoden von »supertest«
10.4.2 Ausblick »Jest« in Kombination mit »supertest« liefert Ihnen ein mächtiges Werkzeug für das Testen von HTTP-Kommunikation, sei es in Bezug auf REST-APIs wie in diesem Rezept oder in Bezug auf normale Websites, bspw.um die Struktur des zurückgegebenen HTML-Codes zu testen. In diesem Rezept haben wir lediglich GET-Anfragen formuliert, aber natürlich können Sie mit »supertest« auch die anderen Arten von HTTP-Anfragen stellen. Wie wäre es z. B. mit einem Unit-Test, der sicherstellt, dass neue Kontakte über POST-Anfragen korrekt angelegt werden? Dazu müssten Sie im Test Folgendes durchführen: 왘 die Anzahl der aktuellen Kontakte ermitteln (GET-Anfrage) 왘 einen neuen Kontakt anlegen (POST-Anfrage) 왘 erneut die Anzahl der aktuellen Kontakte ermitteln und sicherstellen, dass sich die
Anzahl entsprechend erhöht hat (GET-Anfrage) Eine beispielhafte Implementierung hierzu sehen Sie in Listing 10.7. Hier sehen Sie auch direkt einen weiteren Vorteil von »supertest«. Es funktioniert auch mit Promises, sodass sich das Formulieren der drei genannten HTTP-Anfragen auch vom Code her übersichtlich durch async/await anordnen lässt.
467
10
Testing und TypeScript
const supertest = require('supertest'); const app = require('../src/start'); describe('Contact API', () => { /* ... */ describe('POST /api/v1/contacts', () => { it('should increase the number of all contacts', async (done) => { const testApp = supertest(app); // Anzahl der aktuellen Kontakte ermitteln const response = await testApp.get('/api/v1/contacts'); expect(response.body.length).toBe(2); // Neuen Kontakt anlegen await testApp.post('/api/v1/contacts').send({ id: '3', firstName: 'Peter', lastName: 'Mustermann' }); // Anzahl der Kontakte ermitteln und prüfen const response2 = await testApp.get('/api/v1/contacts'); expect(response2.body.length).toBe(3); done(); }); }); }); Listing 10.7 Unit-Test für eine POST-Anfrage
Verwandte Rezepte 왘 Rezept 74: Unit-Tests schreiben 왘 Rezept 75: Unit-Tests automatisch neu ausführen 왘 Rezept 76: Die Testabdeckung ermitteln
10.5 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren Sie möchten eine Node.js-Applikation mit TypeScript entwickeln, um in die Vorzüge zu kommen, die diese Sprache gegenüber JavaScript bietet.
468
10.5 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren
10.5.1 Lösung Wenn Sie mit JavaScript entwickeln, werden Sie früher oder später auch über die von Microsoft entwickelte Programmiersprache TypeScript stolpern, die mehr oder weniger eine Erweiterung von JavaScript darstellt, dieses um viele sinnvolle Features erweitert und bereits viele Vorschläge zu zukünftigen ECMAScript-Standards implementiert. Auch wenn mittlerweile einige Sprachkonstrukteure wie die Klassensyntax oder die Modulsyntax bereits in JavaScript übernommen wurden, bietet TypeScript noch deutlich mehr Features, die man in JavaScript bislang vergeblich sucht. Ein ganz wesentlicher Vorteil von TypeScript gegenüber JavaScript bspw. ist die statische Typüberprüfung während der Kompilierung. Bevor TypeScript nämlich überhaupt ausgeführt werden kann, muss es zunächst in JavaScript kompiliert werden (Abbildung 10.4). Während dieses Kompilierungsschritts überprüft der TypeScriptCompiler die in der Applikation verwendeten Typen und meldet bereits zu diesem Zeitpunkt Typfehler, die bei normalem JavaScript eventuell erst zur Laufzeit der Applikation gefunden würden.
TypeScript
TypeScriptCompiler
JavaScript
Abbildung 10.4 TypeScript wird durch einen Compiler in JavaScript übersetzt.
Den Schritt des Kompilierens von TypeScript zu JavaScript können Sie zwar explizit durchführen, mittlerweile gibt es aber auch entsprechende Tools, die das Kompilieren automatisch im Hintergrund durchführen, sodass Sie sich somit komplett auf die Entwicklung Ihrer Applikation konzentrieren können.
Hinweis Auf der Homepage von TypeScript finden Sie unter https://www.typescriptlang.org/ samples/ einige Beispielapplikationen, in denen TypScript zum Einsatz kommt. So lässt sich TypeScript sowohl auf Client-Seite als auch auf Server-Seite verwenden, bspw. um »React«-Anwendungen, »Angular«-Anwendungen und auch »Express«Anwendungen zu erstellen.
Projekt vorbereiten Um TypeScript in Aktion zu sehen, legen Sie sich zunächst wie gewohnt ein neues Beispielprojekt an: $ mkdir typescript-app $ cd typescript-app $ npm init -y
469
10
Testing und TypeScript
Installieren Sie anschließend das Package »typescript« (https://www.npmjs.com/ package/typescript), das u. a. den TypeScript-Compiler enthält und benötigt wird, um TypeScript-Dateien in JavaScript übersetzen zu können: $ npm i -D typescript
Ergänzen Sie nun die Datei package.json um das in Listing 10.8 gezeigte npm-Skript, das mithilfe von npx den TypeScript-Compiler ausführt und auf die Dateien in dem aktuellen Verzeichnis anwendet. { "name": "recipe-01", "version": "1.0.0", "description": "", "scripts": { "build": "npx tsc -p ." }, "keywords": [], "author": "Philip Ackermann ", "license": "MIT", "devDependencies": { "typescript": "^3.2.1", "ts-node": "^7.0.1" } } Listing 10.8 »package.json«-Datei mit angepassten npm-Skripts
Als Nächstes benötigen Sie eine Konfigurationsdatei tsconfig.json, die Sie entweder von Hand anlegen oder mit folgendem Befehl generieren können: $ npx tsc \ --init \ --rootDir src \ --outDir lib \ --esModuleInterop \ --resolveJsonModule \ --lib es6,dom \ --module commonjs
Den Inhalt der generierten Konfigurationsdatei finden Sie in Listing 10.9, wobei ich der Übersichtlichkeit wegen die generierten Kommentare entfernt habe und als target den Wert »es5« durch »es2017« ersetzt habe (Details zu den einzelnen Optionen finden Sie unter https://www.typescriptlang.org/docs/handbook/compileroptions.html).
470
10.5 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren
{ "compilerOptions": { /* Basic Options */ "target": "es2017", "module": "commonjs", "lib": ["es6","dom"], // "allowJs": true, // "checkJs": true, // "jsx": "preserve", // "declaration": true, // "declarationMap": true, // "sourceMap": true, // "outFile": "./", "outDir": "lib", "rootDir": "src", // "composite": true, // "removeComments": true, // "noEmit": true, // "importHelpers": true, // "downlevelIteration": true, // "isolatedModules": true, /* Strict Type-Checking Options */ "strict": true, // "noImplicitAny": true, // "strictNullChecks": true, // "strictFunctionTypes": true, // "strictBindCallApply": true, // "strictPropertyInitialization": true, // "noImplicitThis": true, // "alwaysStrict": true, /* // // // //
Additional Checks */ "noUnusedLocals": true, "noUnusedParameters": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true,
/* // // // //
Module Resolution Options */ "moduleResolution": "node", "baseUrl": "./", "paths": {}, "rootDirs": [],
471
10
Testing und TypeScript
// "typeRoots": [], // "types": [], // "allowSyntheticDefaultImports": true, "esModuleInterop": true, // "preserveSymlinks": true, /* // // // //
Source Map Options */ "sourceRoot": "", "mapRoot": "", "inlineSourceMap": true, "inlineSources": true,
/* Experimental Options */ // "experimentalDecorators": true, // "emitDecoratorMetadata": true, /* Advanced Options */ "resolveJsonModule": true } } Listing 10.9 Generierte »tsconfig.json«-Datei
JavaScript zu TypeScript migrieren In dem vorliegenden Rezept haben wir den Vorteil der Greenfield-Entwicklung, also der Entwicklung auf grüner Wiese. Das heißt, wir starten mit einem frischen Projekt. So lernen Sie anhand eines einfachen Beispiels, wie Sie TypeScript konkret für ein Projekt einrichten. Möchten Sie dagegen ein bestehendes JavaScript-Projekt zu TypeScript migrieren, finden Sie unter https://www.typescriptlang.org/docs/handbook/ migrating-from-javascript.html zusätzliche Tipps für das entsprechende Vorgehen.
Den Quelltext vorbereiten TypeScript-Dateien haben üblicherweise die Dateiendung .ts. Innerhalb dieser Dateien können Sie sowohl TypeScript als auch JavaScript verwenden (zumal TypeScript ja eine Obermenge von JavaScript ist). Legen Sie also im Ordner src die fünf Dateien Food.ts, Animal.ts, Dog.ts, index.ts und start.ts an, und kopieren Sie den Inhalt aus Listing 10.10 in die entsprechend benannten Dateien.
472
10.5 Rezept 78: Eine Node.js-Applikation in TypeScript implementieren
Wie Sie anhand des Quelltextes sehen, unterstützt TypeScript bereits die Modulsyntax von ES2015, stellt darüber hinaus das Konzept von Interfaces bereit (Schlüsselwort interface) und erlaubt (bspw. bei der Definition von Parametern) die Angabe von Typinformationen. Die Methode eat() des Interfaces Animal z. B. kann nur mit einem Parameter vom Typ Food aufgerufen werden. Wird der Methode etwas anderes übergeben, erkennt der
TypeScript-Compiler dies als Fehler und bricht das Kompilieren mit einer entsprechenden Fehlermeldung ab. // src/Food.ts export class Food { } // src/Animal.ts import { Food } from './Food'; export interface Animal { eat(food: Food): void; } // src/Dog.ts import { Animal } from './Animal'; export class Dog implements Animal { // bewusst leergelassen } // src/index.ts export * from './Animal'; export * from './Dog'; export * from './Food'; // src/start.ts import { Dog, Food } from '.'; const dog = new Dog(); dog.eat(new Food()); Listing 10.10 Einfaches Beispiel in TypeScript
473
10
Testing und TypeScript
Tipp Als ersten Schritt für die Migrierung einer JavaScript-Code-Basis hin zu TypeScript bietet es sich an, einfach alle .js-Dateien in entsprechende .ts-Dateien umzubenennen. Anschließend können Sie TypeScript-spezifische Features wie Interfaces und Typinformationen Schritt für Schritt einführen.
TypeScript zu JavaScript kompilieren Wenn Sie nun den Kompiliervorgang über npm run build (bzw. npx tsc -p .) starten, sollte der Compiler einen Fehler melden, und zwar aufgrund der Tatsache, dass die Klasse Dog das Interface Animal wegen fehlender eat()-Methode nicht korrekt implementiert: $ npm run build tsc -p . src/Dog.ts:3:14 - error TS2420: Class 'Dog' incorrectly implements interface 'Animal'. Property 'eat' is missing in type 'Dog' but required in type 'Animal'. 3 export class Dog implements Animal { ~~~ src/Animal.ts:4:3 4 eat(food: Food): void; ~~~~~~~~~~~~~~~~~~~~~~ 'eat' is declared here. Found 1 error.
Ergänzen Sie daher die Klasse Dog wie folgt um die Methode eat(), und kompilieren Sie den Code erneut: import { Animal } from './Animal'; import { Food } from './Food'; export class Dog implements Animal { eat(food: Food) { console.log('Dog eats food') } }
Der Kompiliervorgang sollte nun erfolgreich sein und für jede der fünf TypeScriptDateien eine entsprechende JavaScript-Datei in den Ordner lib generieren.
474
10.6
Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
Die kompilierte Anwendung können Sie mit folgendem Befehl aufrufen: $ node lib/start.js Dog eats food
10.5.2 Ausblick Neben den in diesem Rezept genannten Features wie Typisierung und Interfaces bietet TypeScript gegenüber JavaScript noch einige interessante weitere Features. Dazu zählen abstrakte Klassen, Generics, das Überladen von Methoden, Zugriffsmodifikatoren für Methoden und vieles andere mehr. Auf diese Features kann ich an dieser Stelle aus Platzgründen jedoch nicht näher eingehen. Wenn Sie sich dennoch zu diesem Thema weiter informieren möchten, empfehle ich Ihnen das auf der offiziellen Website von TypeScript angebotene »TypeScript Handbook« unter https://www.typescriptlang.org/docs/home.html.
Verwandte Rezepte 왘 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
10.6 Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren Sie möchten wissen, wie Sie eine Node.js-Applikation automatisch neu starten, wenn sich der dazugehörige Quelltext geändert hat, und dies bspw. dazu einsetzen, in TypeScript-basierten Applikationen den TypeScript-Code bei Änderungen automatisch in JavaScript zu kompilieren.
10.6.1 Lösung Das automatische Neustarten einer Node.js-Applikation kann in vielen Fällen hilfreich sein, besonders während der Entwicklung, bspw. um die Applikation automatisch bei Änderungen an den entsprechenden Quelltextdateien neu zu starten. Ein Tool, das ich Ihnen in diesem Zusammenhang empfehle, ist das Tool »nodemon« (https://github.com/remy/nodemon/).
Installation und Verwendung Installieren können Sie das Tool als globales Package mithilfe des folgenden Befehls: $ npm install -g nodemon
475
10
Testing und TypeScript
Anschließend steht global der Befehl nodemon zur Verfügung, den Sie beim Starten einer Applikation einfach anstatt des node-Befehls verwenden. Statt eine Applikation also wie folgt zu starten: $ node app.js
starten Sie die Applikation über folgenden Befehl: $ nodemon app.js
TypeScript-Dateien direkt ausführen Im Zusammenhang mit der TypeScript-Entwicklung ist das Package »nodemon« insofern hilfreich, als dass es bei Änderungen nicht nur eine Applikation neu starten, sondern auch die entsprechenden TypeScript-Dateien automatisch neu kompilieren kann. Verwenden Sie für die folgenden Schritte als Basis das Projekt aus dem vorherigen Rezept. Installieren Sie außerdem das Package »ts-node« (https://www.npmjs.com/ package/ts-node), mit dessen Hilfe es möglich ist, eine TypeScript-Applikation direkt unter Node.js auszuführen. Das Package kompiliert unter Verwendung des TypeScript-Compilers den Code einer Applikation, bevor sie mit Node.js ausgeführt wird. So sparen Sie sich den Schritt der manuellen Kompilierung. Testen Sie den Befehl wie folgt, was dazu führen sollte, dass intern der Code der Applikation (ausgehend von der Datei start.ts) kompiliert und anschließend die kompilierten JavaScript-Dateien ausgeführt werden: $ npx ts-node src/start.ts Dog eats food
TypeScript-Dateien automatisch kompilieren Um nun die TypeScript-Applikation so auszuführen, dass sie bei Änderungen am Quelltext neu gestartet wird, rufen Sie den oben gezeigten Befehl einfach in Kombination mit »nodemon« auf. »nodemon« registriert dann Änderungen an den TypeScript-Dateien, und »ts-node« sorgt dafür, dass die Dateien entsprechend kompiliert werden und die Applikation neu gestartet wird: $ npx nodemon --exec ts-node src/start.ts [nodemon] 1.18.7 [nodemon] to restart at any time, enter rs [nodemon] watching: *.* [nodemon] starting ts-node src/start.ts Dog eats food [nodemon] clean exit - waiting for changes before restart
476
10.6
Rezept 79: TypeScript-basierte Applikationen automatisch neu kompilieren
// Änderung an "src/start.ts" durch Hinzufügen // einer weiteren Codezeile "dog.eat(new Food());" [nodemon] restarting due to changes... [nodemon] starting ts-node src/start.ts Dog eats food Dog eats food [nodemon] clean exit - waiting for changes before restart
Weitere Konfigurationsmöglichkeiten Über verschiedene Parameter lässt sich das Verhalten von »nodemon« genauer konfigurieren (Tabelle 10.2). Folgender Befehl bspw. würde dafür sorgen, dass nur das Verzeichnis app beobachtet wird (--watch), dabei nur TypeScript-Dateien berücksichtigt werden (--ext), bei Änderungen der TypeScript-Compiler ausgeführt wird (--exec), Testdateien ignoriert werden (--ignore), bei Änderungen fünf Sekunden gewartet wird (--delay) und die Datei src/start.ts gestartet wird. $ nodemon \ --watch app \ --ext ts \ --exec ts-node \ --ignore '*.test.ts' \ --delay 5 \ src/start.ts
Parameter
Beschreibung
--delay
Standardmäßig wartet »nodemon« eine Sekunde, bis die entsprechende Applikation neu gestartet wird. Über diesen Parameter ist es möglich, diesen Zeitraum zu verändern.
--exec
Erlaubt die Angabe einer ausführbaren Datei, die bei Änderungen an der beobachteten Datei mit dieser Datei als Parameter ausgeführt wird. Eignet sich bspw. dazu, um beim Beobachten von TypeScript-Dateien diese bei Änderungen automatisch durch den TypeScript-Compiler in JavaScript übersetzen zu lassen.
--ext
Für den Fall, dass man mehrere Dateien oder ganze Verzeichnisse von Dateien überwacht, dabei aber nicht alle Dateitypen beobachten möchte, können über diesen Parameter explizit Dateitypen (in Form der entsprechenden Dateiendung) angegeben werden, die beobachtet werden sollen.
Tabelle 10.2 Parameter von »nodemon«
477
10
Testing und TypeScript
Parameter
Beschreibung
--ignore
Über diesen Parameter können explizit Dateitypen angegeben werden, die ignoriert werden sollen.
--verbose
Aktiviert eine etwas ausführlicherer Ausgabe, das heißt, »nodemon« liefert bspw. Ausgaben dazu, welche Datei sich geändert hat etc.
--watch
Standardmäßig überwacht »nodemon« das aktuelle Verzeichnis und dessen Unterverzeichnisse. Über diesen Parameter können Verzeichnisse explizit angegeben werden.
Tabelle 10.2 Parameter von »nodemon« (Forts.)
Alternativ zu den genannten Kommandozeilenparametern können Sie die Konfiguration von »nodemon« auch über eine Konfigurationsdatei nodemon.json definieren, die Sie in das entsprechende Verzeichnis legen. Die analoge Konfiguration zu dem eben gezeigten Befehl sähe bspw. wie folgt aus: { "watch": ["start"], "ext": "ts", "ignore": ["*.test.ts"], "delay": "5", "execMap": { "ts": "ts-node" } }
Darüber hinaus können Sie die Konfiguration auch über die Datei package.json vornehmen, indem Sie die Eigenschaft nodemonConfig ergänzen. Das dieser Eigenschaft hinterlegte Objekt hat dabei den gleichen Aufbau wie in der Konfigurationsdatei eben: { "name": "example-nodemon", "version": "1.0.0", "description": "", "nodemonConfig": { "watch": [ "start" ], "ext": "ts", "ignore": [ "*.test.ts"
478
10.7
Zusammenfassung
], "delay": "5", "execMap": { "ts": "ts-node" } }, ... }
10.6.2 Ausblick Das Package »nodemon« bietet Ihnen eine flexible Möglichkeit, Node.js-Applikationen bei Änderungen am Quelltext automatisch neu zu starten. Insbesondere der Workflow bei der Entwicklung von TypeScript-basierten Node.js-Applikationen kann dadurch enorm beschleunigt werden, weil Sie nicht immer manuell den TypeScriptCode erst kompilieren und dann die kompilierte Applikation (ebenfalls manuell) neu starten müssen.
Verwandte Rezepte 왘 Rezept 29: Dateien und Verzeichnisse überwachen 왘 Rezept 75: Unit-Tests automatisch neu ausführen
10.7 Zusammenfassung In diesem Kapitel haben Sie gesehen, wie Sie unter Node.js Unit-Tests erstellen und wie Sie Node.js-Packages und Node.js-Applikationen unter Verwendung von TypeScript implementieren können. Damit haben Sie zwei wichtige Grundsteine für die Entwicklung stabiler Node.js-Applikationen kennengelernt. Zusammenfassend wissen Sie jetzt, wie Sie 왘 Unit-Tests schreiben (Rezept 74), 왘 Unit-Tests automatisch neu ausführen (Rezept 75), 왘 die Testabdeckung ermitteln (Rezept 76), 왘 einen Unit-Test für REST-APIs schreiben (Rezept 77) 왘 eine Node.js-Applikation in TypeScript implementieren (Rezept 78), 왘 TypeScript-basierte Applikationen automatisch neu kompilieren (Rezept 79).
479
Kapitel 11 Skalierung, Performance und Sicherheit Wie lassen sich Node.js-Applikationen skalieren? Wie lassen sich Performanceprobleme erkennen und die Performance verbessern? Und was ist bezüglich der Sicherheit von Node.js-Applikationen zu beachten? Antworten auf diese Fragen liefere ich Ihnen in diesem Kapitel.
Im Folgenden möchte ich Ihnen zeigen, wie Sie Node.js-Anwendungen skalieren und die Performance verbessern können, wie Sie CPU- und Speicherprobleme identifizieren und welche Aspekte bezüglich der Sicherheit von Node.js-Anwendungen zu beachten sind. Konkret schauen wir uns dabei Folgendes an: 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten 왘 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen 왘 Rezept 83: Eine Node.js-Anwendung clustern 왘 Rezept 84: Unterprozesse über einen Prozessmanager verwalten 왘 Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch
ermitteln 왘 Rezept 86: Speicherprobleme identifizieren 왘 Rezept 87: CPU-Probleme identifizieren 왘 Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen 왘 Rezept 89: JavaScript dynamisch laden und ausführen
481
11
Skalierung, Performance und Sicherheit
11.1 Rezept 80: Externe Anwendungen als Unterprozess ausführen Sie möchten externe Anwendungen als Unterprozess ausführen.
11.1.1 Exkurs: Multithreading vs. Multiprocessing Unter Node.js ist es nicht möglich, innerhalb eines einzelnen Prozesses mehrere Threads zu verwenden: Multithreading, wie es bspw. in Java möglich ist, sieht die Architektur von Node.js nicht vor (zumindest noch nicht als Stable-Feature, denn seit Node.js 10 gibt es mit Worker Threads ein experimentelles Feature, das genau das möglich macht). Zwar werden intern asynchrone I/O-Operationen auf verschiedene Threads verteilt, die Event-Loop jedoch, die für die Abarbeitung von JavaScript-Events zuständig ist, läuft innerhalb eines einzelnen Threads (Abbildung 11.1). Single-Threaded JavaScript
C++ Threads
Event Queue Event Loop
Thread Pool
Events Callback
Abbildung 11.1 Threads in Node.js
Statt über Multithreading kann Parallelisierung in Node.js daher (Stand: Juli 2019) nur über Multiprocessing erreicht werden, also das Auslagern von einzelnen Aufgaben in separate Unterprozesse bzw. Kindprozesse. Der Unterschied zwischen Multithreading und Multiprocessing: Bei Ersterem teilen sich die einzelnen Threads die Ressourcen des Prozesses, in dem sie laufen, bei Letzterem hat jeder Prozess (und damit jeder Thread) seine eigenen Ressourcen (Abbildung 11.2).
482
11.1 Rezept 80: Externe Anwendungen als Unterprozess ausführen
Single-Threaded Process Code
Daten
Stack
Register
Thread
Multi-Threaded Process Code
Daten
Register
Register
Register
Stack
Stack
Stack
Thread
Thread
Thread
Abbildung 11.2 Mutlithreading vs. Multiprocessing
11.1.2 Lösung Für das Multiprocessing stehen Ihnen über das »child_process«-Package der Node.jsStandard-API verschiedene Möglichkeiten zur Verfügung. Am einfachsten arbeiten die Funktionen exec() bzw. execFile(): Erstere erlaubt es, beliebige Kommandozeilenbefehle in einem separaten Unterprozess auszuführen, letztere führt den Inhalt einer Datei in einem Unterprozess aus. Ein einfaches Beispiel für die Verwendung der exec()-Funktion zeigt Listing 11.1, in dem über den Befehl docker ps die aktuell gestarteten Docker-Container aufgelistet werden (Voraussetzung hierfür ist natürlich, dass auf dem Rechner, auf dem Sie dieses Programm ausführen, Docker installiert ist und der Befehl docker in der Kommandozeile zur Verfügung steht). Alternativ können Sie natürlich auch einen anderen Befehl ausführen, bspw. für das Auflisten von Dateien in einem Verzeichnis (das wäre unter Linux und macOS der Befehl ls und unter Windows der Befehl dir). Der eigentliche Befehl wird der Funktion exec() dabei als erster Parameter übergeben, als zweiten Parameter übergeben Sie eine Callback-Funktion, die ihrerseits mit drei Parametern aufgerufen wird, sobald der Unterprozess beendet wurde: error enthält im Fall eines Fehlers das entsprechende Fehlerobjekt, stdout einen Buffer, der den Inhalt der Standardausgabe des Unterprozesses enthält, und stderr einen weiteren Buffer, der analog die Standardfehlerausgabe des Unterprozesses enthält (Abbildung 11.3).
483
11
Skalierung, Performance und Sicherheit
const { exec } = require('child_process'); const cmd = 'docker ps'; exec(cmd, (error, stdout, stderr) => { if (error) { throw error; } console.log(stdout); }); Listing 11.1 Aufruf eines Unterprozesses über »exec()«
exec()
Shell Commands
Callback
Buffer stdout stderr Callback
Abbildung 11.3 Funktionsweise der Methode »exec()«
Listing 11.2 erreicht das Gleiche wie der Code aus Listing 11.1, verwendet dabei aber die Funktion execFile(), um den Inhalt der Datei input.sh auszuführen (Abbildung 11.4). const { execFile } = require('child_process'); execFile('./input.sh', (error, stdout, stderr) => { if (error) { throw error; }
484
11.1 Rezept 80: Externe Anwendungen als Unterprozess ausführen
console.log(stdout); }); Listing 11.2 Aufruf eines Unterprozesses über »execFile()«
execFile()
Externe Anwendung Callback
stdout (Buffer) stderr (Buffer) Callback
Abbildung 11.4 Funktionsweise der Methode »execFile()«
11.1.3 Ausblick Die Funktionen exec() und execFile() eignen sich immer dann, wenn Sie ein Programm als Unterprozess aufrufen möchten, das eine überschaubar große Ausgabe liefert. Da in beiden Fällen die Ausgabe des Unterprozesses über einen Buffer an den Elternprozess geleitet wird (der naturgemäß eine endliche Größe im Speicher hat), eignen sich beide Funktionen nicht dafür, wenn das aufgerufene Programm kontinuierlich Daten ausgibt. In solchen Fällen greifen Sie daher besser zu der im nächsten Rezept vorgestellten Technik.
Verwandte Rezepte 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten 왘 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen 왘 Rezept 83: Eine Node.js-Anwendung clustern
485
11
Skalierung, Performance und Sicherheit
11.2 Rezept 81: Externe Anwendungen als Stream verarbeiten Sie möchten externe Anwendungen als Stream verarbeiten.
11.2.1 Lösung Neben exec() und execFile() stellt das »child_process«-Package noch die Funktion spawn() zur Verfügung. Anders als die beiden erstgenannten verwendet spawn() keinen Buffer, um vom Unterprozess Daten an den Elternprozess weiterzuleiten, sondern stellt für die Kommunikation zwischen den Prozessen die Ein- und Ausgabe des Unterprozesses jeweils als Stream bereit (Abbildung 11.5).
spawn() Externe Anwendung
ChildProcess stdout (Stream) stderr (Stream) Callback
Abbildung 11.5 Funktionsweise der Methode »spawn()«
Im Gegensatz zu den Buffern bei exec() und execFile(), die erst nach Abschluss des jeweils ausgeführten Unterprozesses an den Elternprozess zurückgesendet werden, stehen die Streams bzw. die in den jeweiligen Stream geschriebenen Daten mehr oder weniger unverzüglich zur Laufzeit des Unterprozesses bereit und lassen sich innerhalb des Elternprozesses sofort weiterverarbeiten. Ein noch entscheidenderer Vorteil ist aber, dass bei der Verwendung von spawn() dank der zugrunde liegenden Streams beliebig große Daten übertragen werden können, während bei exec() und execFile() die maximale Größe der zu übertragenden Daten durch die Größe des Buffers begrenzt ist.
486
11.2
Rezept 81: Externe Anwendungen als Stream verarbeiten
Dazu drei Beispiele: In Listing 11.3 sehen Sie die Implementierung einer Utility-Funktion download(), die eine URL als Zeichenkette akzeptiert und mithilfe der Funktion spawn() das Kommandozeilentool curl für den eigentlichen Download verwendet. Der Funktion spawn() übergibt man als ersten Parameter den auszuführenden Befehl und optional als zweiten Parameter ein Array mit den Werten, die dem jeweiligen Befehl als Argumente übergeben werden sollen (im Beispiel also die URL). Zugriff auf die Ausgabe haben Sie über die Eigenschaft stdout des von spawn() zurückgegebenen ChildProcess-Objekts in Form eines Readable Streams. Wird auf diesem Stream nun das »data«-Event ausgelöst, werden im Beispiel die jeweiligen Daten einfach in den zuvor erzeugten Writable Stream weitergeleitet und auf diese Weise nach und nach in die dahinterliegende Datei geschrieben (Gleiches könnte man über Piping noch etwas schlanker und eleganter machen, aber das spare ich mir für das dritte Beispiel auf). const fs = require('fs'); const path = require('path'); const { spawn } = require('child_process'); const DOWNLOAD_DIR = path.join(__dirname, 'downloads'); const download = (url) => { const fileName = url.parse(url).pathname.split('/').pop(); const file = fs.createWriteStream(DOWNLOAD_DIR + fileName); const curl = spawn('curl', [url]); curl.stdout.on('data',(data) => file.write(data)); curl.stdout.on('end', (data) => { file.end(); console.log(`${fileName} downloaded to ${DOWNLOAD_DIR}`); }); curl.on('exit', (code) => { if (code === 0) { console.log('Download successful'); } else { console.log(`Download failed: ${code}`); } }); }; Listing 11.3 Aufruf des Befehls »curl« über »spawn()«
Das zweite Beispiel sehen Sie in Listing 11.4. Hier wird das Kommandozeilentool tail aufgerufen, über das es möglich ist, Änderungen an Dateien zu überwachen. Dabei können einzelne Dateien, aber auch mehrere Dateien überwacht werden, und es ist
487
11
Skalierung, Performance und Sicherheit
sogar möglich, Muster wie bspw. access_*.log anzugeben, um alle Dateien zu überwachen, die diesem Muster entsprechen. Das Tool ist zwar nicht so mächtig wie das in Rezept 29 vorgestellte Package »chokidar«, weil es – einmal gestartet – neu hinzukommende Dateien, die auf ein Muster zutreffen, nicht beachtet. Dafür ist das Tool extrem schnell und arbeitet sehr zuverlässig, sodass es je nach Anwendungsfall durchaus eine interessante Alternative für die Einbindung in eine Node.js-Applikation darstellt. Der in Listing 11.4 verwendete Befehl tail -F -n 1 access.log sorgt dafür, dass bei Änderungen an der Datei access.log jeweils die letzte Zeile ausgegeben wird. const { spawn } = require('child_process'); const tail = spawn('tail', ['-F', '-n', '1', 'access.log']); tail.stdout.on('data', (data) => { data = data.toString(); console.log(data); }); tail.stderr.on('data', (data) => { console.error(`Error:\n${data}`); }); Listing 11.4 Aufruf des Befehls »tail« über »spawn()«
Das dritte Beispiel in Listing 11.5 zeigt, wie einfach das Arbeiten mit spawn() sein kann: Mithilfe der Methode pipe(), die Stream-Objekten zur Verfügung steht (siehe auch Rezept 32), lassen sich nämlich mehrere durch spawn() gestartete Unterprozesse hintereinanderschalten, und zwar, indem der Ausgabe-Stream eines Unterprozesses an den Eingabe-Stream eines anderen Unterprozesses weitergeleitet wird. Im Beispiel wird auf diese Weise für die Kommandozeilenbefehle cat (Ausgabe von Dateiinhalten), sort (Sortierung von Zeilen) und uniq (Filtern von doppelten Zeilen) zunächst jeweils ein eigener Unterprozess erzeugt. Anschließend wird die Ausgabe von cat als Eingabe von sort verwendet und die Ausgabe von sort als Eingabe von uniq. const { spawn } = require('child_process'); const cat = spawn('cat', ['someData.csv']); const sort = spawn('sort'); const uniq = spawn('uniq'); // Ausgabe des Dateiinhalts cat.stdout.pipe(sort.stdin);
488
11.3
Rezept 82: Node.js-Applikationen als Unterprozess aufrufen
// Sortieren der Zeilen sort.stdout.pipe(uniq.stdin); // Filtern doppelter Zeilen uniq.stdout.pipe(process.stdout); Listing 11.5 Hintereinanderschalten von Unterprozessen über »spawn()« und »pipe()«
11.2.2 Ausblick Die Funktion spawn() sollten Sie beim Aufruf von Programmen als Unterprozesse immer dann in Betracht ziehen, wenn das aufgerufene Programm entweder eine sehr große Ausgabe liefert oder die Größe der Ausgabe nicht vorhersehbar ist, aber auch in solchen Fällen, in denen das Programm kontinuierlich eine Ausgabe erzeugt (und damit letztendlich auch eine unvorhersehbar große Ausgabe erzeugt). Im nächsten Rezept zeige ich Ihnen, wie Sie Node.js-Applikationen als Unterprozess aufrufen.
Verwandte Rezepte 왘 Rezept 29: Dateien und Verzeichnisse überwachen 왘 Rezept 30: Daten mit Streams lesen 왘 Rezept 31: Daten mit Streams schreiben 왘 Rezept 32: Mehrere Streams über Piping kombinieren 왘 Rezept 33: Eigene Streams implementieren 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen 왘 Rezept 83: Eine Node.js-Anwendung clustern
11.3 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen Sie möchten eine Node.js-Applikation als Unterprozess aufrufen.
11.3.1 Lösung Die letzte der Helfermethoden im »child_process«-Package ist die Funktion fork(), die einen Sonderfall der im vorherigen Rezept vorgestellten Funktion spawn() darstellt: Sie kann dazu verwendet werden, neue Node.js-Unterprozesse zu erstellen. Wie auch spawn() liefert die Funktion dabei ein Objekt vom Typ ChildProcess. Wesentlicher Unterschied dabei ist, dass dieses Objekt nun noch einen Kommunikationskanal zur Verfügung stellt, mit dessen Hilfe zwischen Unterprozess und Eltern-
489
11
Skalierung, Performance und Sicherheit
prozess über IPC (Inter-Process Communication) kommuniziert werden kann (Abbildung 11.6).
fork()
Node.js Anwendung
ChildProcess stdout (Stream) stderr (Stream) Callback IPC Channel
Abbildung 11.6 Funktionsweise der Methode »fork()«
So ist es innerhalb eines Unterprozesses möglich, über process.on('message') Nachrichten vom Elternprozess zu empfangen und über process.send() Nachrichten an den Elternprozess zu versenden. Umgekehrt ist es im Elternprozess über die gleichen Methoden (aufgerufen auf der jeweiligen ChildProcess-Instanz) möglich, Nachrichten von einem Unterprozess zu empfangen bzw. Nachrichten an einen Unterprozess zu versenden. Ein einfaches Beispiel hierfür zeigt Listing 11.6. Zu sehen ist hier der Quelltext aus zwei Dateien: Die Datei parent.js enthält den Quelltext für den Elternprozess, die Datei child.js den Quelltext für den Unterprozess. Der Funktion fork() übergeben Sie den Pfad zu der JavaScript-Datei, die als Unterprozess aufgerufen werden soll. Optional können Sie dabei – in Listing 11.6 nicht gemacht – als zweiten Parameter die Argumente in Form eines Arrays übergeben, die an den Unterprozess übergeben werden sollen sowie als dritten Parameter ein Konfigurationsobjekt, über das sich bspw. das Arbeitsverzeichnis für den Unterprozess und die Umgebungsvariablen vorkonfigurieren lassen. // parent.js const { fork } = require('child_process');
490
11.3
Rezept 82: Node.js-Applikationen als Unterprozess aufrufen
const forked = fork('child.js'); forked.on('message', (message) => { console.log('Message from child', message); }); forked.send({ hello: 'world' }); // child.js process.on('message', (message) => { console.log('Message from parent:', message); }); process.send({ hello: 'world' }); Listing 11.6 Aufruf einer Node.js-Applikation über »fork()«
Über den Kommunikationskanal, der zwischen Elternprozess und Unterprozess besteht, können Daten relativ einfach in beide Richtungen ausgetauscht werden. Besonders praktisch ist dabei, dass Sie direkt Objekte versenden können, ohne diese manuell aufseiten des Senders über JSON.stringify() als Zeichenkette zu serialisieren und aufseiten des Empfängers wieder über JSON.parse() in ein Objekt umzuwandeln.
Praxisbeispiel Im Folgenden möchte ich Ihnen noch ein praxisnäheres Beispiel für den Einsatz der Funktion fork() geben. In Listing 11.7 sehen Sie zunächst ein Negativbeispiel für einen Webserver, der noch ohne die Funktion fork() implementiert ist. Wenn Sie diesen Code starten, können Sie über die Route http://localhost:3000/sum die Funktion sum() anstoßen, welche die Summe der Zahlen 0 bis n berechnet, wobei n als Query-Parameter übergeben werden kann. Der Aufruf http://localhost:3000/sum?n= 2000 bspw. berechnet die Summe der Zahlen 0 bis 2.000. Problematisch wird das Ganze, wenn Sie für n eine sehr große Zahl einsetzen (bspw. 200.000.000.000) und eine entsprechende Anfrage an den Webserver senden. Da der Aufruf den Haupt-Thread blockiert, kann der Webserver während der Berechnung keine weiteren Anfragen entgegennehmen. Wenn Sie versuchen, in einem anderen Browser-Fenster die Anfrage http://localhost:3000/sum?n=2000 auszuführen, werden Sie feststellen, dass der Webserver die Anfrage nicht direkt bearbeiten kann, sondern erst, wenn die zuvor für den größeren Wert des Parameters n gestellte Anfrage abgearbeitet wurde.
491
11
Skalierung, Performance und Sicherheit
const http = require('http'); const url = require('url'); const sum = (n) => { let sum = 0; for (let i = 0; i < n; i++) { sum += i; } return sum; }; const server = http.createServer(); server.on('request', (request, response) => { const parts = url.parse(request.url, true); if (parts.pathname === '/sum') { const query = parts.query; const n = parseInt(query.n); const result = sum(n); return response.end(`Result is ${result}`); } else { response.end('ok'); } }); server.listen(3000); Listing 11.7 Negativbeispiel: die lange Berechnung blockiert den Haupt-Thread.
Daran ändert sich auch nichts, wenn die Funktion wie in Listing 11.8 asynchron implementiert wird. Auch hier ist der Haupt-Thread während der Berechnung blockiert und kann keine weiteren Anfragen bearbeiten. const http = require('http'); const url = require('url'); const server = http.createServer(); const sum = async (n) => { return new Promise((resolve, reject) => { let sum = 0; for (let i = 0; i < n; i++) {
492
11.3
Rezept 82: Node.js-Applikationen als Unterprozess aufrufen
sum += i; } resolve(sum); }); }; server.on('request', (request, response) => { const parts = url.parse(request.url, true); if (parts.pathname === '/sum') { const query = parts.query; const n = parseInt(query.n); sum(n).then((result) => { response.end(`Sum is ${result}`); }); } else { response.end('ok'); } }); server.listen(3000); Listing 11.8 Negativbeispiel: die lange Berechnung blockiert auch im asynchronen Modus den Haupt-Thread
Um dem Problem entgegenzuwirken, bietet es sich an, die Funktion sum() in ein separates Skript auszulagern (Listing 11.9) und im Hauptprogramm über die Funktion fork() aufzurufen (Listing 11.10). Nach dem Aufruf wird der Parameter n (im Elternprozess) in Form einer JSON-Nachricht an den Unterprozess gesendet (alternativ könnte man ihn auch direkt dem Aufruf von fork() übergeben) und innerhalb des Unterprozesses damit die Funktion sum() aufgerufen. Steht das Ergebnis fest, wird umgekehrt eine Nachricht vom Unterprozess an den Elternprozess gesendet und dort dann die HTTP-Anfrage an den entsprechenden Client zurückgeschickt. Wenn Sie diesen Code ausführen und, wie oben beschrieben, eine Anfrage mit einem sehr großen Wert des Parameters n an den Webserver stellen und parallel dazu eine weitere Anfrage in einem separaten Browser-Fenster stellen (mit einem kleineren Wert des Parameters n), können Sie sehen, dass die zweite Anfrage parallel bearbeitet wird und die Antwort vom Webserver schneller zurückkommt. const sum = (n) => { let sum = 0; for (let i = 0; i < n; i++) { sum += i; }
493
11
Skalierung, Performance und Sicherheit
return sum; }; process.on('message', (message) => { const result = sum(message.n); process.send(result); }); Listing 11.9 Die komplexe Berechnung wird in den Unterprozess ausgelagert. const http = require('http'); const url = require('url'); const { fork } = require('child_process'); const server = http.createServer(); server.on('request', (request, response) => { const parts = url.parse(request.url, true); if (parts.pathname === '/sum') { const query = parts.query; const n = parseInt(query.n); const sum = fork('sum.js'); sum.send({ n }); sum.on('message', (result) => { response.end(`Sum is ${result}`); }); } else { response.end('ok'); } }); server.listen(3000); Listing 11.10 Die komplexe Berechnung wird vom Elternprozess delegiert.
Hinweis Das in den Beispielen verwendete Package »url« ist übrigens Bestandteil der Node.jsAPI (https://nodejs.org/api/url.html) und stellt einige nützliche Utility-Funktionen rund um das Arbeiten mit URLs zur Verfügung.
494
11.4
Rezept 83: Eine Node.js-Anwendung clustern
11.3.2 Ausblick In diesem und den beiden vorherigen Rezepten haben Sie gesehen, welche Möglichkeiten Sie in Node.js haben, Unterprozesse aufzurufen. Zusammenfassend lassen sich exec() und execFile() eher für solche Anwendungsfälle verwenden, in denen eine Ausgabe von festem (bzw. nicht zu großem) Umfang erwartet wird, etwa für Statusmeldungen oder die Auflistung begrenzter Datentabellen. Die Funktion spawn() eignet sich dagegen eher für das Ausführen von Kommandos, bei denen der Umfang der Ausgabe nicht feststeht bzw. stark variieren kann, etwa beim Verarbeiten von Dateien, beim Download von Dateien etc. Die in diesem Rezept vorgestellte Funktion fork() ist die beste Wahl, wenn Sie aus einer Node.js-Applikation eine andere Node.jsApplikation aufrufen möchten. Folgende Tabelle fasst die wichtigsten Unterschiede kurz zusammen: Methode
Beschreibung
execFile()
Ausführen einer externen Anwendung; Ausgabe als Buffer über Callback beim Beenden des Prozesses.
exec()
Ausführen einer externen Anwendung innerhalb einer Shell; Ausgabe als Buffer über Callback beim Beenden des Prozesses.
spawn()
Ausführen einer externen Anwendung; Ein- und Ausgabe als Stream während der Ausführung sowie Events beim Beenden des Prozesses.
fork()
Ausführen einer Node.js-Anwendung; Ein- und Ausgabe als Stream während der Ausführung sowie Events beim Beenden des Prozesses, zusätzlich IPC zwischen Elternprozess und Unterprozessen.
Tabelle 11.1 Methoden für das Multiprocessing in Node.js
Verwandte Rezepte 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten 왘 Rezept 83: Eine Node.js-Anwendung clustern
11.4 Rezept 83: Eine Node.js-Anwendung clustern Sie möchten eine Node.js-Anwendung in einem Cluster betreiben.
495
11
Skalierung, Performance und Sicherheit
11.4.1 Lösung Im vorherigen Rezept habe ich Ihnen gezeigt, wie Sie Node.js-Applikationen als Unterprozesse aufrufen können, und Sie haben anhand eines Beispiels gesehen, wie darüber verhindert werden kann, dass komplexe Berechnungen den Haupt-Thread blockieren. Dabei haben Sie die Funktion fork() aus dem »child_process«-Package verwendet, um den jeweiligen Unterprozess zu erstellen, und mithilfe von InterProcess Communication die Kommunikation zwischen dem Elternprozess und dem Unterprozess gesteuert. In diesem Rezept möchte ich Ihnen nun zeigen, wie Sie das Erstellen und Verwalten von Node.js-Unterprozessen mithilfe des »cluster«-Packages vereinfachen können. Das Package baut auf dem »child_process«-Package auf und stellt einige Utilitys zur Verfügung und ermöglicht es, ein kleines »Netzwerk« von Unterprozessen zu erstellen. Die Kommunikation zwischen dem Elternprozess (in diesem Kontext auch: Masterprozess) und Unterprozessen (in diesem Kontext: Workern) geschieht wie bei der Verwendung von fork() über Inter-Process Communication.
Praxisbeispiel Ein klassisches Beispiel für die Verwendung des »cluster«-Packages in Node.js ist das Betreiben eines Webservers im Cluster-Modus. Rufen Sie sich dafür kurz den Code für einen einfachen Webserver in Erinnerung (Rezept 54), der unter Verwendung des »http«-Moduls wie folgt implementiert werden könnte: const http = require('http'); http .createServer((request, response) => { console.log(`Worker ${process.pid} handle request`); const content = 'Hallo Welt'; response.writeHead(200, { 'Content-Length': content.length, 'Content-Type': 'text/plain' }); response.end(content); }) .listen(3000); Listing 11.11 Webserver in Single-Modus
Der Code ist relativ einfach: Der Server läuft unter dem Port 3000 und antwortet auf alle Anfragen mit einem knappen »Hello World«, wobei er jeweils eine kurze Mel-
496
11.4
Rezept 83: Eine Node.js-Anwendung clustern
dung inklusive der Prozess-ID des aktuellen Prozesses auf die Konsole schreibt. Wenn Sie nun (bspw. mit HTTPie oder einem anderen HTTP-Client) Anfragen an http://localhost:3000 stellen, werden Sie in der Kommandozeilenausgabe sehen, dass immer der gleiche Prozess die Anfrage entgegennimmt und bearbeitet: $ node start-single.js Process 21139 handle request Process 21139 handle request Process 21139 handle request Process 21139 handle request Process 21139 handle request
Höchstwahrscheinlich werden Sie den HTTP-Client von Hand nicht so schnell hintereinander ausführen können, dass selbst dieser kleine einprozessige Webserver ins Schwitzen kommt (es sei denn, Sie schreiben sich hierfür ein kleines Shell-Skript). Aber man kann sich leicht ausmalen, wie sich das Ganze für produktive Webserver verhält, bei denen mehrere Tausend Anfragen gleichzeitig eingehen.
Hinweis Einige Tools, die Ihnen helfen können, solche Szenarien lokal zu simulieren, sind JMeter (http://jmeter.apache.org/), Gatling (https://gatling.io/) oder das in Node.js geschriebene Artillery (https://artillery.io). Über diese Tools können Sie komplexe Lasttests und Performancetests für Webserver bzw. Webservices konfigurieren und durchführen.
Zum Glück ist es unter Node.js dank des »cluster«-Packages relativ einfach, den oben gezeigten Webserver im Cluster zu betreiben, sodass alle verfügbaren Prozessorkerne verwendet und HTTP-Anfragen auf mehrere Worker verteilt werden (Stichwort: Lastverteilung bzw. Load Balancing). Den entsprechenden Code dazu zeigt Listing 11.12. Über cluster.isMaster lässt sich innerhalb der Anwendung ermitteln, ob der Code vom Masterprozess ausgeführt wird. Ist dies der Fall, wird für jeden zur Verfügung stehenden Prozessor (numCPUs) über cluster.fork() ein neuer Worker erstellt (nicht zu verwechseln mit der gleichnamigen Funktion aus dem »child_process«-Package). Für jeden dieser Worker wird das Skript ebenfalls aufgerufen, dabei aber – weil cluster.isMaster nicht erfüllt ist – nicht der Teil innerhalb des if-Blocks, sondern der Teil innerhalb des else-Blocks ausgeführt, in dem im Wesentlichen der gleiche Code wie in Listing 11.11 verwendet wird. Lediglich die Konsolenausgabe wurde etwas angepasst, um zu veranschaulichen, dass die Anfragen von verschiedenen Workern abgearbeitet werden. Hervorzuheben ist, dass – obwohl jeder Worker denselben Port verwendet – es zu keinen Port-Konflikten kommt. Der Grund, warum das funktioniert: In Wirklichkeit
497
11
Skalierung, Performance und Sicherheit
hört nur der Masterprozess auf den angegebenen Port und verteilt intern die Anfragen an die einzelnen Worker. Dabei spielt es keine Rolle, wie viele Prozessorkerne zur Verfügung stehen bzw. wie viele Worker erzeugt werden: Alle Worker teilen sich eine TCP-Verbindung und nehmen unabhängig voneinander die weitergeleiteten HTTPAnfragen vom Masterprozess entgegen. const cluster = require('cluster'); const http = require('http'); const numCPUs = require('os').cpus().length; if (cluster.isMaster) { for (let i = 0; i < numCPUs; i++) { console.log(`Worker ${i + 1} started`); cluster.fork(); } cluster.on('exit', (worker, code, signal) => { console.log(`Worker ${worker.process.pid} died`); }); } else { // Einzelne Worker teilen sich eine TCP-Verbindung http .createServer((request, response) => { console.log(`Worker ${cluster.worker.id} (${process.pid}) handle request`); const content = 'Hallo Welt'; response.writeHead(200, { 'Content-Length': content.length, 'Content-Type': 'text/plain' }); response.end(content); }) .listen(3000); } Listing 11.12 Webserver im Cluster-Modus
Wenn Sie das Programm aus Listing 11.12 starten und anschließend wieder einige HTTP-Anfragen an http://localhost:3000 abschicken, sehen Sie in der Konsolenausgabe des Servers, dass die einzelnen Anfragen von verschiedenen Workern (bzw. verschiedenen Unterprozessen) abgearbeitet werden: $ node Worker Worker Worker Worker
498
start-cluster.js 1 started 2 started 3 started 4 started
11.5 Rezept 84: Unterprozesse über einen Prozessmanager verwalten
Worker Worker Worker Worker Worker Worker Worker Worker Worker Worker Worker Worker Worker Worker Worker
1 2 4 3 1 2 4 3 1 2 4 3 1 2 4
(21189) (21190) (21192) (21191) (21189) (21190) (21192) (21191) (21189) (21190) (21192) (21191) (21189) (21190) (21192)
handle handle handle handle handle handle handle handle handle handle handle handle handle handle handle
request request request request request request request request request request request request request request request
11.4.2 Ausblick Das Package »cluster« nimmt Ihnen einiges an Arbeit ab, wenn es darum geht, Anfragen bzw. Berechnungen auf verschiedene Unterprozesse zu verteilen. Insbesondere wenn Sie, wie in dem gezeigten Beispiel, einen Webserver implementieren, sollten Sie sich die zur Verfügung stehenden Prozessorkerne zunutze machen, um die Reaktionsfähigkeit des Webservers zu verbessern.
Verwandte Rezepte 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten 왘 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen 왘 Rezept 84: Unterprozesse über einen Prozessmanager verwalten
11.5 Rezept 84: Unterprozesse über einen Prozessmanager verwalten Sie möchten Unterprozesse über einen Prozessmanager verwalten, um bspw. beim Absturz eines Unterprozesses diesen automatisch neu zu starten.
11.5.1 Lösung Mithilfe des im vorherigen Rezept vorgestellten »cluster«-Packages können Sie bereits ein einfaches Load Balancing innerhalb von Node.js realisieren. Doch was pas-
499
11
Skalierung, Performance und Sicherheit
siert, wenn einer der Worker abstürzt? Für solche Fälle sollten Sie Maßnahmen treffen. Kurzum: Prozesse sollten automatisch neu gestartet werden. Ein Tool, das Ihnen hierbei helfen kann, ist der Prozessmanager PM2 (http://pm2.keymetrics.io/). Listing 11.13 zeigt das Beispiel aus dem vorherigen Rezept mit einer kleinen Anpassung: Sobald ein Unterprozess eine HTTP-Anfrage bearbeitet, beendet er sich über process.exit(1) selbst und simuliert damit einen Absturz. const cluster = require('cluster'); const http = require('http'); const numCPUs = require('os').cpus().length; if (cluster.isMaster) { for (let i = 0; i < numCPUs; i++) { console.log(`Worker ${i + 1} started`); cluster.fork(); } cluster.on('exit', (worker, code, signal) => { console.log(`Worker ${worker.process.pid} died`); }); } else { // Einzelne Worker teilen sich eine TCP-Verbindung http .createServer((request, response) => { console.log(`Worker ${cluster.worker.id} handled request`); const content = 'Hallo Welt'; response.writeHead(200, { 'Content-Length': content.length, 'Content-Type': 'text/plain' }); response.end(content); // Simulierter Absturz process.exit(1); }) .listen(3000); } Listing 11.13 Simulierter Absturz eines Workers
Rufen Sie diese Anwendung auf, und stellen Sie dann mehrere Anfragen an den Webserver, lautet die Ausgabe der Anwendung in etwa wie folgt: Worker 1 started Worker 2 started Worker 3 started
500
11.5 Rezept 84: Unterprozesse über einen Prozessmanager verwalten
Worker Worker Worker Worker Worker Worker Worker Worker Worker
4 started 1 handled request 91188 died 2 handled request 91189 died 4 handled request 91191 died 3 handled request 91190 died
Je nach Anzahl der vorhandenen Prozessorkerne wird die Applikation irgendwann komplett beendet, ohne dass einzelne Unterprozesse wieder neu gestartet werden. Genau bei dieser Problematik hilft PM2: Es erkennt, wenn ein Unterprozess beendet wurde, und startet dann einen entsprechenden neuen Unterprozess. Dadurch ist gewährleistet, dass die entsprechende Applikation reaktionsfähig bleibt.
Installation und Verwendung Installieren lässt sich PM2 über folgenden Befehl: $ npm install pm2 -g
Anschließend steht Ihnen das Tool über den Befehl pm2 zur Verfügung. Um bspw. die Anwendung (gespeichert als Datei start.js) von eben im Cluster-Modus mit vier Prozessorkernen zu starten, reicht folgender Befehl: $ pm2 start start.js -i 4
Wenn Sie nun HTTP-Anfragen an den Webserver absenden und einer der Worker »abstürzt«, bemerkt PM2 diesen Absturz und startet den entsprechenden Prozess neu. $ pm2 start start.js -i 4 [PM2] Starting /Users/philipackermann/workspace/nodejskochbuch/cluster/ start.js in cluster_mode (4 instances) [PM2] Done. ┌────────────┬─────────┬────────┬───┬─────┬───────────┐ │ Name │ mode │ status │ ↺ │ cpu │ memory │ ├────────────┼─────────┼────────┼───┼─────┼───────────┤ │ start │ cluster │ online │ 0 │ 19% │ 29.0 MB │ │ start │ cluster │ online │ 0 │ 34% │ 28.9 MB │ │ start │ cluster │ online │ 0 │ 47% │ 28.6 MB │ │ start │ cluster │ online │ 0 │ 33% │ 21.1 MB │ └────────────┴─────────┴────────┴───┴─────┴───────────┘ Use pm2 show to get more details about an app
501
11
Skalierung, Performance und Sicherheit
Analog zu dem Starten von Applikationen steht für das Stoppen ebendieser der Befehl pm2 stop zur Verfügung. Als Argument übergeben Sie diesem Befehl entweder die ID, die PM2 der Applikation beim Starten vergeben hat, oder den Namen der Anwendung, bspw. pm2 stop 0 oder pm2 stop start.js. Das Ausführen der Applikation wird dadurch abgebrochen, die Applikation selbst aber weiterhin von PM2 verwaltet. Möchten Sie dagegen erreichen, dass die Applikation nicht nur gestoppt, sondern auch nicht mehr von PM2 verwaltet wird, verwenden Sie den Befehl pm2 delete. Um eine Anwendung neu zu starten, können Sie den Befehl pm2 restart verwenden. In beiden Fällen übergeben Sie als Argument wieder entweder die ID oder den Namen der neu zu startenden Applikation. Detaillierte Informationen zu dem Status einer Applikation lassen sich über die Befehle pm2 show und pm2 describe ermitteln, eine Übersicht über den jeweiligen Status aller Applikationen über den Befehl pm2 list. Über den Befehl pm2 logs können Sie sich zudem die Logs anzeigen zu lassen. Anschließend werden die Konsolenausgaben aller mit PM2 verwalteten Applikationen (entsprechend unterschiedlich gekennzeichnet) in Echtzeit auf die Konsole ausgegeben. Eine Übersicht über diese Befehle sowie eine Auswahl weiterer Befehle für PM2 finden Sie in folgender Tabelle. Befehl
Beschreibung
Fork-Modus pm2 start
Starten einer Applikation.
pm2 start --name
Starten einer Applikation mit individuellem Namen.
pm2 start --watch
Starten einer Applikation und Neustart bei Änderungen am Quelltext.
Cluster-Modus pm2 start -i 0
Starten von Applikationen basierend auf der Anzahl der zur Verfügung stehenden CPUs.
pm2 start -i
Starten einer bestimmten Menge von Instanzen einer Applikation.
Tabelle 11.2 Übersicht über wichtige PM2-Befehle
502
11.5 Rezept 84: Unterprozesse über einen Prozessmanager verwalten
Befehl
Beschreibung
Übersicht und Monitoring pm2 list
Auflisten aller Prozesse inklusive des jeweiligen Status.
pm2 jlist
Wie pm2 list, nur dass die Ergebnisse im JSON- Format ausgegeben werden.
pm2 prettylist
Wie pm2 jlist, nur dass die Ergebnisse in formatiertem JSON ausgegeben werden.
pm2 show
Zeigt alle Informationen über einen bestimmten Prozess an.
pm2 monit
Starten des Monitorings für alle Prozesse.
Logs pm2 logs
Ausgabe der Logs aller von PM2 verwalteten Applikationen.
pm2 flush
Leeren aller Logs.
Weitere Aktionen pm2 stop all
Stoppt alle Prozesse.
pm2 restart all
Startet alle Prozesse neu.
pm2 reload all
Lädt alle Prozesse neu.
pm2 gracefulReload all
Sendet zunächst eine »Exit«Nachricht an die Prozesse und lädt diese erst dann neu.
pm2 stop
Stoppen eines bestimmten Prozesses.
pm2 restart
Starten eines bestimmten Prozesses.
Tabelle 11.2 Übersicht über wichtige PM2-Befehle (Forts.)
503
11
Skalierung, Performance und Sicherheit
Befehl
Beschreibung
pm2 delete
Entfernen eines bestimmten Prozesses.
pm2 delete all
Entfernen aller Prozesse.
Entwicklungsmodus pm2-dev run
Starten einer Anwendung im Entwicklungsmodus.
Tabelle 11.2 Übersicht über wichtige PM2-Befehle (Forts.)
11.5.2 Ausblick PM2 ist ein ausgereifter Prozessmanager für Node.js mit integriertem Load Balancing, der Ihnen u. a. dabei hilft, Applikationen bzw. Unterprozesse bei Abstürzen neu zu starten, und damit sicherstellt, dass eine Applikation dauerhaft erreichbar ist.
Verwandte Rezepte 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 81: Externe Anwendungen als Stream verarbeiten 왘 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen 왘 Rezept 83: Eine Node.js-Anwendung clustern
11.6 Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln Sie möchten Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln.
11.6.1 Lösung: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln mit der Standard-Node.js-API Das Auslesen von allgemeinen Systeminformationen, der CPU-Auslastung und des Speicherverbrauchs kann aus verschiedenen Gründen notwendig sein: Beispielsweise, wenn Sie herausfinden möchten, welches Betriebssystem verwendet wird, um ausgehend davon innerhalb Ihrer Applikation bestimmte Abläufe anzustoßen oder nicht. Oder wenn Sie herausfinden möchten, wie viele Prozessorkerne zur Verfügung stehen, um auf Basis dieser Informationen für jeden Kern einen Unterprozess des
504
11.6
Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln
aktuellen Prozesses zu erzeugen (siehe Rezept 83). Auch wenn Sie wissen möchten, wie viel Speicher insgesamt vorhanden und wie viel von diesem Speicher belegt ist, um abhängig davon innerhalb Ihrer Applikation regulieren zu können, ob eine speicherintensive Aufgabe durchgeführt oder damit bis zu einem späteren Zeitpunkt gewartet werden soll. Die Standard-API von Node.js stellt für das Auslesen von allgemeinen Systeminformationen das Package »os« (kurz für Operating System, https://nodejs.org/api/os. html) zur Verfügung. Darüber können Sie, wie in Listing 11.14 gezeigt, verschiedene der genannten Informationen abrufen, bspw. die verwendete Systemarchitektur (arch()), die Anzahl an CPUs inklusive Detailinformationen zu jeder CPU (cpus()) sowie Informationen zu dem noch freien Speicher (freemem()). Eine vollständige Auflistung der zur Verfügung stehenden Methoden finden Sie in Tabelle 11.2. const os = require('os'); console.log(os.arch()); // x64 console.log(os.cpus()); // [ // { // model: 'Intel(R) Core(TM) i5-3230M CPU @ 2.60GHz', // speed: 2600, // times: { user: 1037180, nice: 0, sys: 621350, idle: 5246580, irq: 0 } // }, // { // model: 'Intel(R) Core(TM) i5-3230M CPU @ 2.60GHz', // speed: 2600, // times: { user: 510710, nice: 0, sys: 273220, idle: 6120070, irq: 0 } // }, // { // model: 'Intel(R) Core(TM) i5-3230M CPU @ 2.60GHz', // speed: 2600, // times: { user: 993180, nice: 0, sys: 485310, idle: 5425510, irq: 0 } // }, // { // model: 'Intel(R) Core(TM) i5-3230M CPU @ 2.60GHz', // speed: 2600, // times: { user: 521370, nice: 0, sys: 277610, idle: 6105020, irq: 0 } // } // ];
505
11
Skalierung, Performance und Sicherheit
console.log(os.endianness()); // LE console.log(os.freemem()); // 95858688 console.log(os.homedir()); // /Users/philipackermann console.log(os.hostname()); // Philips-MBP.fritz.box console.log(os.loadavg()); // [ 2.494140625, 2.47216796875, 2.4873046875 ] console.log(os.platform()); // darwin console.log(os.release()); // 15.6.0 console.log(os.tmpdir()); // /var/folders/dc/5_bbrz6j12s055j4psqwh2qc0000gn/T console.log(os.totalmem()); // 8589934592 console.log(os.type()); // Darwin console.log(os.uptime()); // 43420 console.log(os.userInfo()); // { uid: 501, // gid: 20, // username: 'philipackermann', // homedir: '/Users/philipackermann', // shell: '/bin/bash' } Listing 11.14 Ermitteln von allgemeinen Systeminformationen
506
11.6
Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln
Methode
Beschreibung
os.arch()
Liefert Informationen zur Systemarchitektur, für welche die jeweilige Node.js-Version kompiliert wurde.
os.cpus()
Liefert Informationen zu jedem CPU-Kern.
os.endianness()
Liefert Informationen bezüglich der verwendeten Byte-Reihenfolge (https://de.wikipedia.org/ wiki/Byte-Reihenfolge), »BE« für Big Endian oder »LE« für Little Endian.
os.freemem()
Liefert den freien Systemspeicher als Bytes.
os.getPriority([pid])
Liefert die Priorität eines Prozesses bezüglich des Schedulings.
os.homedir()
Liefert das Home-Verzeichnis des aktuellen Nutzers.
os.hostname()
Liefert den Hostnamen des Betriebssystems.
os.loadavg()
Liefert den Durchschnitt der Systemaktivität.
os.networkInterfaces()
Liefert Informationen bezüglich der verfügbaren Netzwerk-Interfaces.
os.platform()
Liefert Informationen zur Plattform des jeweiligen Betriebssystems, bspw. »linux«, »darwin« oder »win32«.
os.release()
Liefert Release-Informationen zum aktuellen Betriebssystem.
os.setPriority([pid, ]priority)
Setzt die Priorität eines Prozesses bezüglich des Schedulings.
os.tmpdir()
Liefert das standardmäßige Verzeichnis, das für temporäre Dateien verwendet wird.
os.totalmem()
Liefert den vollständigen Systemspeicher als Bytes.
os.type()
Liefert den Typ des aktuellen Betriebssystems, bspw. »Linux« für Linux-Systeme, »Darwin« für macOS und »Windows_NT« für Windows.
Tabelle 11.3 Methoden für das Ermitteln von Systeminformationen
507
11
Skalierung, Performance und Sicherheit
Methode
Beschreibung
os.uptime()
Liefert die Betriebszeit.
os.userInfo([options])
Liefert Informationen zum aktuell angemeldeten Nutzer.
Tabelle 11.3 Methoden für das Ermitteln von Systeminformationen (Forts.)
Neben den Methoden im »os«-Package stellt Node.js seit Version 6.1.0 über das globale process-Objekt die Methoden cpuUsage() und memoryUsage() zur Verfügung, um die CPU-Auslastung und den Speicherverbrauch des jeweiligen Node.js-Prozesses zu ermitteln: console.log(process.cpuUsage()); // { user: 82340, system: 14597 } console.log(process.memoryUsage()); // { // rss: 21766144, // heapTotal: 8388608, // heapUsed: 4384376, // external: 8240 // } // Hinzufügen von 50.000.000 zufälligen // Zahlenwert zu Array const randoms = []; for (let i=0; i { try { const system = await si.system(); console.log(system); // { manufacturer: 'Apple Inc.', // model: 'MacBookPro10,2', // version: '1.0', // ... } const cpu = await si.cpu(); console.log(cpu); // { manufacturer: 'Intel®', // brand: 'Core™ i5-3230M', // vendor: 'GenuineIntel', // family: '6',
509
11
Skalierung, Performance und Sicherheit
// model: '58', // stepping: '9', // revision: '', // voltage: '', // speed: '2.60', // speedmin: '2.60', // speedmax: '2.60', // cores: 4, // cache: { l1d: 32768, l1i: 32768, l2: 262144, l3: 3145728 } } const cpuCurrentspeed = await si.cpuCurrentspeed(); console.log(cpuCurrentspeed); // { // min: 2.6, // max: 2.6, // avg: 2.6, // cores: [2.6, 2.6, 2.6, 2.6] // } const mem = await si.mem(); console.log(mem); // { // total: 8589934592, // free: 137330688, // used: 8452603904, // active: 3061174272, // available: 5528760320, // buffcache: 5391429632, // swaptotal: 1073741824, // swapused: 214433792, // swapfree: 859308032 // } const battery = await si.battery(); console.log(battery); // { // hasbattery: true, // cyclecount: 1372, // ischarging: false, // maxcapacity: 6193, // currentcapacity: 437, // percent: 7, // timeremaining: 19, // acconnected: false,
510
11.7 Rezept 86: Speicherprobleme identifizieren
// type: 'Li-ion', // model: '', // manufacturer: 'Apple', // serial: 'D862456P0PBF955AD' // } } catch (error) { console.log(error); } })(); Listing 11.16 Ermitteln von Systeminformationen, CPU-Auslastung und Speicherverbrauch
Eine vollständige Auflistung aller Systeminformationen, die sich mithilfe des Packages »systeminformation« ermitteln lassen, würde an dieser Stelle den Rahmen sprengen. Daher empfehle ich Ihnen, einen Blick auf die offizielle Online-Referenz unter https://github.com/sebhildebrandt/systeminformation#reference zu werfen. Dort finden Sie auch Informationen darüber, welche der jeweiligen Methoden unter welchem Betriebssystem unterstützt werden.
11.6.3 Ausblick Sie wissen jetzt, wie Sie innerhalb einer Node.js-Applikation verschiedene Systeminformationen ermitteln können, darunter auch die CPU-Auslastung und den aktuell belegten Arbeitsspeicher. Diese Informationen können Ihnen bereits einen Hinweis auf Speicherprobleme oder CPU-Probleme geben. In den nächsten beiden Rezepten zeige ich Ihnen allerdings zwei effektivere Wege, um Speicherprobleme und CPUProbleme identifizieren zu können.
Verwandte Rezepte 왘 Rezept 80: Externe Anwendungen als Unterprozess ausführen 왘 Rezept 83: Eine Node.js-Anwendung clustern 왘 Rezept 86: Speicherprobleme identifizieren 왘 Rezept 87: CPU-Probleme identifizieren
11.7 Rezept 86: Speicherprobleme identifizieren Sie möchten Speicherprobleme identifizieren, indem Sie den Heap einer Node.jsApplikation untersuchen.
511
11
Skalierung, Performance und Sicherheit
11.7.1 Lösung Im vorherigen Rezept haben Sie bereits gesehen, dass Sie über das process-Objekt mithilfe der Methode cpuUsage() die CPU-Auslastung und mithilfe der Methode memoryUsage() die Speicherauslastung ermitteln können. Letztere liefert ein Objekt mit vier Eigenschaften: heapTotal und heapUsed beziehen sich auf den Speicherverbrauch von V8, external bezieht sich auf den Speicherverbrauch von Objekten in C, und rss (Resident Set Size) gibt den Speicher an, der im Hauptspeicher für den aktuellen Prozess vorgesehen ist. Die Methode memoryUsage() gibt Ihnen allerdings nur ein grobes Indiz dafür, ob ein Speicherproblem existiert. Detaillierte Informationen darüber, was genau die Ursache für das Speicherproblem ist, liefert Ihnen diese Methode nicht. Wenn Sie detaillierte Informationen benötigen, bspw. welche Objekte sich genau auf dem Heap befinden, kommen Sie mit dieser Methode allein also nicht weiter. Abhilfe hierbei schaffen sogenannte Heap Dumps. Dabei handelt es sich um ein zu einem definierten Zeitpunkt erstelltes Speicherabbild einer Applikation.
Beispielapplikation Um Ihnen zu zeigen, wie Sie einen Heap Dump erzeugen und auswerten, benötigen Sie noch eine kleine Beispielapplikation, die ein Speicherproblem verursacht. Listing 11.17 zeigt diese Beispielapplikation: Implementiert ist hier ein HTTP-Server, der (zu Demonstrationszwecken) dummerweise jede eingehende Anfrage in einem Array ablegt. Die Folge: Je mehr Anfragen an den Server gestellt werden, desto größer wird das Array und desto größer der im Heap belegte Speicherplatz. const express = require('express'); const app = express(); const port = 3000; const requestsLog = []; app.get('/', (request, response) => { response.send('Hello World'); requestsLog.push(request); }); app.listen(port, (error) => { if (error) { console.error(error); } else { console.log(Server is listening on ${port});
512
11.7 Rezept 86: Speicherprobleme identifizieren
} }); Listing 11.17 Webserver mit einem Speicherproblem
Lasttests ausführen Für das Absenden mehrerer Tausend HTTP-Anfragen (und für das Durchführen von Lasttests bzw. Benchmarking-Tests von Webservern im Allgemeinen) empfehle ich Ihnen automatisierte Tools wie »JMeter« (https://jmeter.apache.org/) oder »autocannon« (https://www.npmjs.com/package/autocannon). Letzteres steht praktischerweise als Package für Node.js zur Verfügung und kann über den Befehl npm install -g autocannon installiert werden. Anschließend können Sie das Tool über den Befehl autocannon starten. Um bspw. 500.000 Anfragen über 10 verschiedene Verbindungen an den obigen Webserver zu stellen, rufen Sie das Tool wie folgt auf: $ autocannon http://localhost:3000 -a 500000 -c 10
Die Ausgabe von »autocannon« für diesen Befehl sehen Sie in Abbildung 11.7. Zum Vergleich zeigt Abbildung 11.8 diejenige Ausgabe, wenn aufseiten des Webservers die Zeile für das Speichern der HTTP-Anfragen auskommentiert wird (wir also in weiser Voraussicht den konstruierten Bug behoben haben). Interessant ist hierbei vor allem die Angabe unter »Latency«, also die Latenz bzw. Verzögerung, mit der jede Anfrage beantwortet wird. Im Durchschnitt liegen für die »Bug-Version« 99 % der Anfragen bei sechs Millisekunden, in der korrigierten Version dagegen 99 % bei einer Millisekunde. Und während in der korrigierten Version die Latenz maximal 10,88 Millisekunden beträgt, benötigt der Webserver in der »Bug-Version« im schlechtesten Fall 342,98 Millisekunden für die Beantwortung einer einzelnen Anfrage! Noch schlimmer: Für jede weitere Anfrage erhöht sich dieser Wert weiter, und bereits ein Test mit 550.000 Anfragen führt bei mir zu einem Absturz des Webservers.
Abbildung 11.7 Ausgabe von »autocannon« bei Speichern der Requests
513
11
Skalierung, Performance und Sicherheit
Abbildung 11.8 Ausgabe von »autocannon« ohne Speichern der Requests
Auch wenn Sie für das vorliegende Beispiel bereits wissen, was die Ursache für das Speicherproblem ist, möchte ich Ihnen im Folgenden zeigen, wie Sie die Suche nach dem Speicherproblem systematisch angehen würden. Dazu zeige ich Ihnen zwei verschiedene Techniken, um einen Heap Dump, also ein Abbild des Speichers, zu erstellen.
Heap Dump ermitteln mit den Chrome Developer Tools Die einfachste Möglichkeit, die keine Änderungen am Quelltext voraussetzt, führt über die Chrome Developer Tools. Starten Sie dazu die obige Server-Anwendung unter Angabe des Parameters --inspect im Debug-Modus: $ node --inspect server.js Debugger listening on ws://127.0.0.1:9229/e494c164-520a-439f-8fca-0634744cae57 For help, see: https://nodejs.org/en/docs/inspector Server is listening on 3000
Rufen Sie anschließend im Chrome Browser die URL chrome://inspect/#devices auf, und wählen Sie unter dem Abschnitt Remote Target die Anwendung über Inspect aus. In dem sich nun öffnenden Fenster können Sie über den Button Take snapshot einen Heap Dump erstellen (Abbildung 11.9). Wenn Sie den Heap Dump direkt nach Starten des Webservers erstellen, sollte dies nur wenige Sekunden dauern und der Heap Dump nicht größer als 5 MB sein (Abbildung 11.10).
514
11.7 Rezept 86: Speicherprobleme identifizieren
Abbildung 11.9 Erstellen eines Heap Dumps mit den Chrome Developer Tools
Abbildung 11.10 Heap Dump für die Ausgangssituation
515
11
Skalierung, Performance und Sicherheit
Führen Sie nun »autocannon« aus, allerdings nur mit 100.000 Anfragen (da der Webserver im Debug-Modus gestartet ist, würde er für die Bearbeitung von 500.000 Anfragen viel zu lange benötigen – wenn er es denn überhaupt schaffen würde). $ autocannon http://localhost:3000 -a 100000 -c 10
Erstellen Sie anschließend einen zweiten Heap Dump. Gehen Sie dazu wieder auf den Eintrag Profiles, und klicken Sie erneut auf den Button Take snapshot. Das Erstellen des Heap Dumps sollte dieses Mal wesentlich länger dauern, und die Größe des Heap Dumps sollte ungefähr bei 376 MB liegen (Abbildung 11.11).
Abbildung 11.11 Heap Dump nach 100.000 Anfragen an den Webserver
Bereits jetzt können Sie anhand der prozentuellen Speicherbelegung eingrenzen, wo das Speicherproblem liegt (27 % des Speichers sind, wie in Abbildung 11.11 zu sehen, durch das Array mit den gespeicherten HTTP-Anfragen belegt). Noch einfacher ist es aber, wenn Sie den zweiten Heap Dump mit dem ersten vergleichen. Dazu wechseln Sie in der Ansicht weiter oben in dem Drop-down-Menü von Summary auf Comparison und wählen anschließend rechts daneben den zuerst erstellten Heap Dump aus (Abbildung 11.12). Wie Sie in dieser Vergleichsansicht sehen können, sind zwischen dem ersten und dem zweiten Heap Dump exakt 100.000 Objekte vom Typ IncomingMessage hinzuge-
516
11.7 Rezept 86: Speicherprobleme identifizieren
kommen, also derjenigen Objekte, die eine eingehende HTTP-Anfrage repräsentieren (siehe https://nodejs.org/api/http.html#http_class_http_incomingmessage). Mithilfe dieser Information können Sie nun relativ einfach eingrenzen, wo das Speicherproblem liegt.
Abbildung 11.12 Vergleich zweier Heap Dumps und Eingrenzen des Speicherproblems
Heap Dump ermitteln über das Package »heapdump« Alternativ zu der im vorherigen Abschnitt gezeigten Technik können Sie einen Heap Dump auch programmatisch direkt innerhalb einer Node.js-Applikation erstellen. Dies bietet sich bspw. dann an, wenn Sie keinen direkten Zugriff auf die Applikation haben bzw. diese nicht für das Remote-Debugging über die Chrome Developer Tools gestartet wurde. Ein Package, das für diesen Zweck zur Verfügung steht, ist das Package »heapdump« (https://www.npmjs.com/package/heapdump), das Sie wie folgt installieren können: $ npm install heapdump
Für das Erstellen eines Heap Dumps stellt das Package die Methode writeSnapshot() zur Verfügung. Wie Sie diese Methode verwenden, sehen Sie in dem entsprechend angepassten Code für den Webserver in Listing 11.18. Damit das Erstellen des Heap Dumps von außen gesteuert werden kann, ist der Aufruf von writeSnapshot() hier
517
11
Skalierung, Performance und Sicherheit
zusätzlich in eine eigene Route (»/heapdump«) eingebettet, die über eine gewöhnliche GET-Anfrage aufgerufen werden kann. const const const const
heapdump = require('heapdump'); express = require('express'); app = express(); port = 3000;
const requestsLog = []; app.get('/', (request, response) => { response.send('Hello World'); requestsLog.push(request); }); app.get('/heapdump', (request, response) => { response.send('Writing heapdump'); heapdump.writeSnapshot((error, filename) => { console.log(`Heap dump written to ${filename}`); }); }); app.listen(port, (error) => { if (error) { console.error(error); } else { console.log(`Server is listening on ${port}`); } }); Listing 11.18 Webserver mit zusätzlicher Route zum Erstellen eines Heap Dumps
Wenn Sie die entsprechende Route aufrufen, speichert »heapdump« den Heap Dump unter einer Datei mit der Endung heapsnapshot, deren Namen mit »heapdump« beginnt, bspw. heapdump-95722040.377381.heapsnapshot. Um diese Datei sinnvoll auszuwerten, benötigen Sie allerdings ein entsprechendes Hilfsprogramm. Praktischerweise erlauben es die Chrome Developer Tools über die Memory-Ansicht ebenfalls, externe Snapshot-Dateien zu laden. Dazu müssen Sie die Anwendung selbst nicht im Debug-Modus starten, sondern lediglich in einem beliebigen BrowserFenster die Chrome Developer Tools öffnen und die Memory-Ansicht auswählen. Klicken Sie dann mit der rechten Maustaste links auf den Eintrag Profiles, und wählen Sie die Datei aus (Abbildung 11.13). Anschließend können Sie den Heap, wie im vorherigen Abschnitt gezeigt, untersuchen.
518
11.7 Rezept 86: Speicherprobleme identifizieren
Abbildung 11.13 Laden einer externen Heap-Dump-Datei in den Chrome Developer Tools
11.7.2 Ausblick Sie wissen jetzt, wie Sie mithilfe von Heap Dumps Speicherprobleme in einer Node.jsApplikation identifizieren können. Die Chrome Developer Tools stellen Ihnen dabei eine hilfreiche Oberfläche zur Verfügung, um Heap Dumps zu generieren, zu inspizieren und miteinander zu vergleichen. Im nächsten Rezept zeige ich Ihnen, wie Sie CPU-Probleme identifizieren.
Verwandte Rezepte 왘 Rezept 19: Applikationen mit Chrome Developer Tools debuggen 왘 Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln 왘 Rezept 70: Über AMQP auf RabbitMQ zugreifen
519
11
Skalierung, Performance und Sicherheit
11.8 Rezept 87: CPU-Probleme identifizieren Sie möchten CPU-Probleme identifizieren, indem Sie mit einem Profiler den Stack einer Node.js-Applikation untersuchen.
11.8.1 Lösung Node.js verfügt über einen eigenen Profiler, mit dessen Hilfe sich messen lässt, wie viel Zeit für das Ausführen einzelner Funktionen benötigt wird bzw. genauer wie viele CPU-Ticks für das Ausführen einer Funktion benötigt werden. Dazu erstellt der Profiler in regelmäßigen Abständen ein Abbild des Stacks, sammelt die Ergebnisse und generiert einen Bericht, der die Funktionen anhand der Ausführungszeit sortiert.
Beispielapplikation Bevor ich Ihnen zeige, wie Sie den Profiler von Node.js verwenden und wie Sie die erstellten Berichte in eine lesbare Form bringen, benötigen Sie noch ein Negativbeispiel, das ein potenzielles CPU-Problem verursacht. Den Code für dieses Beispiel sehen Sie in Listing 11.19. Gezeigt ist hier ein in »Express« geschriebener Webserver, der zwei Routen definiert: Über den Endpoint http://localhost:3000/register lassen sich Nutzer erstellen (wobei der Einfachheit halber nur Nutzername und Passwort zu übergeben sind), und über den Endpoint http://localhost:3000/auth lässt sich – ebenfalls unter Angabe des Nutzernamens und des Passwortes – eine einfache Authentifizierung vornehmen. Das Entscheidende an diesem Beispiel (das Bottleneck sozusagen) ist aber die Verwendung der Methode pbkdf2Sync() aus dem »crypto«-Modul der Standard-Node.jsAPI. Diese Methode implementiert die Passwort-Based Key Derivation Function 2 (https://de.wikipedia.org/wiki/PBKDF2) und wird häufig – zumindest in der synchronen Variante unter Node.js – zur Veranschaulichung von Performanceproblemen herangezogen, weil sie – im Gegensatz zu der asynchronen Variante – nicht sonderlich schnell arbeitet bzw. relativ lange die weitere Programmausführung blockiert. Dies wird insbesondere dann deutlich, wenn die Methode häufig hintereinander aufgerufen wird, was Sie gleich provozieren, indem Sie viele Anfragen an den Webserver stellen.
Hinweis Das Beispiel ist natürlich wieder etwas konstruiert. In einer realen Applikation würden Sie vermutlich keinen eigenen Authentifizierungsmechanismus implementieren, sondern eher auf ein Framework wie »Passport.js« zurückgreifen (siehe Rezept 59).
520
11.8
const const const const const
Rezept 87: CPU-Probleme identifizieren
crypto = require('crypto'); express = require('express'); bodyParser = require('body-parser'); app = express(); port = 3000;
const users = new Map(); app.use(bodyParser.json()); app.post('/register', (request, response) => { const { username, password } = request.body; const salt = crypto.randomBytes(128).toString('base64'); const hash = crypto.pbkdf2Sync(password, salt, 10000, 512, 'sha512'); users.set(username, { salt, hash }); response.sendStatus(200); }); app.post('/auth', (request, response) => { const { username, password } = request.body; const { salt, hash } = users.get(username); const encryptHash = crypto.pbkdf2Sync(password, salt, 10000, 512, 'sha512'); if (crypto.timingSafeEqual(hash, encryptHash)) { response.sendStatus(200); } else { response.sendStatus(401); } }); app.listen(port, (error) => { if (error) { console.error(error); } else { console.log(`Server is listening on ${port}`); } }); Listing 11.19 Webserver mit einem CPU-Problem
521
11
Skalierung, Performance und Sicherheit
Die Applikation starten Sie nun wie gewohnt über folgenden Befehl: $ node server.js
Mithilfe von HTTPie können Sie wie folgt über den Endpoint http://localhost:3000/ register einen neuen Nutzer anlegen und über den Endpoint http://localhost:3000/ auth die Authentifizierung anstoßen. Die Antwort sollte in beiden Fällen – vorausgesetzt es wurden korrekte Credentials übergeben – ein »OK« vom Webserver sein. $ http POST http://localhost:3000/register \ username=maxmustermann \ password=12345 HTTP/1.1 200 OK Connection: keep-alive Content-Length: 2 Content-Type: text/plain; charset=utf-8 Date: Tue, 25 Jun 2019 14:28:03 GMT ETag: W/"2-nOO9QiTIwXgNtWtBJezz8kv3SLc" X-Powered-By: Express OK $ http POST http://localhost:3000/auth \ username=maxmustermann \ password=12345 HTTP/1.1 200 OK Connection: keep-alive Content-Length: 2 Content-Type: text/plain; charset=utf-8 Date: Tue, 25 Jun 2019 14:28:40 GMT ETag: W/"2-nOO9QiTIwXgNtWtBJezz8kv3SLc" X-Powered-By: Express OK
Lasttests ausführen Um den Webserver jetzt unter Last zu setzen, verwenden Sie das aus dem vorherigen Rezept bekannte Tool »autocannon«. Folgender Befehl bspw. simuliert 500 POSTAnfragen an den Endpoint http://localhost:3000/auth, wobei Nutzername und Passwort als Body übergeben werden: $ autocannon http://localhost:3000/auth \ -m POST \ -H Content-Type="application/json" \ -b '{"username":"maxmustermann", "password":"12345"}' \ -a 500
522
11.8
Rezept 87: CPU-Probleme identifizieren
Die Ausgabe dieses Befehls zeigt Abbildung 11.14. Wie Sie ganz unten in der Abbildung sehen können, benötigt der Webserver für die Bearbeitung der 500 Anfragen ungefähr 32 Sekunden (32.1s), was im Schnitt etwas mehr als 15 Anfragen pro Sekunden entspricht (15.63 in der Spalte Avg). Das könnte schneller sein, und im Folgenden zeige ich Ihnen, wie Sie das Problem systematisch eingrenzen können.
Abbildung 11.14 Ausgabe von »autocannon«
CPU-Probleme identifizieren Node.js stellt, wie eingangs erwähnt, einen eigenen Profiler zur Verfügung, der intern detaillierte Informationen zu der Laufzeit von Funktionen etc. sammelt und diese in Form eines Berichts speichert. Um den Profiler zu aktivieren, muss beim Starten der entsprechenden Applikation der Parameter –-prof mit angegeben werden. Stoppen Sie also den Webserver, und starten Sie ihn wie folgt erneut: $ node --prof server.js
Erzeugen Sie nun wieder über folgenden Befehl einen Nutzer: $ http POST http://localhost:3000/register \ username=maxmustermann \ password=12345
Und führen Sie anschließend erneut den Lasttest mit »autocannon« aus: $ autocannon http://localhost:3000/auth \ -m POST \ -H Content-Type="application/json" \ -b '{"username":"maxmustermann", "password":"12345"}' \ -a 500
Node.js erstellt daraufhin eine Datei mit der Endung .log, deren Name mit »isolate« beginnt, bspw. isolate-0x103801000-95074-v8.log. Um die darin enthaltenen Infor-
523
11
Skalierung, Performance und Sicherheit
mationen jedoch sinnvoll interpretieren zu können, müssen Sie zunächst den Profiling Processor von Node.js verwenden, der über den Parameter --prof-process gestartet werden kann. Folgender Befehl bspw. leitet die Ausgabe des Profiling Processors direkt in eine Datei processed.txt um, die Sie anschließend in jedem beliebigen Texteditor öffnen können: $ node --prof-process isolate-0x103801000-95074-v8.log > processed.txt
Interessant ist in dieser Textdatei zunächst der Bereich »Summary« (Listing 11.20). Wie Sie hier sehen können, spielt sich der Großteil der CPU-Ticks, nämlich 99,9 % innerhalb des C++-Codes, also innerhalb nativer Module ab. Um dem Performanceproblem auf die Spur zu kommen, lohnt es sich daher, einen genaueren Blick auf diese Code-Stellen zu werfen. [Summary]: ticks total nonlib name 2 0.0% 0.0% JavaScript 25371 99.9% 99.9% C++ 31 0.1% 0.1% GC 4 0.0% Shared libraries 11 0.0% Unaccounted Listing 11.20 Profiling-Datei Zusammenfassung
Suchen Sie also innerhalb der Datei nach dem mit der Kennzeichnung »[C++]« markierten Bereich (wenn das Problem innerhalb des JavaScript-Codes liegen würde, könnten Sie entsprechende Detailinformationen übrigens in dem mit der Kennzeichnung »[JavaScript]« markierten Bereich finden). Einen Ausschnitt für diesen Bereich sehen Sie in Listing 11.21. Innerhalb dieses Bereichs sind die nativen Methoden nach der Anzahl der CPU-Ticks sortiert aufgelistet Was hierbei wiederum sofort ins Auge fällt, ist, dass der Großteil der CPU-Ticks beim Ausführen der Methode node::crypto::PBKDF2() gemessen wurde. [C++]: ticks total nonlib name 24817 97.8% 97.8% T node::crypto::PBKDF2(v8::FunctionCallbackInfo const&) 310 1.2% 1.2% T __ZN2v88internal21Builtin_MakeTypeErrorEiPmPNS0_7 IsolateE 41 0.2% 0.2% T node::native_module::NativeModuleEnv::Compile Function(v8::FunctionCallbackInfo const&) 30 0.1% 0.1% t node::fs::Read(v8::FunctionCallbackInfo const&)
524
11.8
30
0.1%
Rezept 87: CPU-Probleme identifizieren
0.1% t node::fs::InternalModuleReadJSON(v8::FunctionCall backInfo const&)
Listing 11.21 C++-Bereich der Profiling-Datei (gekürzt und formatiert)
Sie ahnen natürlich schon, dass diese native Methode von der JavaScript-Methode pbkdf2Sync() aufgerufen wird. Um dies aber weiter verifizieren zu können und vor allem um herauszufinden, durch welche Methoden diese native Methode aufgerufen wird, suchen Sie nach dem Eintrag »[Bottom up (heavy) profile]«. Listing 11.22 zeigt einen Ausschnitt für diesen Bereich. Die Methoden sind hier – zusammen mit dem jeweiligen Call-Stack, dem Methodenaufruf-Stack – nach der Anzahl der CPU-Ticks sortiert aufgelistet. Anhand dieser Information lässt sich schnell ermitteln, dass die native Methode node::crypto::PBKDF2() tatsächlich von der JavaScript-Methode pbkdf2Sync() aufgerufen wird und diese wiederum von unserem Webserver (server.js). Damit haben Sie das CPU-Problem gefunden und können sich nun an die Behebung machen. [Bottom up (heavy) profile]: Note: percentage shows a share of a particular caller in the total amount of its parent calls. Callers occupying less than 1.0% are not shown. ticks parent name 24817 97.8% T node::crypto::PBKDF2(v8::FunctionCallbackInfo const&) 24817 100.0% T __ZN2v88internal21Builtin_HandleApiCallEiPmPNS0_7IsolateE 24817 100.0% LazyCompile: ~handleError internal/crypto/pbkdf2.js:74:21 24817 100.0% LazyCompile: ~pbkdf2Sync internal/crypto/pbkdf2.js:44:20 24762 99.8% LazyCompile: ~ /Users/cleancoderocker/nodejskochbuch/cpu/src/server.js:22:19 24762 100.0% LazyCompile: ~handle /Users/cleancoderocker/nodejskochbuch/cpu/…/express/…/layer.js:86:49 310 1.2% T __ZN2v88internal21Builtin_MakeTypeErrorEiPmPNS0_7IsolateE
525
11
Skalierung, Performance und Sicherheit
85 27.4% T __ZN2v88internal21Builtin_MakeTypeErrorEiPmPNS0_7IsolateE Listing 11.22 Profiling-Datei (gekürzt und formatiert)
CPU-Probleme beheben In dem vorliegenden Szenario kann das CPU-Problem relativ einfach behoben werden, indem Sie – wie in folgendem Listing gezeigt – anstatt der synchronen Variante pbkdf2Sync() einfach die asynchrone Variante pbkdf2() verwenden. const const const const const
crypto = require('crypto'); express = require('express'); bodyParser = require('body-parser'); app = express(); port = 3000;
const users = new Map(); app.use(bodyParser.json()); app.post('/register', (request, response) => { const { username, password } = request.body; const salt = crypto.randomBytes(128).toString('base64'); const hash = crypto.pbkdf2Sync(password, salt, 10000, 512, 'sha512'); users.set(username, { salt, hash }); response.sendStatus(200); }); app.post('/auth', (request, response) => { const { username, password } = request.body; const { salt, hash } = users.get(username); crypto.pbkdf2(password, salt, 10000, 512, 'sha512', (error, encryptHash) => { if (crypto.timingSafeEqual(hash, encryptHash)) { response.sendStatus(200); } else { response.sendStatus(401); } }); });
526
11.8
Rezept 87: CPU-Probleme identifizieren
app.listen(port, (error) => { if (error) { console.error(error); } else { console.log(`Server is listening on ${port}`); } }); Listing 11.23 Die asynchrone Variante behebt das CPU-Problem.
Starten Sie die Applikation nun erneut, und rufen Sie anschließend wieder folgende Befehle auf, um einen Nutzer anzulegen und den Lasttest mithilfe von »autocannon« zu starten: $ http POST http://localhost:3000/register username=maxmustermann password= 12345 $ autocannon http://localhost:3000/auth \ -m POST \ -H Content-Type="application/json" \ -b '{"username":"maxmustermann", "password":"12345"}' \ -a 500 \ -c 10
In der Ausgabe von »autocannon« (Abbildung 11.15) können Sie nun sehen, dass die Bearbeitung der 500 HTTP-Anfragen ungefähr doppelt so schnell vonstattengeht wie zuvor. Die 500 Anfragen werden nun in 17 Sekunden abgearbeitet (gegenüber vorher 32 Sekunden), was im Schnitt 29 Anfragen pro Sekunde entspricht (gegenüber vorher ungefähr 15 Anfragen).
Abbildung 11.15 Ausgabe von »autocannon«
527
11
Skalierung, Performance und Sicherheit
Hinweis Mit den in Rezept 82 und Rezept 83 gezeigten Techniken können Sie die Performance des Webservers noch weiter optimieren, indem Sie die Last auf verschiedene Prozessorkerne verteilen.
11.8.2 Ausblick In diesem Rezept haben Sie gesehen, wie sich mithilfe des Profilers von Node.js CPUProbleme bzw. Bottlenecks in einer Node.js-Applikation identifizieren lassen. Mit dem Wissen aus diesem und den vorherigen Rezepten sind Sie nun bestens dafür gerüstet, Performanceprobleme von Node.js-Applikationen systematisch eingrenzen und beheben zu können. In den folgenden beiden Rezepten werden wir uns dem Thema »Sicherheit« zuwenden: Hier werde ich Ihnen zeigen, wie Sie Schwachstellen von Abhängigkeiten identifizieren und JavaScript-Code dynamisch (und sicher!) laden und ausführen.
Verwandte Rezepte 왘 Rezept 19: Applikationen mit Chrome Developer Tools debuggen 왘 Rezept 82: Node.js-Applikationen als Unterprozess aufrufen 왘 Rezept 83: Eine Node.js-Anwendung clustern 왘 Rezept 85: Systeminformationen, CPU-Auslastung und Speicherverbrauch ermitteln 왘 Rezept 86: Speicherprobleme identifizieren
11.9 Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen Sie möchten überprüfen, ob die in einem Node.js-Projekt verwendeten Abhängigkeiten Schwachstellen aufweisen.
11.9.1 Lösung: Schwachstellen erkennen mit npm Wenn Sie mit Node.js arbeiten, werden Sie schnell merken, dass sich in relativ kurzer Zeit vieles an Abhängigkeiten in Ihrem Projekt ansammelt. So kann es sein, dass sich bereits nach wenigen Minuten über 100 Packages im node_modules-Ordner befinden. In Rezept 13 haben Sie bereits gesehen, dass es ratsam ist, automatisierte Tools
528
11.9
Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen
zu verwenden, um die Lizenzen von Abhängigkeiten zu ermitteln. Gleiches gilt für Schwachstellen bzw. Sicherheitslücken: Auch hier bietet es sich an, automatisierte Tools einzusetzen. Seit Version 6 von npm haben Sie die Möglichkeit, direkt über den npm-Befehl Schwachstellen von Abhängigkeiten zu erkennen. Wie Sie eventuell schon in einigen Rezepten in diesem Buch bei der Installation von bestimmten Packages bemerkt haben, erhalten Sie seit npm 6 bereits während der Installation einen entsprechenden Hinweis für Packages mit bekannten Schwachstellen. Installieren Sie bspw. die Version 4.5 von »express«, liefert Ihnen npm einen Hinweis über insgesamt 24 Schwachstellen, inklusive einer Angabe darüber, wie viele Schwachstellen davon vernachlässigbar (»low«), wie viele moderat (»moderate«) und wie viele schwerwiegend (»high«) sind. $ npm install [email protected] npm notice created a lockfile as package-lock.json. You should commit this file. npm WARN [email protected] No description npm WARN [email protected] No repository field. + [email protected] added 33 packages from 22 contributors in 3.365s [!] 24 vulnerabilities found [54 packages audited] Severity: 9 low | 9 moderate | 6 high Run npm audit for more detail
Hinweis Wenn Sie diese automatische Überprüfung während der Installation unterdrücken möchten, können Sie dies übrigens durch Angabe des Parameters --no-audit: $ npm install [email protected] --no-audit
Wenn Sie die Überprüfung dagegen global abschalten möchten, müssen Sie die npm-Konfiguration audit auf false setzen: $ npm set audit false
Detailinformationen zu den gefundenen Schwachstellen können Sie sich zusätzlich über den Befehl npm audit ausgeben lassen: $ npm audit # ... (siehe Screenshot)
529
11
Skalierung, Performance und Sicherheit
found 24 vulnerabilities (9 low, 9 moderate, 6 high) in 54 scanned packages run npm audit fix to fix 24 of them. Listing 11.24 Ausgabe der bekannten Schwachstellen (Ausschnitt)
Abbildung 11.16 Ausgabe des Befehls »npm audit«
Als Ergebnis erhalten Sie einen Report, der bekannte Schwachstellen auflistet und dazu jeweils folgende Informationen liefert: 왘 das betroffene Package (im Beispiel »negotiator«) 왘 das Package, das Sie direkt eingebunden haben und welches das betroffene Pack-
age als direkte oder indirekte Abhängigkeit hat (im Beispiel »express«) 왘 den genauen Pfad vom eingebundenen Package zu dem betroffenen Package (im
Beispiel »express > accepts > negotiator«) 왘 einen Link für weitergehende Informationen über die Schwachstelle sowie Maß-
nahmen, um die Schwachstelle zu beseitigen (im Beispiel https://nodesecurity.io/ advisories/106, Abbildung 11.17)
Tipp Über den Befehl npm audit --json können Sie sich den Report auch im JSON-Format ausgeben lassen, das sich besonders gut für die automatische Weiterverarbeitung eignet.
530
11.9
Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen
Abbildung 11.17 Unter nodesecurity.io finden Sie detaillierte Informationen zu bekannten Schwachstellen.
11.9.2 Lösung: Schwachstellen automatisch beheben mit npm Als weiteren Unterbefehl von npm audit können Sie über den Befehl npm audit fix npm direkt dazu veranlassen – soweit möglich –, die Schwachstellen durch ein VersionsUpdate der eingebundenen Packages zu beheben (dabei werden die Updates nur bis zu der Version vorgenommen, wie sie durch die in der package.json-Datei definierten semantischen Versionsnummern möglich sind): $ npm audit fix npm WARN [email protected] No description npm WARN [email protected] No repository field. + [email protected] added 22 packages from 25 contributors, removed 5 packages and updated 28 packages in 2.989s fixed 24 of 24 vulnerabilities in 54 scanned packages
11.9.3 Lösung: Schwachstellen erkennen mit Third-Party-Tools Die ehemalige Node Security Platform (https://nodesecurity.io/), auch bekannt als NSP, wurde im April 2018 von npm, Inc., der Firma hinter npm, gekauft und bildet seitdem die Grundlage für das mit npm 6 eingeführte npm audit. Mehr nachzulesen dazu ist unter https://medium.com/npm-inc/npm-acquires-lift-security-258e257ef639.
531
11
Skalierung, Performance und Sicherheit
Für den Fall, dass Sie eine ältere Version verwenden (oder verwenden müssen), können Sie auf verschiedene andere Tools zurückgreifen, bspw. »Snyk« (https://snyk.io) oder »Retire.js« (http://retirejs.github.io/retire.js/), die ich Ihnen in den nächsten beiden Abschnitten kurz vorstellen möchte.
11.9.4 Lösung: Schwachstellen erkennen mit »Snyk« »Snyk« (https://snyk.io) ist eine Open-Source-Plattform für die Erkennung von Schwachstellen in Quelltext und unterstützt u. a. Java, Python, Ruby und Node.js. Das Package ist für Open-Source-Projekte kostenlos (für kommerzielle Projekte gibt es verschiedene Preismodelle, siehe https://snyk.io/plans) und lässt sich relativ einfach mit GitHub-Repositories verbinden.
Installation und Verwendung »Snyk« stellt sowohl eine Weboberfläche zur Verfügung als auch ein Kommandozeilenwerkzeug, das Sie mithilfe von npm wie folgt installieren: $ npm install -g snyk
Um »Snyk« nutzen zu können, müssen Sie sich zunächst authentifizieren, bspw. über einen GitHub- oder einen BitBucket-Account. Den Authentifizierungsprozess starten Sie über folgenden Befehl: $ snyk wizard
Dies öffnet ein Browser-Fenster, über das Sie »Snyk« den Zugang zu dem entsprechenden Account gewähren müssen. Anschließend können Sie beliebige Packages auf Schwachstellen hin prüfen. Das schließt auch Packages ein, die Sie noch gar nicht als Abhängigkeit in Ihrem Projekt verwenden. Möchten Sie eine bestimmte Version eines Packages testen, geben Sie die Versionsnummer einfach wie folgt an: $ snyk test [email protected] Testing [email protected]... ... × High severity vulnerability found in qs Description: Denial of Service (Memory Exhaustion) Info: https://snyk.io/vuln/npm:qs:20140806 Introduced through: [email protected] From: [email protected] Remediation: You've tested an outdated version of express. Upgrade to [email protected] (triggers upgrades to [email protected] > [email protected])
532
11.9
Rezept 88: Schwachstellen von verwendeten Abhängigkeiten erkennen
× High severity vulnerability found in qs Description: Prototype Override Protection Bypass Info: https://snyk.io/vuln/npm:qs:20170213 Introduced through: [email protected] From: [email protected] Remediation: You've tested an outdated version of express. Upgrade to [email protected] (triggers upgrades to [email protected] > [email protected]) × High severity vulnerability found in negotiator Description: Regular Expression Denial of Service (DoS) Info: https://snyk.io/vuln/npm:negotiator:20160616 Introduced through: [email protected] From: [email protected] > [email protected] Remediation: You've tested an outdated version of express. Upgrade to [email protected] (triggers upgrades to [email protected] > [email protected] > [email protected]) ... Organisation: Package manager: Open source: Project path:
cleancoderocker npm yes [email protected]
Tested [email protected] for known vulnerabilities, found 13 vulnerabilities, 31 vulnerable paths. Run snyk wizard to address these issues. Listing 11.25 Auf Schwachstellen hin testen mit »Snyk« (Ausschnitt)
11.9.5 Lösung: Schwachstellen erkennen mit »Retire.js« »Retire.js« (http://retirejs.github.io/retire.js/) unterscheidet sich von »Snyk« insofern, als dass für die Verwendung keine Registrierung bzw. Authentifizierung notwendig ist. Stattdessen können Sie das Tool einfach lokal installieren und direkt verwenden. »Retire.js« steht ebenfalls als Kommandozeilenwerkzeug zur Verfügung, lässt sich darüber hinaus aber auch über entsprechende Plugins in Build-Tools wie Gulp (https://gulpjs.com) oder Grunt (https://gruntjs.com) oder über Browser-Plugins in die Browser Firefox und Chrome integrieren.
533
11
Skalierung, Performance und Sicherheit
Installation und Verwendung Um »Retire.js« zu verwenden, installieren Sie es über folgenden Befehl: $ npm install -g retire
Anschließend steht Ihnen der Befehl retire zur Verfügung. Aufgerufen innerhalb eines Node.js-Packages, überprüft das Package die verwendeten Abhängigkeiten auf bekannte Sicherheitslücken hin. Als Ausgangsbeispiel verwenden Sie wieder »express« in Version 4.5: $ $ $ $
mkdir app cd app npm init -y npm install [email protected]
Rufen Sie nun im selben Verzeichnis den Befehl retire auf, werden – nach initialem Herunterladen von Konfigurationsdateien, die »Retire.js« benötigt – die Sicherheitslücken aufgelistet, jeweils mit einer Angabe darüber, über welchen Abhängigkeitspfad die betroffene Abhängigkeit eingebunden ist, einer kurzen Beschreibung der Schwachstelle sowie einem Link (wie bei npm audit), der weitergehende Informationen sowie Tipps zur Behebung bereitstellt. $ retire Downloading https://raw.githubusercontent.com/RetireJS/retire.js/master/ repository/jsrepository.json ... Downloading https://raw.githubusercontent.com/RetireJS/retire.js/master/ repository/npmrepository.json ... ... app 1.0.0 ↳ express 4.5.1 ↳ cookie-signature 1.0.4 qs 0.6.6 has known vulnerabilities: severity: medium; advisory: qs_dos_ extended_event_loop_blocking; https://nodesecurity.io/advisories/28 severity: high; summary: qs_denial-of-service-memory-exhaustion; https:// nodesecurity.io/advisories/29 app 1.0.0 ↳ express 4.5.1 ↳ qs 0.6.6 send 0.5.0 has known vulnerabilities: severity: medium; CVE: CVE-2014-6394, advisory: send-directory-traversal; https://nodesecurity.io/advisories/32 severity: medium; summary: discloses root path; https://nodesecurity.io/ advisories/56 https://github.com/pillarjs/send/pull/70 https://github.com/ expressjs/serve-static/blob/master/HISTORY.md#181--2015-01-20 app 1.0.0 ↳ express 4.5.1
534
11.10
Rezept 89: JavaScript dynamisch laden und ausführen
↳ send 0.5.0 serve-static 1.3.2 has known vulnerabilities: severity: medium; advisory: serve-static-open-redirect, CVE: CVE-2015-1164; http://nodesecurity.io/ advisories/serve-static-open-redirect ... Listing 11.26 Ausgabe von »Retire.js« (Ausschnitt)
11.9.6 Ausblick Sie sollten Packages, die Sie für Ihr Node.js-Projekt als Abhängigkeiten einbinden, regelmäßig – am besten im Rahmen von Continuous Integration – auf Schwachstellen und Sicherheitslücken hin überpüfen. Seit npm 6 steht dazu der Befehl npm audit zur Verfügung. Wenn Sie dagegen mit einer älteren npm-Version arbeiten, bieten sich Alternativen wie »Snyk« oder »Retire.js« an. Insbesondere Ersteres ist durch seine übersichtlichen Reports auch für den Fall, dass Sie mit einer neueren npm-Version arbeiten, unbedingt einen Blick wert.
Verwandte Rezepte 왘 Rezept 13: Lizenzen der verwendeten Abhängigkeiten ermitteln
11.10 Rezept 89: JavaScript dynamisch laden und ausführen Sie möchten JavaScript-Code dynamisch zur Laufzeit laden und ausführen.
11.10.1 Einführung Das dynamische Laden von JavaScript-Code kann für verschiedene Szenarien interessant sein. Angenommen Sie haben bspw. die Aufgabe, eine Webapplikation zu entwickeln, die über ein Plugin-System dynamisch durch den Nutzer erweitert werden können soll. Eigene Plugins sollen in Form von JavaScript-Codeschnipseln über ein Webformular hochgeladen, an das Backend weitergeleitet und dann auf ServerSeite ausgeführt werden. Bei diesen Anforderungen sollten bei Ihnen eigentlich schon alle Alarmglocken klingeln. Und das nicht ohne Grund. Eröffnet der beschriebene Plugin-Mechanismus doch zumindest das Potenzial, um schädlichen Code in die Applikation zu schleusen. In diesem Rezept möchte ich Ihnen daher zeigen, was Sie beim dynamischen Ausführen von JavaScript-Code beachten sollten. Doch zunächst ein Blick auf die »Lösung«, die Sie nicht anwenden sollten.
535
11
Skalierung, Performance und Sicherheit
11.10.2 Keine Lösung: JavaScript mit eval() ausführen Für das Ausführen bzw. das Interpretieren von JavaScript-Code zur Laufzeit sieht der ECMAScript-Standard die globale Funktion eval() vor. Der Code kann dabei in Form einer Zeichenkette übergeben werden, wird dann interpretiert und ausgeführt: const code = ` const a = 5; const b = 6; a + b; `; const result = eval(code); console.log(result); // 11 Listing 11.27 Ausführen von Code mit der Funktion »eval()«
Allerdings wird die Verwendung der Funktion in der JavaScript-Community mittlerweile als Bad Practice angesehen, auch bekannt unter dem Namen eval() is evil. Der Grund dafür ist, dass der auf diese Weise ausgeführte Code auch Dinge anstellen kann, die nicht unbedingt gewollt sind. Da der Code Zugriff auf den gesamten JavaScript-Kontext hat, könnte auf diese Weise bspw. relativ einfach Code in ein System geschleust werden, der den aktuellen Prozess beendet: const code = ` console.log('Exiting process'); process.exit(0); `; console.log('Before executing code'); eval(code); // Wird nicht ausgeführt console.log('After executing code');
Mindestens genauso fies ist folgender Code, der dafür sorgt, dass die jeweilige Applikation in einer Endlosschleife hängen bleibt: eval('while(true) console.log(1)');
Ebenfalls möglich – wobei dies wahrscheinlich nicht im Sinn des Hackers wäre – ist es, die eval()-Funktion selbst zu überschreiben: eval('eval = undefined');
Anhand dieser kleinen Beispiele sehen Sie sofort, dass die Verwendung von eval() um jeden Preis verhindert werden muss, zumindest, wenn Sie dynamischen Code ausführen wollen.
536
11.10
Rezept 89: JavaScript dynamisch laden und ausführen
Zumindest sollten Sie genau wissen, was Sie tun, und sich auf jeden Fall davor hüten, auf diese Weise externen Code auszuführen, auf den Sie keinen Einfluss haben. Beispielsweise, wenn Sie, wie eingangs beschrieben, ein Plugin-System implementieren und einzelne Plugins in Form von JavaScript-Code einlesen. Denn: Code, der über die eval()-Funktion ausgeführt wird, verfügt über die gleichen Rechte wie der Code, der die eval()-Funktion aufruft. Er wird innerhalb des gleichen Prozesses ausgeführt und hat Zugriff auf die gleichen Objekte wie der aufrufende Code, und zwar auf alle Objekte im jeweiligen Scope. Das stellt ein enormes Sicherheitsrisiko dar, weil auf diese Weise Objekte sehr einfach überschrieben bzw. verändert werden können, z. B. wie in folgendem Code: const user = { name: 'max', email: '[email protected]' }; const code = ` user.email = '[email protected]'; `; eval(code); console.log(user); // { name: 'max', email: '[email protected]' }
Wenn nun die Funktion eval() nicht für das Ausführen von Code verwendet werden sollte, welche Möglichkeit haben Sie dann? Die Antwort darauf ist, den Code in einem eigenen Kontext auszuführen, von dem aus er keinen Zugriff auf den Kontext des umgebenden Codes hat.
11.10.3 Lösung: JavaScript mit »vm« ausführen Eine Möglichkeit, JavaScript-Code in einem eigenen Kontext auszuführen, bietet das Modul »vm« der Standard-Node.js-API über die Methoden createContext() und runInContext() (Listing 11.28). Die Methode createContext() dient dabei dem Anlegen eines neuen Kontextes: Hier übergeben Sie als Parameter ein sogenanntes SandboxObjekt, also einen Bereich, auf den sowohl der aufrufende Code als auch der im Kontext aufgerufene Code Zugriff haben. Intern wird durch den Aufruf von createContext() das Sandbox-Objekt mit einer neuen Instanz eines V8-Kontextes verknüpft. Die Methode runInContext() dient dem Ausführen von Code in dem zuvor angelegten Kontext. Dieser Methode übergeben Sie als ersten Parameter den auszuführenden Code und als zweiten Parameter das Sandbox-Objekt.
537
11
Skalierung, Performance und Sicherheit
const vm = require('vm'); const x = 1; const sandbox = { x: 2 }; vm.createContext(sandbox); const code = ` x += 20; y = 25; `; vm.runInContext(code, sandbox); console.log(sandbox.x); console.log(sandbox.y); console.log(x); // console.log(y);
// // // //
22 25 1 not defined
Listing 11.28 Ausführen von Code mit dem »vm«-Modul
Um die Schritte für das Erstellen eines neuen Kontextes und das Ausführen von Code in diesem Kontext direkt in einem Schritt zu machen, können Sie alternativ die Methode runInNewContext() verwenden: const vm = require('vm'); const x = 1; const sandbox = { x: 2 }; const code = ` x += 20; y = 25; `; vm.runInNewContext(code, sandbox); console.log(sandbox.x); console.log(sandbox.y); console.log(x); // console.log(y);
// // // //
22 25 1 not undefined
Listing 11.29 Anlegen von neuem Kontext und Ausführen von Code in einem Schritt
538
11.10
Rezept 89: JavaScript dynamisch laden und ausführen
Versuchen Sie nun, Code auszuführen, der bspw. versucht, auf das process-Objekt zuzugreifen … const vm = require('vm'); const code = ` console.log('Exiting process'); process.exit(0); `; console.log('Before executing code'); try { const sandbox = {}; vm.runInNewContext(code, sandbox); } catch (error) { console.error(error); } console.log('After executing code');
… kommt es zu einem Fehler, weil innerhalb des erzeugten Kontextes, in dem der geladene Code läuft, kein process-Objekt vorhanden ist: $ node src/start-vm-new-context.js Before executing code evalmachine.:3 process.exit(0); ^ ReferenceError: process is not defined at evalmachine.:3:3 at Script.runInContext (vm.js:102:20) at Script.runInNewContext (vm.js:108:17) at Object.runInNewContext (vm.js:291:38) at Object. (/Users/cleancoderocker/workspaces/nodejskochbuch/ .../src/start-vm-new-context.js:8:4) at Module._compile (internal/modules/cjs/loader.js:702:30) at Object.Module._extensions..js (internal/modules/cjs/loader.js:713:10) at Module.load (internal/modules/cjs/loader.js:612:32) at tryModuleLoad (internal/modules/cjs/loader.js:551:12) After executing code
So weit, so gut. Allerdings ist auch die Ausführung von Code über »vm« nicht ganz sicher, bzw. weist »vm« eine Schachstelle auf, über die Sie sich im Klaren sein sollten.
539
11
Skalierung, Performance und Sicherheit
Prinzipiell geht es bei dem dynamischen Laden und Ausführen von (Fremd-)Code ja darum, den Zugriff auf den Kontext des eigenen Codes zu unterbinden. Über »vm« wird so bspw. der Zugriff auf globale Objekte wie process oder console unterbunden. Dennoch gibt es einen Weg, innerhalb des ausgeführten Codes trotzdem Zugriff auf diese Objekte zu bekommen. Und zwar über das Sandbox-Objekt, wie anhand des Exploits in Listing 11.30 zu sehen. Wenn Sie in dem Sandbox-Objekt nämlich andere Objekte als Eigenschaften definieren, kann innerhalb des aufgerufenen Codes über deren constructor-Eigenschaft auf eine Funktion zugegriffen werden, über die wiederum auf globale Objekte (im Beispiel process und console) zugegriffen werden kann. const vm = require('vm'); const sandbox = { someObject: {} }; const code = ` const ForeignObject = someObject.constructor; const ForeignFunction = ForeignObject.constructor; const process = ForeignFunction('return process')(); const console = ForeignFunction('return console')(); console.log('Exiting process'); process.exit(0); `; console.log('Before executing code'); vm.runInNewContext(code, sandbox); // Wird nie ausgeführt console.log('After executing code'); Listing 11.30 »vm« erlaubt über diesen Exploit den Zugriff auf globale Objekte.
Aus diesem Grund kann ich Ihnen eigentlich auch nicht zur Verwendung des »vm«Moduls raten. Zumindest nicht, wenn Sie, wie im letzten Beispiel gezeigt, über das Sandbox-Objekt weitere Objekte definieren und dadurch der Exploit ausgespielt werden kann. In jedem Fall auf der sicheren Seite sind Sie aber, wenn Sie die im nächsten Abschnitt beschriebene Lösung verwenden.
11.10.4 Lösung: JavaScript mit »vm2« ausführen Eine Alternative zu »vm«, die genau dem zuvor beschriebenen Problem entgegenwirkt, ist das Package »vm2« (https://github.com/patriksimek/vm2), das Sie wie folgt installieren: $ npm install vm2
Intern verwendet das Package sogenannte Proxy-Objekte, über die der Zugriff auf die Sandbox und deren Inhalt gesteuert (und begrenzt) wird. Wie in Listing 11.31 zu sehen,
540
11.11 Zusammenfassung
legen Sie über den Aufruf new VM() einen neuen Kontext an, wobei Sie als Eigenschaft des übergebenen Konfigurationsobjekts wieder das Sandbox-Objekt definieren. Anschließend können Sie Code über die Methode run() ausführen. const { VM } = require('vm2'); const sandbox = { someObject: {} }; const vm = new VM({ sandbox }); const code = ` const ForeignObject = someObject.constructor; const ForeignFunction = ForeignObject.constructor; const process = ForeignFunction('return process')(); const console = ForeignFunction('return console')(); console.log('Exiting process'); process.exit(0); `; console.log('Before executing code'); try { vm.run(code, sandbox); } catch (error) { console.error(error); } console.log('After executing code'); Listing 11.31 »vm2« verhindert den Zugriff auf globale Objekte.
11.10.5 Ausblick In diesem Rezept haben Sie gesehen, was Sie beim dynamischen Laden und Ausführen von JavaScript-Code beachten sollten. Die Funktion eval() sollten Sie vermeiden, da der hierüber aufgerufene Code Zugriff auf den gleichen Kontext wie der aufrufende Code hat. Das Package »vm« bessert diesbezüglich zwar nach, kann allerdings über entsprechende Exploits ebenfalls gehackt werden. Das Package »vm2« stellt derzeit die sicherste Möglichkeit dar, um JavaScript-Code dynamisch ausführen zu können.
11.11 Zusammenfassung In diesem Kapitel haben Sie gesehen, wie Sie Node.js-Anwendungen skalieren und die Performance verbessern können, wie Sie CPU- und Speicherprobleme identifizieren und welche Aspekte bezüglich der Sicherheit von Node.js-Anwendungen zu beachten sind. Zusammenfassend wissen Sie jetzt, wie Sie
541
11
Skalierung, Performance und Sicherheit
왘 externe Anwendungen als Unterprozess ausführen (Rezept 80), 왘 externe Anwendungen als Stream verarbeiten (Rezept 81), 왘 Node.js-Applikationen als Unterprozess aufrufen (Rezept 82), 왘 eine Node.js-Anwendung clustern (Rezept 83), 왘 Unterprozesse über einen Prozessmanager verwalten (Rezept 84), 왘 Systeminformationen, CPU-Auslastung und Speicherverbrauch
ermitteln (Rezept 85), 왘 Speicherprobleme identifizieren (Rezept 86), 왘 CPU-Probleme identifizieren (Rezept 87), 왘 Schwachstellen von verwendeten Abhängigkeiten erkennen (Rezept 88), 왘 JavaScript dynamisch laden und ausführen (Rezept 89).
542
Kapitel 12 Native Module In diesem Kapitel möchte ich Ihnen zeigen, wie Sie native Module in C bzw. C++ implementieren und diese aus JavaScript heraus ausrufen.
Das Implementieren nativer Module mit C oder C++ kann in verschiedenen Fällen sinnvoll sein, bspw. wenn Sie das letzte Quäntchen bezüglich der Performance herauskitzeln möchten. Anwendungsfälle hierfür wären z. B. Bild- oder Videobearbeitung oder generell Algorithmen, welche die CPU stark in Anspruch nehmen. Auch wenn Sie auf Low-Level-APIs des Betriebssystems zugreifen möchten oder wenn Sie eine Schnittstelle von Node.js zu existierenden C- bzw. C++-Bibliotheken schaffen möchten (bspw. zur Integration von Legacy-Anwendungen), sind native Module unumgänglich. Die Lernkurve für die Implementierung von nativen Modulen ist allerdings leider recht steil. Unnötig zu sagen, dass es nicht besser wird, wenn man zuvor noch nie in C bzw. C++ entwickelt hat. Die folgenden Rezepte dienen daher in erster Linie dazu, Ihnen eventuelle Berührungsangst vor nativen Modulen zu nehmen, und nicht dazu, aus Ihnen einen C-Profi zu machen. Einschlägige Literatur zu diesem Thema gibt es schließlich zur Genüge. In diesem Kapitel lernen Sie also Folgendes: 왘 Rezept 90: Native Node.js-Module mit der V8-API erstellen 왘 Rezept 91: Native Node.js-Module mit der NAN-API erstellen 왘 Rezept 92: Native Node.js-Module mit der N-API erstellen 왘 Rezept 93: Werte und Objekte zurückgeben mit der N-API 왘 Rezept 94: Callbacks aufrufen mit der N-API 왘 Rezept 95: Promises zurückgeben mit der N-API 왘 Rezept 96: Assertions verwenden mit der N-API 왘 Rezept 97: Native Node.js-Module debuggen
12.1 Rezept 90: Native Node.js-Module mit der V8-API erstellen Sie möchten native Node.js-Module mit der V8-API erstellen.
543
12
Native Module
12.1.1 Lösung Node.js verwendet intern für die Ausführung des JavaScript-Codes bekanntermaßen die JavaScript-Engine V8 von Google (https://v8.dev/). V8 ist selbst in C++ geschrieben und stellt eine entsprechende API zur Verfügung. Innerhalb von nativen Node.jsModulen können Sie nun mit dieser API (und mit der API von Node.js selbst) interagieren (Abbildung 12.1).
V8-API natives Modul Node.js-API
Abbildung 12.1 Bei der Entwicklung von nativen Modulen greifen Sie auf die V8-API und die Node.js-API zu.
Allerdings sollten Sie wissen, dass der direkte Zugriff auf die V8-API, wie er in diesem Rezept beschrieben ist, einen wesentlichen Nachteil hat: Ändert sich die API von V8, müssen Sie auch Ihre nativen Module entsprechend anpassen. Aus diesem Grund gibt es mittlerweile zwei alternative Ansätze, die ich Ihnen in den nächsten beiden Rezepten vorstellen werde. Nichtsdestoweniger sollten Sie als fortgeschrittener Node.js-Entwickler wissen, wie Sie auf die V8-API zugreifen können.
Voraussetzungen Damit Sie überhaupt native Module entwickeln können (unabhängig davon, welchen Ansatz Sie verwenden), benötigen Sie entsprechende Tools, um C- bzw. C++-Code kompilieren zu können. Für Linux sind dies bspw. die Tools »make« (https:// www.gnu.org/software/make/) und »GCC« (https://gcc.gnu.org/), für macOS bspw. »Xcode« (https://developer.apple.com/xcode/) und für Windows bspw. »Visual Studio« (https://www.visualstudio.com/). Bevor Sie also mit den folgenden Rezepten fortfahren, stellen Sie zunächst sicher, dass Sie die für Ihr Betriebssystem passenden Tools installiert haben.
Hinweis Das in diesem Buch mehrfach verwendete Visual Studio Code kann übrigens von Haus aus nicht C/C++ kompilieren. Hier müssten Sie gegebenenfalls ein entsprechendes Plugin nachinstallieren (siehe auch https://code.visualstudio.com/docs/languages/cpp).
544
12.1 Rezept 90: Native Node.js-Module mit der V8-API erstellen
Ein natives Modul erstellen Um ein natives Modul zu erstellen, legen Sie zunächst über folgende Befehle ein neues Node.js-Package an: $ $ $ $
mkdir my-native-module cd my-native-module npm init -y mkdir src
Den Beispiel-Code für ein relativ einfaches natives Modul, das eine Funktion bereitstellt, die eine Zeichenkette als Parameter entgegennimmt und auf der Konsole ausgibt, sehen Sie in Listing 12.1. Was der Quelltext genau macht, dazu gleich mehr. Kopieren Sie zunächst den Code in eine Datei native.cc, und legen Sie diese in das eben angelegte Verzeichnis src. #include namespace example { using using using using using using using
v8::Exception; v8::FunctionCallbackInfo; v8::Isolate; v8::Local; v8::Object; v8::String; v8::Value;
void printString(const FunctionCallbackInfo &args) { Isolate *isolate = args.GetIsolate(); if (!args[0]->IsString()) { isolate->ThrowException(Exception::TypeError( String::NewFromUtf8(isolate, "Parameter must be a string"))); return; } String::Utf8Value s(args[0]); std::string message(*s); printf("Inside C++: %s\n", message.c_str()); }
545
12
Native Module
void InitAll(Local exports) { NODE_SET_METHOD(exports, "printString", printString); } NODE_MODULE(module, InitAll) } // namespace example Listing 12.1 Beispiel für die Verwendung der V8-API (»src/native.cc«)
Hinweis Quelltextdateien für C++ speichern Sie mit der Dateiendung .cc oder .cpp. Der Compiler kommt mit beiden Formaten zurecht.
Gehen wir den Quelltext im Einzelnen durch: Die Anweisung #include entspricht in C++ in etwa dem require() aus Node.js, d. h., hierüber definieren Sie, welche anderen Dateien Sie für die Kompilierung Ihres Codes benötigen. Dabei geben Sie allerdings nicht die konkrete Implementierung an, sondern verlinken sogenannte Header-Dateien, die lediglich das Interface enthalten. Die Anweisung #include bindet bspw. die von Node.js zur Verfügung gestellte API ein (siehe https://github.com/nodejs/node/blob/master/src/node.h und https:// nodejs.org/api/addons.html). Die eingebundene Node.js-API wiederum bindet die von V8 zur Verfügung gestellte API ein (https://github.com/v8/v8/blob/master/include/v8.h), sodass Sie im Folgenden auch Zugriff auf den v8-Namensraum und die dort definierten Klassen haben. Über das Schlüsselwort namespace definieren Sie anschließend einen eigenen Namensraum (hier: example). Damit stellen Sie sicher, dass es zwischen Ihrem Code und dem eingebundenen Code keine Namenskonflikte gibt. Über das Schlüsselwort using können Sie den Compiler dazu veranlassen, bei der Auflösung von unqualifizierten Namen auch in anderen Namensräumen zu suchen. Über using v8::Exception bspw. definieren Sie, dass bei Verwendung von Exception innerhalb Ihres Codes nicht nur in dem von Ihnen definierten Namensraum, sondern auch im Namensraum v8 gesucht werden soll. Lassen Sie diese Anweisungen weg, müssen Sie innerhalb Ihres Codes stattdessen immer den voll qualifizierten Namen angeben (bspw. v8::Exception statt Exception). Dies wiederum kann sinnvoll sein, um Namenskonflikte zu Klassen in Ihrem Namensraum zu vermeiden (da im Beispiel aber keine eigene Klasse Exception definiert wird, kommt es hier zu keinem Konflikt).
546
12.1 Rezept 90: Native Node.js-Module mit der V8-API erstellen
Hinweis Der voll qualifzierte Name bezeichnet in der Programmierung den eindeutigen Namen einer Komponente (bspw. einer Klasse), der neben dem eigentlichen Namen der Komponente auch den entsprechenden Namespace (im Fall von C/C++) oder Paketnamen (im Fall von Java) enthält. Bei einem unqualifizierten Namen dagegen fehlt Letzteres, sodass nur der eigentliche Name der Komponente bleibt.
Die Funktion printString() soll im Beispiel die Funktion sein, die über das native Modul bereitgestellt wird und später vom JavaScript-Code aus aufgerufen werden kann. Innerhalb dieser Funktion haben Sie über das args-Objekt Zugriff auf die Argumente, mit denen die Funktion (aus JavaScript heraus) aufgerufen wurde: void printString(const FunctionCallbackInfo &args) { ... }
Über Isolate* können Sie dabei auf den sogenannten Isolate zugreifen, einen Bereich innerhalb von V8, in dem der jeweilige Code isoliert läuft. Isolate *isolate = args.GetIsolate();
Bei NODE_MODULE und NODE_SET_METHOD handelt es sich um sogenannte Makros, die vom Compiler zur Compile-Zeit in entsprechenden Code umgewandelt werden. Über NODE_MODULE() registrieren Sie das Modul im Modulsystem von Node.js. Ohne diesen Aufruf könnten Sie das Modul zwar kompilieren, nicht aber vom JavaScript-Code darauf zugreifen. Über NODE_SET_METHOD() wiederum definieren Sie die Methoden des vom Modul exportieren Objekts. Mit anderen Worten erreichen Sie darüber das, was Sie in JavaScript über exports.method = method erreichen würden: void InitAll(Local exports) { NODE_SET_METHOD(exports, "printString", printString); } NODE_MODULE(module, InitAll)
Ein natives Modul kompilieren Um den Code eines nativen Moduls zu kompilieren, benötigen Sie das Package »node-gyp« (https://www.npmjs.com/package/node-gyp), das standardmäßig bei der Installation von npm mitinstalliert wird und das Tool »gyp« (»Generate Your Projects, https://gyp.gsrc.io/) bereitstellt. Die Konfiguration für »node-gyp« definieren Sie dabei über eine Datei binding.gyp im JSON-Format (Listing 12.2), die Sie in das
547
12
Native Module
Wurzelverzeichnis des jeweiligen Packages legen. Dabei geben Sie über target_name den Namen des Moduls und über sources die einzubindenden Quelltextdateien an: { "targets": [{ "target_name": "native", "sources": [ "src/native.cc" ] }] } Listing 12.2 Die Datei »binding.gyp«
Rufen Sie nun folgenden Befehl auf, übernimmt »node-gyp« intern das Kompilieren automatisch für Sie: $ npm install
Das kompilierte Modul finden Sie anschließend unter dem Verzeichnis /build/Release (Abbildung 12.2).
Abbildung 12.2 Struktur des kompilierten Codes
Hinweis Alternativ können Sie »node-gyp« auch über npm install -g node-gyp als globales Package installieren und den Schritt der Kompilierung anschließend über node-gyp build aufrufen.
Ein natives Modul in JavaScript einbinden Damit Sie das native Modul über Ihr Package nach außen zur Verfügung stellen, erzeugen Sie wie gewohnt eine Datei index.js und kopieren den Code aus Listing 12.3 hinein. Hier passiert nichts anderes, als dass über require() das native Modul geladen wird, wobei Sie der Funktion den Pfad zu dem kompilierten Modul als Parameter übergeben. Anschließend haben Sie über die Variable binding Zugriff auf die im nativen Modul definierte Funktion printString().
548
12.1 Rezept 90: Native Node.js-Module mit der V8-API erstellen
const binding = require('./build/Release/native.node'); module.exports = binding.printString; Listing 12.3 Die Datei »index.js«
Um Ihr Package und das native Modul zu testen, legen Sie anschließend eine kleine Testdatei start.js mit folgendem Inhalt an: const printString = require('./'); printString('Hello World'); Listing 12.4 Die Datei »start.js«
Führen Sie nun diese Testdatei aus, sollte die Ausgabe wie folgt lauten: $ node start.js Inside C++: Hello World
Hinweis In Listing 12.4 wird das native Modul mit einer relativen Pfadangabe geladen (require('./')), aber natürlich können Sie das native Modul auch von anderen Packages aus laden.
Das Package »bindings« Im vorherigen Abschnitt haben Sie gesehen, dass beim Kompiliervorgang der kompilierte Code in dem Verzeichnis build/Release gespeichert wird. Aus historischen Gründen kann sich dieses Verzeichnis allerdings je nach verwendeter Node.js-Version und verwendeten Build-Tools unterscheiden. Auch für den Fall, dass Sie native Module debuggen, wird der Code unter einem anderen Verzeichnis gespeichert (siehe Rezept 97, »Native Node.js-Module debuggen«). Daher ist das Arbeiten mit relativen Pfaden nicht sonderlich empfehlenswert. Ein Package, das Ihnen diesbezüglich hilft, ist das Package »bindings« (https://github.com/TooTallNate/node-bindings), das Sie für das entsprechende Package, das den nativen Code enthält, wie folgt installieren: $ npm install bindings
Anschließend können Sie das native Modul, wie in Listing 12.5 zu sehen, direkt über den Namen statt über den Pfad einbinden und müssen sich nicht mehr darum kümmern, den richtigen Pfad zu dem kompilierten Code zu finden:
549
12
Native Module
const binding = require('bindings')('native'); module.exports = binding.printString; Listing 12.5 Das Package »bindings« hilft Ihnen beim Einbinden des kompilierten Codes.
12.1.2 Ausblick In diesem Rezept haben Sie gesehen, wie Sie mithilfe der V8-API native Module für Node.js erstellen können. Der Nachteil dieser Vorgehensweise: Ändert sich die API von Node.js oder V8, müssen Sie Ihre nativen Module gegebenenfalls anpassen und erneut kompilieren, damit diese funktionsfähig bleiben. Auch wenn das Node.jsTeam versucht, wesentliche Änderungen an der API zu minimieren, hat es dabei keinen Einfluss auf den Release-Plan und die APIs von V8. Aus diesen Gründen hat sich im Laufe der Zeit eine alternative API herausgebildet, die ich Ihnen im nächsten Rezept vorstellen möchte.
Verwandte Rezepte 왘 Rezept 91: Native Node.js-Module mit der NAN-API erstellen 왘 Rezept 92: Native Node.js-Module mit der N-API erstellen
12.2 Rezept 91: Native Node.js-Module mit der NAN-API erstellen Sie möchten native Node.js-Module mit der NAN-API erstellen, damit Sie unabhängig von Änderungen an der V8-API bleiben.
12.2.1 Lösung Die sogenannten Native Abstractions for Node.js, kurz NAN, wirken der im vorherigen Rezept geschilderten Problematik bei der direkten Verwendung der V8-API entgegen. Ursprünglich als Third-Party-Modul gestartet, wurde es Ende 2015 von der Node.js Foundation übernommen. Die Idee von NAN ist es, den konkreten Zugriff auf die C/C++-APIs von Node.js und V8 zu abstrahieren und eine zusätzliche Abstraktionsschicht von (neuen) APIs anzubieten (Abbildung 12.3). Verwendet man diese Abstraktionsschicht für die Entwicklung von Modulen, ist sichergestellt, dass bei Änderungen an der internen API von Node.js oder an der API von V8 der eigene Modul-Code nicht angepasst werden muss, weil die Änderungen intern durch die NAN-API bzw. deren Implementierung abgefangen werden.
550
12.2 Rezept 91: Native Node.js-Module mit der NAN-API erstellen
V8-API natives Modul
NAN-API Node.js-API
Abbildung 12.3 Die NAN-API abstrahiert vom direkten Zugriff auf die APIs von V8 und Node.js.
Ein natives Modul erstellen Da die Projektstruktur für den folgenden Code nicht von der Struktur des vorherigen Rezepts abweicht, können Sie sich von dem dortigen Package auch eine Kopie machen und diese als Basis für das vorliegende Rezept verwenden. Alternativ können Sie natürlich auch schnell ein neues Package erstellen: $ $ $ $
mkdir my-native-module-nan cd my-native-module-nan npm init -y mkdir src
Um NAN zu verwenden, müssen Sie das entsprechende Package »nan« (https://github.com/nodejs/nan) zunächst explizit über npm installieren. Aus den im vorherigen Rezept genannten Gründen ist es zudem hilfreich, direkt auch das Helferpackage »bindings« zu installieren: $ npm install nan $ npm install bindings
Die Datei package.json müsste danach ungefähr wie folgt aussehen: { "name": "my-native-module-nan", "version": "1.0.0", "description": "Rezept: native Node.js-Module mit der NAN-API erstellen", "scripts": { "start": "node ./src/start.js" }, "keywords": [ "javascript", "nodejs" ], "author": "Philip Ackermann", "license": "MIT",
551
12
Native Module
"dependencies": { "bindings": "^1.3.0", "nan": "^2.11.1" } } Listing 12.6 Die Datei »package.json« als Basis für das NAN-Package
Außerdem müssen Sie in der Datei binding.gyp wie folgt den Eintrag targets um die Eigenschaft include_dirs erweitern. Dies ist Voraussetzung dafür, dass Sie gleich in Ihrem nativen Code die entsprechende Header-Datei für NAN einbinden können. { "targets": [{ "target_name": "native", "sources": [ "src/native.cc" ], "include_dirs": [ "