Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 10: Exception Filter và xử lý lỗi trong NestJS

Tiếp tục với series, ở bài trước TaskFlow API đã chặn được id không hợp lệ, nhưng gọi /projects/99 vẫn nhận 200 với body rỗng. Bài này mình sẽ giới thiệu với mọi người về exception filter và xử lý lỗi trong NestJS để trả về đúng 404 và đưa mọi lỗi của API về cùng một định dạng.

1. Xử lý lỗi mặc định trong NestJS.

Exception nào ném ra trong controller, service, pipe... mà không được bắt sẽ đi đến tầng xử lý exception của NestJS và được chuyển thành response JSON. Việc này do một exception filter toàn cục có sẵn đảm nhận.

Ở Bài 9, ParseIdPipe ném BadRequestException nên client nhận 400. Còn khi code ném một lỗi thông thường, VD throw new Error('Mất kết nối database'), client chỉ nhận {"statusCode":500,"message":"Internal server error"}, nội dung lỗi thật được in ra console kèm stack trace. Nghĩa là chỉ lỗi kiểu HttpException mới quyết định được status code và message trả về.

2. HttpException và các exception có sẵn.

Các bạn ném HttpException (import từ @nestjs/common) với cú pháp như sau:

throw new HttpException(response, status, options);

Trong đó:

  • response: chuỗi thì thành message, object thì được gửi nguyên làm body.
  • status: HTTP status code, nên dùng enum HttpStatus, VD HttpStatus.FORBIDDEN.
  • options (không bắt buộc): cause là lỗi gốc để ghi log (không gửi cho client), errorCode sẽ nói ở phần 3.
throw new HttpException('Bạn không phải chủ project', HttpStatus.FORBIDDEN);
// {"statusCode":403,"message":"Bạn không phải chủ project"}

Thực tế ít khi phải dùng HttpException trực tiếp vì đã có sẵn class con cho từng status: BadRequestException (400), UnauthorizedException (401), ForbiddenException (403), NotFoundException (404), ConflictException (409), InternalServerErrorException (500)... (danh sách đầy đủ tại đây).

VD: Ném NotFoundException trong ProjectsService khi không tìm thấy project. update() và remove() gọi lại findOne() nên cũng trả 404:

- src/projects/projects.service.ts (đoạn trích, thêm NotFoundException vào import từ @nestjs/common)

findOne(id: number): Project {
    const project = this.projects.find((project) => project.id === id);
    if (!project) {
        throw new NotFoundException(`Không tìm thấy project ${id}`);
    }
    return project;
}

update(id: number, dto: UpdateProjectDto): Project {
    const project = this.findOne(id);
    Object.assign(project, dto);
    return project;
}

remove(id: number): void {
    const project = this.findOne(id);
    this.projects.splice(this.projects.indexOf(project), 1);
}

Trong ProjectsController, các bạn sửa kiểu trả về của findOne() và update() từ Project | undefined thành Project:

curl http://localhost:3000/api/v1/projects/99
# {"message":"Không tìm thấy project 99","error":"Not Found","statusCode":404}

3. errorCode và custom exception.

Nhiều lỗi khác nhau có thể cùng status 404, client muốn xử lý riêng từng lỗi thì phải so sánh message, mà message thì có thể đổi. NestJS 12 thêm option errorCode: một mã lỗi cố định gửi kèm trong body:

throw new NotFoundException(`Không tìm thấy project ${id}`, {
    errorCode: 'PROJECT_NOT_FOUND',
});
// {"message":"Không tìm thấy project 99","error":"Not Found","statusCode":404,"errorCode":"PROJECT_NOT_FOUND"}

Lỗi này sẽ còn được ném ở nhiều chỗ, mình gom message và mã lỗi vào một custom exception. Custom exception nên kế thừa HttpException (hoặc class con của nó) để NestJS vẫn trả đúng response:

nest g class projects/exceptions/project-not-found.exception --no-spec --flat --format

- src/projects/exceptions/project-not-found.exception.ts

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

export class ProjectNotFoundException extends NotFoundException {
    constructor(id: number) {
        super(`Không tìm thấy project ${id}`, {
            errorCode: 'PROJECT_NOT_FOUND',
        });
    }
}

Trong findOne() các bạn thay dòng ném lỗi bằng throw new ProjectNotFoundException(id);, import nó từ ./exceptions/project-not-found.exception.js và bỏ NotFoundException khỏi import.

4. Exception filter.

Body mặc định thiếu đường dẫn, thời điểm lỗi, và mỗi loại lỗi có field khác nhau. Muốn tự quyết định response khi có lỗi, các bạn viết exception filter: class cài đặt interface ExceptionFilter với method catch(). Mình sẽ viết filter đưa mọi lỗi của TaskFlow API về dạng { statusCode, errorCode, message, path, timestamp }:

nest g filter common/filters/all-exceptions --no-spec --flat --format

- src/common/filters/all-exceptions.filter.ts

import {
    ArgumentsHost,
    Catch,
    ExceptionFilter,
    HttpException,
    HttpStatus,
} from '@nestjs/common';
import type { Request, Response } from 'express';

export interface ErrorResponse {
    statusCode: number;
    errorCode: string;
    message: string | string[];
    path: string;
    timestamp: string;
}

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
    catch(exception: unknown, host: ArgumentsHost): void {
        const ctx = host.switchToHttp();
        const request = ctx.getRequest<Request>();
        const response = ctx.getResponse<Response>();

        let statusCode: number = HttpStatus.INTERNAL_SERVER_ERROR;
        let message: string | string[] = 'Internal server error';
        let errorCode: string | undefined;

        if (exception instanceof HttpException) {
            statusCode = exception.getStatus();
            errorCode = exception.errorCode;
            const body = exception.getResponse();
            message =
                typeof body === 'string'
                    ? body
                    : ((body as { message?: string | string[] }).message ??
                      exception.message);
        } else {
            // Lỗi ngoài dự kiến: in ra console để sửa, không gửi chi tiết cho client
            console.error(exception);
        }

        const errorResponse: ErrorResponse = {
            statusCode,
            errorCode: errorCode ?? HttpStatus[statusCode] ?? 'UNKNOWN_ERROR',
            message,
            path: request.originalUrl,
            timestamp: new Date().toISOString(),
        };
        response.status(statusCode).json(errorResponse);
    }
}

Trong đó:

  • @Catch() để trống: bắt mọi exception. @Catch(HttpException) thì chỉ bắt HttpException và class con.
  • host: ArgumentsHost chứa các tham số của request, switchToHttp() lấy ra Request, Response của Express. Filter tự gửi response bằng response.status().json().
  • message lấy từ getResponse() để giữ mảng lỗi validation (exception.message lúc đó chỉ là "Bad Request Exception").
  • errorCode: lấy của exception nếu có, không thì lấy tên status trong enum HttpStatus (404 thành NOT_FOUND).
  • Lỗi không phải HttpException luôn trả 500 với message chung, chi tiết chỉ in ra console (Logger ở Bài 26).
  • request.originalUrl: đường dẫn đầy đủ. Với route không tồn tại, request.url đã bị Express cắt thành /v1/abc.

5. Phạm vi áp dụng filter.

Giống pipe ở Bài 9, filter gắn được ở cấp method hoặc controller bằng @UseFilters(AllExceptionsFilter) (import từ @nestjs/common), hoặc toàn cục. Filter cấp controller không bắt được lỗi của route không tồn tại (Cannot GET /api/v1/abc) vì request đó không vào controller nào, nên với định dạng lỗi chung mình đăng ký toàn cục:

- src/main.ts (đoạn trích, ngay sau useGlobalPipes())

import { AllExceptionsFilter } from './common/filters/all-exceptions.filter.js';

// ...
    app.useGlobalFilters(new AllExceptionsFilter());

Khởi động lại ứng dụng (dữ liệu trở về hai project mẫu) và thử các loại lỗi:

curl http://localhost:3000/api/v1/projects/99
# {"statusCode":404,"errorCode":"PROJECT_NOT_FOUND","message":"Không tìm thấy project 99","path":"/api/v1/projects/99","timestamp":"2026-11-15T06:38:43.776Z"}

curl http://localhost:3000/api/v1/abc
# {"statusCode":404,"errorCode":"NOT_FOUND","message":"Cannot GET /api/v1/abc","path":"/api/v1/abc","timestamp":"2026-11-15T06:38:43.825Z"}

curl -X POST http://localhost:3000/api/v1/projects \
    -H 'Content-Type: application/json' \
    -d '{"name":"","ownerId":99}'
# {"statusCode":400,"errorCode":"BAD_REQUEST","message":["property ownerId should not exist","name should not be empty"],"path":"/api/v1/projects","timestamp":"2026-11-15T06:38:43.941Z"}

PATCH, DELETE với /projects/99 cũng nhận 404 cùng định dạng.

Lưu ý: Filter đăng ký bằng useGlobalFilters() nằm ngoài mọi module nên không inject được dependency. Khi cần DI, các bạn đăng ký nó trong providers của module với token APP_FILTER từ @nestjs/core: { provide: APP_FILTER, useClass: AllExceptionsFilter }.

6. Lời kết.

Như vậy mình đã giới thiệu với mọi người về exception filter và xử lý lỗi trong NestJS: HttpException và các exception có sẵn, errorCode mới ở NestJS 12, custom exception, exception filter và một định dạng lỗi chung cho TaskFlow API. Bài sau mình sẽ giới thiệu về middleware trong NestJS và viết một middleware ghi log mọi request gửi đến API.

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha