Что такое перехватчики (interceptors)?

Question

Accepted Answer

**Перехватчики** оборачивают выполнение обработчика маршрута, позволяя вам запускать логику **перед и после** его работы — и преобразовывать запрос или ответ. Они вдохновлены аспектно-ориентированным программированием и идеально подходят для сквозных задач, таких как логирование, преобразование ответов, кэширование и измерение времени.

## Структура: перед + после через 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
    );
  }
}
```

Перехватчик реализует `intercept()`. Код перед `next.handle()` выполняется **перед** обработчиком; `next.handle()` возвращает RxJS `Observable` ответа, и операторы вроде `tap`/`map` позволяют вам действовать на ответ **после** завершения обработчика.

## Преобразование ответа (частый случай использования)

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

Используя `map`, перехватчик может переформатировать каждый ответ — например, оборачивая все ответы в стандартный конверт, очень распространённый паттерн для согласованных API-ответов.

## Другие мощные использования

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

## Применение перехватчиков

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

## Перехватчики 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
```

Определяющая особенность: перехватчики могут запускать логику **после** обработчика и **преобразовывать ответ** — что middleware и guards не могут делать чисто.

## Почему это важно

Перехватчики — мощный инструмент NestJS для элегантной обработки **сквозных задач**, и их отличительная способность — запускать логику как перед, так и после обработчика, а также преобразовывать ответ — делает их правильным инструментом для задач, которые middleware и guards не могут решить.

Понимание этого важно, потому что многие распространённые требования естественным образом отображаются на перехватчики: согласованное форматирование ответов (оборачивание всех ответов в стандартный конверт `{ success, data }`), логирование/измерение (расчёт длительности обработчика), кэширование (возврат кэшированных ответов), таймауты, преобразование ошибок и сериализация (исключение чувствительных полей).

Знание структуры (Observable `next.handle()` с `tap`/`map`/`catchError` для действия до/после), частых случаев использования и особенно **того, чем перехватчики отличаются от middleware и guards** (возможность оборачивать и преобразовывать ответ) — ключевая часть архитектурной компетентности в NestJS.

Перехватчики держат сквозную логику DRY и централизованной вместо того, чтобы дублировать её по обработчикам, делая их часто используемым и важным инструментом для создания чистых, поддерживаемых приложений на NestJS.