Lập lịch tác vụ tự động bằng Task Scheduling (Cron Jobs)

Trong lập trình ứng dụng Backend, việc thiết lập các tác vụ tự động chạy theo chu kỳ thời gian là rất phổ biến (ví dụ: tự động dọn dẹp các tài khoản chưa kích hoạt sau 30 ngày, gửi báo cáo doanh thu lúc 0h mỗi ngày, sao lưu dữ liệu lúc 2h sáng). NestJS hỗ trợ lập lịch tác vụ thông qua module chuyên biệt @nestjs/schedule, cho phép bạn thiết lập các Cron Jobs cực kỳ đơn giản bằng các Decorator trực quan. Tài liệu này hướng dẫn cách cài đặt và ra lệnh cho Claude Code viết các tác vụ tự động chạy chuẩn xác nhất.

1. Cài đặt và Kích hoạt

Cài đặt thư viện:

npm install @nestjs/schedule

Kích hoạt ScheduleModule trong `app.module.ts`:

src/app.module.ts

import { Module } from '@nestjs/common';
import { ScheduleModule } from '@nestjs/schedule';
import { TasksModule } from './tasks/tasks.module';

@Module({
  imports: [
    ScheduleModule.forRoot(), // Kích hoạt bộ lập lịch tác vụ
    TasksModule,
  ],
})
export class AppModule {}

2. Các Decorator Lập lịch phổ biến

NestJS hỗ trợ 3 dạng lập lịch chính dựa trên tần suất chạy:

A. `@Cron()` - Tác vụ chạy theo chu kỳ Lịch biểu

Dùng khi bạn muốn chạy tác vụ vào một thời điểm chính xác (ví dụ: 12h trưa mỗi ngày).

src/tasks/tasks.service.ts

import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';

@Injectable()
export class TasksService {
  private readonly logger = new Logger(TasksService.name);

  // Cách 1: Sử dụng hằng số có sẵn của NestJS (Khuyên dùng)
  @Cron(CronExpression.EVERY_HOUR)
  handleHourlyTask() {
    this.logger.debug('Tác vụ tự động chạy mỗi giờ một lần.');
  }

  // Cách 2: Sử dụng biểu thức Cron tùy chỉnh (Standard Cron Expression)
  // Quy tắc 6 trường: giây | phút | giờ | ngày-trong-tháng | tháng | ngày-trong-tuần
  @Cron('0 30 2 * * *') // Chạy vào lúc 02:30:00 sáng mỗi ngày
  handleBackupTask() {
    this.logger.log('Bắt đầu sao lưu cơ sở dữ liệu hệ thống...');
  }
}

B. `@Interval()` - Tác vụ chạy lặp lại sau mỗi chu kỳ mili-giây

Dùng khi bạn muốn tác vụ chạy lặp lại liên tục sau mỗi khoảng thời gian cố định kể từ lúc ứng dụng khởi động thành công (1 giây = 1000 mili-giây).

import { Interval } from '@nestjs/schedule';

@Interval(10000) // Chạy lặp lại sau mỗi 10 giây (10,000 ms)
handleInterval() {
  console.log('Tác vụ kiểm tra trạng thái dịch vụ chạy định kỳ mỗi 10 giây.');
}

C. `@Timeout()` - Tác vụ chỉ chạy duy nhất 1 lần sau khi khởi động

Dùng khi bạn muốn thực hiện một logic khởi tạo hoặc cấu hình hệ thống trễ một khoảng thời gian sau khi ứng dụng NestJS vừa khởi động xong.

import { Timeout } from '@nestjs/schedule';

@Timeout(5000) // Chạy duy nhất một lần sau khi app start 5 giây
handleTimeout() {
  console.log('Tác vụ khởi tạo cấu hình hệ thống ban đầu đã hoàn tất.');
}

3. Hướng dẫn viết Prompt cho Claude Code lập lịch tác vụ

Khi làm việc với Claude Code, bạn chỉ cần chỉ rõ Tần suất chạy hoặc Mục đích nghiệp vụ, AI sẽ tự động tính toán biểu thức Cron hoặc chọn Decorator phù hợp nhất.

Prompt mẫu tạo Cron Job dọn dẹp hệ thống:

Hãy tích hợp tính năng tự động chạy tác vụ (Task Scheduling) trong NestJS giúp tôi:
1. Đăng ký 'ScheduleModule' trong 'app.module.ts'.
2. Tạo một Service 'CleanupTasksService' trong thư mục 'src/tasks'.
3. Viết một hàm 'deleteExpiredTokens' tự động chạy định kỳ lúc 3:00 sáng mỗi ngày (sử dụng Cron Expression).
4. Logic bên trong hàm:
   - Gọi đến 'AuthService' để xóa toàn bộ các JWT Token đã hết hạn lưu trong cơ sở dữ liệu.
   - Sử dụng thư viện 'Logger' của '@nestjs/common' để ghi nhật ký bắt đầu và kết thúc quá trình dọn dẹp.

​Lập lịch tác vụ tự động bằng Task Scheduling (Cron Jobs)

​1. Cài đặt và Kích hoạt

​Cài đặt thư viện:

​Kích hoạt ScheduleModule trong app.module.ts:

​2. Các Decorator Lập lịch phổ biến

​A. @Cron() - Tác vụ chạy theo chu kỳ Lịch biểu

​B. @Interval() - Tác vụ chạy lặp lại sau mỗi chu kỳ mili-giây

​C. @Timeout() - Tác vụ chỉ chạy duy nhất 1 lần sau khi khởi động

​3. Hướng dẫn viết Prompt cho Claude Code lập lịch tác vụ

​Prompt mẫu tạo Cron Job dọn dẹp hệ thống: