NestJS의 특징과 아키텍처
NestJS가 모듈·컨트롤러·프로바이더와 DI 컨테이너로 확장 가능한 Node.js 서버 구조를 만드는 원리를 이해합니다.
Node.js 서버 개발을 해보면 초기에는 빠르게 만들 수 있지만, 기능이 늘어날수록 구조가 흔들리는 순간을 자주 만나게 됩니다.
라우팅, 비즈니스 로직, 인증, 예외 처리, 테스트 코드가 섞이기 시작하면 작은 변경에도 영향 범위를 예측하기 어려워집니다.
많은 팀이 이 시점에서 프레임워크를 바꿔야 하는지를 고민하게 되고, 그 대안 중 하나가 NestJS입니다.
Nest는 Express를 기본 HTTP 플랫폼으로 사용합니다. @nestjs/platform-fastify의 FastifyAdapter를 전달하면 Fastify로 바꿀 수 있지만, 이 경우 Express 전용 패키지나 조리법은 그대로 동작하지 않을 수 있어 Fastify에 맞는 대안을 사용해야 합니다.
하지만 단순히 HTTP 프레임워크 위에 장식을 얹은 도구는 아닙니다.
대규모 서버 개발에서 필요한 구조와 규칙을 기본값으로 제공하는 프레임워크에 가깝습니다.
이 절에서는 NestJS가 왜 주목받는지, 그리고 실제로 어떤 아키텍처 원칙이 개발 생산성과 운영 안정성을 높이는지 현실적인 관점으로 정리하겠습니다.
NestJS는 Node.js 환경에서 효율적(Efficient)이고 안정적(Reliable)이며 확장성(Scalable) 있는 서버 애플리케이션을 구축하기 위한 진보적인(Progressive) Node.js 프레임워크입니다.
이 정의에 담긴 핵심 키워드는 효율성, 신뢰성, 확장성, 그리고 진보성입니다.
이 단어들이 실제 개발에서 어떤 의미를 갖는지, 지금부터 구조와 아키텍처 맥락에서 하나씩 풀어보겠습니다.
NestJS, 왜 선택해야 할까요?
Node.js 생태계에는 Express.js, Koa.js와 같은 웹 프레임워크가 이미 많이 존재합니다.
NestJS는 이들과 달리 데코레이터 메타데이터, IoC/DI 컨테이너, 모듈 그래프를 기본 전제로 두며, 이 절에서는 그 구조 차이가 프로젝트 경계에 어떤 영향을 주는지 봅니다.
가장 큰 이유는 아키텍처의 견고함에 있습니다.
기존 Node.js 프레임워크들이 비교적 자유로운 개발 스타일을 제공한 반면, NestJS는 모듈화(Modularity)되고 구조화된 아키텍처를 지향합니다.
이 접근은 애플리케이션 규모가 커질수록 더 큰 효과를 냅니다.
정해진 규칙과 명확한 역할 덕분에 코드 복잡도를 낮추고, 장기 유지보수와 협업 환경에서의 일관된 코드 품질 유지가 쉬워집니다.
또한, NestJS는 TypeScript를 기반으로 구축되었습니다.
TypeScript는 JavaScript에 정적 타입을 추가해 컴파일 단계에서 타입 불일치 일부를 줄이고, 데코레이터와 생성자 주입 패턴을 코드 구조 안에 드러내기 좋습니다.
이는 대규모 애플리케이션에서 의존성 경계와 테스트 대역을 관리할 때 특히 중요한 요소입니다.
HTTP 요청도 정해진 수명주기를 따릅니다. 일반적인 정상 경로는 middleware → guards → interceptors(컨트롤러 전) → pipes → controller → service(호출한 경우) → interceptors(컨트롤러 후) → response 순서입니다. Exception filter는 정상 응답 단계가 아니라, 처리되지 않은 예외가 발생했을 때만 남은 경로를 건너뛰고 실행됩니다. 필터는 route → controller → global 우선순위로 탐색되며, 가장 가까운 일치 필터가 처리한 같은 예외가 다음 필터로 연쇄 전달되지는 않습니다.
NestJS HTTP 요청 수명주기
가드가 허용하고 정상 반환하는 요청 하나를 추적합니다. 거부·미처리 예외 경로는 원표의 조건별 종료이며 정상 응답 뒤에 이어 실행하지 않습니다.
Nest 요청 · 정상 흐름과 예외
요청은 실행 경계를 따라 진행하고, 반환은 interceptor를 반대로 풉니다
등록한 구성 요소가 있는 일반 HTTP 흐름입니다. Service는 호출한 경우에 사용하며, 처리되지 않은 예외는 남은 정상 경로 대신 일치하는 filter로 처리합니다.
먼저 · 요청을 받아 실행 문맥 준비
- HTTP 어댑터
기본 Express 또는 선택한 FastifyAdapter가 요청을 받습니다.
- Middleware
global → 경로에 바인딩한 module middleware 순서입니다.
- Guards
global → controller → route 순서로 진행 여부를 판단합니다.
- Interceptor · 실행 전
global → controller → route 순서로 핸들러 실행을 감쌉니다.
이어서 · 인자 처리와 핸들러, 반환
- Pipes
global → controller → route → parameter 범위에서 인자를 변환·검증합니다.
- Controller
선택한 method handler를 실행합니다.
- Provider / Service · 호출한 경우
컨트롤러가 필요한 업무 규칙이나 외부 작업을 위임합니다.
- Interceptor · 반환 경로
route → controller → global 순서로 풀린 뒤 응답합니다.
처리되지 않은 예외 → Exception filter
route → controller → global 우선순위로 가장 가까운 일치 filter가 처리합니다. 같은 예외가 다음 filter로 연쇄 전달되지는 않습니다.
Interceptor의 catchError가 pipe·controller·service의 오류를 처리할 수도 있습니다. middleware 예외는 route 선택 전이므로 전역 filter가 적용됩니다.
위 두 패널은 앞 단계와 이어지는 단계입니다. Pipe가 여러 인자를 처리하는 세부 순서는 인자 선언 순서와 다를 수 있으며, 표시는 구성 요소의 적용 범위를 요약합니다.
이 예의 조건
- 두 박스는 같은 실행의 진행 정보와 자료·결과를 관찰하는 고정 역할입니다. 박스의 좌우·위아래 위치를 별도 호출 순서로 해석하지 않습니다.
- 조건별 종료는 대안입니다. 실패 뒤 정상 후속 단계를 실행하거나 독립 비교 사례를 같은 요청으로 연결하지 않습니다.
- 미들웨어와 가드를 통과한 요청은 실행 전 인터셉터, 파이프, 컨트롤러와 호출한 서비스, 반환 인터셉터를 거쳐 응답한다. 가드가 거부해 미처리 예외가 발생한 예시에서는 남은 정상 단계를 실행하지 않고 일치하는 예외 필터가 오류 응답을 만든다. 다른 단계의 예외 경계와 세부 순서는 아래 설명에서 확인한다.
관계도의 보충 설명
| 순번 | 원문 표시 |
|---|---|
| 1 | NestJS HTTP 요청 수명주기 |
| 장면 | 관찰 값 | 전환 이유 |
|---|---|---|
| 허용된 요청 진입 선택한 정상 요청이 middleware를 거쳐 guard를 통과합니다. | 선택 조건: guard 허용 · 뒤 경로: 정상 단계 진행 · guard 거부 대안: 남은 정상 단계 미실행·원표 보존 | 가드가 허용한 요청 하나만 다음 정상 실행 단계로 이어집니다. |
| 입력 처리와 handler 실행 전 interceptor와 pipe를 거쳐 controller와 호출한 service를 실행합니다. | interceptor: global→controller→route 진입 · pipe: 인자 변환·검증 · handler: controller·service는 호출한 경우 | 허용된 요청의 인자가 준비되면 업무 handler를 실행합니다. |
| 정상 반환과 응답 정상 결과가 interceptor의 route→controller→global 반환 처리를 거쳐 응답으로 나갑니다. | handler 결과: 정상 반환 · interceptor 반환: route→controller→global · 응답: 정상 HTTP 응답 | 정상 실행을 여기서 마칩니다. 미처리 예외의 가장 가까운 일치 filter는 원표의 별도 대안입니다. |
NestJS HTTP 요청 수명주기
가드가 허용하고 정상 반환하는 요청 하나를 추적합니다. 거부·미처리 예외 경로는 원표의 조건별 종료이며 정상 응답 뒤에 이어 실행하지 않습니다.
Nest 요청 · 정상 흐름과 예외
요청은 실행 경계를 따라 진행하고, 반환은 interceptor를 반대로 풉니다
등록한 구성 요소가 있는 일반 HTTP 흐름입니다. Service는 호출한 경우에 사용하며, 처리되지 않은 예외는 남은 정상 경로 대신 일치하는 filter로 처리합니다.
먼저 · 요청을 받아 실행 문맥 준비
- HTTP 어댑터
기본 Express 또는 선택한 FastifyAdapter가 요청을 받습니다.
- Middleware
global → 경로에 바인딩한 module middleware 순서입니다.
- Guards
global → controller → route 순서로 진행 여부를 판단합니다.
- Interceptor · 실행 전
global → controller → route 순서로 핸들러 실행을 감쌉니다.
이어서 · 인자 처리와 핸들러, 반환
- Pipes
global → controller → route → parameter 범위에서 인자를 변환·검증합니다.
- Controller
선택한 method handler를 실행합니다.
- Provider / Service · 호출한 경우
컨트롤러가 필요한 업무 규칙이나 외부 작업을 위임합니다.
- Interceptor · 반환 경로
route → controller → global 순서로 풀린 뒤 응답합니다.
처리되지 않은 예외 → Exception filter
route → controller → global 우선순위로 가장 가까운 일치 filter가 처리합니다. 같은 예외가 다음 filter로 연쇄 전달되지는 않습니다.
Interceptor의 catchError가 pipe·controller·service의 오류를 처리할 수도 있습니다. middleware 예외는 route 선택 전이므로 전역 filter가 적용됩니다.
위 두 패널은 앞 단계와 이어지는 단계입니다. Pipe가 여러 인자를 처리하는 세부 순서는 인자 선언 순서와 다를 수 있으며, 표시는 구성 요소의 적용 범위를 요약합니다.
이 예의 조건
- 두 박스는 같은 실행의 진행 정보와 자료·결과를 관찰하는 고정 역할입니다. 박스의 좌우·위아래 위치를 별도 호출 순서로 해석하지 않습니다.
- 조건별 종료는 대안입니다. 실패 뒤 정상 후속 단계를 실행하거나 독립 비교 사례를 같은 요청으로 연결하지 않습니다.
- 미들웨어와 가드를 통과한 요청은 실행 전 인터셉터, 파이프, 컨트롤러와 호출한 서비스, 반환 인터셉터를 거쳐 응답한다. 가드가 거부해 미처리 예외가 발생한 예시에서는 남은 정상 단계를 실행하지 않고 일치하는 예외 필터가 오류 응답을 만든다. 다른 단계의 예외 경계와 세부 순서는 아래 설명에서 확인한다.
관계도의 보충 설명
| 순번 | 원문 표시 |
|---|---|
| 1 | NestJS HTTP 요청 수명주기 |
| 장면 | 관찰 값 | 전환 이유 |
|---|---|---|
| 허용된 요청 진입 선택한 정상 요청이 middleware를 거쳐 guard를 통과합니다. | 선택 조건: guard 허용 · 뒤 경로: 정상 단계 진행 · guard 거부 대안: 남은 정상 단계 미실행·원표 보존 | 가드가 허용한 요청 하나만 다음 정상 실행 단계로 이어집니다. |
| 입력 처리와 handler 실행 전 interceptor와 pipe를 거쳐 controller와 호출한 service를 실행합니다. | interceptor: global→controller→route 진입 · pipe: 인자 변환·검증 · handler: controller·service는 호출한 경우 | 허용된 요청의 인자가 준비되면 업무 handler를 실행합니다. |
| 정상 반환과 응답 정상 결과가 interceptor의 route→controller→global 반환 처리를 거쳐 응답으로 나갑니다. | handler 결과: 정상 반환 · interceptor 반환: route→controller→global · 응답: 정상 HTTP 응답 | 정상 실행을 여기서 마칩니다. 미처리 예외의 가장 가까운 일치 filter는 원표의 별도 대안입니다. |
핵심 아키텍처: 모듈, 컨트롤러, 프로바이더
NestJS는 내부적으로 모듈(Modules), 컨트롤러(Controllers), 프로바이더(Providers)라는 세 가지 핵심 구성 요소를 기반으로 애플리케이션을 구축합니다.
@Module()의 controllers, providers, imports, exports 메타데이터가 모듈 스코프와 공개 범위를 만들고, DI 컨테이너가 이 그래프를 기준으로 인스턴스를 연결합니다.
-
모듈 (Modules): NestJS 애플리케이션의 기본 구성 단위입니다.
@Module()데코레이터로 정의하며, 관련 컨트롤러와 프로바이더를 묶어 기능별 응집도를 높여줍니다. 예를 들어 사용자 인증 기능(로그인, 회원가입, 비밀번호 찾기 등)은AuthModule하나로 묶을 수 있습니다. 프로바이더는 기본적으로 선언한 모듈 안에 캡슐화됩니다. 프로바이더를 제공하는 모듈은 해당 프로바이더를exports에 등록하고, 이를 사용하는 다른 모듈은 제공 모듈을imports에 등록해야 그 의존성을 주입받을 수 있습니다. -
컨트롤러 (Controllers): 클라이언트 요청(Request)을 처리하고 응답(Response)을 반환하는 경계입니다.
@Controller()와@Get(),@Post()같은 route decorator로 엔드포인트를 정의합니다. 등록된 pipe는 컨트롤러 메서드보다 먼저 실행되며, DTO로 표현한 입력을ValidationPipe같은 pipe가 변환·검증하도록 구성할 수 있습니다. 컨트롤러는 그 결과를 받아 필요한 프로바이더를 호출합니다. 컨트롤러는 가능한 한 얇게 유지하고, 분기와 외부 연동은 서비스 계층으로 넘기는 편이 테스트와 변경 대응에 유리합니다. -
프로바이더 (Providers): 비즈니스 로직을 담는 서비스뿐 아니라 레포지토리(Repository), 팩토리(Factory), 헬퍼(Helper) 등을 Nest DI 컨테이너에 등록해 주입할 수 있는 구성 요소입니다. 보통
@Injectable()데코레이터로 정의하며, 서비스(Service), 레포지토리, 팩토리, 값 프로바이더 등 다양한 형태로 존재합니다. 프로바이더는 의존성 주입(Dependency Injection) 메커니즘으로 다른 프로바이더나 컨트롤러에 주입되어 사용됩니다. 이 방식은 코드 재사용성을 높이고 테스트를 쉽게 하며 코드 간 결합도를 낮추는 데 크게 기여합니다. 테스트에서는overrideProvider()나 mock provider를 사용해 외부 API, DB, 캐시 같은 의존성을 대체할 수 있습니다.
프로바이더의 인스턴스 수명은 기본적으로 애플리케이션 전체에서 공유되는 singleton(Scope.DEFAULT)입니다. 요청마다 새 인스턴스가 필요한 경우에는 Scope.REQUEST, 주입받는 소비자마다 새 인스턴스가 필요한 경우에는 Scope.TRANSIENT를 명시할 수 있습니다. 요청 스코프는 의존성 체인을 따라 상위 소비자까지 전파될 수 있으므로 필요한 경우에만 선택합니다.
NestJS는 모듈, 컨트롤러, 프로바이더를 분리해 관심사의 분리(Separation of Concerns) 원칙을 구조로 표현합니다.
각 구성 요소의 책임이 명확해지면 유지보수와 테스트가 쉬워집니다.
운영 관점에서도 이 분리는 큰 이점을 줍니다.
관심사가 분리된 구조에서는 요청 전처리는 middleware, 접근 판단은 guard, 입력 변환·검증은 pipe, 실행 전후의 공통 처리는 interceptor, 처리되지 않은 예외의 응답 변환은 exception filter처럼 정책의 실행 경계를 구분할 수 있습니다. 외부 호출 재시도는 일반적인 exception filter 역할이 아니라, 해당 호출을 소유한 provider나 client 경계에서 설계하는 편이 책임에 맞습니다.
결국 NestJS의 강점은 코드를 예쁘게 만드는 것을 넘어, 장애 대응과 변경 대응 속도를 함께 높여준다는 데 있습니다.
아래 표는 기능 경계, 엔드포인트, 업무 규칙, 공통 정책을 어디에 두고 어떤 테스트 경계를 사용할지 정리합니다.
Nest 책임 · 변경과 검증
변경의 종류에 맞춰 Module·HTTP 경계·Provider·공통 정책을 나눕니다
기능 조립, 요청 계약, 업무 규칙, 요청 정책은 서로 다른 변경 이유를 가집니다. 가시성과 provider 인스턴스 수명, 단위 테스트와 HTTP 테스트도 구분합니다.
기능 경계를 추가한다
controllers와 providers를 선언하고 필요한 module을 imports한다. 다른 module에 공개할 provider만 exports한다.TestingModule이 의존성 그래프를 컴파일하는지, 공개한 token만 소비 모듈에서 주입되는지 확인한다.HTTP 엔드포인트를 추가한다
업무 규칙이나 외부 의존을 바꾼다
REQUEST나 TRANSIENT를 선택한다.overrideProvider()의 useValue, useClass, useFactory로 DB·외부 API·캐시를 대체한다.공통 요청 정책을 적용한다
APP_*로 등록한 전역 enhancer를 class token으로 대체하려면 useExisting으로 실제 provider를 노출한 뒤 그 token을 override한다.Module의 provider 가시성과 provider 인스턴스 수명은 서로 다른 결정이다. 구조가 얇은 controller를 자동으로 보장하지는 않으므로 책임 분리를 코드와 테스트에서 함께 유지한다.
예시: 같은 사용자 기능에서도 바뀌는 이유는 다릅니다
사용자 목록을 제공하는 서버에 세 가지 변경을 요청했다고 생각해 보세요. 주소를 /users에서 /members로 바꾸는 일은 HTTP 경로를 선언한 컨트롤러에서 시작합니다. 이름이 빈 사용자를 등록하지 못하게 하는 입력 규칙은 DTO와 파이프에서 확인합니다. 가입한 사용자에게 환영 메시지를 보내는 업무는 서비스가 맡고, 실제 외부 메시지 전송은 별도 프로바이더에 위임할 수 있습니다. 모듈은 이 객체들을 등록하고 연결합니다.
이처럼 객체를 여러 개 만드는 목적은 파일 수를 늘리는 데 있지 않습니다. 어떤 요구가 바뀌었는지에 따라 읽고 고칠 위치를 좁히는 데 있습니다. @Injectable()을 붙였다는 사실과 모듈에서 그 프로바이더를 사용할 수 있다는 사실도 구분해야 합니다.
스스로 구분해 보기
로그인하지 않은 요청을 거부하는 규칙과, 허용된 요청의 응답에 실행 시간을 기록하는 규칙을 각각 어디에 둘지 판단해 보세요. 그리고 거부된 요청에서 컨트롤러와 서비스가 실행되어야 하는지도 설명해 보세요.
판단 근거 확인하기
접근 허용 여부는 가드에서 판단합니다. 가드가 요청을 거부하면 뒤의 컨트롤러와 서비스는 실행하지 않습니다. 허용된 실행을 감싸 시간을 측정하려면 인터셉터가 알맞습니다. 이 위치의 인터셉터가 가드에서 이미 거부된 요청까지 측정한다고 추측하면 안 됩니다. 실행 순서 때문에 적용 범위가 달라지는 것입니다.
정리하면 NestJS의 강점은 프레임워크 문법 자체보다, 요청 경계와 비즈니스 규칙, 의존성 조립 위치를 일관되게 고정해 주는 구조에 있습니다.
다음 절에서는 NestJS 개발 환경을 설정하는 방법에 대해 알아보겠습니다.