[Nest.js] Overview - First Steps, Controllers

첫걸음

이 일련의 글에서는 Nest의 핵심 기초 개념들을 학습하게 됩니다. Nest 애플리케이션의 필수 구성 요소에 익숙해지기 위해, 우리는 기본적인 CRUD 애플리케이션을 만들어보며 입문 수준에서 넓은 범위를 다루는 다양한 기능들을 구현해 볼 것입니다.

언어

우리는 TypeScript를 사랑하지만, 그 무엇보다도 Node.js를 사랑합니다. 그렇기 때문에 Nest는 TypeScript와 순수 JavaScript 모두와 호환됩니다. Nest는 최신 언어 기능들을 활용하기 때문에, 순수 JavaScript로 사용하려면 Babel 컴파일러가 필요합니다.

 

예제에서는 대부분 TypeScript를 사용하지만, 언제든지 코드 스니펫 오른쪽 상단의 언어 전환 버튼을 클릭하여 순수 JavaScript 문법으로 바꿔볼 수 있습니다.

사전 요구사항

운영 체제에 Node.js (버전 20 이상)가 설치되어 있는지 반드시 확인하세요.

설정

Nest CLI를 사용하면 새 프로젝트 설정이 매우 간단합니다. npm이 설치되어 있다면, 운영 체제의 터미널에서 다음 명령어를 사용하여 새로운 Nest 프로젝트를 생성할 수 있습니다:

$ npm i -g @nestjs/cli
$ nest new project-name

힌트
보다 엄격한 기능 세트로 새로운 TypeScript 프로젝트를 생성하려면 nest new 명령어에 --f 플래그를 추가하세요.

 

project-name 디렉터리가 생성되고, node_modules 및 몇 가지 보일러플레이트 파일들이 설치되며, src/ 디렉터리가 생성되어 여러 핵심 파일들로 채워집니다.

src/
├── app.controller.spec.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts

 

다음은 이러한 핵심 파일들에 대한 간략한 설명입니다:

app.controller.ts	단일 라우트를 가진 기본 컨트롤러입니다.
app.controller.spec.ts	해당 컨트롤러의 단위 테스트입니다.
app.module.ts	애플리케이션의 루트 모듈입니다.
app.service.ts	단일 메서드를 가진 기본 서비스입니다.
main.ts	Nest 애플리케이션 인스턴스를 생성하기 위해 핵심 함수인 NestFactory를 사용하는 애플리케이션의 진입 파일입니다.

 

main.ts에는 애플리케이션을 부트스트랩하는 비동기 함수가 포함되어 있습니다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

 

Nest 애플리케이션 인스턴스를 생성하기 위해, NestFactory라는 Nest의 핵심 클래스를 사용합니다. NestFactory는 애플리케이션 인스턴스를 생성할 수 있는 몇 가지 정적 메서드를 제공합니다. 이 중 create() 메서드는 INestApplication 인터페이스를 구현하는 애플리케이션 객체를 반환합니다. 이 객체는 이후 장들에서 설명될 다양한 메서드들을 제공합니다. 위의 main.ts 예제에서는 간단히 HTTP 리스너를 시작하여 애플리케이션이 들어오는 HTTP 요청을 대기할 수 있도록 합니다.

 

참고로, Nest CLI로 스캐폴딩 된 프로젝트는 각 모듈을 전용 디렉터리에 보관하는 관례를 따르도록 초기 프로젝트 구조를 생성합니다.

힌트
기본적으로 애플리케이션 생성 중 오류가 발생하면, 앱은 종료 코드 1과 함께 종료됩니다. 대신 오류를 throw 하도록 하려면 abortOnError 옵션을 비활성화하면 됩니다 (예: NestFactory.create(AppModule, { abortOnError: false })).

 

플랫폼

Nest는 플랫폼에 구애받지 않는 프레임워크를 지향합니다. 플랫폼 독립성 덕분에, 개발자는 다양한 종류의 애플리케이션에서 재사용 가능한 논리 구성 요소들을 만들고 활용할 수 있습니다. 기술적으로 Nest는 어댑터가 제공되면 어떤 Node HTTP 프레임워크와도 작동할 수 있습니다. 기본적으로 지원되는 두 가지 HTTP 플랫폼은 express와 fastify이며, 필요에 따라 적합한 것을 선택하여 사용할 수 있습니다.

platform-express	Express는 Node를 위한 잘 알려진 미니멀리스트 웹 프레임워크입니다. 커뮤니티에 의해 다수의 리소스가 구현되어 있으며, 실전에서 검증된 프로덕션 준비 완료 라이브러리입니다. 기본적으로는 @nestjs/platform-express 패키지가 사용됩니다. 많은 사용자들은 Express만으로도 충분히 만족할 수 있으며, 별도의 설정 없이 바로 사용할 수 있습니다.
platform-fastify	Fastify는 높은 성능과 낮은 오버헤드를 지닌 프레임워크로, 최대한의 효율성과 속도 제공에 중점을 둡니다. Fastify 사용 방법은 여기에서 확인할 수 있습니다.

 

어떤 플랫폼을 사용하든, 각 플랫폼은 고유한 애플리케이션 인터페이스를 제공합니다. 이는 각각 NestExpressApplication과 NestFastifyApplication으로 나타납니다.

 

아래 예제처럼 NestFactory.create() 메서드에 타입을 전달하면, 반환된 app 객체는 해당 플랫폼에만 존재하는 전용 메서드들을 사용할 수 있게 됩니다. 다만, 실제로 플랫폼의 하위 API에 접근할 필요가 없다면 타입을 명시할 필요는 없습니다.

const app = await NestFactory.create<NestExpressApplication>(AppModule);

애플리케이션 실행

설치 과정이 완료되면, 운영 체제의 명령 프롬프트에서 다음 명령어를 실행하여 애플리케이션이 HTTP 요청을 수신하도록 시작할 수 있습니다:

$ npm run start

힌트
개발 속도를 약 20배 빠르게 하려면, -b swc 플래그를 start 스크립트에 전달하여 SWC 빌더를 사용할 수 있습니다. 예:
npm run start -- -b swc

 

이 명령어는 src/main.ts 파일에 정의된 포트에서 HTTP 서버를 시작합니다. 애플리케이션이 실행되면 브라우저를 열고 http://localhost:3000/으로 이동하세요. “Hello World!” 메시지를 볼 수 있어야 합니다.

 

파일 변경 사항을 감지하면서 애플리케이션을 실행하려면 다음 명령어를 사용할 수 있습니다:

$ npm run start:dev

 

이 명령어는 파일을 감시하면서 자동으로 다시 컴파일하고 서버를 재시작합니다.

린트와 포맷팅

CLI는 대규모 개발에서도 신뢰할 수 있는 워크플로우를 스캐폴딩 하기 위해 최선을 다합니다. 따라서 생성된 Nest 프로젝트에는 코드 린터와 포매터가 기본으로 설치되어 있습니다(각각 eslint와 prettier).

힌트
포매터와 린터의 차이점이 궁금하다면 여기를 참고하세요.

 

최대의 안정성과 확장성을 보장하기 위해, 우리는 기본 eslint 및 prettier CLI 패키지를 사용합니다. 이 구성은 공식 확장 프로그램을 통한 깔끔한 IDE 통합을 가능하게 합니다.

 

IDE가 필요하지 않은 헤드리스 환경(CI, Git hooks 등)에서도 사용할 수 있도록 Nest 프로젝트에는 즉시 사용 가능한 npm 스크립트가 함께 제공됩니다.

# eslint로 린트 및 자동 수정
$ npm run lint

# prettier로 포맷팅
$ npm run format

---

컨트롤러

컨트롤러는 들어오는 요청을 처리하고 클라이언트에게 응답을 반환하는 역할을 합니다.

 

컨트롤러의 목적은 애플리케이션의 특정 요청을 처리하는 것입니다. 라우팅 메커니즘은 각 요청을 어떤 컨트롤러가 처리할지를 결정합니다. 일반적으로 하나의 컨트롤러는 여러 개의 라우트를 가지며, 각 라우트는 서로 다른 동작을 수행할 수 있습니다.

 

기본 컨트롤러를 생성하려면 클래스와 데코레이터를 사용합니다. 데코레이터는 클래스에 필요한 메타데이터를 연결하여, Nest가 요청과 해당 컨트롤러를 연결하는 라우팅 맵을 생성할 수 있도록 합니다.

힌트
내장된 유효성 검사 기능과 함께 CRUD 컨트롤러를 빠르게 생성하려면 CLI의 CRUD 생성기를 사용할 수 있습니다: nest g resource [name]

라우팅

다음 예제에서는 기본 컨트롤러를 정의하기 위해 필수적인 @Controller() 데코레이터를 사용합니다. 여기서는 선택적으로 cats라는 경로 접두사를 지정합니다. @Controller() 데코레이터에 경로 접두사를 사용하는 것은 관련된 라우트들을 그룹화하고 중복 코드를 줄이는 데 도움이 됩니다. 예를 들어, 고양이 (cat) 엔티티와의 상호작용을 관리하는 라우트들을 /cats 경로 아래로 묶고 싶다면, @Controller('cats')와 같이 지정하면 됩니다. 이렇게 하면 해당 파일 내의 각 라우트마다 /cats를 반복해서 작성할 필요가 없습니다.

import { Controller, Get } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(): string {
    return 'This action returns all cats';
  }
}

힌트
CLI를 사용하여 컨트롤러를 생성하려면, 다음 명령어를 실행하면 됩니다: nest g controller [main]

 

@Get() HTTP 요청 메서드 데코레이터는 findAll() 메서드 앞에 위치하며, Nest에게 특정 엔드포인트에 대한 HTTP 요청을 처리하는 핸들러를 생성하라고 지시합니다. 이 엔드포인트는 HTTP 요청 메서드(GET)와 라우트 경로에 의해 정의됩니다. 그렇다면 라우트 경로란 무엇일까요? 핸들러의 라우트 경로는 컨트롤러에 선언된 (선택적인) 접두사와 메서드 데코레이터에 지정된 경로를 결합하여 결정됩니다. 현재는 cats 접두사가 설정되어 있고, 메서드 데코레이터에는 별도의 경로가 지정되어 있지 않으므로 Nest는 GET /cats 요청을 이 핸들러에 매핑합니다.

 

앞서 언급했듯이, 라우트 경로는 컨트롤러의 경로 접두사와 메서드 데코레이터에 지정된 경로 문자열을 합쳐서 구성됩니다. 예를 들어 컨트롤러 접두사가 cats이고, 메서드 데코레이터가 @Get('breed') 라면, 실제 라우트는 GET /cats/breed가 됩니다.

 

위 예시에서 GET 요청이 해당 엔드포인트로 들어오면, Nest는 요청을 사용자가 정의한 findAll() 메서드로 라우팅 합니다. 여기서 주의할 점은, 메서드 이름인 findAll은 완전히 임의로 정한 것이며, 라우트를 연결할 메서드를 선언해야 하긴 하지만 Nest는 그 이름 자체에 특별한 의미를 부여하지는 않는다는 것입니다.

 

이 메서드는 200 상태 코드와 함께 응답을 반환하게 되며, 여기서는 단순히 문자열 하나를 응답합니다. 왜 이런 결과가 나타날까요? 이를 설명하려면, Nest가 응답을 조작하는 데 사용하는 두 가지 옵션 개념을 먼저 소개할 필요가 있습니다.

표준 (권장)	Nest의 기본 방식에서는 요청 핸들러가 JavaScript 객체나 배열을 반환할 경우, 자동으로 JSON으로 직렬화되어 응답됩니다. 반면, 문자열, 숫자, 불리언과 같은 JavaScript의 원시 타입을 반환할 경우에는 Nest가 해당 값을 직렬화하지 않고 그대로 전송합니다. 이 방식 덕분에 응답 처리 로직이 매우 단순해지며, 값을 그대로 반환하기만 하면 나머지는 Nest가 처리해줍니다. 또한, 응답의 상태 코드는 기본적으로 항상 200이며, POST 요청의 경우에는 201을 사용합니다. 이 동작은 핸들러 수준에서 @HttpCode(...) 데코레이터를 사용하여 쉽게 변경할 수 있습니다 (자세한 내용은 "Status codes" 참고)
라이브러리 고유 방식	Express와 같은 특정 HTTP 라이브러리의 응답 객체를 직접 사용할 수도 있습니다. 이를 위해서는 핸들러의 인자로 @Res() 데코레이터를 사용해 응답 객체를 주입하면 됩니다(예: findAll(@Res() response)). 이 방식을 사용하면 해당 라이브러리에서 제공하는 응답 메서드들을 직접 사용할 수 있습니다. 예를 들어, Express에서는 response.status(200).send() 같은 코드를 통해 응답을 구성할 수 있습니다.

주의
Nest는 핸들러에서 @Res() 또는 @Next()를 사용하는 경우, 라이브러리 고유 방식(예: Express)을 선택한 것으로 간주합니다. 이 경우 해당 라우트에 대해서는 표준 방식(Standard approach)이 자동으로 비활성화되며, 더 이상 정상적으로 작동하지 않습니다.
만약 두 방식을 동시에 사용하고 싶다면(예: 응답 객체를 주입하여 쿠키나 헤더만 설정하고, 나머지 응답 처리는 Nest에 맡기고 싶은 경우), @Res({ passthrough: true }) 데코레이터를 사용하여 passthrough 옵션을 true로 설정해야 합니다.

요청 객체

핸들러는 종종 클라이언트의 요청 세부 정보에 접근할 필요가 있습니다. Nest는 기본적으로 사용하는 플랫폼(기본은 Express)의 요청 객체에 접근할 수 있도록 지원합니다. 핸들러의 시그니처에 @Req() 데코레이터를 사용하면, Nest가 요청 객체를 주입하여 사용할 수 있게 해 줍니다.

import { Controller, Get, Req } from '@nestjs/common';
import { Request } from 'express';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(@Req() request: Request): string {
    return 'This action returns all cats';
  }
}

힌트
위 예제처럼 request: Request와 같이 Express의 타입 정보를 활용하려면, @types/express 패키지를 설치해야 합니다.

 

요청 객체는 HTTP 요청을 나타내며, 쿼리 문자열, 파라미터, HTTP 헤더, 바디 등의 속성을 포함합니다 (자세한 내용은 여기 참고). 대부분의 경우 이러한 속성들을 수동으로 접근할 필요는 없습니다. 대신, Nest는 @Body()나 @Query()와 같은 전용 데코레이터들을 기본으로 제공하여 쉽게 사용할 수 있도록 해줍니다. 아래는 Nest에서 제공하는 데코레이터들과 각각이 나타내는 플랫폼별 객체들의 목록입니다.

@Request(), @Req()	req
@Response(), @Res()	res
@Next()	next
@Session()	req.session
@Param(key?: string)	req.params / req.params[key]
@Body(key?: string)	req.body / req.body[key]
@Query(key?: string)	req.query / req.query[key]
@Headers(key?: string)	req.headers / req.headers[name]
@Ip()	req.ip
@HostParam()	req.hosts

 

기본 HTTP 플랫폼 (예: Express, Fastify) 간의 타입 호환성을 위해, Nest는 @Res()와 @Response() 데코레이터를 제공합니다. @Res()는 단순히 @Response()의 별칭이며, 둘 다 기본 플랫폼의 응답 객체를 직접 노출합니다. 이를 사용할 때는 해당 플랫폼의 타입 정보 (예: @types/express)를 함께 설치하여 타입 지원을 최대한 활용하는 것이 좋습니다. @Res() 또는 @Response()를 메서드 핸들러에 주입하면, 해당 핸들러는 Nest의 라이브러리 고유 모드 (Library-specific mode)로 전환됩니다. 이 경우 응답 처리는 개발자의 책임이며, 반드시 res.json(...), res.send(...) 등의 메서드를 호출하여 어떤 형태로든 응답을 반환해야 합니다. 그렇지 않으면 HTTP 서버는 응답 없이 대기 상태에 빠지게 됩니다.

힌트
커스텀 데코레이터를 만드는 방법은 해당 챕터에서 확인할 수 있습니다.

리소스

앞서 우리는 고양이 (cats) 리소스를 가져오는 (GET 라우트) 엔드포인트를 정의하였습니다. 일반적으로는 새로운 데이터를 생성하는 엔드포인트도 함께 제공하고 싶을 것입니다. 이를 위해 POST 핸들러를 생성해 보겠습니다:

import { Controller, Get, Post } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Post()
  create(): string {
    return 'This action adds a new cat';
  }

  @Get()
  findAll(): string {
    return 'This action returns all cats';
  }
}

 

이처럼 매우 간단합니다. Nest는 표준 HTTP 메서드에 대한 데코레이터들을 모두 제공합니다: @Get(), @Post(), @Put(), @Delete(), @Patch(), @Options(), @Head(). 추가로, @All()은 모든 HTTP 메서드를 처리하는 엔드포인트를 정의할 수 있게 해 줍니다.

라우트 와일드카드

NestJS는 패턴 기반 라우트도 지원합니다. 예를 들어, 경로의 끝에서 모든 문자 조합과 일치시키기 위해 별표(*)를 와일드카드로 사용할 수 있습니다. 아래 예제에서 findAll() 메서드는 abcd/로 시작하는 모든 라우트에 대해 실행됩니다. 그 뒤에 어떤 문자가 오든 상관없습니다.

@Get('abcd/*')
findAll() {
  return 'This route uses a wildcard';
}

 

abcd/* 경로는 abcd/, abcd/123, abcd/abc 등과 일치합니다. 하이픈(-)과 점(.)은 문자열 기반 경로에서 문자 그대로 해석됩니다.

 

이 방식은 Express와 Fastify 모두에서 동작합니다. 그러나 최신 버전의 Express(v5)에서는 라우팅 시스템이 더 엄격해졌습니다. 순수 Express에서는 경로를 동작시키기 위해 명명된 와일드카드를 사용해야 합니다. 예를 들어 abcd/*splat과 같이 사용하는데, 여기서 splat은 단순히 와일드카드 파라미터의 이름일 뿐이며 특별한 의미는 없습니다. 원하는 이름으로 지정할 수 있습니다. 다만, Nest는 Express를 위한 호환성 레이어를 제공하므로 여전히 별표 (*)를 와일드카드로 사용할 수 있습니다.

 

경로 중간에서 별표를 사용할 경우, Express는 명명된 와일드카드(e.g., ab{*aplat}cd)를 요구하며, Fastify는 이를 전혀 지원하지 않습니다.

상태 코드

앞서 언급했듯이, 응답의 기본 상태 코드는 항상 200이며, POST 요청의 경우에는 기본값이 201입니다. 이 동작은 핸들러 수준에서 @HttpCode(...) 데코레이터를 사용하여 쉽게 변경할 수 있습니다.

@Post()
@HttpCode(204)
create() {
  return 'This action adds a new cat';
}

힌트
HttpCode는 @nestjs/common 패키지에서 임포트 하세요.

 

상태 코드가 고정적이지 않고 여러 조건에 따라 달라지는 경우가 많습니다. 이런 경우에는 라이브러리 고유 응답 객체(@Res()를 사용하여 주입)를 사용할 수 있으며, 오류가 발생한 경우에는 예외를 던질 수도 있습니다.

응답 헤더

커스텀 응답 헤더를 지정하려면 @Header() 데코레이터를 사용하거나, 라이브러리 고유 응답 객체를 사용해 res.header()를 직접 호출할 수 있습니다.

@Post()
@Header('Cache-Control', 'no-store')
create() {
  return 'This action adds a new cat';
}

힌트
Header는 @nestjs/common 패키지에서 임포트 하세요.

리다이렉션

응답을 특정 URL로 리다이렉션 하려면 @Redirect() 데코레이터를 사용하거나, 라이브러리 고유 응답 객체를 사용하여 res.redirect()를 직접 호출할 수 있습니다.

 

@Redirect()는 url과 statusCode 두 개의 인자를 받으며, 둘 다 선택 사항입니다. statusCode를 생략하면 기본값은 302 (Found)입니다.

@Get()
@Redirect('https://nestjs.com', 301)

힌트
경우에 따라 HTTP 상태 코드나 리다이렉션 URL을 동적으로 결정하고 싶을 수 있습니다. 이럴 땐 @nestjs/common의 HttpRedirectResponse 인터페이스를 따르는 객체를 반환하면 됩니다.

 

반환된 값은 @Redirect() 데코레이터에 전달된 모든 인자를 덮어씁니다. 예를 들어:

@Get('docs')
@Redirect('https://docs.nestjs.com', 302)
getDocs(@Query('version') version) {
  if (version && version === '5') {
    return { url: 'https://docs.nestjs.com/v5/' };
  }
}

라우트 파라미터

정적인 경로로는 요청의 일부로 동적 데이터를 받아야 할 경우 (예: GET /cats/1에서 id가 1인 고양이를 가져오기) 원하는 동작을 할 수 없습니다. 이런 경우에는 경로에 라우트 파라미터 토큰을 추가하여 URL에서 동적 값을 추출할 수 있습니다. 아래 @Get() 데코레이터 예제에서처럼, 라우트 파라미터를 정의할 수 있습니다. 이렇게 정의된 파라미터 값은 메서드 시그니처에 @Param() 데코레이터를 사용하여 접근할 수 있습니다.

힌트
파라미터를 포함한 경로는 정적 경로 뒤에 선언해야 합니다. 그래야 파라미터 경로가 정적 경로로 향하는 트래픽을 가로채지 않게 됩니다.

@Get(':id')
findOne(@Param() params: any): string {
  console.log(params.id);
  return `This action returns a #${params.id} cat`;
}

 

@Param() 데코레이터는 메서드의 매개변수 (위 예제에서는 params)를 데코레이션 하여, 라우트 파라미터들을 해당 매개변수의 속성으로 접근할 수 있게 해 줍니다. 코드에서 보이듯이, param.id를 참조하여 id 파라미터에 접근할 수 있습니다.

또는, 데코레이터에 특정 파라미터 토큰을 전달함으로써, 메서드 내부에서 해당 라우트 파라미터를 이름으로 직접 참조할 수도 있습니다.

힌트
Param은 @nestjs/common 패키지에서 임포트 하세요.

@Get(':id')
findOne(@Param('id') id: string): string {
  return `This action returns a #${id} cat`;
}

서브도메인 라우팅

@Controller 데코레이터는 host 옵션을 받을 수 있으며, 이를 통해 들어오는 HTTP 요청의 호스트가 특정 값과 일치해야만 해당 컨트롤러가 처리되도록 설정할 수 있습니다.

@Controller({ host: 'admin.example.com' })
export class AdminController {
  @Get()
  index(): string {
    return 'Admin page';
  }
}

경고
Fastify는 중첩 라우터 (nested routers)를 지원하지 않기 때문에, 서브 도메인 라우팅을 사용하는 경우 기본 Express 어댑터를 사용하는 것이 권장됩니다.

 

라우트 경로와 마찬가지로, host 옵션에서도 토큰을 사용하여 호스트명 내 특정 위치의 동적 값을 캡처할 수 있습니다. 아래 @Controller() 데코레이터 예제에 있는 호스트 파라미터 토큰이 이러한 사용법을 보여줍니다. 이렇게 선언된 호스트 파라미터는 메서드 시그니처에 @HostParam() 데코레이터를 추가하여 접근할 수 있습니다.

@Controller({ host: ':account.example.com' })
export class AccountController {
  @Get()
  getInfo(@HostParam('account') account: string) {
    return account;
  }
}

상태 공유

다른 프로그래밍 언어에서 온 개발자에게는 Nest에서 거의 모든 것이 들어오는 요청 간에 공유된다는 점이 다소 놀라올 수 있습니다. 여기에는 데이터베이스 커넥션 풀, 전역 상태를 가진 싱글톤 서비스 등과 같은 리소스들이 포함됩니다. 이는 Node.js가 각 요청을 개별 스레드로 처리하는 다중 스레드 무상태 모델 (request/response Multi-Threaded Stateless Model)을 사용하지 않기 때문입니다. 그 결과, Nest에서 싱글톤 인스턴스를 사용하는 것은 애플리케이션에 대해 전혀 문제가 되지 않습니다.

 

그렇다고 해도, 일부 예외적인 경우에는 컨트롤러에 요청 기반 수명 (request-based lifetime)을 설정해야 할 필요가 있습니다. 예를 들어 GraphQL 애플리케이션에서의 요청 단위 캐싱, 요청 추적, 멀티 태넌시 구현 등이 이에 해당됩니다. 의존성 주입 범위 (scope)를 제어하는 방법에 대해서는 여기에서 더 자세히 알아볼 수 있습니다.

비동기 처리

우리는 현대적인 JavaScript, 특히 비동기 데이터 처리 방식에 주목합니다. Nest가 비동기 함수를 완벽히 지원하는 이유도 바로 이것입니다. 모든 async 함수는 Promise를 반환해야 하며, 이를 통해 Nest는 나중에 반환될 값을 자동으로 처리할 수 있습니다. 아래는 그 예시입니다:

@Get()
async findAll(): Promise<any[]> {
  return [];
}

 

이 코드는 완전히 유효합니다. 그러나 Nest는 한 단계 더 나아가 라우트 핸들러가 RxJS의 Observable 스트림을 반환하는 것도 허용합니다. Nest는 내부적으로 해당 스트림에 대해 구독을 처리하고, 스트림이 완료되면 최종적으로 방출된 값을 응답으로 반환합니다.

@Get()
findAll(): Observable<any[]> {
  return of([]);
}

 

두 방식 모두 유효하며, 상황에 따라 가장 적합한 방식을 선택하면 됩니다.

요청 본문

이전 예제에서는 POST 라우트 핸들러가 클라이언트로부터 전달된 어떤 파라미터도 받지 않았습니다. 이제 @Body() 데코레이터를 추가하여 이를 개선해 보겠습니다.

 

진행에 앞서(TypeScript를 사용하는 경우), DTO(Data Transfer Object) 스키마를 정의해야 합니다. DTO는 네트워크를 통해 데이터를 주고받는 방식을 정의하는 객체입니다. 이 DTO 스키마는 TypeScript의 인터페이스나 단순 클래스 중 하나로 정의할 수 있지만, 여기서는 클래스 사용을 권장합니다. 왜일까요? 클래스는 JavaScript ES6 표준의 일부이기 때문에 컴파일된 JavaScript에서도 실제 엔티티로 유지됩니다. 반면, 인터페이스는 트랜스파일 시 제거되기 때문에 런타임에서는 Nest가 이를 참조할 수 없습니다. 이는 Pipe 기능들이 런타임에서 변수의 메타타입에 접근해야 하는 경우에 매우 중요하며, 클래스일 때만 가능합니다.

 

이제 CreateCatDto 클래스를 만들어봅시다:

export class CreateCatDto {
  name: string;
  age: number;
  breed: string;
}

 

이 클래스는 세 가지 기본 속성만 가지고 있습니다. 이후에는 이 새로 만든 DTO를 CatsController에서 사용할 수 있습니다:

@Post()
async create(@Body() createCatDto: CreateCatDto) {
  return 'This action adds a new cat';
}

힌트
Nest의 ValidationPipe는 메서드 핸들러에서 받아서는 안 되는 속성들을 필터링할 수 있습니다. 이 경우 허용할 속성들을 화이트리스트로 지정하면, 화이트리스트에 포함되지 않은 속성은 결과 객체에서 자동으로 제거됩니다. CreateCatDto 예제에서는 name, age, breed 속성이 화이트리스트에 해당합니다. 자세한 내용은 여기에서 확인할 수 있습니다.

쿼리 파라미터

라우트에서 쿼리 파라미터를 처리할 때는 @Query() 데코레이터를 사용하여 들어오는 요청에서 해당 값을 추출할 수 있습니다. 실제로 어떻게 동작하는지 살펴보겠습니다.

 

예를 들어, age와 breed 같은 쿼리 파라미터를 기반으로 고양이 목록을 필터링하고자 하는 라우트를 만든다고 가정해 봅시다. 먼저, CatsController에서 쿼리 파라미터를 정의합니다:

@Get()
async findAll(@Query('age') age: number, @Query('breed') breed: string) {
  return `This action returns all cats filtered by age: ${age} and breed: ${breed}`;
}

 

이 예제에서 @Query() 데코레이터는 쿼리 문자열에서 age와 breed 값을 추출하는 데 사용됩니다. 예를 들어 다음과 같은 요청을 보낸다면:

GET /cats?age=2&breed=Persian

 

age는 2, breed는 Persian으로 설정됩니다.

애플리케이션에서 중첩된 객체나 배열과 같은 복잡한 쿼리 파라미터를 처리해야 하는 경우:

?filter[where][name]=John&filter[where][age]=30
?item[]=1&item[]=2

 

사용 중인 HTTP 어댑터 (Express 또는 Fastify)에 적절한 쿼리 파서 설정이 필요합니다. Express에서는 확장 파서 (extended parser)를 사용할 수 있습니다. 이를 통해 풍부한 형태의 쿼리 객체를 처리할 수 있습니다.

const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.set('query parser', 'extended');

 

Fastify에서는, querystringParser 옵션을 사용할 수 있습니다.

const app = await NestFactory.create<NestFastifyApplication>(
  AppModule,
  new FastifyAdapter({
    querystringParser: (str) => qs.parse(str),
  }),
);

힌트
qs는 중첩 구조와 배열을 지원하는 쿼리 문자열 파서입니다. npm install qs 명령어로 설치할 수 있습니다.

예외 처리

오류를 처리하는 방법 (즉, 예외 처리)에 대한 내용은 별도의 장에서 다루고 있습니다. 여기에서 확인할 수 있습니다.

전체 리소스 예제

아래는 여러 데코레이터를 활용하여 기본 컨트롤러를 생성하는 예제입니다. 이 컨트롤러는 내부 데이터를 조회하고 조작하기 위한 몇 가지 메서드를 제공합니다.

import { Controller, Get, Query, Post, Body, Put, Param, Delete } from '@nestjs/common';
import { CreateCatDto, UpdateCatDto, ListAllEntities } from './dto';

@Controller('cats')
export class CatsController {
  @Post()
  create(@Body() createCatDto: CreateCatDto) {
    return 'This action adds a new cat';
  }

  @Get()
  findAll(@Query() query: ListAllEntities) {
    return `This action returns all cats (limit: ${query.limit} items)`;
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return `This action returns a #${id} cat`;
  }

  @Put(':id')
  update(@Param('id') id: string, @Body() updateCatDto: UpdateCatDto) {
    return `This action updates a #${id} cat`;
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return `This action removes a #${id} cat`;
  }
}

힌트
Nest CLI는 모든 보일러플레이트 코드를 자동으로 생성해 주는 제너레이터(스키매틱) 기능을 제공합니다. 이를 통해 수동 작업을 줄이고 전반적인 개발 경험을 향상할 수 있습니다. 이 기능에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

시작하기 (Getting up and running)

CatsController를 완전히 정의하더라도, Nest는 이를 자동으로 인식하거나 인스턴스를 생성하지 않습니다.

 

컨트롤러는 반드시 어떤 모듈의 일부로 포함되어야 하며, 그렇기 때문에 @Module() 데코레이터 안의 controllers 배열에 등록해야 합니다. 현재 루트 모듈인 AppModule 외에 다른 모듈을 정의하지 않았으므로, CatsController를 AppModule에 등록하여 사용할 것입니다.

import { Module } from '@nestjs/common';
import { CatsController } from './cats/cats.controller';

@Module({
  controllers: [CatsController],
})
export class AppModule {}

 

Module() 데코레이터를 사용하여 메타데이터를 모듈 클래스에 연결했기 때문에, 이제 Nest는 어떤 컨트롤러들을 마운트해야 하는지 쉽게 파악할 수 있습니다.

라이브러리 고유 방식

지금까지는 응답을 처리하는 Nest의 표준 방식을 살펴보았습니다. 또 다른 방식은 라이브러리 고유 응답 객체를 사용하는 것입니다. 특정 응답 객체를 주입하려면 @Res() 데코레이터를 사용할 수 있습니다. 차이점을 강조하기 위해 CatsController를 다음과 같이 작성해 보겠습니다:

import { Controller, Get, Post, Res, HttpStatus } from '@nestjs/common';
import { Response } from 'express';

@Controller('cats')
export class CatsController {
  @Post()
  create(@Res() res: Response) {
    res.status(HttpStatus.CREATED).send();
  }

  @Get()
  findAll(@Res() res: Response) {
     res.status(HttpStatus.OK).json([]);
  }
}

 

이 방식은 헤더 조작이나 라이브러리 고유 기능 접근 등 응답 객체에 대한 완전한 제어권을 제공하여 더 높은 유연성을 가지지만, 주의해서 사용해야 합니다. 일반적으로 이 방법은 명확성이 떨어지고 몇 가지 단점을 동반합니다. 가장 큰 단점은 코드가 플랫폼 종속적이 된다는 점입니다. 사용하는 하위 라이브러리에 따라 응답 객체의 API가 달라질 수 있기 때문입니다. 또한 응답 객체 등을 모킹해야 하므로 테스트가 더 복잡해질 수 있습니다.

 

게다가 이 방식을 사용할 경우, @HttpCode(), @Header() 데코레이터나 Interceptor 등 Nest의 표준 응답 처리 방식에 의존하는 기능들과의 호환성이 떨어지게 됩니다. 이러한 문제를 해결하려면 다음과 같이 passthrough 옵션을 활성화할 수 있습니다:

@Get()
findAll(@Res({ passthrough: true }) res: Response) {
  res.status(HttpStatus.OK);
  return [];
}

 

이 방식을 사용하면, 특정 조건에 따라 쿠키나 헤더를 설정하는 등 네이티브 응답 객체와 직접 상호작용할 수 있으면서도, 나머지 응답 처리는 Nest 프레임워크에 맡길 수 있습니다.

Reference

• Nest.js | First Steps
• Nest.js | Controllers