Seminar NestJS – Grundlagen und REST-APIs

NestJS bietet eine strukturierte Plattform für serverseitige TypeScript-Anwendungen. Der produktive Nutzen entsteht, wenn Module, Dependency Injection, Request-Lifecycle und Querschnittsfunktionen als zusammenhängendes System verstanden werden.

Der Kurs baut eine REST-Anwendung von der leeren Projektstruktur bis zum getesteten, dokumentierten und konfigurierbaren Dienst auf. Jeder Schritt ergänzt ein Architekturprinzip und enthält Kontrollpunkte für typische Fehlkonfigurationen.

Inhaltsübersicht

• Lernziele
• Projektaufbau und NestJS-Kernkonzepte
• Request-Lifecycle und Querschnittsfunktionen
• REST-Design, DTOs und Validierung
• Konfiguration, Datenzugriff und Fehlerbehandlung
• Tests und produktionsnahe Vorbereitung
• Praxisprojekt: Verwaltungs-API für Aufgaben und Teams
• Prüfpunkte und typische Fehler

Lernziele

• Projektstruktur, Module, Controller, Provider und Dependency Injection sicher anwenden.
• Request-Lifecycle sowie Zusammenspiel von Middleware, Guards, Interceptors, Pipes und Filtern verstehen.
• REST-Ressourcen mit klaren DTOs, Statuscodes, Versionierung und Pagination gestalten.
• Konfiguration und Umgebungswerte typisiert, validiert und testbar bereitstellen.
• Relationalen Datenzugriff sauber kapseln und Fehler in stabile API-Antworten übersetzen.
• Unit-, Integrations- und End-to-End-Tests sowie API-Dokumentation integrieren.

Projektaufbau und NestJS-Kernkonzepte

Die Anwendung wird nach fachlichen Modulen gegliedert. Controller übernehmen Transport, Provider kapseln Anwendungslogik und Adapter verbinden Infrastruktur.

1. Projekt erzeugen, Compiler- und Qualitätskonfiguration prüfen und Startskripte vereinheitlichen.
2. Root-Modul sowie erste fachliche Module mit klaren Verantwortlichkeiten anlegen.
3. Controller mit Routen erstellen und Parameterbindung nachvollziehen.
4. Services und weitere Provider registrieren und über Konstruktorinjektion verwenden.
5. Provider-Sichtbarkeit über exports und imports gezielt steuern.
6. Custom Provider mit Tokens für austauschbare Implementierungen einsetzen.
7. Zyklische Abhängigkeiten erkennen und durch bessere Modulgrenzen vermeiden.

Entscheidungskriterien und Hinweise

• Module werden nach Fachlichkeit und nicht nur nach technischen Klassen geschnitten.
• Abhängigkeiten werden sichtbar injiziert und nicht über globale Zustände beschafft.

Request-Lifecycle und Querschnittsfunktionen

Eine HTTP-Anfrage durchläuft mehrere Erweiterungspunkte. Ihre Reihenfolge bestimmt, wo Authentifizierung, Transformation, Messung und Fehlerbehandlung greifen.

1. Middleware für protokollnahe Vorverarbeitung und Korrelationsdaten einsetzen.
2. Guards für Zugriffsvoraussetzungen und Berechtigungsentscheidungen verwenden.
3. Pipes für Validierung und Transformation von Parametern und DTOs konfigurieren.
4. Interceptors für Messung, Mapping, Caching und Antwortverarbeitung nutzen.
5. Exception Filter für stabile externe Fehlerverträge implementieren.
6. Globale und lokale Erweiterungspunkte mit klarer Priorität kombinieren.
7. Request-scoped Provider nur bei tatsächlichem Bedarf einsetzen.

Entscheidungskriterien und Hinweise

• Querschnittsfunktionen besitzen eine dokumentierte Reihenfolge.
• Request Scope wird wegen seiner Laufzeitkosten bewusst begrenzt.

REST-Design, DTOs und Validierung

Die API wird ressourcenorientiert gestaltet, ohne fachliche Aktionen künstlich in CRUD zu pressen. Eingabe- und Ausgabeverträge bleiben unabhängig von internen Klassen.

1. Ressourcen, Identitäten und zulässige Zustandsübergänge definieren.
2. Routen, Methoden, Statuscodes und Fehlercodes konsistent festlegen.
3. DTOs für Erstellen, Ändern, Filtern und Ausgeben getrennt modellieren.
4. Globale Validierung mit Whitelist und kontrollierter Transformation aktivieren.
5. Pagination, Sortierung und Filter mit festen Grenzen umsetzen.
6. API-Versionierung und Deprecation-Strategie vorbereiten.
7. OpenAPI-Dokumentation erzeugen und gegen reale Antworten prüfen.

Entscheidungskriterien und Hinweise

• DTOs sind API-Verträge und keine wiederverwendeten ORM-Klassen.
• Pagination besitzt stabile Sortierung und harte Seitengrenzen.

Konfiguration, Datenzugriff und Fehlerbehandlung

Konfiguration wird als typisierter Vertrag behandelt. Datenzugriff liegt hinter einer Schnittstelle, damit Controller weder Datenbankdetails noch Umgebungsvariablen kennen.

1. Konfigurationswerte zentral laden, validieren und nach Fachmodulen gruppieren.
2. Secrets getrennt von normalen Laufzeitwerten behandeln.
3. Repository- oder Adapter-Schnittstelle für den Datenzugriff definieren.
4. Transaktionsgrenzen an fachlichen Operationen ausrichten.
5. Datenbankfehler in stabile Konflikt-, Nichtgefunden- oder Validierungsfehler übersetzen.
6. Health-Endpunkte für Prozess, Abhängigkeiten und Betriebsbereitschaft unterscheiden.

Entscheidungskriterien und Hinweise

• Fehlende Konfiguration führt zu einem frühen, verständlichen Startabbruch.
• Controller enthalten keine direkten Datenbankzugriffe.

Tests und produktionsnahe Vorbereitung

Tests prüfen unterschiedliche Risiken auf der passenden Ebene. Kleine Unit-Tests geben schnelles Feedback; End-to-End-Tests sichern den vollständigen HTTP-Vertrag.

1. Provider mit Testmodul und kontrollierten Abhängigkeiten isoliert prüfen.
2. Controller- und Pipe-Verhalten mit repräsentativen Eingaben testen.
3. Integrationstest für Repository und reale Testdatenbank aufbauen.
4. Anwendung für End-to-End-Tests starten und vollständige HTTP-Abläufe prüfen.
5. Dokumentation, Validierung, Fehlerantworten und Statuscodes in Contract-Tests absichern.
6. Strukturierte Logs, Korrelations-ID und kontrolliertes Shutdown-Verhalten ergänzen.
7. Build, Linting, Tests und Startprüfung in einer Pipeline zusammenführen.

Entscheidungskriterien und Hinweise

• Tests prüfen Verhalten und nicht unnötig interne Methodenaufrufe.
• Produktionsvorbereitung umfasst Start, Shutdown, Health und Telemetrie.

Praxisprojekt: Verwaltungs-API für Aufgaben und Teams

Eine modulare Verwaltungs-API bildet Teams, Aufgaben und Statuswechsel ab. Neben CRUD-Operationen enthält sie Suche, Pagination, fachliche Aktionen, Datenpersistenz und einen Betriebsstatus.

Die Implementierung wird fortlaufend durch Unit-, Integrations- und End-to-End-Tests abgesichert. Am Ende steht ein reproduzierbarer Build mit API-Dokumentation und validierter Konfiguration.

1. Projekt und fachliche Module für Teams und Aufgaben strukturieren.
2. Controller, Services und Provider mit klaren Abhängigkeiten implementieren.
3. DTOs, globale ValidationPipe, Fehlerfilter und Antwortmapping ergänzen.
4. Repository-Adapter und relationale Testdatenbank anbinden.
5. Pagination, Filter, Statuswechsel und Konfliktbehandlung umsetzen.
6. OpenAPI-Beschreibung erzeugen und mit End-to-End-Tests abgleichen.
7. Health-Endpunkt, strukturierte Logs und kontrolliertes Shutdown-Verhalten einrichten.
8. Gesamten Prüfpfad aus Build, Linting, Tests und Startprüfung ausführen.

Prüfpunkte und typische Fehler

• Module werden fachlich geschnitten und nicht nur nach Controller, Service und Entity getrennt.
• Controller enthalten keine Datenbankzugriffe oder umfangreiche Fachlogik.
• DTOs bleiben eigenständige API-Verträge.
• Globale Querschnittsfunktionen besitzen eine bewusst dokumentierte Reihenfolge.
• Konfiguration scheitert früh und verständlich bei ungültigen Werten.
• End-to-End-Tests prüfen reale HTTP-Antworten, Statuscodes und Fehlerverträge.