NestJS全局异常捕获进阶学习笔记

//  错误写法：注册了两个全局 Filter，只有最后一个会生效
app.useGlobalFilters(new HttpExceptionFilter(), new AllExceptionsFilter());
// → 只有 AllExceptionsFilter 会执行，HttpExceptionFilter 被覆盖！

@Catch()  // 不传参数 → 捕获所有异常
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const isHttpException = exception instanceof HttpException;

    if (isHttpException) {
      // HTTP 异常的处理逻辑
    } else {
      // 非 HTTP 异常的处理逻辑
    }
  }
}

// @Catch(HttpException)   → 只捕获 HTTP 异常
// @Catch()                → 捕获所有异常（HTTP + WebSocket + 其他）

pnpm install request-ip

import * as requestIP from 'request-ip';

// 在过滤器中获取客户端 IP
const clientIp = requestIP.getClientIp(request);

const request = ctx.getRequest<Request>();

const requestInfo = {
  ip: requestIP.getClientIp(request),       // 客户端 IP
  method: request.method,                    // 请求方法：GET / POST
  url: request.url,                          // 请求路径：/api/v1/user/123
  body: request.body,                        // 请求体参数
  params: request.params,                    // 路径参数：/user/:id → { id: '123' }
  query: request.query,                      // 查询参数：?page=1 → { page: '1' }
  headers: request.headers,                  // 请求头信息
  timestamp: new Date().toISOString(),       // 请求时间
};

const errorResponse = {
  code: 500,
  message: 'Internal Server Error',
  headers: undefined,    // ← 这个字段不会出现在响应中
};

response.status(500).json(errorResponse);

// 实际响应给前端：
// { "code": 500, "message": "Internal Server Error" }
// headers 字段被自动过滤掉了

pnpm install request-ip @types/request-ip -D

// src/filters/all-exception.filter.ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
  Logger,
} from '@nestjs/common';
import { Request, Response } from 'express';
import * as requestIP from 'request-ip';

@Catch()  // 不传参数：捕获所有异常
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger(AllExceptionsFilter.name);

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

    // 获取客户端 IP
    const clientIp = requestIP.getClientIp(request);

    // 判断异常类型
    const isHttpException = exception instanceof HttpException;

    const status = isHttpException
      ? exception.getStatus()
      : HttpStatus.INTERNAL_SERVER_ERROR;

    const message = isHttpException
      ? exception.message
      : 'Internal Server Error';

    // 采集完整请求信息
    const requestInfo = {
      ip: clientIp,
      method: request.method,
      url: request.url,
      body: request.body,
      params: request.params,
      query: request.query,
      headers: request.headers,
      timestamp: new Date().toISOString(),
    };

    // 构造错误响应（undefined 字段不会出现在 JSON 中）
    const errorResponse = {
      code: status,
      message,
      ...requestInfo,
    };

    // 记录错误日志
    this.logger.error(
      `${request.method} ${request.url} - ${message}`,
      exception instanceof Error ? exception.stack : String(exception),
    );

    // 返回响应
    response.status(status).json(errorResponse);
  }
}

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { AllExceptionsFilter } from './filters/all-exception.filter';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 注册全局过滤器（只能有一个）
  app.useGlobalFilters(new AllExceptionsFilter());

  await app.listen(3000);
}
bootstrap();

# 测试 1：请求不存在的路由
curl http://localhost:3000/api/v1/not-exist

# 测试 2：带参数的请求
curl "http://localhost:3000/user/123?page=1" -X POST -H "Content-Type: application/json" -d '{"name":"test"}'

{
  "code": 404,
  "message": "Cannot GET /api/v1/not-exist",
  "ip": "::1",
  "method": "GET",
  "url": "/api/v1/not-exist",
  "body": {},
  "params": {},
  "query": {},
  "headers": {
    "user-agent": "curl/8.0",
    "host": "localhost:3000",
    "accept": "*/*"
  },
  "timestamp": "2026-03-30T09:00:00.000Z"
}

2026-03-30T09:00:00.000Z error: GET /api/v1/not-exist - Cannot GET /api/v1/not-exist
    Error: Cannot GET /api/v1/not-exist
        at ...（完整堆栈信息）