Czym są interceptory?

Question

Accepted Answer

**Interceptory** opakowują wykonanie handlera routu, umożliwiając uruchomienie logiki **przed i po** jego wykonaniu — oraz transformację żądania lub odpowiedzi. Są inspirowane programowaniem zorientowanym na aspekty, idealne dla zagadnień międzywarstwoowych takich jak logowanie, transformacja odpowiedzi, cache'owanie i pomiar czasu.

## Struktura: przed + po za pośrednictwem 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
    );
  }
}
```

Interceptor implementuje `intercept()`. Kod przed `next.handle()` wykonuje się **przed** handlerem; `next.handle()` zwraca RxJS `Observable` odpowiedzi, a operatory takie jak `tap`/`map` pozwalają działać na odpowiedzi **po** zakończeniu handlera.

## Transformacja odpowiedzi (częsty przypadek użycia)

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

Za pomocą `map`, interceptor może zmienić kształt każdej odpowiedzi — np. opakowując wszystkie odpowiedzi w standardową kopertę, bardzo częsty wzorzec dla spójnych odpowiedzi API.

## Inne potężne przypadki użycia

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

## Stosowanie interceptorów

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

## Interceptory vs middleware vs guardy

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

Wyróżniającą cechą: interceptory mogą uruchamiać logikę **po** handlerze i **transformować odpowiedź** — czego middleware i guardy nie mogą zrobić w czysty sposób.

## Dlaczego to ważne

Interceptory to potężna funkcja NestJS do elegancko obsługiwania **zagadnień międzywarstwoowych**, a ich wyróżniającą możliwością — uruchamianie logiki zarówno przed *jak i po* handlerze oraz transformacja odpowiedzi — czyni je właściwym narzędziem do potrzeb, które middleware i guardy nie mogą spełnić.

Rozumienie ich jest ważne, ponieważ wiele typowych wymagań naturalnie mapuje się na interceptory: spójne formatowanie odpowiedzi (opakowywanie wszystkich odpowiedzi w standardową kopertę `{ success, data }`), logowanie/timing (pomiar czasu trwania handlera), cache'owanie (zwracanie zbuforowanych odpowiedzi), timouty, transformacja błędów i serializacja (wykluczanie wrażliwych pól).

Znajomość struktury (Observable `next.handle()`, z `tap`/`map`/`catchError` do działania przed/po), typowych przypadków użycia, a szczególnie **jak interceptory różnią się od middleware i guardów** (zdolność do opakowania i transformacji odpowiedzi) jest kluczową częścią kompetencji architektonicznej NestJS.

Interceptory utrzymują logikę międzywarstwoową DRY i scentralizowaną zamiast duplikowanej na wielu handlerach, czyniąc je często używanym, ważnym narzędziem do budowania czystych, łatwych w utrzymaniu aplikacji NestJS.