interceptor란 무엇인가요?

Question

interceptor란 무엇인가요?

Accepted Answer

**Interceptor**는 라우트 핸들러의 실행을 감싸, 그 **이전과 이후에** 로직을 실행하고 요청이나 응답을 변환할 수 있게 합니다. 관점 지향 프로그래밍(AOP)에서 영감을 받았으며, 로깅, 응답 변환, 캐싱, 타이밍 같은 횡단 관심사에 이상적입니다.

## 구조: RxJS를 통한 이전 + 이후

```ts
@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    console.log("Before handler");          // 라우트 핸들러 이전에 실행
    const now = Date.now();

return next.handle().pipe(               // next.handle() = 핸들러 호출
      tap(() => console.log(`After: ${Date.now() - now}ms`)),   // 이후에 실행
    );
  }
}
```

Interceptor는 `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() })),
      // 모든 응답을 일관된 envelope로 감쌈: { success, data, timestamp }
    );
  }
}
```

`map`을 사용하면 interceptor가 모든 응답을 재구성할 수 있습니다 — 예: 모든 응답을 표준 envelope로 감싸는, 일관된 API 응답을 위한 매우 일반적인 패턴입니다.

## 기타 강력한 사용

```ts
// 캐싱 — 캐시된 응답을 반환하고 핸들러를 완전히 건너뜀
// 타임아웃 — 너무 오래 걸리는 요청을 실패시킴
return next.handle().pipe(timeout(5000));

// 오류 매핑 — 예외 변환
return next.handle().pipe(catchError(err => throwError(() => new BadGatewayException())));

// 필드 제외 (직렬화) — ClassSerializerInterceptor가 @Exclude() 필드 제거
```

```text
일반적인 interceptor 사용:
  ✓ 요청 로깅/타이밍 (이전 + 이후)
  ✓ 응답 변환 (일관된 envelope, 필드 제외)
  ✓ 응답 캐싱
  ✓ 타임아웃 추가
  ✓ 오류 매핑/처리
```

## interceptor 적용하기

```ts
@UseInterceptors(LoggingInterceptor)   // 메서드 또는 controller 수준
app.useGlobalInterceptors(new TransformInterceptor());   // 전역
```

## interceptor 대 middleware 대 guard

```text
Middleware  → 모든 것보다 먼저 실행, 원시 req/res (응답을 쉽게 다룰 수 없음)
Guard       → 핸들러 이전에 인가 결정 (허용/차단)
Interceptor → 핸들러를 감쌈 — 이전과 이후에 실행, 응답을 변환할 수 있음
```

결정적인 특징: interceptor는 핸들러 **이후에** 로직을 실행하고 **응답을 변환**할 수 있습니다 — middleware와 guard는 이를 깔끔하게 할 수 없습니다.

## 왜 중요한가

Interceptor는 **횡단 관심사**를 우아하게 처리하는 강력한 NestJS 기능이며, 그 독특한 능력 — 핸들러 이전과 *이후* 모두에 로직을 실행하고 응답을 변환하는 것 — 은 middleware와 guard가 다룰 수 없는 요구에 적합한 도구로 만듭니다.

많은 일반적인 요구사항이 자연스럽게 interceptor에 매핑되므로 이를 이해하는 것이 중요합니다: 일관된 응답 포맷(모든 응답을 표준 `{ success, data }` envelope로 감싸기), 로깅/타이밍(핸들러 소요 시간 측정), 캐싱(캐시된 응답 반환), 타임아웃, 오류 변환, 직렬화(민감한 필드 제외).

구조(`next.handle()` Observable과 이전/이후에 작용하는 `tap`/`map`/`catchError`), 일반적인 사용 사례, 특히 **interceptor가 middleware 및 guard와 어떻게 다른지**(응답을 감싸고 변환하는 능력)를 아는 것은 NestJS 아키텍처 역량의 핵심 부분입니다.

Interceptor는 횡단 로직을 핸들러 전체에 중복하지 않고 DRY하게 중앙화하여, 깔끔하고 유지보수 가능한 NestJS 애플리케이션을 구축하는 데 자주 사용되는 중요한 도구입니다.