BIGboss248/nextjs-wordpress

Compétence de Vérification de Santé & Observabilité Next.js (nextjs-healthcheck)

Un flux de travail modulaire et prêt pour la production pour créer et maintenir des points de terminaison de vérification de santé (/api/health), des sondes de santé Docker Compose sans dépendances et des métriques d'exécution Node.js dans les applications Next.js App Router.

---

Aperçu du Flux de Travail

flowchart TD
    A["1. Analyser le Projet<br/>(Base de données & Docker Compose)"] --> B["2. Générer /api/health<br/>(Modèles avec Métriques)"]
    B --> C["3. Injecter les Sondes Docker<br/>(docker-compose.yml)"]
    C --> D["4. Vérifier & Valider<br/>(curl & docker compose ps)"]

---

Runbook d'Exécution Étape par Étape

Suivez cette liste de vérification séquentiellement pour implémenter et vérifier la surveillance de la santé de l'application :

1. Découverte du Projet & Inspection des Dépendances

• Localiser le Chemin du Gestionnaire de Route : Déterminez si le projet utilise app/ ou src/app/ (cible : app/api/health/route.ts ou src/app/api/health/route.ts).
• Détecter la Base de Données / les Stockages Externes : Analysez package.json à la recherche d'ORM et de clients (Prisma, Drizzle, Supabase, Mongoose, PostgreSQL, Redis). Consultez database-probes.md.
• Localiser les Fichiers Docker Compose : Découvrez docker-compose.yml, docker-compose.prod.yml ou d'autres piles compose. Consultez docker-compose-probes.md.

2. Implémenter le Gestionnaire de Route de Vérification de Santé

• Sélectionner le Modèle de Route :
  • Si Pas de Base de Données : Déployez route-no-db.ts.template.
  • Si Base de Données Présente : Déployez route-with-db.ts.template et câblez le client de base de données spécifique au projet avec un timeout strict de 2 secondes.
• Appliquer l'Exécution Dynamique : Assurez-vous que export const dynamic = "force-dynamic"; et les en-têtes Cache-Control: no-store, no-cache, must-revalidate sont présents.
• Configurer les Métriques Non Bloquantes : Collectez la saturation du tas V8, le délai de la boucle d'événements ($p99$ lag via perf_hooks) et la durée de fonctionnement du processus. Consultez status-and-metrics.md.
• Appliquer la Discipline des Codes de Statut HTTP : Retournez 200 OK pour healthy/degraded et 503 Service Unavailable pour unhealthy.

3. Configurer les Sondes de Santé Docker Compose

• Identifier les Services Next.js : Inspectez les fichiers compose détectés pour les blocs de service Next.js (nextjs-app, web, app).
• Injecter le Bloc Healthcheck : Ajoutez une sonde de santé Node.js fetch sans dépendances à partir de docker-compose.healthcheck.template.yml.

4. Vérification & Test

• Test API Local :

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

  Vérifiez la réponse HTTP 200 avec une charge utile JSON valide (status, timestamp, uptimeSeconds, checks).
• Vérification de l'État de Santé du Service Compose :

  docker compose ps
  

  Vérifiez que l'état du service passe à (healthy) après la période de démarrage initiale.

---

Cas Limites & Pièges Connus de l'IA

[!WARNING]

• force-dynamic Manquant : Le Next.js App Router peut évaluer statiquement ou mettre en cache les réponses de route si export const dynamic = "force-dynamic" est omis, ce qui entraîne des horodatages obsolètes et des métriques de durée de fonctionnement figées.
• Connexions de Base de Données Bloquantes : Ne jamais interroger des bases de données externes sans un timeout de compétition (max 2000ms). Une latence réseau non gérée se répercutera en épuisement du pool de requêtes.
• Dépendances d'Outils Externes dans les Conteneurs : Ne pas compter sur curl ou wget dans les vérifications de santé Docker ; les images minimales de production (par exemple node:alpine ou distroless) en manquent souvent. Utilisez fetch natif Node.js via node -e.
• Fuites de Secrets : Ne jamais imprimer d'URLs de connexion à la base de données, de mots de passe ou de traces d'erreurs internes brutes dans la charge utile publique de la réponse /api/health.

---

Schéma de Résumé de Sortie

Après avoir terminé la configuration de la vérification de santé, fournissez un rapport de résumé concis :

### Configuration de la Surveillance de Santé Terminée

- **Gestionnaire de Route** : `[app/api/health/route.ts](file:///...)`
- **Sondes de Base de Données** : [Configurées : Prisma / Drizzle / Aucune] (Timeout : 2000ms)
- **Métriques d'Exécution** : Saturation du Tas V8 & Délai de la Boucle d'Événements (p99)
- **Piles Docker Compose Mises à Jour** : `docker-compose.yml`, `docker-compose.prod.yml`
- **Statut de Vérification** : RÉUSSI (HTTP 200 / Conteneur Sain)

---

Guides de Référence & Modèles

• Référence des Codes de Statut & Métriques — Matrice d'état architectural, formules de mémoire et seuils de latence.
• Référence des Sondes de Base de Données — Liste de vérification de détection, encapsulation des timeouts et modèles de sonde ORM.
• Référence des Sondes Docker Compose — Règles de correspondance des services et définitions de fetch sans dépendances.
• Modèle de Route (Sans DB) — Gestionnaire de route complet pour applications sans état.
• Modèle de Route (Avec DB) — Gestionnaire de route complet avec sondes de dépendances.
• Modèle de Vérification de Santé Docker Compose — Fragment compose réutilisable.