Sự kiện vòng đời (Lifecycle Events)

Một ứng dụng Nest, cũng như mọi thành phần ứng dụng, đều có một vòng đời (lifecycle) do Nest quản lý. Nest cung cấp lifecycle hook giúp bạn quan sát các sự kiện vòng đời quan trọng, và có khả năng hành động (chạy code đã đăng ký trên module, provider hoặc controller của bạn) khi các sự kiện đó xảy ra.

Trình tự vòng đời (Lifecycle sequence)

Sơ đồ dưới đây mô tả trình tự các sự kiện vòng đời quan trọng của ứng dụng, từ lúc ứng dụng được bootstrap cho tới khi tiến trình node thoát. Ta có thể chia toàn bộ vòng đời thành ba giai đoạn: khởi tạo (initializing), chạy (running) và kết thúc (terminating). Nhờ vòng đời này, bạn có thể lên kế hoạch khởi tạo phù hợp cho module và service, quản lý các kết nối đang hoạt động, và tắt ứng dụng một cách nhẹ nhàng (gracefully) khi nhận được tín hiệu kết thúc (termination signal).

Các sự kiện vòng đời

Sự kiện vòng đời xảy ra trong lúc ứng dụng bootstrap và shutdown. Nest gọi các phương thức lifecycle hook đã đăng ký trên module, provider và controller tại mỗi sự kiện vòng đời sau đây (shutdown hook cần được bật trước, như mô tả bên dưới). Như sơ đồ trên thể hiện, Nest cũng gọi các phương thức nội bộ tương ứng để bắt đầu lắng nghe kết nối, và để dừng lắng nghe kết nối.

Trong bảng dưới đây, onModuleInit và onApplicationBootstrap chỉ được kích hoạt nếu bạn gọi tường minh app.init() hoặc app.listen().

Trong bảng dưới đây, onModuleDestroy, beforeApplicationShutdown và onApplicationShutdown chỉ được kích hoạt nếu bạn gọi tường minh app.close() hoặc nếu tiến trình nhận một tín hiệu hệ thống đặc biệt (như SIGTERM) và bạn đã gọi đúng enableShutdownHooks lúc bootstrap ứng dụng (xem phần Application shutdown bên dưới).

* Với các sự kiện này, nếu bạn không gọi tường minh app.close(), bạn phải chủ động bật (opt-in) để chúng hoạt động với các tín hiệu hệ thống như SIGTERM. Xem Application shutdown bên dưới.

Cách dùng

Mỗi lifecycle hook được đại diện bởi một interface. Về mặt kỹ thuật, các interface này là tùy chọn vì chúng không tồn tại sau khi biên dịch TypeScript. Tuy nhiên, dùng chúng vẫn là một thực hành tốt để tận dụng type checking mạnh và hỗ trợ từ editor. Để đăng ký một lifecycle hook, hãy implement interface tương ứng. Ví dụ, để đăng ký một phương thức được gọi trong lúc khởi tạo module trên một class cụ thể (ví dụ: Controller, Provider hoặc Module), hãy implement interface OnModuleInit bằng cách cung cấp phương thức onModuleInit(), như bên dưới:

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

@Injectable()
export class UsersService implements OnModuleInit {
  onModuleInit() {
    console.log(`The module has been initialized.`);
  }
}

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

@Injectable()
export class UsersService {
  onModuleInit() {
    console.log(`The module has been initialized.`);
  }
}

Khởi tạo bất đồng bộ (Asynchronous initialization)

Cả hai hook OnModuleInit và OnApplicationBootstrap đều cho phép bạn trì hoãn quá trình khởi tạo ứng dụng (trả về một Promise, hoặc đánh dấu phương thức là async và await một lệnh gọi bất đồng bộ hoàn tất trong thân phương thức).

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

async onModuleInit() {
  await this.fetch();
}

Application shutdown

Các hook onModuleDestroy(), beforeApplicationShutdown() và onApplicationShutdown() được gọi trong giai đoạn kết thúc (terminating) (khi có lời gọi tường minh tới app.close() hoặc khi nhận tín hiệu hệ thống như SIGTERM nếu đã opt-in). Tính năng này thường được dùng cùng Kubernetes để quản lý vòng đời container, hoặc bởi Heroku cho dynos hay các dịch vụ tương tự.

Shutdown hook listener tiêu tốn tài nguyên hệ thống, nên mặc định chúng bị tắt. Để dùng shutdown hook, bạn phải bật listener bằng cách gọi enableShutdownHooks():

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

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

  // Bắt đầu lắng nghe shutdown hook
  app.enableShutdownHooks();

  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

Khi ứng dụng nhận một tín hiệu kết thúc, nó sẽ gọi lần lượt các phương thức onModuleDestroy(), beforeApplicationShutdown(), rồi onApplicationShutdown() đã đăng ký (theo đúng trình tự mô tả ở trên) với tín hiệu tương ứng là tham số đầu tiên. Nếu một hàm đã đăng ký await một lệnh gọi bất đồng bộ (trả về promise), Nest sẽ không tiếp tục trình tự cho tới khi promise đó resolve hoặc reject.

@Injectable()
class UsersService implements OnApplicationShutdown {
  onApplicationShutdown(signal: string) {
    console.log(signal); // ví dụ "SIGINT"
  }
}

@Injectable()
class UsersService implements OnApplicationShutdown {
  onApplicationShutdown(signal) {
    console.log(signal); // ví dụ "SIGINT"
  }
}