O que são interceptadores?

Question

Accepted Answer

**Interceptadores** envolvem a execução de um manipulador de rota, permitindo executar lógica **antes e depois** dele — e transformar a requisição ou resposta. Eles são inspirados em programação orientada a aspectos, ideais para preocupações transversais como logging, transformação de resposta, cache e temporização.

## A estrutura: antes + depois via RxJS

```ts
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log("Before handler");          // runs BEFORE the route handler
    const now = Date.now();

return next.handle().pipe(               // next.handle() = invoke the handler
      tap(() => console.log(`After: ${Date.now() - now}ms`)),   // runs AFTER
    );
  }
}
```

Um interceptador implementa `intercept()`. Código antes de `next.handle()` executa **antes** do manipulador; `next.handle()` retorna um `Observable` RxJS da resposta, e operadores como `tap`/`map` permitem agir na resposta **depois** que o manipulador se completa.

## Transformando a resposta (um uso comum)

```ts
@Injectable()
export class TransformInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    return next.handle().pipe(
      map(data => ({ success: true, data, timestamp: new Date().toISOString() })),
      // wraps EVERY response in a consistent envelope: { success, data, timestamp }
    );
  }
}
```

Usando `map`, um interceptador pode reformular cada resposta — por exemplo, envolvendo todas as respostas em um envelope padrão, um padrão muito comum para respostas de API consistentes.

## Outros usos poderosos

```ts
// caching — return a cached response, skipping the handler entirely
// timeout — fail requests taking too long
return next.handle().pipe(timeout(5000));

// error mapping — transform exceptions
return next.handle().pipe(catchError(err => throwError(() => new BadGatewayException())));

// excluding fields (serialization) — ClassSerializerInterceptor strips @Exclude() fields
```

```text
Common interceptor uses:
  ✓ Logging / timing requests (before + after)
  ✓ Transforming responses (consistent envelopes, field exclusion)
  ✓ Caching responses
  ✓ Adding timeouts
  ✓ Mapping/handling errors
```

## Aplicando interceptadores

```ts
@UseInterceptors(LoggingInterceptor)   // method or controller level
app.useGlobalInterceptors(new TransformInterceptor());   // global
```

## Interceptadores vs middleware vs guards

```text
Middleware  → runs BEFORE everything, with raw req/res (can't easily touch the response)
Guard       → AUTHORIZATION decision (allow/block) before the handler
Interceptor → wraps the handler — runs BEFORE and AFTER, can TRANSFORM the response
```

A característica definidora: interceptadores podem executar lógica **depois** do manipulador e **transformar a resposta** — o que middleware e guards não conseguem fazer de forma limpa.

## Por que isso importa

Interceptadores são uma funcionalidade poderosa do NestJS para lidar com **preocupações transversais** elegantemente, e sua capacidade distintiva — executar lógica antes *e depois* do manipulador, e transformar a resposta — os torna a ferramenta certa para necessidades que middleware e guards não conseguem abordar.

Compreendê-los é importante porque muitos requisitos comuns se mapeiam naturalmente para interceptadores: formatação de resposta consistente (envolvendo todas as respostas em um envelope `{ success, data }` padrão), logging/temporização (medindo duração do manipulador), cache (retornando respostas em cache), timeouts, transformação de erro e serialização (excluindo campos sensíveis).

Conhecer a estrutura (o `Observable` de `next.handle()`, com `tap`/`map`/`catchError` para agir antes/depois), os casos de uso comuns, e especialmente **como interceptadores diferem de middleware e guards** (a capacidade de envolver e transformar a resposta) é uma parte importante da competência arquitetônica do NestJS.

Interceptadores mantêm lógica transversal DRY e centralizada em vez de duplicada entre manipuladores, tornando-os uma ferramenta frequentemente usada e importante para construir aplicações NestJS limpas e mantíveis.