BIGboss248/nextjs-wordpress

Next.js Health Check & Observability Skill (nextjs-healthcheck)

Ein modularer, produktionsreifer Workflow zum Erstellen und Verwalten von Health-Check-Endpunkten (/api/health), Docker-Compose-Health-Proben ohne externe Abhängigkeiten und Node.js-Laufzeitmetriken für Next.js-App-Router-Anwendungen.

---

Workflow-Übersicht

flowchart TD
    A["1. Projekt scannen<br/>(Datenbank & Docker Compose)"] --> B["2. /api/health generieren<br/>(Vorlagen mit Metriken)"]
    B --> C["3. Docker-Proben injizieren<br/>(docker-compose.yml)"]
    C --> D["4. Überprüfen & validieren<br/>(curl & docker compose ps)"]

---

Schritt-für-Schritt-Ausführungs-Runbook

Befolgen Sie diese Checkliste nacheinander, um das Anwendungs-Health-Monitoring zu implementieren und zu überprüfen:

1. Projekterkennung & Abhängigkeitsprüfung

• Route-Handler-Pfad lokalisieren: Prüfen, ob das Projekt app/ oder src/app/ verwendet (Ziel: app/api/health/route.ts oder src/app/api/health/route.ts).
• Datenbank / Externe Speicher erkennen: package.json nach ORMs und Clients durchsuchen (Prisma, Drizzle, Supabase, Mongoose, PostgreSQL, Redis). Siehe database-probes.md.
• Docker-Compose-Dateien lokalisieren: docker-compose.yml, docker-compose.prod.yml oder andere Compose-Stacks finden. Siehe docker-compose-probes.md.

2. Health-Check-Route-Handler implementieren

• Route-Vorlage auswählen:
  • Keine Datenbank: route-no-db.ts.template bereitstellen.
  • Datenbank vorhanden: route-with-db.ts.template bereitstellen und den projektspezifischen DB-Client mit einem strikten 2-Sekunden-Timeout anbinden.
• Dynamische Ausführung erzwingen: export const dynamic = "force-dynamic"; und Cache-Control: no-store, no-cache, must-revalidate Header sicherstellen.
• Nicht-blockierende Metriken konfigurieren: V8-Heap-Auslastung, Event-Loop-Verzögerung (p99 über perf_hooks) und Prozess-Betriebszeit sammeln. Siehe status-and-metrics.md.
• HTTP-Statuscode-Disziplin durchsetzen: 200 OK für healthy/degraded und 503 Service Unavailable für unhealthy zurückgeben.

3. Docker-Compose-Health-Proben konfigurieren

• Next.js-Dienste identifizieren: Die erkannten Compose-Dateien nach Next.js-Dienstblöcken durchsuchen (nextjs-app, web, app).
• Healthcheck-Block injizieren: Die abhängigkeitsfreie Node.js-fetch-Health-Probe aus docker-compose.healthcheck.template.yml hinzufügen.

4. Überprüfung & Tests

• Lokaler API-Test:

  curl -i http://localhost:3000/api/health
  

  HTTP-200-Antwort mit gültigem JSON-Payload überprüfen (status, timestamp, uptimeSeconds, checks).
• Compose-Health-Status-Prüfung:

  docker compose ps
  

  Übergang des Dienststatus zu (healthy) nach der Startphase überprüfen.

---

Edge Cases & Bekannte KI-Fallstricke

[!WARNING]

• Fehlendes force-dynamic: Der Next.js App Router kann Routen statisch evaluieren oder cachen, wenn export const dynamic = "force-dynamic" fehlt, was zu veralteten Zeitstempeln und eingefrorenen Betriebszeitmetriken führt.
• Hängende Datenbankverbindungen: Führen Sie niemals Abfragen an externe Datenbanken ohne ein Race-Timeout (max. 2000 ms) durch. Unbehandelte Netzwerklatenz kann zu einer Erschöpfung des Request-Pools führen.
• Externe Tool-Abhängigkeiten in Containern: Verwenden Sie kein curl oder wget in Docker-Health-Checks; produktionsnahe Minimal-Images (z.B. node:alpine oder distroless) enthalten diese oft nicht. Verwenden Sie stattdessen das native Node.js fetch über node -e.
• Geheimnisleaks: Geben Sie niemals Datenbank-Verbindungs-URLs, Passwörter oder interne rohe Fehler-Traces im öffentlichen /api/health-Antwort-Payload aus.

---

Ausgabe-Zusammenfassungs-Schema

Nach Abschluss der Health-Check-Einrichtung einen prägnanten Zusammenfassungsbericht bereitstellen:

### Health-Monitoring-Konfiguration abgeschlossen

- **Route-Handler**: `[app/api/health/route.ts](file:///...)`
- **Datenbank-Proben**: [Konfiguriert: Prisma / Drizzle / Keine] (Timeout: 2000ms)
- **Laufzeitmetriken**: V8-Heap-Auslastung & Event-Loop-Verzögerung (p99)
- **Aktualisierte Docker-Compose-Stacks**: `docker-compose.yml`, `docker-compose.prod.yml`
- **Überprüfungsstatus**: BESTANDEN (HTTP 200 / Container Healthy)

---

Referenzanleitungen & Vorlagen

• Referenz zu Statuscodes & Metriken — Architektonische Statusmatrix, Speicherformeln und Verzögerungsschwellen.
• Referenz zu Datenbank-Proben — Erkennungscheckliste, Timeout-Wrapping und ORM-Probenmuster.
• Referenz zu Docker-Compose-Proben — Dienstabgleichsregeln und abhängigkeitsfreie Fetch-Definitionen.
• Route-Vorlage (Keine DB) — Vollständiger Route-Handler für zustandslose Anwendungen.
• Route-Vorlage (Mit DB) — Vollständiger Route-Handler mit Abhängigkeitsproben.
• Docker-Compose-Healthcheck-Vorlage — Wiederverwendbares Compose-Snippet.