如何使用 Nest.js 异常过滤器来处理错误

作者
Tweet
Share
Share
Pin
0 Shares

在 Nest.js 框架中，异常过滤器提供了一种强大的机制，用于集中管理应用程序中的错误处理流程。 它们允许开发者在全局范围内或针对特定的控制器拦截并处理各种异常情况。

通过运用异常过滤器，开发者可以有效地组织错误处理逻辑，定制错误响应的格式，并确保整个应用程序的错误处理机制具有一致性。 理解异常过滤器的概念以及如何在实践中运用它们，对于构建健壮且易于维护的应用程序至关重要。

Nest.js 中的默认错误处理机制

Nest.js 框架内置了一个异常处理层，它会自动捕获并处理那些未被开发者代码明确处理的异常。

当应用程序中发生未经处理的错误时，Nest.js 会自动捕获该异常，并向客户端返回一个 HTTP 500 内部服务器错误响应。 默认情况下，Nest.js 返回的 JSON 响应格式如下所示：

 {
  "statusCode": 500,
  "message": "Internal server error"
}

然而，如果您的代码抛出的错误对象本身包含了 `statusCode` 和 `message` 属性，Nest.js 则会优先使用这些自定义值，而不是返回默认的响应内容。

为了避免这种过于通用的默认行为，并向客户端提供更具信息量和针对性的错误响应，开发者需要采取主动措施，妥善处理应用程序中可能出现的各种错误。 这可以通过使用 Nest.js 提供的内置异常过滤器或者创建自定义异常过滤器来实现。

自定义异常过滤器的创建过程

为了演示如何创建自定义异常过滤器，我们将创建一个能够处理所有 HTTP 异常的过滤器。

首先，创建一个名为 `http.exception.ts` 的文件，并在其中添加以下所需的导入语句：

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

上述导入的含义如下：

  • `ExceptionFilter`: 这是一个接口，用于描述异常过滤器的具体实现。
  • `Catch`: 这是一个装饰器，用于将类标记为 Nest.js 的异常过滤器。
  • `ArgumentsHost`: 这是一个接口，它提供了用于检索传递给处理函数的参数的方法。它允许开发者根据不同的执行环境（如 HTTP、RPC 或 WebSocket）来获取所需的参数。
  • `HttpException`: 这是一个类，用于定义 Nest.js 中基本的 HTTP 异常。
  • `Request` 和 `Response`: 这两个接口分别对应 Express.js 中的请求和响应对象。

接下来，创建一个名为 `HttpExceptionFilter` 的类，并使其实现 `ExceptionFilter` 接口。 使用 `@Catch` 装饰器来指定该过滤器将处理 `HttpException`：

 @Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {}

现在，让我们用以下代码填充 `HttpExceptionFilter` 类：

 catch(exception: HttpException, host: ArgumentsHost) {
    
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    
    const request = ctx.getRequest<Request>();
    
    const status = exception.getStatus();
    
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message:
        exception.message
       || exception.getResponse()['message']
       || 'Internal Server Error',
    });
}

这段代码的主要作用是从 `ArgumentsHost` 对象中获取请求和响应对象，并从异常对象中提取相关信息。 然后，它向客户端返回一个结构化的 JSON 响应，其中包含了关于错误的详细信息，例如状态码、时间戳、请求路径以及错误消息。

异常过滤器的绑定

您可以根据实际需求，将异常过滤器绑定到特定的控制器或者整个应用程序。

要实现全局绑定，首先需要在 `main.ts` 文件中导入异常过滤器。 然后，将该异常过滤器的实例传递给 `app.useGlobalFilters` 方法：

 
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './exception/http.exception';
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  app.useGlobalFilters(new HttpExceptionFilter());
  await app.listen(4050);
}
bootstrap();

要将异常过滤器绑定到特定的控制器，需要导入 `UseFilters` 装饰器以及相应的异常过滤器。 然后，使用 `@UseFilters` 装饰器来标记控制器类，并将异常过滤器的实例作为参数传递给装饰器：

 @Controller()
@UseFilters(new HttpExceptionFilter())
export class AppController {}

过滤器绑定的位置决定了其作用范围。 绑定到控制器的过滤器将只处理该控制器内部抛出的异常，而绑定到应用程序的过滤器则会处理整个应用程序中抛出的异常。

使用内置异常类抛出错误

Nest.js 提供了许多内置的异常类，开发者可以使用它们来抛出不同类型的错误。

例如，您可以使用 `NotFoundException` 类来抛出一个 404 状态码的错误：

   getUserById(id: number) {
    const user = users.find((user) => user.id === id);
    if (!user) {
      throw new NotFoundException({
        message: `User with id ${id} not found`,
      });
    }
  }

这段代码会检查是否存在具有指定 ID 的用户。 如果不存在，则会抛出一个 `NotFoundException` 异常，并附带一条说明用户未找到的消息。

常见的内置异常类

除了 `NotFoundException`，Nest.js 还提供了其他常用的内置异常类，包括但不限于以下这些：

  • `BadRequestException`: 用于抛出 400 状态码的错误，表示客户端的请求无效或格式错误，服务器无法处理。这通常意味着客户端需要修改请求才能使其有效。
  • `UnauthorizedException`: 用于抛出 401 状态码的错误，表示用户未经身份验证或缺乏访问资源的必要权限。
  • `ForbiddenException`: 用于抛出 403 状态码的错误，表示用户已经过身份验证，但是没有权限执行特定的操作。
  • `RequestTimeoutException`: 用于抛出 408 状态码的错误，表示请求超时。 当服务器因处理时间过长而终止请求时，可以使用此异常。
  • `ConflictException`: 用于抛出 409 状态码的错误，表示客户端的请求与资源的当前状态之间存在冲突。 例如，尝试创建一个已存在的资源时。
  • `InternalServerErrorException`: 用于抛出 500 状态码的错误，表示服务器内部发生意外错误，导致服务器无法满足请求。

Nest.js 错误处理的最佳实践

在 Nest.js 中处理错误时，务必使用异常过滤器来捕获和处理全局或特定控制器的异常。 此外，可以针对特定的异常类型创建自定义过滤器，以便更精细地控制错误处理逻辑。

同时，请确保使用适当的内置异常类来抛出正确且有意义的错误，这可以显著提高 Nest.js 应用程序的可靠性和用户体验。