Lifecycle-хуки и graceful shutdown

У lifecycle две фазы, у каждой фиксированный порядок

У Nest-приложения есть рождение и смерть, и оба — упорядоченные события, в которые можно встроиться. Знание порядка — это вся суть: оно говорит, когда твои внедрённые зависимости гарантированно готовы и когда их безопасно закрывать.

Init идёт снизу вверх. Когда ты вызываешь app.listen() (или app.init()), Nest резолвит граф зависимостей и затем запускает, на провайдер/модуль:

1. onModuleInit() — вызывается для модуля после того, как разрешены собственные зависимости этого модуля. Это первый момент, когда твои внедрённые провайдеры гарантированно сконструированы и связаны.
2. onApplicationBootstrap() — вызывается после того, как каждый модуль закончил инициализацию, прямо перед тем, как сервер начнёт слушать. Это первый момент, когда готово всё приложение, включая провайдеры из других модулей.

Teardown идёт в обратном порядке. На app.close() или сигнал завершения Nest разматывает в обратном порядке зависимостей:

1. onModuleDestroy() — пришёл сигнал завершения; начинаем разбирать.
2. beforeApplicationShutdown(signal) — выполняется после всех обработчиков onModuleDestroy(), до закрытия соединений; получает сигнал ("SIGTERM", "SIGINT", …).
3. onApplicationShutdown(signal) — выполняется после закрытия соединений; последний вздох, где ты освобождаешь пулы, consumer’ы очередей и клиентов.

Обратный порядок важен: модуль, зависящий от базы данных, разбирается до модуля базы — так что он никогда не пытается использовать соединение, которого уже нет. Каждый интерфейс вносит один метод — OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, BeforeApplicationShutdown, OnApplicationShutdown — и ты реализуешь только нужные. Асинхронные хуки ожидаются: возврат Promise приостанавливает последовательность, пока он не зарезолвится.

onModuleInit против конструктора

Конструктор провайдера выполняется при инстанцировании, пока Nest ещё связывает граф. В этот момент твои внедрённые зависимости существуют (они сконструированы первыми), но любая нужная им асинхронная настройка — TCP-соединение, прогретый кэш, подтянутый конфиг — ещё не выполнилась. Делать настоящий I/O в конструкторе — ловушка: конструкторы не могут быть async, так что ты либо блокируешь синхронно, либо стреляешь и забываешь висящий промис, и у тебя нет чистого места обработать сбой.

onModuleInit() — это ответ. Когда нужно открыть соединение, прогреть кэш или убедиться, что внешний сервис доступен до прихода трафика, — именно сюда принадлежит этот код. Он выполняется один раз, сразу после разрешения зависимостей модуля, он может быть async, и Nest ожидает его перед тем, как двигаться дальше. Это делает его верным домом для прогрева, которому нужны готовые зависимости:

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

@Injectable()
export class DatabaseService implements OnModuleInit, OnApplicationShutdown {
  private pool!: Pool;

  constructor(private readonly config: ConfigService) {
    // конструктор: зависимости есть, но НИКАКОГО async I/O здесь
    this.pool = new Pool({ connectionString: this.config.get('DB_URL') });
  }

  async onModuleInit(): Promise<void> {
    // прогрев: зависимости готовы, await учитывается
    await this.pool.query('SELECT 1'); // докажем, что пул коннектится, до приёма трафика
  }

  async onApplicationShutdown(signal: string): Promise<void> {
    // слив: соединения закрываются последними, после завершения работы в полёте
    console.log(`shutting down on ${signal}`);
    await this.pool.end(); // закрыть каждый клиент в пуле
  }
}

Разделение намеренное: конструируй дёшево, коннекться в onModuleInit, освобождай в onApplicationShutdown. Если запрос прогрева выбросит, Nest прервёт старт с понятной ошибкой, вместо того чтобы поднять сервис, который не может достучаться до базы. Используй onApplicationBootstrap вместо onModuleInit только когда прогрев зависит от того, что полностью поднят другой модуль — например, прогрев кэша из сервиса, объявленного в другом модуле, который сначала должен закончить свой onModuleInit.

Graceful shutdown, сделанный правильно

Shutdown-хуки не делают ничего, пока ты не подпишешься. app.enableShutdownHooks() регистрирует слушателей процесса на SIGTERM/SIGINT, чтобы Nest мог запустить teardown-последовательность; это выключено по умолчанию, потому что навешивание слушателей сигналов имеет цену, и Nest не станет навязывать её молча.

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    // также принудительно закрыть простаивающие Keep-Alive сокеты, чтобы процесс реально вышел
    forceCloseConnections: true,
  });
  app.enableShutdownHooks(); // ОБЯЗАТЕЛЬНО: иначе SIGTERM просто убьёт процесс
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Теперь фактическая последовательность на SIGTERM: перестать принимать новую работу, слить запросы в полёте, затем закрыть ресурсы. HTTP-адаптер Nest останавливает сервер и ждёт завершения открытых ответов, прежде чем зарезолвить закрытие, — но долгоживущие сокеты Connection: Keep-Alive могут держать процесс в заложниках, и поэтому существует forceCloseConnections. Как только запросы слиты, твой onApplicationShutdown закрывает пул базы, consumer’ы очередей и Kafka-клиентов — в обратном порядке зависимостей, так что ничто не закрывает ресурс, который ещё нужен другому провайдеру.