Événements du Cycle de Vie

Une application Nest, tout comme chaque élément d’application, a un cycle de vie géré par Nest. Nest fournit des hooks de cycle de vie qui offrent une visibilité sur les événements clés du cycle de vie et permettent d’agir (exécuter du code enregistré sur vos modules, fournisseurs ou contrôleurs) lorsqu’ils se produisent.

Séquence du cycle de vie

Le diagramme suivant montre la séquence des événements clés du cycle de vie de l’application, depuis le moment où l’application est bootstrappée jusqu’à ce que le processus Node se termine. Nous pouvons diviser le cycle de vie global en trois phases : initialisation, exécution et termination. Grâce à ce cycle de vie, vous pouvez prévoir l’initialisation appropriée des modules et des services, gérer les connexions actives et arrêter proprement votre application lorsqu’elle reçoit un signal de terminaison.

Événements du cycle de vie

Les événements du cycle de vie se produisent lors du bootstrapping et de l’arrêt de l’application. Nest appelle les méthodes de hook de cycle de vie enregistrées sur les modules, les fournisseurs et les contrôleurs à chacun des événements de cycle de vie suivants (les hooks d’arrêt doivent d’abord être activés, comme décrit ci-dessous). Comme le montre le diagramme ci-dessus, Nest appelle également les méthodes sous-jacentes appropriées pour commencer à écouter les connexions et à arrêter d’écouter les connexions.

Dans le tableau suivant, onModuleDestroy, beforeApplicationShutdown et onApplicationShutdown ne sont déclenchés que si vous appelez explicitement app.close() ou si le processus reçoit un signal système spécial (comme SIGTERM) et que vous avez correctement appelé enableShutdownHooks au bootstrap de l’application (voir ci-dessous la partie Arrêt de l’application).

Méthode de hook de cycle de vie	Événement de cycle de vie déclenchant l’appel de la méthode de hook
onModuleInit()	Appelée une fois que les dépendances du module hôte ont été résolues.
onApplicationBootstrap()	Appelée une fois tous les modules initialisés, mais avant d’écouter les connexions.
onModuleDestroy()*	Appelée après qu’un signal de terminaison (par exemple, SIGTERM) a été reçu.
beforeApplicationShutdown()*	Appelée après que tous les gestionnaires de onModuleDestroy() ont été terminés (promesses résolues ou rejetées). Une fois terminé (promesses résolues ou rejetées), toutes les connexions existantes seront fermées (appel de app.close()).
onApplicationShutdown()*	Appelée après la fermeture des connexions (app.close() résout).

• Pour ces événements, si vous n’appelez pas explicitement app.close(), vous devez opter pour les faire fonctionner avec des signaux système tels que SIGTERM. Voir Arrêt de l’application ci-dessous.

Danger

L’avertissement suivant s’applique : Les hooks de cycle de vie listés ci-dessus ne sont pas déclenchés pour les classes à portée de requête. Les classes à portée de requête ne sont pas liées au cycle de vie de l’application et leur durée de vie est imprévisible. Elles sont exclusivement créées pour chaque requête et automatiquement collectées par le garbage collector après l’envoi de la réponse.

Astuce

L’ordre d’exécution de onModuleInit() et onApplicationBootstrap() dépend directement de l’ordre des imports de module, en attendant le hook précédent.

Utilisation

Chaque hook de cycle de vie est représenté par une interface. Les interfaces sont techniquement optionnelles car elles n’existent pas après la compilation TypeScript. Néanmoins, il est bon de les utiliser afin de bénéficier d’un typage fort et d’outils d’éditeur. Pour enregistrer un hook de cycle de vie, implémentez l’interface appropriée. Par exemple, pour enregistrer une méthode à appeler lors de l’initialisation du module dans une classe particulière (par exemple, Contrôleur, Fournisseur ou Module), implémentez l’interface OnModuleInit en fournissant une méthode onModuleInit(), comme montré ci-dessous :

Exemple d'implémentation de hook de module

import { Injectable, OnModuleInit } from '@nestjs/common';

@Injectable()
export class UsersService implements OnModuleInit {
  onModuleInit() {
    console.log(`Le module a été initialisé.`);
  }
}

Initialisation asynchrone

Les hooks OnModuleInit et OnApplicationBootstrap vous permettent de différer le processus d’initialisation de l’application (retourner une Promise ou marquer la méthode comme async et await la complétion d’une méthode asynchrone dans le corps de la méthode).

async onModuleInit(): Promise<void> {
  await this.fetch();
}

Arrêt de l’application

Les hooks onModuleDestroy(), beforeApplicationShutdown() et onApplicationShutdown() sont appelés dans la phase de terminaison (en réponse à un appel explicite à app.close() ou à la réception de signaux système tels que SIGTERM, si opté-in). Cette fonctionnalité est souvent utilisée avec Kubernetes pour gérer les cycles de vie des conteneurs, par Heroku pour les dynos ou des services similaires.

Les écouteurs de hook d’arrêt consomment des ressources système, donc ils sont désactivés par défaut. Pour utiliser les hooks d’arrêt, vous devez activer les écouteurs en appelant enableShutdownHooks() :

Activation des hooks d'arrêt

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Commence à écouter les hooks d'arrêt
  app.enableShutdownHooks();

  await app.listen(3000);
}
bootstrap();

Attention

En raison de limitations inhérentes à la plateforme, NestJS a un support limité pour les hooks d’arrêt d’application sur Windows. Vous pouvez vous attendre à ce que SIGINT fonctionne, ainsi que SIGBREAK et dans une certaine mesure SIGHUP - en savoir plus. Cependant, SIGTERM ne fonctionnera jamais sur Windows car tuer un processus dans le gestionnaire de tâches est inconditionnel, c’est-à-dire qu’il n’y a aucun moyen pour une application de détecter ou de l’empêcher. Voici une documentation pertinente de libuv pour en apprendre davantage sur la manière dont SIGINT, SIGBREAK et d’autres sont gérés sur Windows. De plus, consultez la documentation de Node.js sur les événements de signal de processus.

Appeler app.close() ne termine pas le processus Node mais ne déclenche que les hooks onModuleDestroy() et onApplicationShutdown(), donc s’il existe des intervalles, des tâches de fond longue durée, etc., le processus ne sera pas automatiquement terminé.