Seminar NestJS – Migration auf Version 11

Ein Framework-Upgrade ist erfolgreich, wenn Verhalten, Build, Tests und Betrieb nachweisbar stabil bleiben. Eine erfolgreiche Paketinstallation allein belegt keine Kompatibilität von Routen, Middleware, Adaptern, Drittmodulen oder Health Checks.

Der Workshop verwendet einen kontrollierten Migrationspfad mit Inventur, Baseline, schrittweiser Aktualisierung und Rückfallmöglichkeit. Er konzentriert sich auf erfahrene Teams und verzichtet auf allgemeine Grundlagen.

Inhaltsübersicht

• Lernziele
• Bestandsaufnahme und belastbare Baseline
• Schrittweise technische Migration
• Abnahme, Rollout und Rückfall
• Migrationslabor: Anwendung von Version 10 auf 11
• Prüfpunkte und typische Fehler

Lernziele

• Runtime, Paketgraph, Adapter und projektspezifische Erweiterungen vollständig inventarisieren.
• Relevante Verhaltensänderungen zwischen NestJS 10 und 11 auf die Anwendung abbilden.
• Routing, Query Parsing, Middleware, dynamische Module, Cache, Konfiguration und Health Checks prüfen.
• Migration in kleinen, reproduzierbaren Schritten durchführen und durch Tests absichern.
• Rollout, Beobachtung, Datenbankverträglichkeit und Rollback vor der Freigabe klären.

Bestandsaufnahme und belastbare Baseline

Vor jeder Änderung wird ein reproduzierbarer Ausgangszustand hergestellt. Build, Tests, zentrale API-Verträge und Betriebskennzahlen bilden die Vergleichsbasis.

1. Node.js-, Paketmanager-, NestJS-, Plattformadapter- und TypeScript-Versionen erfassen.
2. Direkte und transitive NestJS-Abhängigkeiten sowie Community-Erweiterungen inventarisieren.
3. Build, Linting, Unit-, Integrations- und End-to-End-Tests im Ausgangszustand ausführen.
4. Routen, Query-Parameter, Middleware-Ketten, Cache-Verhalten und Health-Endpunkte prüfen.
5. Produktionsrelevante Latenz-, Fehler- und Startwerte dokumentieren.
6. Branch-, Tag- und Rückfallstrategie vor der ersten Paketänderung festlegen.

Entscheidungskriterien und Hinweise

• Eine Migration ohne belastbare Baseline kann Verhaltensänderungen nicht zuverlässig bewerten.
• Ungepflegte Drittmodule erhalten vorab eine Ersatz- oder Risikostrategie.

Schrittweise technische Migration

Die Aktualisierung trennt Framework-Kern, Plattformadapter und optionale Module. Dadurch bleiben Fehlerursachen eingrenzbar und Änderungen kontrolliert rücknehmbar.

1. Runtime-Voraussetzungen aktualisieren und lokale sowie CI-Umgebungen angleichen.
2. NestJS-Kernpakete und CLI auf kompatible Versionen anheben.
3. Express- oder Fastify-Adapter sowie zugehörige Middleware aktualisieren.
4. Routingmuster, Wildcards, optionale Parameter und Query Parsing mit Contract-Tests prüfen.
5. Dynamische Module, Konfigurationsfabriken und Provider-Injektion testen.
6. Cache-Integration, Health Checks und plattformspezifische Erweiterungen kontrollieren.
7. Veraltete Workarounds entfernen und Änderungen in kleinen Commits dokumentieren.

Entscheidungskriterien und Hinweise

• Kernpakete und Adapter verwenden zueinander kompatible Hauptversionen.
• Router- und Query-Verhalten wird mit realen Requests geprüft und nicht nur kompiliert.

Abnahme, Rollout und Rückfall

Die technische Abnahme umfasst Startverhalten, externe Verträge, Datenbankkompatibilität und Telemetrie. Der neue Stand wird mit der Ausgangsbasis verglichen.

1. Vollständige Testpipeline und API-Contract-Prüfungen ausführen.
2. Smoke Tests für Anmeldung, Kernabläufe, Fehlerfälle und Health-Endpunkte durchführen.
3. Startzeit, Speicher, Antwortzeiten und Fehlerquote mit der Baseline vergleichen.
4. Datenbankmigrationen für parallelen Betrieb rückwärtskompatibel planen.
5. Canary- oder stufenweisen Rollout mit definierten Abbruchschwellen verwenden.
6. Rollback technisch testen und nicht nur als theoretischen Plan dokumentieren.

Entscheidungskriterien und Hinweise

• Datenbankänderungen dürfen einen kurzfristigen Rückfall nicht blockieren.
• Freigabe erfolgt erst nach funktionaler und betrieblicher Abnahme.

Migrationslabor: Anwendung von Version 10 auf 11

Eine vorbereitete Anwendung enthält REST-Routen, Middleware, dynamische Konfiguration, Cache, Datenbankzugriff und Health Checks. Mehrere Stellen reagieren bewusst auf geänderte Plattform- oder Routereigenschaften.

Der gesamte Pfad wird in kleinen Commits durchgeführt. Jeder Commit muss bauen und einen definierten Teil der Testmatrix erfüllen, bevor die nächste Abhängigkeit aktualisiert wird.

1. Baseline mit Paketgraph, Build, Tests, Routen- und Betriebsprüfung erzeugen.
2. Runtime und NestJS-Kernpakete aktualisieren.
3. Plattformadapter, Middleware und Routerfälle migrieren.
4. Dynamische Module, Cache, Konfiguration und Health Checks korrigieren.
5. Vollständige Test- und Contract-Suite ausführen.
6. Stufenweisen Rollout mit Beobachtungsschwellen simulieren.
7. Rollback auf den Ausgangsstand durchführen und Funktionsfähigkeit erneut prüfen.

Prüfpunkte und typische Fehler

• Alle Kernpakete und Adapter verwenden kompatible Hauptversionen.
• Wildcard- und Parameter-Routen werden mit realen Requests geprüft.
• Query Parsing und Middleware-Reihenfolge entsprechen dem vereinbarten API-Vertrag.
• Drittmodule ohne bestätigte Kompatibilität besitzen einen Ersatz- oder Risikoplan.
• Datenbankänderungen verhindern keinen kurzfristigen Rückfall.
• Abnahme enthält Messwerte und einen tatsächlich ausgeführten Rollback-Test.