---
category: Middleware & Interceptors.md
tags: [auto-wikified, technical-documentation, merged, middleware & interceptors.md]
title: Interceptors
description: "인터셉터(Interceptors)는 애플리케이션의 핵심 비즈니스 로직을 수정하지 않고도 로깅, 보안, 성능 모니터링 등 횡단 관심사(Cross-cutting concerns)를 일관되게 처리하기 위해 사용되는 컴포넌트이자 패턴이다 [1, 2]."
last_updated: 2026-05-04
---

# Interceptors


## 📌 Brief Summary
인터셉터(Interceptors)는 애플리케이션의 핵심 비즈니스 로직을 수정하지 않고도 로깅, 보안, 성능 모니터링 등 횡단 관심사(Cross-cutting concerns)를 일관되게 처리하기 위해 사용되는 컴포넌트이자 패턴이다 [1, 2]. 주로 클라이언트의 요청이 컨트롤러에 도달하기 전이나 컨트롤러가 응답을 반환한 후에 개입하여 사전 및 사후 처리를 수행한다 [2, 3]. Spring Boot, NestJS 등의 현대적인 프레임워크에서 기본적으로 지원되며, 요청 처리 파이프라인을 구조화하고 코드 중복을 줄이는 데 핵심적인 역할을 한다 [4-6].

## 📖 Core Content
* **Spring Boot의 인터셉터 메커니즘**
  * Spring Boot에서 인터셉터는 Spring MVC의 기능으로 제공되며, 서블릿 필터(Filter) 이후와 컨트롤러 실행 사이의 단계에서 동작한다 [3].
  * `HandlerInterceptor` 인터페이스를 구현하여 사용하며, 주로 컨트롤러 요청에 대한 권한 검사(Authorization), 실행 시간 로깅, 요청 속성 수정과 같은 전/후처리 작업에 사용된다 [3, 4, 7].

* **NestJS의 인터셉터 파이프라인**
  * NestJS는 Angular의 구조적 패턴을 차용하여 요청 처리 파이프라인의 일부로 인터셉터를 제공한다 [5].
  * 기존 Express 프레임워크의 단순 미들웨어에 비해 인증, 로깅, 유효성 검사 등의 패턴을 훨씬 더 구조화된 방식으로 처리할 수 있게 해준다 [8]. 
  * 특히 RxJS 스트림을 활용하여 비동기 작업의 흐름을 유연하게 제어할 수 있다는 것이 강력한 장점이다 [2, 6].

* **실전 활용 및 구조적 적용 (공통)**
  * **캐싱 레이어 구현:** 프레임워크에 관계없이 인터셉터(또는 데코레이터)를 사용하면 기존 비즈니스 로직 코드를 수정하지 않고도 캐싱 동작을 추가할 수 있다 [2].
  * **모듈화 전략:** NestJS와 같은 환경에서는 여러 기능에서 공통으로 쓰이는 인터셉터를 `SharedModule`이나 `CoreModule`에 선언하여 중앙 집중적으로 구성하고, 일회성 초기화 및 의존성 관리를 수행하는 패턴이 권장된다 [9, 10].

## ⚖️ Trade-offs & Caveats
* **적용 범위와 계층적 제약 (Spring Boot):** Spring Boot의 인터셉터는 오직 Spring MVC 계층에 종속되어 동작하므로, 정적 리소스를 포함한 모든 HTTP 요청을 제어하는 서블릿 필터(Filter)를 완전히 대체할 수는 없다 [3, 7]. 또한, 컨트롤러 밖의 서비스나 리포지토리 계층의 메서드를 가로채는 데는 사용할 수 없으며, 이러한 세밀한 제어가 필요할 경우 AOP(Aspect-Oriented Programming)를 별도로 활용해야 한다 [3, 7].
* **초기 학습 곡선 (NestJS):** Express의 단순한 미들웨어 패턴(req, res, next)에 익숙한 개발자가 인터셉터 기반의 처리 파이프라인을 도입할 경우, 의존성 주입(DI) 및 데코레이터 등과 맞물려 초기 학습에 시간이 걸릴 수 있다 [11].
* **전역(Global) 설정의 남용 위험:** 공통 인터셉터를 선언할 때 편의를 위해 `@Global()` 데코레이터를 사용하여 애플리케이션 전역에서 사용할 수 있게 설정할 수 있다. 하지만 이를 무분별하게 남용할 경우 모듈의 독립성이 저하되고 의존성이 불투명해지는 기술 부채를 유발할 수 있으므로, 진정한 의미의 횡단 관심사에만 제한적으로 사용해야 한다 [9].

---
*Last updated: 2026-05-03*

## 📚 Legacy Insights & Additional Context
> [!NOTE]
> Below is content merged from previous versions of this documentation.

## 📌 한 줄 통찰 (The Karpathy Summary)
미들웨어(Middleware)와 인터셉터(Interceptor)는 로깅, 인증, 캐싱, 예외 처리와 같이 애플리케이션 전반에 걸쳐 공통으로 요구되는 횡단 관심사(Cross-Cutting Concerns)를 캡슐화하고 중앙 집중화하는 구조적 컴포넌트이다 [1]. 프레임워크에 따라 처리되는 계층이 다르며, 미들웨어는 주로 서블릿이나 HTTP 요청/응답 파이프라인 전반에서 동작하고, 인터셉터와 AOP는 프레임워크의 특정 모델이나 메서드 실행 전후에서 세밀한 흐름 제어를 제공한다 [2-6]. 이를 통해 핵심 비즈니스 로직의 오염을 방지하고 시스템의 유지보수성과 확장성을 높인다 [1, 7].

## 📖 구조화된 지식 (Synthesized Content)
* **프레임워크별 횡단 관심사 처리 메커니즘 분리**
  * **Spring Boot (다층적 제어)**: 요청 처리 파이프라인의 깊이에 따라 세 가지 메커니즘을 제공한다 [2, 8].
    * **Filters (필터)**: 서블릿 계층에서 동작하며 Spring MVC 도달 전후의 모든 HTTP 요청(정적 리소스 포함)을 가로채어 CORS, 압축, 인증, 전역 로깅 등을 처리한다 [3, 8].
    * **Interceptors (인터셉터)**: Spring MVC 계층에서 컨트롤러 실행 전후에 작동하여 요청 수정, 지표 수집, 권한 부여 등을 수행한다 [4, 8].
    * **AOP (관점 지향 프로그래밍)**: 프레임워크 내 어떠한 Spring Bean 객체의 메서드(컨트롤러, 서비스, 리포지토리)에 대해서도 실행 전, 후, 주변(around)을 가로채어 로깅, 캐싱, 트랜잭션 등을 비즈니스 로직 수정 없이 처리한다 [5, 8].
  * **Express.js 및 NestJS**:
    * **Express.js**: `req, res, next` 구조를 가진 단순하고 유연한 미들웨어 패턴을 사용하지만, 프로젝트 규모가 커질수록 아키텍처적 일관성을 유지하기 어렵다는 단점이 있다 [9, 10].
    * **NestJS**: Express 기반 위에 구축되어 기존 미들웨어를 지원할 뿐만 아니라, Guard, Interceptor, Pipe, Middleware 등 구조화된 파이프라인을 도입했다 [6, 11]. 특히 NestJS의 인터셉터는 RxJS 스트림을 활용하여 비동기 흐름을 유연하게 제어할 수 있다 [6].
  * **Django**: 미들웨어와 데코레이터를 사용하여 단순하고 직관적인 중앙 집중식 흐름 제어를 지원한다 [6]. 그러나 모델의 생명주기 이벤트에 반응하는 Signals(시그널) 또한 횡단 관심사 처리에 쓰이는데, 이는 대규모 시스템에서 지양해야 할 패턴으로 언급된다 [12, 13].
* **클린 아키텍처 환경의 적용**
  * MediatR 기반 파이프라인 등을 활용하여 로깅, 유효성 검사, 캐싱을 인프라 레이어의 파이프라인 동작(Pipeline Behavior)으로 구현함으로써, 핵심 비즈니스 로직과 횡단 관심사를 완벽히 디커플링(Decoupling)할 수 있다 [7, 14, 15].

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
* **추상화로 인한 디버깅 난이도 증가 ("Magic" Behavior)**: Spring Boot의 AOP나 일부 Aspect 지향 도구를 사용하여 런타임에 로직을 삽입하는 방식은 코드를 깔끔하게 유지해주지만, 코드상에 명시적인 호출이 나타나지 않기 때문에 의도치 않은 동작이 발생할 경우 추적 및 디버깅을 매우 어렵게 만든다 [16, 17].
* **성능 오버헤드 (Runtime Cost)**: Castle.DynamicProxy 등과 같이 런타임에 프록시 래퍼(Proxy Wrapper)를 생성하여 메서드 호출을 가로채는 방식은 성능 저하 비용을 동반할 수 있으며, 극단적인 성능 최적화가 필요한 환경에서는 부담이 될 수 있다 [18].
* **Django Signals의 부작용 (Side Effects)**: 횡단 관심사를 처리하기 위해 이벤트를 암시적으로 실행시키는 Django의 시그널 패턴은 비즈니스 로직이 혼재될 위험이 크며, 실행 흐름을 불투명하게 만들고 예측 불가능한 부수 효과를 초래하여 유지보수성을 크게 떨어뜨린다 [12, 13]. 대규모 시스템에서는 이를 피하고 명시적인 서비스 레이어 호출을 권장한다 [13].

## 🔗 지식 연결 (Graph)

### Related Concepts

#### [아키텍처/기반 기술]
- [[Cross-Cutting Concerns]]
  - 연결 이유: 미들웨어와 인터셉터가 시스템에서 구조적으로 분리하여 해결하고자 하는 핵심 요구사항이자 철학이다 [1].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 애플리케이션의 핵심 비즈니스 로직 외에 로깅, 인증, 에러 핸들링 등을 시스템 전역에서 어떻게 모듈화할지 이해할 수 있다.
- [[AOP (Aspect-Oriented Programming)]]
  - 연결 이유: Spring Boot 등에서 메서드 레벨의 횡단 관심사를 주입하기 위해 사용되는 프로그래밍 패러다임이다 [5].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 객체 지향 설계를 넘어 코드의 산재(Scattering)와 얽힘(Tangling)을 방지하는 원리를 배울 수 있다.

#### [구현/활용 도구]
- [[Spring Boot]]
  - 연결 이유: Filter, Interceptor, AOP라는 각기 다른 깊이의 횡단 관심사 처리 파이프라인을 가장 명확하게 구현 및 분류하고 있는 백엔드 프레임워크이다 [2, 8].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 서블릿 영역과 프레임워크 컨트롤러, 내부 서비스 빈(Bean) 계층 간의 물리적/논리적 동작 차이를 파악할 수 있다.
- [[NestJS]]
  - 연결 이유: Express의 단순 미들웨어 구조의 한계를 보완하기 위해 Guard, Interceptor, Pipe 등의 구조적 패턴을 강제한다 [6, 11].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: Node.js 생태계에서 엔터프라이즈 급의 파이프라인 아키텍처가 어떻게 구축되는지 학습할 수 있다.
- [[Django Signals]]
  - 연결 이유: Django에서 이벤트 기반으로 횡단 관심사를 처리하는 수단이나 대규모 애플리케이션에서는 안티 패턴으로 꼽힌다 [12, 13].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 암시적(Implicit) 로직 실행이 초래하는 디버깅 문제와 부수 효과의 위험성을 이해할 수 있다.

### Deeper Research Questions
- Spring Boot의 Filter, Interceptor, AOP는 구체적으로 어떤 라이프사이클 순서로 실행되며, 각각이 발생시키는 성능 오버헤드에는 어떤 차이가 있는가?
- NestJS의 Interceptor에서 RxJS 스트림을 활용할 때, 일반적인 Express 미들웨어나 Promise 기반 처리와 비교하여 어떤 비동기적 이점을 얻을 수 있는가?
- 클린 아키텍처 환경에서 미들웨어(또는 Pipeline Behavior)가 프레임워크 의존적인 '입력 유효성 검사'와 도메인 의존적인 '비즈니스 룰 유효성 검사'를 어떻게 분리하여 처리하는가?
- 런타임 프록시 생성에 따른 성능 저하(Runtime cost)를 피하기 위해 컴파일 타임(Compile-Time)이나 링크 타임(Link-Time)에 AOP를 위빙(Weaving)하는 기술적 원리는 무엇인가?
- 대규모 Django 프로젝트에서 시그널(Signals)의 부수 효과를 피하면서도 이벤트 기반의 횡단 관심사를 명시적이고 안전하게 처리하기 위한 현대적인 대안 아키텍처는 무엇인가?

### Practical Application Contexts
- **Implementation:** 비즈니스 컨트롤러 파일마다 로그 작성 및 토큰 검증 코드를 붙여넣는 대신, 단일 미들웨어, 필터 또는 인터셉터 클래스를 작성하여 전역적으로 혹은 특정 라우트에만 주입하도록 구현한다.
- **System Design:** 아키텍처 설계 시, 로깅 등은 최외곽 서블릿 필터나 미들웨어에 배치하고, 사용자 권한 부여나 트랜잭션 관리는 비즈니스 로직과 인접한 프레임워크 인터셉터 또는 AOP 영역에 계층적으로 배치하여 응집도를 높인다.
- **Operation / Maintenance:** 중앙 집중화된 예외 처리 및 로깅 미들웨어를 구축함으로써, 프로덕션 운영 중 에러 발생 시 로그 형식을 일관되게 유지하고 시스템 이슈를 빠르게 추적/분석할 수 있다.
- **Learning Path:** 단순한 함수 형태인 Express.js 미들웨어의 작동 원리를 먼저 학습한 후, 계층적 권한 검사와 반환 값 변형을 처리하는 NestJS의 Guard 및 Interceptor로 지식을 확장해 나간다.
- **My Project Relevance:** 현재 유지보수 중인 프로젝트 내에서 비즈니스 모델이나 컨트롤러 내부에 캐싱, 에러 추적 코드가 하드코딩되어 있다면, 이를 별도의 인터셉터/AOP 로직으로 추출하여 리팩토링하는 작업의 근거가 된다.

### Adjacent Topics
- [[Clean Architecture]]
  - 확장 방향: 인프라와 도메인을 완벽히 분리하려는 철학 안에서, 미들웨어 레이어가 기술 종속성을 어떻게 외부로 밀어내는지 확장하여 탐구한다.
- [[Event-Driven Architecture]]
  - 확장 방향: 횡단 관심사 로직(특히 로깅, 알림 등)을 미들웨어의 동기적 파이프라인에서 벗어나 메시지 큐 등을 활용한 비동기 이벤트 방식으로 처리하는 아키텍처로 지식을 확장한다.

---
*Last updated: 2026-05-03*
---
*Last updated: 2026-05-03*
- Raw Source: 00_Raw/2026-05-03/Middleware & Interceptors.md
---
