🌀 NestJS Interceptor 완전 가이드 – 응답 변형, 로깅, 캐싱, 성능 추적까지

🌀 NestJS Interceptor 완전 가이드 – 응답 변형, 로깅, 캐싱, 성능 추적까지

---

NestJS에서 **Interceptor(인터셉터)**는 Controller 메서드 전후로 실행되어, 응답을 가공하거나 요청을 감싸는 강력한 기능을 제공합니다.
이 글은 NestJS 공식 문서 Interceptors를 기반으로 한글 번역 + 실전 중심 해설로 정리했습니다.

💡 Interceptor는 NestJS의 "Aspect-Oriented Programming(AOP)"을 실현하는 가장 대표적인 도구입니다.

---

✅ Interceptor는 언제 사용하나요?

• 응답 데이터 구조 변경
• 요청/응답 로깅
• 요청 시간 측정 (Performance)
• 결과 캐싱
• 에러 리포트 감싸기 (try/catch 대신)

---

1️⃣ Interceptor 기본 구조

import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const now = Date.now();
    return next.handle().pipe(
      tap(() => console.log(`⏱ 처리 시간: ${Date.now() - now}ms`)),
    );
  }
}

구조 설명

• intercept()는 요청을 가로채는 메서드
• next.handle()은 실제 핸들러 실행
• tap()은 응답이 완료된 후 후처리

---

2️⃣ 라우트에 Interceptor 적용하기

@UseInterceptors(LoggingInterceptor)
@Get()
getData() {
  return { message: 'Hello Interceptor!' };
}

@UseInterceptors() 데코레이터를 통해 특정 컨트롤러/라우트에 인터셉터 적용 가능합니다.

---

반응형

이 지점은 실무 응답 가공 및 로깅 예제가 나오는 구간으로 애드센스 광고 삽입 최적 위치입니다.

<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-XXXXXXX"
     data-ad-slot="YYYYYYY"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>

---

3️⃣ 응답 데이터 가공 Interceptor 예제

@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, ApiResponse<T>> {
  intercept(context: ExecutionContext, next: CallHandler): Observable<ApiResponse<T>> {
    return next.handle().pipe(
      map(data => ({
        success: true,
        data,
        timestamp: new Date().toISOString(),
      })),
    );
  }
}

interface ApiResponse<T> {
  success: boolean;
  data: T;
  timestamp: string;
}

컨트롤러에서 return한 원시 데이터가, 가공된 JSON 형태로 자동 변경됩니다.

---

4️⃣ 전역 Interceptor 등록

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalInterceptors(new TransformInterceptor());
  await app.listen(3000);
}

전역 등록을 통해 모든 라우트에서 공통된 응답 구조 유지가 가능합니다.

---

5️⃣ 캐싱 인터셉터 (실무 예시)

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  private cache = new Map<string, any>();

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const key = context.switchToHttp().getRequest().url;
    if (this.cache.has(key)) {
      return of(this.cache.get(key));
    }

    return next.handle().pipe(
      tap(data => this.cache.set(key, data)),
    );
  }
}

실무에서 Redis와 연동하여 고도화된 캐시 시스템도 구현 가능합니다.

---

6️⃣ Error 감싸기 (실행 결과 Wrapper)

@Injectable()
export class ErrorWrapperInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      catchError(err => {
        return throwError(() => new HttpException({
          success: false,
          error: err.message || '알 수 없는 오류',
        }, err.status || 500));
      }),
    );
  }
}

---

🧠 Interceptor vs Middleware vs Guard vs Pipe

항목 시점 역할

Middleware	Controller 진입 전	요청 로깅, 쿠키 파싱 등
Guard	라우트 진입 전	인증/인가
Pipe	핸들러 실행 전	유효성 검사, 타입 변환
Interceptor	실행 전/후	응답 가공, 로깅, 캐싱

---

🔚 마무리 요약

• Interceptor는 응답 처리, 로깅, 변환, 캐싱 등 후처리에 최적화된 도구
• CallHandler.handle()은 Observable 기반 → RxJS 연산자 사용 가능
• 실무에서 TransformInterceptor, ErrorInterceptor, CacheInterceptor는 필수 도입 요소

---

 

NestJS Interceptor,NestJS 응답 가공,NestJS 응답 포맷,NestJS 로깅 Interceptor,NestJS TransformInterceptor,NestJS 전역 인터셉터,NestJS 캐시 인터셉터,NestJS Error 처리,NestJS 성능측정,NestJS 구조화 응답

---