Nest.js 内置 HTTP 异常笔记

Nest.js 内置 HTTP 异常笔记

一、核心概念

Nest.js 从 @nestjs/common 导出的所有内置 HTTP 异常均继承自 HttpException 基类，每个异常对应标准的 HTTP 状态码，用于在控制器/服务中快速抛出符合 RESTful 规范的错误响应，无需手动拼接状态码和响应格式。

二、完整内置异常列表（含状态码+使用场景）

三、基础使用方式

1. 最简使用（仅指定错误消息）

import { Controller, Get, NotFoundException } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get(':id')
  findOne(@Param('id') id: string) {
    const user = null; // 模拟查询不到用户
    if (!user) {
      // 仅指定消息，error 字段会默认显示 HTTP 状态码对应的默认描述（如 "Not Found"）
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }
}

响应结果：

{
  "message": "User with ID 123 not found",
  "error": "Not Found",
  "statusCode": 404
}

2. 完整使用（指定消息+原因+描述）

import { Controller, Post, BadRequestException } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Post()
  create(@Body() createUserDto: any) {
    try {
      // 模拟参数校验失败
      if (!createUserDto.username) {
        throw new Error('Username is required');
      }
    } catch (error) {
      throw new BadRequestException('Failed to create user', {
        cause: error, // 原始错误（用于日志排查，不会返回给客户端）
        description: 'Username is a mandatory field', // 客户端可见的详细描述
      });
    }
  }
}

响应结果：

{
  "message": "Failed to create user",
  "error": "Username is a mandatory field",
  "statusCode": 400
}

四、进阶用法：自定义 HTTP 异常

若内置异常无法满足需求（如自定义状态码/响应格式），可继承 HttpException 实现自定义异常：

import { HttpException, HttpStatus } from '@nestjs/common';

// 自定义异常：请求频率过高（429 状态码）
export class TooManyRequestsException extends HttpException {
  constructor(message: string = 'Too many requests', description?: string) {
    super(
      {
        message,
        error: description || 'Too Many Requests',
        statusCode: HttpStatus.TOO_MANY_REQUESTS, // 429
      },
      HttpStatus.TOO_MANY_REQUESTS,
    );
  }
}

// 使用自定义异常
@Controller('api')
export class ApiController {
  @Get()
  getData() {
    throw new TooManyRequestsException('请求过于频繁', '请等待 60 秒后重试');
  }
}

响应结果：

{
  "message": "请求过于频繁",
  "error": "请等待 60 秒后重试",
  "statusCode": 429
}

五、全局异常过滤器（统一响应格式）

实际开发中，通常会自定义全局异常过滤器，统一所有 HTTP 异常的响应格式（如增加 timestamp 字段）：

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

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();
    const exceptionResponse = exception.getResponse() as { message: string; error: string };

    response.status(status).json({
      code: status, // 自定义码段
      msg: exceptionResponse.message,
      detail: exceptionResponse.error,
      timestamp: new Date().toISOString(), // 错误时间
      path: ctx.getRequest().url, // 请求路径
    });
  }
}

// 在 main.ts 注册全局过滤器
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './filters/http-exception.filter';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter()); // 全局生效
  await app.listen(3000);
}
bootstrap();

统一后的响应示例：

{
  "code": 400,
  "msg": "Something bad happened",
  "detail": "Some error description",
  "timestamp": "2026-02-24T10:00:00.000Z",
  "path": "/users"
}

总结

1. Nest 内置 HTTP 异常覆盖了所有常见 HTTP 状态码，每个异常对应明确的业务场景，可直接抛出无需手动处理状态码；
2. 内置异常支持自定义 message、cause（日志用）和 description（客户端可见），兼顾排查和用户体验；
3. 若内置异常不满足需求，可继承 HttpException 实现自定义异常，或通过全局过滤器统一响应格式。