【NestJS】13 异常过滤器（Exception Filter）

深入理解 NestJS 异常过滤器机制，掌握统一错误处理、自定义异常响应和错误日志记录，从基础异常处理到企业级错误管理的完整实践指南。

在开发过程中，错误是不可避免的。异常过滤器可以捕获和处理这些错误，返回友好的错误响应给客户端。这对于 API 开发非常重要，因为我们需要向客户端提供清晰、一致的错误信息 🛡️

一、什么是异常过滤器？#

异常过滤器的定义 🎯#

异常过滤器（Exception Filter） 是捕获和处理异常的类。它实现了 ExceptionFilter 接口，可以捕获特定类型的异常并返回自定义的响应。

异常过滤器的核心作用：

捕获应用中抛出的异常
转换异常为统一的响应格式
记录错误日志便于排查
向客户端返回友好的错误信息

📚 参考资源：

NestJS Exception Filters 官方文档 - 官方完整指南

HTTP 状态码规范 - MDN HTTP 状态码文档

异常过滤器的执行时机 📍#

在 NestJS 的请求处理流程中，异常过滤器的位置如下：

1
请求处理 → 异常抛出 → 异常过滤器 → 响应返回

当请求处理过程中的任何环节抛出异常时，异常过滤器会被自动调用。

异常过滤器的核心用途#

异常过滤器在实际应用中主要用于四大场景：

统一错误格式：将所有错误转换为统一的 JSON 格式
记录错误日志：记录详细的错误信息，便于排查问题
友好错误提示：向客户端返回易于理解的错误信息
错误分类处理：根据不同类型的错误返回不同的响应

二、内置异常类#

HttpException 基础异常类#

HttpException 是 NestJS 的基础异常类，所有 HTTP 异常都继承自它。

基本用法：

1
throw new HttpException('用户不存在', HttpStatus.NOT_FOUND);

这会返回 404 错误，响应体是：

1
{
2
  "statusCode": 404,
3
  "message": "用户不存在",
4
  "error": "Not Found"
5
}

📚 参考资源：

HTTP 状态码完整列表 - HTTP 状态码速查表

常用内置异常类#

NestJS 提供了丰富的内置异常类，涵盖了常见的 HTTP 错误场景：

BadRequestException - 400 错误

1
throw new BadRequestException('参数错误');

用于客户端请求参数不正确的场景。

UnauthorizedException - 401 错误

1
throw new UnauthorizedException('未授权，请先登录');

用于用户未认证的场景。

ForbiddenException - 403 错误

1
throw new ForbiddenException('没有权限访问此资源');

用于用户已认证但权限不足的场景。

NotFoundException - 404 错误

1
throw new NotFoundException('资源不存在');

用于请求的资源不存在的场景。

ConflictException - 409 错误

1
throw new ConflictException('资源冲突，用户名已存在');

用于资源冲突的场景，如重复创建。

InternalServerErrorException - 500 错误

1
throw new InternalServerErrorException('服务器内部错误');

用于服务器内部错误的场景。

自定义异常响应#

可以自定义异常的响应内容，提供更详细的错误信息：

1
throw new HttpException(
2
  {
3
    statusCode: 400,
4
    message: '参数验证失败',
5
    errors: ['用户名不能为空', '邮箱格式不正确'],
6
  },
7
  HttpStatus.BAD_REQUEST,
8
);

三、创建异常过滤器#

基本异常过滤器#

创建一个基本的异常过滤器，捕获所有异常：

1
import {
2
  ExceptionFilter,
3
  Catch,
4
  ArgumentsHost,
5
  HttpException,
6
  HttpStatus,
7
} from '@nestjs/common';
8
import { Request, Response } from 'express';
9

10
@Catch()
11
export class AllExceptionsFilter implements ExceptionFilter {
12
  catch(exception: unknown, host: ArgumentsHost) {
13
    const ctx = host.switchToHttp();
14
    const response = ctx.getResponse<Response>();
15
    const request = ctx.getRequest<Request>();
16

17
    const status =
18
      exception instanceof HttpException
19
        ? exception.getStatus()
20
        : HttpStatus.INTERNAL_SERVER_ERROR;
21

22
    const message =
23
      exception instanceof HttpException
24
        ? exception.getResponse()
25
        : '服务器内部错误';
26

27
    response.status(status).json({
28
      statusCode: status,
29
      timestamp: new Date().toISOString(),
30
      path: request.url,
31
      message: message,
32
    });
33
  }
34
}

@Catch() 装饰器详解#

@Catch() 装饰器用于指定要捕获的异常类型：

捕获特定异常：

1
@Catch(HttpException) // 只捕获 HttpException
2
export class HttpExceptionFilter implements ExceptionFilter {
3
  // ...
4
}

捕获所有异常：

1
@Catch() // 捕获所有异常
2
export class AllExceptionsFilter implements ExceptionFilter {
3
  // ...
4
}

捕获多种异常：

1
@Catch(HttpException, ValidationException) // 捕获多种异常
2
export class MultipleExceptionFilter implements ExceptionFilter {
3
  // ...
4
}

ArgumentsHost 详解#

ArgumentsHost 提供了执行上下文的完整信息：

1
catch(exception: unknown, host: ArgumentsHost) {
2
  const ctx = host.switchToHttp();
3
  const request = ctx.getRequest();   // 获取请求对象
4
  const response = ctx.getResponse(); // 获取响应对象
5

6
  // 访问请求信息
7
  console.log(request.method);  // GET, POST, etc.
8
  console.log(request.url);     // /user/123
9
  console.log(request.headers); // 请求头
10
}

📚 参考资源：

ArgumentsHost API 文档 - 执行上下文详解

四、全局异常处理#

在模块中注册全局异常过滤器#

在 app.module.ts 中注册全局异常过滤器：

1
import { APP_FILTER } from '@nestjs/core';
2
import { AllExceptionsFilter } from './common/filters/all-exceptions.filter';
3

4
@Module({
5
  providers: [
6
    {
7
      provide: APP_FILTER,
8
      useClass: AllExceptionsFilter,
9
    },
10
  ],
11
})
12
export class AppModule {}

在 main.ts 中注册#

也可以在 main.ts 中注册全局异常过滤器：

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

3
app.useGlobalFilters(new AllExceptionsFilter());

注册多个异常过滤器#

可以注册多个异常过滤器，它们会按照注册顺序执行：

1
@Module({
2
  providers: [
3
    {
4
      provide: APP_FILTER,
5
      useClass: HttpExceptionFilter,
6
    },
7
    {
8
      provide: APP_FILTER,
9
      useClass: AllExceptionsFilter,
10
    },
11
  ],
12
})
13
export class AppModule {}

五、实战：统一的错误处理系统#

需求分析 📋#

创建一个完整的异常处理系统，实现以下功能：

统一错误响应格式
记录详细的错误日志
处理不同类型的异常
提供友好的错误信息
区分开发环境和生产环境的错误信息

完整实现#

第一步：创建统一异常过滤器

创建 src/common/filters/all-exceptions.filter.ts 文件：

1
import {
2
  ExceptionFilter,
3
  Catch,
4
  ArgumentsHost,
5
  HttpException,
6
  HttpStatus,
7
  Logger,
8
} from '@nestjs/common';
9
import { Request, Response } from 'express';
10

11
@Catch()
12
export class AllExceptionsFilter implements ExceptionFilter {
13
  private readonly logger = new Logger(AllExceptionsFilter.name);
14

15
  catch(exception: unknown, host: ArgumentsHost) {
16
    const ctx = host.switchToHttp();
17
    const response = ctx.getResponse<Response>();
18
    const request = ctx.getRequest<Request>();
19

20
    let status = HttpStatus.INTERNAL_SERVER_ERROR;
21
    let message = '服务器内部错误';
22
    let error: any = null;
23

24
    // 处理 HttpException
25
    if (exception instanceof HttpException) {
26
      status = exception.getStatus();
27
      const exceptionResponse = exception.getResponse();
28

29
      if (typeof exceptionResponse === 'string') {
30
        message = exceptionResponse;
31
      } else if (typeof exceptionResponse === 'object') {
32
        const responseObj = exceptionResponse as any;
33
        message = responseObj.message || '请求失败';
34
        error = responseObj.error || null;
35
      }
36
    }
37
    // 处理其他异常
38
    else if (exception instanceof Error) {
39
      message = exception.message || '服务器内部错误';
40
      this.logger.error(
41
        `未处理的异常: ${exception.message}`,
42
        exception.stack,
43
        'AllExceptionsFilter',
44
      );
45
    }
46

47
    // 记录错误日志
48
    this.logger.error(
49
      `${request.method} ${request.url} - ${status} - ${message}`,
50
    );
51

52
    // 返回统一格式的错误响应
53
    const errorResponse = {
54
      code: status,
55
      message: Array.isArray(message) ? message[0] : message,
56
      data: null,
57
      timestamp: new Date().toISOString(),
58
      path: request.url,
59
      ...(error && { error }),
60
    };
61

62
    response.status(status).json(errorResponse);
63
  }
64
}

第二步：注册全局异常过滤器

在 src/app.module.ts 中注册：

1
import { APP_FILTER } from '@nestjs/core';
2
import { AllExceptionsFilter } from './common/filters/all-exceptions.filter';
3

4
@Module({
5
  providers: [
6
    {
7
      provide: APP_FILTER,
8
      useClass: AllExceptionsFilter,
9
    },
10
  ],
11
})
12
export class AppModule {}

测试验证 ✅#

1. 测试 HttpException

在控制器中抛出异常：

1
@Get(':id')
2
findOne(@Param('id', ParseIntPipe) id: number) {
3
  if (id > 100) {
4
    throw new NotFoundException(`用户 ID ${id} 不存在`);
5
  }
6
  return { id, name: '测试用户' };
7
}

⚠️ 注意：如果在 UserController 顶部使用了 JWT 验证守卫，测试时需要先注释掉。

访问 GET /user/999，应该返回：

1
{
2
  "code": 404,
3
  "message": "用户 ID 999 不存在",
4
  "data": null,
5
  "timestamp": "2024-01-01T10:00:00.000Z",
6
  "path": "/user/999"
7
}

2. 测试未处理的异常

在控制器中抛出未处理的异常：

1
@Get('error')
2
testError() {
3
  throw new Error('这是一个测试错误');
4
}

访问 GET /user/error，应该返回：

1
{
2
  "code": 500,
3
  "message": "这是一个测试错误",
4
  "data": null,
5
  "timestamp": "2024-01-01T10:00:00.000Z",
6
  "path": "/user/error"
7
}

六、特定异常过滤器#

HTTP 异常过滤器#

创建一个专门处理 HTTP 异常的过滤器：

1
import {
2
  ExceptionFilter,
3
  Catch,
4
  ArgumentsHost,
5
  HttpException,
6
} from '@nestjs/common';
7
import { Request, Response } from 'express';
8

9
@Catch(HttpException)
10
export class HttpExceptionFilter implements ExceptionFilter {
11
  catch(exception: HttpException, host: ArgumentsHost) {
12
    const ctx = host.switchToHttp();
13
    const response = ctx.getResponse<Response>();
14
    const request = ctx.getRequest<Request>();
15
    const status = exception.getStatus();
16
    const exceptionResponse = exception.getResponse();
17

18
    let message: string;
19
    let error: any;
20

21
    if (typeof exceptionResponse === 'string') {
22
      message = exceptionResponse;
23
      error = null;
24
    } else if (typeof exceptionResponse === 'object') {
25
      const responseObj = exceptionResponse as any;
26
      message = responseObj.message || '请求失败';
27
      error = responseObj.error || null;
28
    } else {
29
      message = '请求失败';
30
      error = null;
31
    }
32

33
    response.status(status).json({
34
      code: status,
35
      message: Array.isArray(message) ? message[0] : message,
36
      data: null,
37
      timestamp: new Date().toISOString(),
38
      path: request.url,
39
      ...(error && { error }),
40
    });
41
  }
42
}

验证异常过滤器#

创建一个专门处理验证异常的过滤器：

1
import {
2
  ExceptionFilter,
3
  Catch,
4
  ArgumentsHost,
5
  BadRequestException,
6
} from '@nestjs/common';
7
import { Request, Response } from 'express';
8

9
@Catch(BadRequestException)
10
export class ValidationExceptionFilter implements ExceptionFilter {
11
  catch(exception: BadRequestException, host: ArgumentsHost) {
12
    const ctx = host.switchToHttp();
13
    const response = ctx.getResponse<Response>();
14
    const request = ctx.getRequest<Request>();
15
    const exceptionResponse = exception.getResponse() as any;
16

17
    response.status(400).json({
18
      code: 400,
19
      message: '数据验证失败',
20
      errors: Array.isArray(exceptionResponse.message)
21
        ? exceptionResponse.message
22
        : [exceptionResponse.message],
23
      data: null,
24
      timestamp: new Date().toISOString(),
25
      path: request.url,
26
    });
27
  }
28
}

七、异常过滤器的应用范围#

全局异常过滤器#

在 app.module.ts 中使用 APP_FILTER 注册全局异常过滤器（前面已经讲过）。

控制器级别异常过滤器#

使用 @UseFilters() 装饰器应用到控制器：

1
@Controller('user')
2
@UseFilters(HttpExceptionFilter)
3
export class UserController {
4
  // 所有方法都使用此过滤器
5
}

方法级别异常过滤器#

使用 @UseFilters() 装饰器应用到方法：

1
@Post()
2
@UseFilters(ValidationExceptionFilter)
3
create(@Body() createUserDto: CreateUserDto) {
4
  // 只有这个方法使用此过滤器
5
}

多个异常过滤器#

可以同时应用多个异常过滤器：

1
@UseFilters(HttpExceptionFilter, ValidationExceptionFilter)
2
export class UserController {
3
  // 按顺序应用多个过滤器
4
}

八、错误日志记录#

记录错误日志#

在异常过滤器中记录详细的错误日志：

1
import { Logger } from '@nestjs/common';
2

3
@Catch()
4
export class AllExceptionsFilter implements ExceptionFilter {
5
  private readonly logger = new Logger(AllExceptionsFilter.name);
6

7
  catch(exception: unknown, host: ArgumentsHost) {
8
    // ...
9

10
    // 记录错误日志
11
    if (exception instanceof Error) {
12
      this.logger.error(
13
        `异常: ${exception.message}`,
14
        exception.stack,
15
        'AllExceptionsFilter',
16
      );
17
    }
18

19
    // 记录请求信息
20
    this.logger.error(
21
      `${request.method} ${request.url} - ${status} - ${message}`,
22
    );
23

24
    // ...
25
  }
26
}

📚 参考资源：

NestJS Logger 文档 - 日志系统详解

日志级别#

根据错误的严重程度使用不同的日志级别：

1
if (status >= 500) {
2
  this.logger.error(/* 服务器错误 */);
3
} else if (status >= 400) {
4
  this.logger.warn(/* 客户端错误 */);
5
} else {
6
  this.logger.log(/* 正常日志 */);
7
}

九、异常过滤器的最佳实践#

1. 使用全局异常过滤器 🌐#

1
// ✅ 推荐：全局异常处理
2
@Module({
3
  providers: [
4
    {
5
      provide: APP_FILTER,
6
      useClass: AllExceptionsFilter,
7
    },
8
  ],
9
})
10
export class AppModule {}

2. 提供友好的错误信息 💬#

1
// ✅ 推荐：友好的错误信息
2
throw new NotFoundException('用户不存在，请检查用户 ID 是否正确');
3

4
// ❌ 避免：模糊的错误信息
5
throw new NotFoundException('Not found');

3. 记录详细的错误日志 📝#

1
// ✅ 推荐：记录详细日志
2
this.logger.error(
3
  `${request.method} ${request.url}`,
4
  exception.stack,
5
  'AllExceptionsFilter',
6
);

4. 分类处理异常 🎯#

1
// ✅ 推荐：根据异常类型分类处理
2
if (exception instanceof HttpException) {
3
  // 处理 HTTP 异常
4
} else if (exception instanceof Error) {
5
  // 处理其他异常
6
}

5. 不要暴露敏感信息 🔒#

1
// ✅ 推荐：生产环境隐藏详细错误
2
const isDevelopment = process.env.NODE_ENV === 'development';
3

4
const errorResponse = {
5
  code: status,
6
  message: message,
7
  ...(isDevelopment && { stack: exception.stack }),
8
};
9

10
// ❌ 避免：暴露敏感信息
11
throw new Error(`数据库连接失败: ${dbPassword}`);

6. 统一错误响应格式 📊#

1
// ✅ 推荐：统一的错误响应格式
2
interface ErrorResponse {
3
  code: number;
4
  message: string;
5
  data: null;
6
  timestamp: string;
7
  path: string;
8
  error?: any;
9
}

十、常见问题排查#

问题 1：异常过滤器未执行#

问题描述：异常过滤器没有执行，异常未被捕获。

可能原因：

异常过滤器未注册
使用了 @Res() 装饰器
异常类型不匹配

解决方案：

1
// ✅ 确保异常过滤器已注册
2
@Module({
3
  providers: [
4
    {
5
      provide: APP_FILTER,
6
      useClass: AllExceptionsFilter,
7
    },
8
  ],
9
})
10

11
// ✅ 避免使用 @Res() 装饰器
12
// 使用 @Res() 会禁用异常过滤器
13

14
// ✅ 检查 @Catch() 装饰器
15
@Catch() // 捕获所有异常
16
@Catch(HttpException) // 只捕获 HttpException

问题 2：错误响应格式不正确#

问题描述：错误响应格式不符合预期。

可能原因：异常过滤器逻辑有误。

解决方案：检查异常过滤器的逻辑，确保正确处理不同类型的异常。

问题 3：错误日志未记录#

问题描述：错误日志没有记录。

可能原因：未在异常过滤器中记录日志。