AgentSkillsCN

NestJS Error Handling

在全局异常过滤器与标准错误格式方面的规范。

SKILL.md
--- frontmatter
name: NestJS Error Handling
description: Global Exception Filters and standard error formats.
metadata:
  labels: [nestjs, errors, filters]
  triggers:
    files: ['**/*.filter.ts', 'main.ts']
    keywords: [ExceptionFilter, Catch, HttpException]

NestJS Error Handling Standards

Priority: P1 (OPERATIONAL)

Global error handling and exception management patterns.

  • •

    Requirement: Centralize error formatting.

  • •

    Platform Agnostic: Do not import Request/Response from Express/Fastify types directly.

    • •Use: HttpAdapterHost to access the underlying platform response methods.
    • •const { httpAdapter } = this.httpAdapterHost;
  • •

    Structure:

    • •Implement strictly typed error responses.
    • •Refer to API Standards for ApiErrorResponse.
    json
    {
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "timestamp": "ISO...",
  "path": "/users"
}

Error Flow

  1. •Service: Throws specific or generic errors (e.g., EntityNotFoundError).
  2. •Interceptor: Maps low-level errors to HTTP Exceptions (e.g., catchError(err => throw new NotFoundException())).
    • •Why: Keeps Exception Filters focused on formatting, not business logic interpretation.
  3. •Global Filter: Formats the final JSON response.

Built-in Exceptions

  • •Use: Throw NotFoundException, ForbiddenException, BadRequestException.
  • •Custom: Extend HttpException only for domain-specific failures that need specific status codes.

Logging

  • •Context: Always pass MyClass.name to the Logger constructor.
  • •Levels:
    • •error: 500s (Stack trace required).
    • •warn: 400s (Client errors).

Security (Information Leakage)

  • •Production: NEVER expose stack traces in HTTP responses (process.env.NODE_ENV === 'production').
  • •Sanitization: Ensure ApiException payloads do not leak internal file paths or raw variable dumps.