O que são filtros de exceção?

Question

Accepted Answer

**Filtros de exceção** lhe dão controle total sobre como erros são **capturados e transformados em respostas**. Eles ficam no final do ciclo de vida da requisição, capturando exceções lançadas em qualquer lugar da requisição e permitindo que você customize o formato da resposta de erro, status e logging.

## Um filtro de exceção básico

```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,
    });
  }
}
```

O decorador `@Catch()` especifica quais tipos de exceção este filtro trata, e o método `catch()` recebe a exceção mais o contexto — permitindo que você crie qualquer resposta que desejar.

## Capturando TODAS as exceções (incluindo non-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: "..." });
  }
}
```

Um filtro com `@Catch()` (sem argumento) trata toda exceção — o lugar para logar erros inesperados e garantir que até erros non-HTTP retornem uma resposta limpa e segura (sem vazar stack traces para clientes).

## Aplicando filtros

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

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

Filtros são geralmente aplicados **globalmente** para impor um formato de erro consistente em toda a API.

## Por que usar filtros de exceção?

```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
```

## Filtros vs lançar exceções

```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.
```

## Por que isso importa

Filtros de exceção são um recurso importante do NestJS para construir APIs robustas e profissionais com **tratamento de erros consistente e controlado**.

Enquanto a camada de exceção integrada do NestJS já transforma exceções lançadas em respostas HTTP, filtros de exceção lhe dão controle total para customizar esse comportamento — o que importa por várias razões reais: impor uma **forma de resposta de erro consistente** em cada endpoint (para que clientes sempre recebam erros no mesmo formato), **centralizar logging de erros** (capturando todo erro em um único lugar em vez de espalhado por try/catch), lidar com segurança **erros non-HTTP inesperados** (convertendo-os para 500s limpos em vez de causar crash ou vazar detalhes), e **segurança** (ocultando stack traces internos e detalhes sensíveis de clientes enquanto os registra internamente).

Um filtro "catch-all" global combinado com lançamento de exceções HTTP específicas no seu código é o padrão para tratamento de erros em nível de produção.

Compreender quando e como usar filtros (versus simplesmente lançar exceções), e aplicá-los globalmente para consistência, é marca registrada de aplicações NestJS bem construídas e reflete prática madura de back-end em torno da preocupação frequentemente negligenciada mas crítica de tratamento de erros.