什么是异常过滤器？

Question

什么是异常过滤器？

Accepted Answer

**异常过滤器**让你完全控制错误如何被**捕获并转换为响应**。它们位于请求生命周期的末端，捕获请求中任何位置抛出的异常，让你自定义错误响应格式、状态和日志记录。

## 基本异常过滤器

```ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";

@Catch(HttpException)                    // catch HttpExceptions specifically
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();

// build a CUSTOM error response shape
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: exception.message,
    });
  }
}
```

`@Catch()` 装饰器指定此过滤器处理的异常类型，`catch()` 方法接收异常和上下文 — 让你可以构造任何你想要的响应。

## 捕获所有异常（包括非 HTTP 异常）

```ts
@Catch()                                 // no argument = catch EVERYTHING
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;                              // unknown errors → 500
    // log the full error internally, return a safe message to the client
    this.logger.error(exception);
    ctx.getResponse().status(status).json({ statusCode: status, message: "..." });
  }
}
```

没有参数的 `@Catch()` 装饰器的过滤器会处理每个异常 — 这是记录意外错误的地方，并确保即使是非 HTTP 错误也返回干净、安全的响应（不向客户端泄露堆栈跟踪）。

## 应用过滤器

```ts
@UseFilters(HttpExceptionFilter)         // method or controller level
export class UsersController {}

app.useGlobalFilters(new AllExceptionsFilter());   // GLOBAL — app-wide, most common
```

过滤器通常**全局**应用以在整个 API 中强制执行一致的错误格式。

## 为什么使用异常过滤器？

```text
✓ Consistent error response format across ALL endpoints (a standard shape)
✓ Centralized error LOGGING (log every error in one place)
✓ Handle non-HTTP errors safely (turn unexpected errors into clean 500s)
✓ Hide internal details from clients (no leaked stack traces — security)
✓ Add context (request path, timestamp, correlation IDs) to error responses
```

## 过滤器与抛出异常的对比

```text
Throwing exceptions (NotFoundException, etc.) → SIGNALS an error with a status
Exception filters → control HOW those errors are FORMATTED/logged into responses
→ You throw exceptions in your code; filters customize the resulting response globally.
```

## 为什么这很重要

异常过滤器是 NestJS 的一项重要功能，用于构建具有**一致、受控的错误处理**的强大、专业的 API。

虽然 NestJS 的内置异常层已经将抛出的异常转换为 HTTP 响应，但异常过滤器给了你完全的控制权来自定义这一行为 — 这对几个实际关注点很重要：在每个端点上强制执行**一致的错误响应格式**（这样客户端总是以相同格式获得错误）、**集中错误日志**（在一个地方捕获每个错误而不是分散的 try/catch）、安全地**处理意外的非 HTTP 错误**（将它们转换为干净的 500s 而不是崩溃或泄露细节）和**安全性**（隐藏内部堆栈跟踪和敏感细节不暴露给客户端，同时在内部记录它们）。

全局