Node.js/NestJS

[NestJS] 2. Nest Controller

턴태 2022. 9. 26. 21:04

컨트롤러

컨트롤러의 목적은 응용 프로그램에 대한 특정 요청을 받는 것입니다. 라우팅 매커니즘은 어떤 컨트롤러가 어떤 요청을 받을지를 컨트롤합니다. 대개 각각의 컨트롤러는 하나 이상의 라우트를 가지며 각각 경로에 따른 개별적인 처리를 수행합니다.

 

기본적으로 컨트롤러를 생성하기 위해서 클래스와 데코레이터를 사용합니다.  데코레이터는 클래스와 메타데이터를 연결하고, 네스트가 라우팅 맵을 생성할 수 있도록 해줍니다.

 

라우팅

기본 컨트롤러를 정의할 때 @Controller() 데코레이터를 사용합니다.

 

Controller 파일을 만들기 위해서 NestCli를 사용할 수 있습니다.

nest g controller [라우트 경로]

예를 들어, cats 라는 라우트들을 묶어 하나의 컨트롤러로 받을 때, 아래와 같이 작성할 수 있습니다.

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

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

findAll() 이전에 있는 @Get() HTTP 요청 메서드 데코레이터는 Nest에게 HTTP 요청에 대한 특정 엔드포인트를 처리할 핸들러를 만들도록 합니다. 엔드포인트는 HTTP 요청 메서드와 라우트 경로에 대응합니다. 이때, 라우트 경로는 Conroller에 선언된 접두사와 데코레이터의 경로를 연결하여 결정됩니다.

 

예를 들어, @Get('profile') 을 적으면 컨트롤러의 cats 이하의 경로로 접근할 수 있습니다.

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

@Controller('cats')
  @Get('profile')
  findProfile(): string {
    return 'Hello, little kitty';
  }
}

여기서 HTTP메서드와 함께 사용하는 메서드는 개발환경에서 확실히 의미있게 하는 것이 중요하지만, Nest는 그 의미를 파악하지 못하기 때문에 자유롭게 메서드를 작성할 수 있습니다. findAll과 findProfile 등이 그 예들 중 하나입니다.

 

그리고 응답에 대해 Nest는 두 가지 옵션을 제공합니다.

 

표준

Nest는 객체를 반환하는 경우에는 자동으로 JSON으로 변환하여 응답합니다. 그러나 자바스크립트의 원시 자료형인 string, number 등은 변환하지 않고 값을 반환합니다. 단순히 보면 일단 값을 전달하면, 나머지 부분은 Nest에서 알아서 처리한다.

 

특정 라이브러리

Nest에서는 다른 라이브러리에서 사용하는 응답 객체를 주입시킬 수 있습니다. @Res()와 같은 데코레이터를 메서드 핸들링 시그니처에서 불러와 사용 가능합니다.

findAll(@Req() response)

 

 

요청객체

핸들러는 종종 요청객체에 담긴 세부 정보에 접근합니다. Nest는 Express 플랫폼을 기반으로 하여 요청객체에 접근할 수 있도록 구현되어 있습니다. 핸들러 시그니처인 @Req() 를 통해서 요청객체에 접근할 수 있습니다. 먼저 Type을 제공하기 위해 @types/express 패키지를 설치해야 합니다.

npm i @types/express

 

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

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

HTTP 요청을 표현하는 것이 요청 객체이며, 쿼리스트링, 파라미터, HTTP 헤더 그리고 바디 등의 속성을 갖고 있습니다. 그래서 이를 이용하기 위해 @Body() 혹은 @Query 같은 데코레이터를 사용할 수 있습니다. 데코레이터는 여러 종류가 있어서 적절히 사용하면 좋습니다.

@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(name?: string) // req.headers/req.headers[name]
@Ip() // req.ip
@HostParam() // req.hosts

리소스

이전에 GET 라우트를 통해 cats 리소스를 가져오는 엔드포인트를 정의하였는데, GET외에 새로운 레코드를 생성하는 엔드포인트를 공급하고 싶을 수 있습니다. 이를 위해 POST 핸들러를 사용할 수 있습니다.

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

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

간단하게 위와 같이 제공할 수 있으며, Get과 Post 외에도 Put, Delete, Patch, Options, Head, All 등으로 HTTPS 메서드의 표준들을 모두 데코레이터로 제공합니다.

 

라우트 와일드카드

패턴이 있는 라우트도 지원됩니다. 예를들어 *(asterisk)가 와일드 카드로 사용되며 모든 문자의 조합과 매치됩니다.

정규표현식의 부분집합으로 사용됩니다. 그렇기에 하이픈(-)이나 점(.)은 경로의 문자로 인식됩니다.

 

상태코드

응답 상태코드는 기본적으로 항상 200인데, POST 요청은 예외로 201입니다. 무조건적이진 않고, @HttpCode(...) 데코레이터를 핸들러에서 사용하면 다른 상태코드를 쓸 수 있습니다.

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

HttpCode 데코레이터는 @nestjs/common/decorators를 임포트하여 사용합니다.

 

사용자 헤더를 특정시키기 위해서 @Header() 데코레이터나 라이브러리 기반 응답 객체를 사용할 수 있습니다.

  @Post()
  @HttpCode(204)
  @Header('Cache-Control', 'none')
  create(): string {
    return 'This action adds a new cat';
  }

이 또한 @nestjs/common/decorators에서 Header를 임포트해야 합니다.

 

리다이렉트

특정한 URL로 응답을 리다이렉트하기 위해서는 @Redirect() 데코레이터를 사용하거나 res.redirect() 같은 라이브러리 기반 응답객체를 직접 사용할 수 있습니다.

 

@Redirect()는 url과 statusCode로 두 가지 매개변수를 취하는데 둘 다 선택사항입니다. 생략했을 때는 기본적으로302(Found) 상태코드로 지정됩니다.

 

동적으로 확인하여 URL을 리다이렉트할 수도 있습니다.

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

localhost:3000/cats/docs?version=5로 접속하면 https://docs.nestjs.com/v5/ 로 리다이렉트 되며 그 외에는 모두 https://docs.nestjs.com 으로 리다이렉트됩니다.

 

라우트 매개변수

정적 경로의 라우트는 동적인 값을 요청의 한 부분으로 받아야 할 때 원하는대로 동작하지 않을 수 있습니다. 예를 들어 회원을 조사한다고 할 때, GET /users/123124124 에서 123124124와 같은 부분을 요청으로 받는 것입니다. 라우트를 매개변수와 함께 정의하기 위해서는 라우트 매개변수를 라우트의 경로에서 토큰으로 추가할 수 있습니다. 이 토큰은 요청 URL에 위치한 동적인 값을 가져올 수 있습니다.  @Param() 데코레이터를 사용하여 이러한 방식을 사용할 수 있습니다.

 

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

경로에 id 매개변수를 사용하여 실제로 동적인 데이터를 응답으로 반환하겠습니다.

서브 도메인 라우팅

@Controller() 데코레이터는 들어오는 특정 값과 매치되는 요청 HTTP 호스트를 옵션으로 선택할 수 있습니다. 예를 들어 어드민 페이지를 만들 때 종종 사용됩니다.

 

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

라우트의 경로와 비슷하게 호스트 옵션은 호스트 이름에 있는 동적인 값을 포착하여 토큰으로 사용할 수 있습니다. 파라미터를 사용했던 것과 유사합니다.

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

비동기

자바스크립트에서 파일을 추적할 때 비동기로 추적하는 것과 같이 현대 자바스크립트 방식을 사용하는데, 이것이 Nest가 비동기 함수를 지원하고 사용할 수 있게 하는 이유입니다.

 

모든 비동기 함수는 Promise를 반환해야 합니다. 즉, Nest가 스스로 해결할 수 있는 지연된(비동기 방식을 통해) 데이터를 반환할 수 있습니다.

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

타입스크립트 문법에따라 타입을 <>에 지정합니다.

 

혹은 RxJS의 observable streams을 사용할 수도 있습니다. 비동기적으로 과정을 처리하고 마지막에 나오는 데이터를 사용하기 때문입니다.

 

요청 페이로드

이전에 POST 라우트 핸들러는 모든 클라이언트 파라미터를 받아들일 수 없었습니다. 하지만, @Body() 데코레이터를 추가하여 이를 해결할 수 있습니다!

 

그러나 타입스크립트를 사용한다면 먼저, DTO 스키마를 정해야 합니다. DTO는 데이터가 네트워크를 통해 어떻게 전송되는지 정의하는 객체입니다. 타입스크립트의 인터페이스들을 사용하거나 간단한 클래스를 통해서 DTO 스키마를 정할 수 있습니다. 공식문서에서는 인터페이스를 사용하는 것이 아니라, 자바스크립트 ES6 표준의 일부인 클래스들을 사용하는 것을 추천합니다. 그렇게 하면 자바스크립트로 컴파일된 원본 엔티티를 보존할 수 있기 때문입니다.

 

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

이렇게 DTO 스키마를 정한 후에 @Body() 데코레이터를 사용하여 Body 요청 페이로드의 파라미터들을 사용할 수 있습니다.

@Post()
async create(@Body() createCatDto: CreateCatDto): Promise<string> {
  return `This action adds a new cat ${createDto.name}`;
}

실제로 Body를 통해 각 매개변수의 인자를 반환할 수 있었습니다.

 

더보기

이외에도 ValidationPipe를 사용하여 메서드 핸들러를 통해 전달된 속성들 중에서 받지 않아야 하는 속성들을 필터링할 수 있습니다. 

세팅

Nest는 아직 CatsController가 존재하는지 모르기 때문에, 이 클래스의 인스턴스를 만들지 못할 것입니다. Nest에 이 클래스가 존재함을 알려야 Nest에서 인스턴스를 만들어 요청을 처리할 수 있게 됩니다.

 

컨트롤러는 항상 모듈에 속해야 하며, 이것이 컨트롤러 배열이 항상 @Module() 데코레이터에 있어야 하는 이유입니다. @Module() 데코레이터를 사용하는 모듈 클래스의 메타데이터에 접근하였고, Nest는 어떤 컨트롤러를 마운트해야 하는지 쉽게 보여줄 수 있습니다.

 

개별적인 라이브러리의 접근 방식

응답을 조작하는 두 번째 방식은 라이브러리 별로 갖고 있는 응답 객체를 사용하는 것으로 응답을 조작할 수 있습니다. 특정 응답 객체를 주입하기 위해서, @Res() 데코레이터를 사용해야 합니다.

 

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([]);
  }
}

이러한 접근이 잘 동작하며, 응답 객체에 대한 다양한 통제 방식이 있어 조금 더 유연하게 응답 객체를 조작할 수 있음에도 불구하고, 조심스레 사용해야 합니다. 일반적으로 이러한 접근은 덜 명확하며 약간의 단점을 갖고 있습니다. 가장 주된 단점은 우리의 코드가 플랫폼에 의존하여 만들어진다는 것입니다(라이브러리에 의존하는 것은 앞으로 그 프레임 워크 기반의 코드를 작성해야 한다는 것입니다). 또한, 응답 객체를 모의로 생성해 테스트 해야하는 등 테스트가 조금 더 어려워집니다.

 

또한, @HttpCode()나 @Header() 데코레이터와 인터셉터들 같은 Nest의 표준 처리 방식에 뿌리를 두는 Nest의 특징들에 대한 호환성을 잃게 됩니다.

 

이를 해결하기 위해서, passthrough 옵션을 true로 설정해야 합니다.

 

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

이로써 Nest의 기본 응답 객체와 상호작용할 수 있지만, 나머지 부분들은 프레임워크에 맡겨야 합니다.

저작자표시 비영리