Custom route decorators

Nest decorator로 불리는 language feature로 build 됬다. Decorator는 programming language에서 흔히 사용되는 개념이다. 하지만 Javascript 세상에서는, 여전히 상대적으로 새로운 개념이다. 어떻게 decorator가 작동하는지 더 이해하기 위해서는, 다음을 기사를 추천한다.

ES2016 decorator는 함수를 반환하는 표현식이며, 대상, 이름, 속성 기술자를 인수로 받을 수 있다. 데코레이터를 적용하려면 데코레이터 앞에 '@' 문자를 붙이고 데코레이팅하려는 것의 맨 위에 배치한다. decorator는 class, method 또는 property를 위해 정의될 수 있다.

Param decorators

Nest는 HTTP route handler와 함께 사용할 수 있는 유용한 param decorator를 제공한다. 아래는 제공되는 Express, Fastify 객체를 쉽게 다를 수 있게 해주는 데코레이터 리스트이다.

추가적으로, custom decorators를 만들 수 있다.

node.js에서는 속성(properties)를 request object에 붙이는게 흔한 관행이다. 이런 속성을 route handler에서 extract할 수 있다.

const user = req.user;

code를 좀 더 readable하고 transparent하게 만들기 위해, @User() decorator를 만들고, 이를 controller 전반에 걸쳐 재사용할 수 있다.

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const User = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

그렇다면 이제 요구사항에 맞게 사용할 수 있다.

@Get()
async findOne(@User() user: UserEntity) {
  console.log(user);
}

Passing Data

만일 decorator의 기능이 조건적으로 이루어져야 한다면, 'data' 매개변수를 사용하여 데코레이터의 팩토리 함수에 인수를 전달할 수 있다. custom decorator를 사용하면 request object에서 특정 key에 해당하는 속성을 추출하여 route handler method에 주입할 수 있다. 이를 통해 코드의 가독성과 재사용성을 높일 수 있다. 예를 들어 authentication layer request의 유효성을 검사한다. 그리고 user entity에 request object를 붙인다. authenticated request의 user entity는 다음과 같을 것 이다.

{
  "id": 101,
  "firstName": "Alan",
  "lastName": "Turing",
  "email": "alan@email.com",
  "roles": ["admin"]
}

name을 key로 갖는 decorator를 정의해보자. 이는 만일 존재한다면 관련된 value를 반환한다.(만일 존재하지 않거나 user object가 만들어져 있지 않다면 undefined를 반환한다.)

// user.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';

export const User = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    const user = request.user;

    // user에서 data에 해당하는 정보가 있다면 그것을 반환
    // 그렇지 data가 지정되지 않았다면 user 객체를 반환
    return data ? user?.[data] : user;
  },
);

// 사용
import { Controller, Get } from '@nestjs/common';
import { User } from './user.decorator'; // 경로는 실제 파일 위치에 따라 다릅니다.

@Controller('profile')
export class ProfileController {
  @Get()
  getProfile(@User() user: any) {
    // 전체 사용자 객체 반환
    console.log(user);
    return user;
  }

  @Get('email')
  getUserEmail(@User('email') email: string) {
    // 사용자 이름만 반환
    console.log(email);
    return email;
  }
}

controller에서 @User() decorator를 통해 어떻게 특정한 property에 접근하는가?

@Get()
async findOne(@User('firstName') firstName: string) {
  console.log(`Hello ${firstName}`);
}

위의 같은 decorator, 허나 다른 key로 다른 property에 접근할 수 있다.
사용자 객체가 깊거나 복잡한 경우, 이 방법을 통해 request handler 구현을 더 쉽게 만들고 가독성을 높일 수 있다.

<팁!>
Typescript 사용자는 createParamDecorator()가 제네릭이라는 점에 주목해야 한다.이를 통해 타입 안전성을 명시적으로 보장할 수 있다. (e.g. createParamDecorator((data, ctx)=> ... )) 또는 factory function에서 매개변수 타입을 지정할 수도 있다. (e.g. createParamDecorator((data:string, ctx)=> ...)) 만일 둘다 생략하면 data의 타입은 any이다.

factory function: 객체를 생성하는 함수. 객체의 생성과 초기화를 담당하며, 동일한 함수로 다양한 형태의 객체를 만들 수 있는 유연성을 제공한다.

Working with pipes

Nest는 기본 내장된 @Body(), @Param(), @Query()에서 처리하는 것과 같은 방식으로 custom param decorator를 처리한다.
이는 pipe는 custom annotated parameter에서도 실행된다는 걸 의미한다. (e.g. 위의 user argument ) 게다가, pipe를 바로 custom decorator에 apply할 수 있다. 그냥 custom decorator에도 pipe가 적용된다는 걸 뜻한다.

@Get()
async findOne(
  @User(new ValidationPipe({ validateCustomDecorators: true }))
  user: UserEntity,
) {
  console.log(user);
}

<팁!>
validateCustomDecorator 옵션은 반드시 true로 설정되어야 한다. ValidationPipe는 default로 custom decorator로 주석이 달린 인수를 검증하지 않는다.

Decorator composition

Nest는 mutiple decorator를 구성할 수 있도록 helper method를 제공한다. 예를 들어, authentication과 관련된 모든 decorator를 하나의 decorator로 combine하기를 원한다고 하자. 이는 다음과 같은 구성으로 완료된다.

import { applyDecorators } from '@nestjs/common';

export function Auth(...roles: Role[]) {
  return applyDecorators(
    SetMetadata('roles', roles),
    UseGuards(AuthGuard, RolesGuard),
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ description: 'Unauthorized' }),
  );
}

이렇다면 다음과 같이 @Auth()decorator를 사용할 수 있다.

@Get('users')
@Auth('admin')
findAllUsers() {}

이렇게 함으로써 4개의 decorator를 하나의 선언으로 완료할 수 있다

<주의사항!>
@nestjs/swagger에서의 @ApiHidePropety() decorator는 조합할 수 없으며, applyDecorators 함수와 함께 제대로 작동하지 않는다.

Interceptors

Interceptor는 NestInterceptor interface를 구현하고 @Injectable() decorator가 주석으로 달린 class이다.

Interceptor는 들어오는 요청(reqeust)와 나가는 응답(response)을 가로채고, 이들 사이에서 추가적인 로직을 실행할 수 있도록 하는 강력한 기능을 제공한다. 인터셉터는 다음과 같은 여러 용도로 사용될 수 있다.
    - 로깅(Logging): 요청 및 응답 정보를 기록
    - 변환(Transformation): 응답 데이터를 특정 형식으로 변환
    - 캐싱(Caching): 반복적인 요청에 대해 캐시된 응답을 제공한다.
    - 에러 처리(Error Handling): 특정한 에러를 처리하거나 에러 메시지를 변환한다.
    - 타이밍(Timing): 요청 처리 시간을 측정한다.

1. Middleware: 모든 미들웨어가 순차적으로 실행된다.
2. Guard: 요청을 처리할 수 있는지 확인하는 모든 가드가 실행된다.
3. Interceptor(전처리): 요청 전처리를 수행하는 모든 인터셉터가 실행된다
4. Pipe: 입력 데이터의 변환 및 유효성 검사를 수행하는 모든 파이프가 실행된다.
5. Controller Handler: 컨트롤러의 핸들러 메서드가 실행된다.
6. Pipe(응답 데이터 변환): 컨트롤러 핸들러가 반환한 데이터를 변환하는 파이프가 있을 경우 실행된다.
7. Interceptor(후처리): 요청 후처리를 수행하는 모든 인터셉터가 실행된다. 

interceptor는 AOP(Aspect Oriented Programming) 기술에 의해 고무된 유용한 기능들의 집합이다.

AOP: OOP와 같은 방식으로 소프트웨어 모듈화를 목표로 하는 프로그래밍 패러다임이다. 주로 관심사의 분리(Separation of Concerns)를     통해 코드의 재사용성과 유지보수성을 높이는 데 중점을 둔다.

• method 실행의 전, 후 로직을 묶는다.
• function으로 부터 반환된 result를 바꿈
• function으로 부터 던져진 exception을 바꿈
• basic fucntion들의 기능 추가
• 특정 조건에 따라 function을 override 하는 것

Basics

각 interceptor는 intercept() method를 구현한다. 이는 두 개의 argument를 받는다. (ExecutionContext, CallHandler) ExecutionContext의 instance이다.(Guards에서의 object과 동일하다.) ExecutionContext는 ArgumentsHost를 상속받는다. 이전의 exception filter chapter에서 ArgumentHost를 살펴보았다. 이것은 original handler에 전달된 arguments들의 wrapper이며, application의 type에 따라 다양한 arguments array를 포함하고 있음을 보았다. 자세한 사항은 exception filters 살펴봐라.

ArgumentHost: 원래 handler에 전달된 argument를 래핑하는 객체로, 어플리케이션의 타입에 따라 다양한 인수 배열을 포함한다.
        이를 통해, request handler에 전달된 모든 인수를 쉽게 접근할 수 있다.
    1. getArgs() : 원래의 핸들러에 전달된 모드 인수 배열을 반환
    2. getArgByIndex(index:number): 특정 인덱스의 인수를 반환
    3. switchToHttp(): Http 컨텍스트로 전환하여 HTTP 요청 및 응답 객체에 접근할 수 있다.
    4. swtichToWs(): WebSocket 컨텍스트로 전환하여 WebSocket 요청 및 응답 객체에 접근할 수 있다.
ExecutionContext: 'ArgumentsHost'를 확장한 인터페이스로, 주로 가드와 인터셉터에서 사용된다.  
    1. getClass(): 현재 처리 중인 클래스(controller)를 반환한다.
    2. getHandler(): 현재 처리 중인 핸들러(method)를 반환한다.
    3. getType(): 현재 실행 컨텍스트의 유형을 반환한다.(HTTP, RPC, WebSocket)


ArgumentHost와 ExecutionContext의 주요 정보
1. HTTP 컨텍스트(Express 사용 시)
    - Request: Express의 요청 객체로, 요청된 URL, 헤더, 본문, 쿼리 파라미터 등을 포함한다.
    - Response: Express의 응답 객체로, 응답을 작성하고 반환하는데 사용된다.
    - Next: (옵션) 미들웨어 체인의 다음 함수로, 일반적으로 사용은 안됨
2. 메서드 및 클래스 정보
    - Handler: 현재 실행 중인 핸들러 메서드
    - Class: 현재 실행 중인 클래스(컨트롤러)

Execution context

ArgumentsHost, ExecutionContext를 extending함으로써 현재 execution process에 대해 추가정보를 제공하는 새로운 helper method들을 추가할 수 있다. 이러한 정보들은 controller, method, execution context를 걸쳐 좀더 generic interceptor를 build하는데 도움된다. ExecutionContext

Call handler

NestJs에서의 interceptor는 request를 가로채어 특정 로직을 실행할 수 있다. 인터셉터의 intercept() method는 두 개의 인자를 받는다. ExecutionContext와 CallHandler. CallHandler의 'handle()' method는 rotue handler method를 호출하는 데 사용된다. 만약 handle() method를 호출하지 않으면, request가 route handler로 전달되지 않고, 해당 route handler method는 실행되지 않는다.

이러한 접근은 intercept() method는 효과적으로 request/response streamdmf 감싼다. 결과대로, 마지막 route handler의 실행 전/후 둘다 custom logic를 실행할 것 이다. intercept() method가 handle() 이 호출되기 전에 실행된다. 하지만 후에 어떻게 영향을 주는가? handle() method가 Observable를 return 하기 때문에, 우리는 강력한 RxJS operator를 사용하여 response를 조작할 수 있다. Aspect Oriented Programming 기술을 사용하면, route handler의 호출(즉, handle() 호출)은 Pointcut이라고 하며 이 지점에서 추가 로직이 삽입 된다.

RxJS: 이벤트나 비동기, 시간을 마치 Array 처럼 다룰 수 있게 만들어 주는 라이브러리

예를 들어, POST /cats request가 들어온다고 가정하자. request는 CatsController안에 정의된 create() handler method로 향할 것이다. interceptor가 handle() method를 호출하지 않으면, 그 경로상의 어느 곳에서든 create() method가 실행되지 않을 것 이다. 한번 handle()이 호출되면(이는 Observable을 반환할 것 이다.) create() handler가 트리거된다. 그리고 Observable를 통해 응답 스트림이 수신되면, 그 스트림에 추가 작업을 수행하고 최종 결과를 호출자에게 반환할 수 있다.

Aspect interception

NestJs에서 인터셉터를 사용하여 사용자 상호작용을 logging 할 수 있다. 예를 들어, 사용자의 호출을 저장하거나, 비동기적으로 이벤트를 디스패치하거나, 타임스탬프를 계산할 수 있다. 아래는 간단한 LoggingInterceptor이다.

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

// pipe
// RxJS의 주요 연산자 중 하나로, Observable의 데이터를 처리하기 위해 다양한 연산자를 연결
// 할 수 있는 메서드이다. pipe를 사용하면 데이터를 변환하거나, 필터링하거나, 부수 효과를 추가하는 
// 등의 작업을 체인 방식으로 적용할 수 있다.

// tap
// RxJS의 연산자 중 하나로, Observable 데이터 스트림을 변경하지 않고, 부수 효과(side effect)를 추가
// 할 수 있게 해준다. 주로 디버깅, 로깅, 데이터 수집 등의 목적으로 사용된다. 
// tap 연산자는 스트림에 있는 각 데이터 항목에 대해 지정된 함수를 호출한다.

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    // route handler 전
    console.log('Before...');

    const now = Date.now();
    // next: CallHandler 인터페이스를 구현한 객체로, 실제 컨트롤러의 핸들러 메서드를 호출하는 handle method를 제공한다.
    // next.handle(): 핸들러 메서드를 호출하고, Observable을 반환한다.
    return next
      .handle()
    // route handler 후
      .pipe(
        tap(() => console.log(`After... ${Date.now() - now}ms`)),
      );
  }
}

<팁!>

NestInterceptor<T,R> 는 generic interface이다.
T는 Observable<T>의 타입을 나타낸다. 요청 핸들러가 반환하는 데이터 스트림의 타입을 나타낸다. 즉, 라우트 핸들러 메서드가 반환하는 데이터 타입 이다.
R는 Observable<R>에 의해 감싸진 값의 타입을 말한다. 인터셉터가 반환하는 최종 데이터 타입이다. 인터셉터가 응답 데이터를 어떻게 변형할지를 정의한다.

<주의사항!>
interceptor는 controller, provider, guard와 동일하게 constructor를 통해 dependency를 inject한다.

handle() 은 RxJS Observable를 반환하기 때문에, 우리는 다양한 RxJS 연산자를 사용하여 stream을 조작할 수 있다.
이를 통해, response data에 추가적인 로직을 적용하거나, 데이터를 변환하고, 부수 효과를 추가할 수 있다. 위의 예에서 tab() 연산자를 사용했다. 이는 Observable 스트림이 정상적으로 완료되거나 예외가 발생할 때 익명 로깅 함수를 호출한다. 그러나 response cycle에는 영향을 미치지 않는다. 이는 주로 디버깅, 로깅, 또는 부수효과를 추가하는 용도로 사용된다.

Binding interceptor

interceptor를 설정하기 위해서는 @nestjs/common에서 @UseInterceptors() decorator를 사용한다. pipe, guards와 마찬가지로interceptor는 또한 controller, method, global scope로 설정할 수 있다.

@UseInterceptors(LoggingInterceptor)
export class CatsController {}

위의 구조로, CatsController안에 정의된 모든 route handler들은 LogginInterceptor를 사용할 수 있다. 만일 GET /cats endpoint가 호출된다면, 다음과 같은 output을 얻을 수 있다.

Before...
After... 1ms

instance가 아닌 LogginInterceptor class 를 전달했다. 이는 instantiation과 dependeny injection 책임을 framework에게 넘겨준다. pipe, guard, exception filter과 동일하게, 또한 instance를 넘겨줄 수 있다.

@UseInterceptors(new LoggingInterceptor())
export class CatsController {}

앞서 언급한 대로 위의 구조는 controller에 선언된 모든 handler에 interceptor를 붙인다. 만일 interceptor의 범위를 single method로 좁히고 싶다면, 간단히 method level로 적용하면 된다.

만일 global interceptor를 설정하고 싶다면, useGlobalInterceptors() method를 사용한다.

const app = await NestFactory.create(AppModule);
app.useGlobalInterceptors(new LoggingInterceptor());

global interceptor는 모든 controller, route handler를 걸친 application에 사용된다. dependency injection면에서, 위의 예 처럼, useGlobalInterceptors()를 사용하여 module 바깥에서 등록된 global interceptor는 dependency를 inject할 수 없다. 왜냐하면 module의 외부에서 inject가 이루어 졌기 때문이다. 이러한 문제를 해결하기 위해서는 다음과 같은 구조로 interceptor를 module 에서 바로 설정하면 된다.

import { Module } from '@nestjs/common';
import { APP_INTERCEPTOR } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: LoggingInterceptor,
    },
  ],
})
export class AppModule {}

<팁!>
이 접근 방식을 사용하여 interceptor에 대한 dependency inject를 수행할 때, 이 구성이 사용되는 모듈에 관계없이 interceptor는 실제로 전역적임을 유의해야 한다. 이는 intercepter(위의 경우 LogginInterceptor)가 정의된 모듈을 선택해야 한다. 또한 'useClass'는 custome provider 등록을 처리하는 유일한 방법이 아니다. 자세히

Response mapping

handle() method는 Observable를 반환한다. stream에는 route handler에서 반환된 value를 포함한다. 그리고 즉, 이는 RxJS의 map() operator를 통해 쉽게 변경할 수 있다. map() 연산자는 Observable의 각 값을 변환하여 새로운 값으로 반환한다. 이를 통해 응답 데이터를 변형하거나 추가적인 로직을 적용할 수 있다.

<주의사항!>
response mapping feature은 라이브러리별 response strategy(즉, '@Res() obejct를 직접 사용하는 것')와 함께 작동하지 않는다.

TransformInterceptor를 만들자. 이는 process를 보여주기 위해 각 response를 간단하게 변형한 것 이다. 이는 response object를 새롭게 만들어진 object의 data 속성에 할당하기 위해 RxJS의 map() 연산자를 사용할 것 이다. 이렇게 만들어진 object는 client에게 반환될 것 이다.

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

// 응답 데이터의 구조를 정의
export interface Response<T> {
  data: T;
}

@Injectable()
//<T, Response<T>>
//    T: 인터셉터가 처리할 입력 데이터의 타입을 나타냄
//    Response<T>: 인터셉터가 반환할 출력 데이터의 타입을 나타냄
export class TransformInterceptor<T> implements NestInterceptor<T, Response<T>> {
  // context: 현재 실행 컨텍스트를 나타냄, 요청 및 응답 객체에 접근할 수 있다.
  // next: CallHandler 인터페이스를 구현한 객체로, 실제 컨트롤러의 핸들러 메서드를 호출하는 handle 메서드를 제공
  intercept(context: ExecutionContext, next: CallHandler): Observable<Response<T>> {
    return next.handle().pipe(map(data => ({ data })));
  }
}

// 사용
import { Controller, Get, UseInterceptors } from '@nestjs/common';
import { TransformInterceptor } from './transform.interceptor';

@Controller('cats')
@UseInterceptors(TransformInterceptor)
export class CatsController {
  @Get()
  findAll() {
    return [{ name: 'Tom' }, { name: 'Jerry' }];
  }
}

Nest 인터셉터는 동기와 비동기 모두에서 작동한다. 필요에 따라 메서드를 간단히 async로 변경할 수 있다.

위의 구조에서 만일 GET /cats endpoints로 호출했을 때, response는 다음과 같은 결과를 도출할 것 이다.

{
  "data": []
}

인터셉터는 어플리케이션 전체에서 발생하는 요구 사항에 대한 재사용 가능한 솔루션을 만드는데 큰 가치를 제공한다.

예를 들어, null값을 빈 문자열("")로 변환해야 한다고 가정해보자. 한 줄의 코드로 이를 수행할 수 있으며, 인터셉터를 전역적으로 바인딩하여 등록된 각 핸들러에서 자동으로 사용되도록 할 수 있다.

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

@Injectable()
export class ExcludeNullInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(map(value => value === null ? '' : value ));
  }
}

Exception mapping

다른 RxJS의 catchError() 연산자는 thrown exception을 override할 수 있다.

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

@Injectable()
export class ErrorsInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next
      .handle()
      .pipe(
          // 핸들러 메서드에서 발생한 에러를 가로채고, 이를 BadGatewayException으로 변환
        catchError(err => throwError(() => new BadGatewayException())),
      );
  }
}

Stream overriding

때때로 완전히 handler의 호출을 막고, 대신에 다른 값을 반환하기를 원하는 이유가 몇 있다. 명백한 예는 response time을 항샹시키기 위해 cache를 구현하는 것 이다. 간단한 simple cache interceptor를 보자. 이는 cache로 부터 interceptor의 response를 반환한다. cache interceptor를 사용하면 response time을 개선하기 위해 cached data를 반환할 수 있다. cache interceptor는 request에 대한 response를 cache하고, 동일한 request가 들어올 때 cached된 데이터를 반환하여 서버의 부담을 줄일 수 있다. 현실적인 예로, 우리는 TTL, cache invalidation, cache size...와 같은 다른 요소들을 고려해야 하지만, 이는 이 논의의 범위를 벗어난다. 여기서 main concept에 를 보여주는 간단한 예시가 있다.

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

@Injectable()
export class CacheInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const isCached = true;
    if (isCached) {
      return of([]);
    }
    return next.handle();
  }
}

위에서 CacheInterceptor는 하드코딩된 isCached 변수와 하드코딩된 [ ]을 가진다. 여기서 핵심 포인트는 RxJS의 of() 연산자로 인해 생성된 new stream을 반환하는 것 이다. 그러므로, route handler는 호출되지 않는다. 누군가 CacheInterceptor를 사용하는 endpoint를 호출하면, response(하드코딩된 빈 배열)이 즉시 반환된다. 일반적인 해결책으로는, Reflector를 사용하여 새로운 custom decorator을 만드는 것 이다. reflector

More operators

RxJS operator를 사용하여 stream을 조작하는 것은 많은 가능성을 제공해 준다. 흔한 use case를 생각해보자. 만일 route requests에서 timeouts를 handle하고 싶다고 하자. 만일 특정 시간이 지난 후에도, endpoint가 아무것도 반환하지 않으면 error response로 종료하고 싶을 수 있다. 다음 코드는 이러한 기능을 구현하는 방법을 보여준다.

import { Injectable, NestInterceptor, ExecutionContext, CallHandler, RequestTimeoutException } from '@nestjs/common';
import { Observable, throwError, TimeoutError } from 'rxjs';
import { catchError, timeout } from 'rxjs/operators';

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    return next.handle().pipe(
      // 요청이 5초 내에 완료되지 않으면 TimeoutError를 발생
      timeout(5000),
      catchError(err => {
        if (err instanceof TimeoutError) {
          return throwError(() => new RequestTimeoutException());
        }
        return throwError(() => err);
      }),
    );
  };
};

5초 후에, request processing은 취소될 것 이다. RequestTimeoutException이 던져지기 전에 custom logic또한 추가할 수 있다.

Guards

guard는 CanActivate interface를 implement하는 @Injectable() decorator이 붙은 class이다.

//Middleware
//    역할: 요청과 응답 사이의 모든 것을 처리. 주로 로깅, 인증, 요청 변환에 사용
//    적용: 모든 경로에 대해 전역적으로 적용되거나 특정 경로에 대해 적용될 수 있다.
//    순서: 요청 수신 직후 실행된다.
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log('Request...');
    next();
  }
}

//Guard
//    역할: 요청이 컨트롤러 핸들러로 들어가기 전에 특정 조건(주로 인증/권한)을 확인하고, 접근을 허용할지 결정한다.
//    적용: 전역, 컨트롤러, 또는 특정 핸들러에 대해 적용될 수 있다.
//    순서: 미들웨어 이후에 실행된다.
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return validateRequest(request);
  }
}

//Pipe
//    역할: 요청 데이터를 변환하고 검증한다.
//    적용: 특정 매개변수, 컨트롤러 메서드, 또는 전역적으로 적용될 수 있다.
//    순서: 가드 이후, 컨트롤러 핸들러에 전달되기 전에 실행된다.
import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParseIntPipe implements PipeTransform<string, number> {
  transform(value: string, metadata: ArgumentMetadata): number {
    const val = parseInt(value, 10);
    if (isNaN(val)) {
      throw new BadRequestException('Validation failed');
    }
    return val;
  }
}

Guard는 single responsibility를 가진다. 이들은 주어진 request가 route handler에 다뤄질 것인지 아닐 지를 결정한다. (permission, role, ACLs. etc에 의거하여) 이는 종종 authorization, authentication으로 사용된다. Authorization(authentication)은 전통적인 Express application에서는 middleware에 의해 다뤄진다. middleware는 authentication에서는 괜찮은 선택이다. token 검증이나 request object에 속성을 붙이는 작업은 특정 rotue context(및 그 메타데이터)와 강하게 연결되어 있지 않기 때문이다.

허나 middleware은 멍청하다. next() function 호출 이후에 어떤 handler가 실행됬는지 알지 모른다. 반면에 Guard는 ExecutionContext instance에 접근한다. 즉, 바로 다음에 무엇이 실행될지 정확하게 안다. exception filter, pipe, 그리고 interceptor과 같이 guard는 request/response cycle의 정확한 지점에서 처리 로직을 선언적으로 삽입할 수 있도록 설계되었다. 이것은 code를 DRY하고 선언적으로 만들어 준다.

ExecutionContext: API 요청이 서버에 도달하면, NestJS는 이 요청에 대한 정보를 ExecutionContext 객체에 캡슐화한다.
    이 컨텍스트 객체는 요청의 세부 사항을 포함하며, 이를 통해 Guard, Interceptor, Pipe, Exeception Filter 등이 요청을 처리할 수 있다.
    1. 현재 실행 컨텍스트 정보 제공
        - 요청 객체, 응답 객체, 컨트롤러 및 핸들러 메서드에 대한 정보를 제공한다.
        - Guard, Interceptor, Filter, Pipe 등이 이 정보를 활용하여 특정 로직을 실행할 수 있다.
    2. 상황별 분기 처리
        - HTTP, WebSocket, RPC(Remote Porcedure Call) 등 다양한 프로토콜에 대해 적절한 컨텍스트를 제공한다.
        - 각 프로토콜에 맞는 요청 처리를 구현할 수 있다.

<팁!>
Guards는 모든 middleware 이후에, 그리고 intercepter or pipe 이전에 실행된다.

Authorization guard

언급한대로, authorization은 Guard를 쓰는 대표적인 시스템이다. 왜냐하면 caller(보통 authenticated user)가 충분한 permission을 가질 때 특정한 route를 호출할 수 있어야 하기 때문이다. AuthGuard authenticated user를 짐작한다.(request header에 token이 붙어있는) Guard는 token을 추출하고 검증할 것이다. 그리고 추출된 정보를 사용하여 request가 처리될지 말지를 결정한다.

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
// AuthGuard가 CanActivate를 구현하여 가드로써 동작할 수 있다.
export class AuthGuard implements CanActivate {
  // canActivate 메서드는 요청이 특정 경로에 접근할 수 있는지 여부를 결정한다.
  // context: 현재 요청의 실행 컨텍스트를 나타내는 ExecutionContext 객체
  // boolean, Promise<boolean>, Observable<boolean> 중 하나를 반환하여 요청이 허용될지 여부를 결정한다.
  canActivate(
    // 현재 요청의 실행 컨텍스트를 나타내는 ExecutionContext 객체
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    // 주어진 요청 객체의 유효성을 검증하는 역할을 한다. 
    // 이 함수는 사용자 정의 함수이며, 주로 요청이 적절한 인증 및 권한을 가지고 있는지 확인하는 데 사용된다.
    // e.g. JWT 토큰의 유효성 검사. 사용자 권한 확인 등을 포함할 수 있다.
    return validateRequest(request);
  }
}

실행 컨텍스트
API 요청이 서버에 도달하면, NestJS는 이 요청에 대한 정보를 ExecutionContext 객체에 캡슐화한다. 이 Context 객체는 요청의 세부 사항을포함하며, 이를 통해 Uard, Interceptor, Pipe, Exception Filter 등이 요청을 처리할 수 있다.

<팁!>
만일 이러한 검증 시스템이 어떤 메커니즘으로 돌아가는지 알고 싶다면, 이 챕터를 찾아가라. 마찬가지로 정교한 authorization example를 확인하고 싶다면 이 챕터를 참고하라.

validateRequest() function의 내부 로직은 simple하거나 정교할 수 있다. 이번 예제의 핵심 포인트는 어떻게 guard가 reqeust/response cycle에서 동작하는가 이다.

모든 guard는 반드시 canActivate() 함수를 구현해야 한다. 이 함수는 현재 request가 허용할지 말지를 나타내는 boolean값을 return 해야한다. 그리고 synchronously 또는 asynchronously 한지에 대한 response를 반환할 수 있다.(Promise 또는 Observable을 통해) Nest는 next action을 제어하기 위해 return value를 사용해야 한다.

• 만일 true를 반환하면 request가 처리되야 함
• 만일 false를 반환하면 request를 거절해야함

Execution context

canActivate() function은 single argument, ExecutionContext instance를 받는다. ExecutionContext는 ArgumentsHost를 상속받는다. 우리는 ArgumentsHost는 이전 filter chapter에서 다루었다. 위의 sample에서, ArgumentsHost에 정의된 동일한 helper method를 사용하여 request 객체에 대한 참조를 얻고 있다. exception filters의 Arguments host section에서 더 자세히 알 수 있다.

ArgumentsHost를 확장함으로써, ExecutionContext 또한 몇 개의 새로운 helper methods를 추가할 수 있다. 이들은 현재 실행중인 process에 대한 추가 detail들을 제공한다. 이러한 detail들은 좀더 generic한 guard를 설계하는데 유용하다. guard들은 controllers, methods 그리고 execution context에 걸쳐서 사용된다. ExecutionContext에 대한 자세한 설명

ArgumentsHost
    - 다양한 유형의 핸들러(HTTP, RPC, WebSocket 등)에 대해 인수를 가져오는 데 사용된다.
    - 파이프, 인터셉터, 예외 필터 등에서 인수를 다루는 데 사용된다.
    주요 메서드
        1. getArgs(): 인수 배열을 반환한다.
        2. getArgByIndex(index: number): 특정 인수를 반환한다.
        3. switchToHttp(): HTTP 컨텍스트로 전환한다.
        4. swtichToRpc(): RPC 컨텍스트로 전환한다.
        5. switchToWs(): WebSocket 컨텍스트로 전환한다.

ExecutionContext 
    - ArgumentsHost를 확장하여 실행 컨텍스트에 대한 더 많은 정보를 제공한다.
    - 현재 실행 중인 컨텍스트(컨트롤러, 핸들러 등)에 대한 추가 메타데이터를 제공한다.
    - 주로 가드와 인터셉터에서 컨트롤러와 핸들러 수준의 정보를 다루는데 사용
    주요 메서드
        1. getClass(): 현재 실행 중인 클래스(컨트롤러)를 반환한다.
        2. getHandler(): 현재 실행 중인 핸들러(메서드)를 반환한다.
        3. getType(): 현재 실행 중인 컨텍스트 타입을 반환한다.

Role-based authentication

이제 좀더 기능적인 특정한 규칙을 통해 허락된 유저만 가능토록하는 기능적인 guard를 설계해보자. 일단 먼저 basic guard template로 시작한다. 아래의 코드는 all request가 처리되도록 허용한다.

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class RolesGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    return true;
  }
}

Binding guards

pipe나 exception filter와 같이, guard는 controller-scoped, global-scoped가 될 수 있다. 아래에서는 @UseGuards() decorator를 사용하여 controller-scoped guard를 설정했다. 이 decorator는 single argument, 혹은 comma-separated list of arguments가 받는다. 이는 한번의 선언(declaration)으로 적절한 guard set이 적용되도록 한다.

@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {}

<팁!>
@nestjs/common package를 통해 @UseGuards()를 import한다.

위에서 RolesGuard class를 전달한다.(instance가 아닌), 이는 framework에게 instance화의 책임을 넘기고 DI를 가능케 한다.
pipe와 exception filter와 비슷하게, instance를 넘겨줄 수 있다.

@Controller('cats')
@UseGuards(new RolesGuard())
export class CatsController {}

위의 구조는 controller에 선언된 모든 handler는 guard가 붙여진다. 만일 single method에 guard가 붙여지길 원한다면, 우리는 @UseGuards() decorator를 method level에서 적용할 수 있다.

global guard를 설정하기 위해서, Nest application instance의 useGlobalGuards() method를 사용할 수 있다.

const app = await NestFactory.create(AppModule);
app.useGlobalGuards(new RolesGuard());

hybrid App의 경우 useGlobalGuards() method는 gateway나 micro service에 guard() 설정하지 못한다.(만일 바꾸고 싶다면 Hybird application 참고) "standard"(non-hybird) microservice app의 경우, useGlobalGuard()는 guard를 global하게 마운트된다.

Global guard의 경우 전체 application, 모든 controller, 모든 route handler에 사용된다. Dependency injection 관점에서, module(위의 코드 처럼 useGlobalGuards())의 바깥에서 global guards는 dependency를 inject하지 못한다. 왜냐하면 이는 모듈의 바깥에서 이루어졌기 때문이다. 이러한 문제를 해결하기 위해, 다음과 같은 방식으로 module에서 바로 guard를 설정하면 된다.

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: RolesGuard,
    },
  ],
})
export class AppModule {}

<팁!>
guard에 대해 이러한 방식으로 dependency injection을 사용할 때, 이러한 구성이 사용되는 모듈에 관계없이 실제로 전역적이라는 점에서 유의해야한다. 어디서 이 작업을 수행할까? guard(위의 예제에서 정의된 RolesGuard)를 정의한 module을 선택해라. 또는 useClass는custom provider 등록을 처리하는 유일한 방법이 아니다. 자세히

Setting roles per handler

앞의 RolesGuard는 잘 동작한다. 하지만 그렇게 smart하지는 않다. 아직 guard의 기능 들중 가장 중요한 것을 보지 않았다.(execution context). 아직 역할이나 각 핸들러에 허용된 역할에 대해 알지 못한다. 예를 들어 CatsController의 경우 다양한 route에 대해 permisstion scheme가 다르다. 일부는 오직 admin user에게만 가능할 수도 있고, 다른 것들은 everyone에게 허용될 수 있다. 어떻게 다양한 route에 대해 각각에 role를 유연하고 재사용가능하게 맞출 수 있을까?

여기서 custom metadata가 중요한 역할을 한다. 자세히 Nest는 Reflector.createDecorator static method를 통해 만들어진 decorator나 built-in @SetMetadata() decorator를 통해 custom metadata를 route handler에 붙이는 능력을 제공한다.

예를 들어, metadata를 handler에 붙여주는 Reflector.createDecorator method를 통해 @Roles() decorator를 만들었다고 가정하자. Reflector는 @nestjs/core package에서 framework에 의해 제공된다.

import { Reflector } from '@nestjs/core';

export const Roles = Reflector.createDecorator<string[]>();

Roles decorator는 string[] type 하나를 인자로 받는 함수이다.

이 decorator를 이용하기 위해, 간단히 handler에 붙인다.

@Post()
@Roles(['admin'])
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

Roles decorator metadata를 create() method에 붙인다. 결국 admin이 있는 user만 이 route에 접근할 수 있다.

대신 Reflector#createDecorator method를 붙이면, 내장된 @SetMetadata() decorator를 사용할 수 있다. 자세히

Putting it all together

앞으로 돌아가 RolesGuard를 다시 묶어준다. 현재, request에 대해 모두 true를 반환한다. 현재 사용자가 할당받은 역할을 현재 처리 중인 route에 필요한 실제 역할과 비교하여 반환 값을 조건부로 만들고자 한다. route의 역할(custom metadata)에 접근하기 위해서, Reflector helper class를 다시 사용해야 한다.

// roles.decorator.ts
import { SetMetadata } from '@nestjs/common';

// SetMetadata(메타데이터 키, 메타데이터 값)
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

// roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Roles } from './roles.decorator';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  // 요청이 핸들러에 접근할 수 있는지 여부를 결정한다.
  canActivate(context: ExecutionContext): boolean {
    // context.getHandler()를 통해 현재 핸들러의 메타데이터를 가져온다.
    // 메타데이터 키 'roles'에 설정된 역할들을 가져와서, 현재 요청을 보낸 사용자의 역할과 비교
    const roles = this.reflector.get('roles', context.getHandler());
    // 역할이 정의되어 있지않다면, 모두 허용한다는 의미
    if (!roles) {
      return true;
    }
    // api를 요청하는 유저의 roles과 현재 api에 지정된 roles를 비교
    const request = context.switchToHttp().getRequest();
    const user = request.user;
    return matchRoles(roles, user.roles);
  }
}

// admin.controller.ts
import { Controller, Get, UseGuards } from '@nestjs/common';
import { RolesGuard } from './roles.guard';
import { Roles } from './roles.decorator';

@Controller('admin')
@UseGuards(RolesGuard)
export class AdminController {
  @Get()
  @Roles('admin') // 'admin' 역할이 필요함을 나타내는 데코레이터
  findAll() {
    return 'This is an admin route';
  }
}

<팁!>
node.js에서, authorized user를 request object에 붙이는 것은 흔한 관행이다. 즉, 위의 코드에서, request.user는 user instance와 허용된 역할을 가지고 있다고 가정하고 가져온다. app 내에서, custom authentication guard(or middleware)에서 이러한 연관을 만들 가능성이 높다. 다음 챕터에서 자세히

<주의사항!>
matchRoles() 함수 내의 logic은 simple하거나 sophisticated 할 수 있다. 이 example의 포인트는 어떻게 guard가 request/response cycle에서 보여지는가 이다.

Reflection and metadata을 참고해라.
endpoint에서 만일 user가 불충분한 권한으로 request 한다면, nest는 자동으로 다음과 같은 response를 보낸다.

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

만일 guard가 false를 반환한다면, framework는 ForbiddenException을 던진다. 만일 다른 error response를 원한다면, 다음과 같이 구체적인 exception을 던져야 한다.

throw new UnauthorizedException();

guard에 의해 발생한 exception은 exception layer에서 다뤄진다.

<팁!>
만일 실제 예시와, 어떻게 authorization이 구현되는지 보고 싶다면, 자세히

Pipes

Pipe는 @Injectable() decorator로 명시된 class이다. 이는 PipeTransform interface를 받는다.

클라이언트가 특정 API를 요청한다면, 먼저 middleware가 요청을 처리하고, 이후 pipe가 요청 데이터를 변환 및 검증하여 컨트롤러 메서드에 전달하게 된다.

Pipe는 두 가지의 역할을 한다.

• transformation: input data를 원하는 형태의 form으로 바꿔준다.(e.g. string to integer)
• validation: input data를 검사한다. 그리고 valid하다면 그대로 넘기고 그렇지 않다면 error를 발생시킨다.

위의 두 경우에서, pipe는 controller route handler에 의해 처리된 arguments에 의해서 동작한다. Nest는 method가 실행되기 전 pipe를 배치 시킨다. 그리고 pipe는 method로 전달될 argument를 받아서 작업을 수행한다. pipe를 통한 transformation 그리고 validation의 작업을 마친 후에, route handler가 그 변환된 argument로 실행시킨다.

parameter(매개변수): 함수 안에서의 정의 및 사용에 나열되어 있는 변수들을 의미
argument(전달인자): 함수를 호출할 때 전달되는 실제 값들

Nest는 별도의 설치가 필요없는 몇 개의 built-in된 pipe를 지닌다. 또한 pipe를 사용자에 맞게 custom 할 수 있다. 이번 chapter에서는, build-in pipe를 소개하고, 어떻게 그들을 route-handler와 묶을 수 있는지를 소개한다. 그리고 여러 custom pipe를 살펴보면서 처음부터 하나를 만드는 방법을 소개한다.

<팁!>
pipe는 exception zone 내부에서 동작한다. 이는 만일 Pipe가 exception을 발생시켜도, 이는 exception layer에 의해 처리된다. (global exceptions filter 그리고 어떤 exception filters) pipe에서 exception이 발생하면, 그 이후에 controller method가 실행되지 않는다는 점이 분명하다. 이는 application에서 들어오는 data의 validation을 검사하는데 있어 굉장히 유용하다.

Middleware, pipe, filter

위의 3개의 장치의 순서는 다음과 같다. Middleware -> pipe, 그리고 filter

Middleware는 reqeust와 response 객체를 변형하거나, 특정 조건에 따라 요청을 차단하거나 logging을 수행한다. 주로 HTTP 요청을 처리하는 초기 단계에서 작동한다.

• 요청 로깅: 요청 정보를 기록
• 인증(Authentication): 사용자의 인증을 처리한다.
• 권한 부여(Authorization): 사용자의 권한을 확인한다.
• 요청 변환(Request Transformation): 요청 데이터를 변환하거나 검증한다.
• 응답 변환(Response Transformation): 응답 데이터를 변환하거나 포맷한다.

Pipe는 요청 데이터를 변형하거나 유효성을 검사한다. 주로 데이터 변환과 유효성 검사를 수행한다.

• 변환(Transformation): 입력 데이터를 원하는 형식으로 변환한다. 예를 들어, 문자열을 정수로 변환할 수 있다.
• 유효성 검사(Validation): 입력 데이터가 특정 조건을 만족하는지 확인한다. 조건을 만족하지 않으면 예외를 발생시킨다.

Filter는 예외가 발생했을 때 이를 처리하여, 적절한 응답을 클라이언트에게 반환한다.

Built-in pipes

Nest는 9개의 pipe가 내장되어 있다. @nestjs/common에서 import 할 수 있다.

• ValidationPipe: 입력 데이터를 유효성 검사를 통해 확인. class-validation library와 함께 사용하여 DTO를 기반으로 유효성 검사 수행
• ParserIntPipe: 문자열을 정수로 변환. 실패하면 "BadRequestException"
• ParseFloatPipe: 문자열을 부동 소수점 숫자로 변환. 실패하면 "BadReqeustException"
• ParseBoolPipe: 문자열을 불리언 값으로 변환. 실패하면 "BadRequestException"
• ParseArrayPipe: 문자열을 배열로 변환. 실패하면 "BadRequestException"
• ParseUUIDPipe: 문자열이 유효한 UUID인지 확인하고, 유효하지 않으면 "BadRequestException"
• ParseEnumPipe: 문자열을 열거형값으로 변환, 실패하면 "BadRequestException"
• DefaultValuePipe: 특정 파라미터가 없을 때 기본값으로 설정한다. 주로 선택적 파라미터에 사용
• ParseFilePipe: 파일 업로드 시 파일을 파싱하고 검증한다. 주로 파일 크기, 타입 등의 조건을 확인

먼저 ParseIntPipe를 살펴보자. transformation을 수행한다.. 여기서 pipe는 method handler parameter가 javascript integer를 바뀜을 보장해준다.(만일 변환에 실패하면 exception을 던진다.) 후의 chapter에서는 ParseIntPipe을 implementation 간단한 custom pipe를 만들 것 이다. 아래의 예제들은 ParseBoolPipe, ParseFloatPipe, ParseEnumPipe, ParseArrayPipe, ParseUUIDPipe와 같은 다른 내장 transformation pipe들에도 적용된다. 이 글에서 이러한 pipe를 'Parse*' 라고 서술할 것이다.

Binding pipes

pipe를 사용하기 위해, pipe class의 instace를 적절한 context에 bind해야한다. 아래의 ParseIntPipe 예시에서, 특정한 route handler method와 pipe를 연결할 것이다. 그리고 method가 호출되기 전에 pipe가 실행될 것이다. 다음과 같은 구조로 사용하여, method parameter 수준에서 pipe를 binding한다.

@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}

findOne() method는 number type parameter를 받을 것이고, 그렇지 않다면 route handler가 호출되기 전에 exception이 발생할 것 이다.

예를 들어 다음과 같은 route가 호출되었다고 하자.

GET localhost:3000/abc

그렇다면 다음과 같은 exception이 호출 될 것이다.

{
  "statusCode": 400,
  "message": "Validation failed (numeric string is expected)",
  "error": "Bad Request"
}

이러한 exception은 findOne() 이 실행되는 것을 막는다.

위에서는 ParseIntPipe의 class를 호출하는 것이지, instance가 아니다. 이는 framework에 instance화의 책임을 떠넘기고 dependency injection을 가능케 한다. pipe와 guard와 마찬가지로, in-place instance를 전달할 수 있다. in-place instance를 전달하는 것은 built-in pipe의 행동을 설정하는데 있어서 유용하다.

@Get(':id')
async findOne(
  @Param('id', new ParseIntPipe({ errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE }))
  id: number,
) {
  return this.catsService.findOne(id);
}

모든 Parse* pipes들도 비슷하게 동작한다. 이들은 모두 route parameter, query string parameter 그리고 request body value의 유효성을 검사한다.

아래의 경우 query string paramter를 검사한다.

@Get()
async findOne(@Query('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}

// 참고
// =================================================================
// 1. @Query:
//    - 출처: URL의 쿼리 문자열에서 데이터를 가져온다
//    - 용도: GET 요청에서 주료 사용된다.
//    - 예시: @@uery('id') id: string은 https://example.com/api? id=123, id 값을 가져온다
@Get()
async findOne(@Query('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}

// 2. @Body
//    - 출처: request 본문에서 데이터를 가져온다.
//     - 용도: POST, PUT, PATCH 요청에서 주료 사용된다.
//    - 예시: @Body() createCatDto: CreateCatDto 는 request 본문에서 데이터를 가져온다.
@Post()
async create(@Body() createCatDto: CreateCatDto) {
  return this.catsService.create(createCatDto);
}

// 3. @Param:
//    - 출처: URL 경로 파라미터에서 데이터를 가져온다.
//    - 용도: 주로 리소스 식별자(id)와 같은 경로 변수에 사용된다.
//    - 예시: @Param('id') id: string은 /api/resource/123 'id' 값을 가져온다.
@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
  return this.catsService.findOne(id);
}

다음의 경우 ParseUUIDPipe를 사용하여 string paramter를 검사하고, uuid인지 유효성 검사를 실시한다.

@Get(':uuid')
async findOne(@Param('uuid', new ParseUUIDPipe()) uuid: string) {
  return this.catsService.findOne(uuid);
}

<팁!>
만일 ParseUUIDPipe() 를 사용할 때는 UUID version 3, 4, 5 를 parse할 수 있다. 만일 특정한 version의 UUID를 검사한다면 pipe option을 통해 설정할 수 있다.

위에서는 Parse* 를 살펴보았다. Binding validation pipe는 약간 다르다.

<팁!>
validation pipe의 광범위한 예에 대해서는 Validation techniques를 참고할 것.

Custom pipes

앞서 언급한 대로, pipe를 customize화 할 수 있다. Nest는 강력한 ParseIntPipe그리고 ValidationPipe를 제공하지만, custom pipe가 어떻게 동작하는지 살펴보기 위해 간단한 custom version을 만들어 보자.

간단하게 input value를 받아 그대로 return 하는 pipe를 만들어보자.

import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';


// ValidationPipe 클래스를 NestJS의 의존성 주입 시스템에 등록한다. 이를 통해 다른 클래스에서 이 파이프를 주입하여
// 사용할 수 있다.
@Injectable()
// PipreTransform 인터페이스를 구현하여 파이프로 사용될 수 있다.
export class ValidationPipe implements PipeTransform {
  // transform 파이프의 핵심 메서드로, 입력 값을 변환한다.
  //    value: 파이프에 전달된 입력 값
  //     metadata: 현재 인수에 대한 메타 데이터
  transform(value: any, metadata: ArgumentMetadata) {
    return value;
  }
}

<팁!>
PipeTransform(string, number)를 했을 때의 console.log(metadata)의 결과

<팁!>
PipeTransform<T,R> 은 반드시 모든 pipe에서 implement해야하는 generic interface이다. T는 input value의 타입이며, R은 transform() method의 return 타입이다.

import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParseIntPipe implements PipeTransform<string, number> {
  transform(value: string, metadata: ArgumentMetadata): number {
    const val = parseInt(value, 10);
    if (isNaN(val)) {
      throw new BadRequestException('Validation failed');
    }
    return val;
  }
}

모든 pipe는 PipeTransform interface에 의해 transform() method를 호출해야한다. 이 method는 다음과 같은 두 개의 parameter를 가진다.

• value: transform 메서드에 전달되는 값으로, 변환 또는 검증이 필요한 입력 데이터이다.
  • 출처: 이 값은 controller method의 parameter에서 가져온다.
  • 용도: validation 검사나 data transform을 수행할 때 사용된다.
• metadata: 현재 인수에 대한 메타데이터를 제공한다.
  • 구성: ArgumentMetadata 인터페이스를 통해 제공된다.
    • type: body, query, param, custom 중 하나로, 인수의 위치를 나타낸다.
    • metatype: 변환 전 원시 타입(String, Number, Boolean)
    • data: parameter의 이름(e.g. 'id')이다.

value parameter는 현재 처리되고 있는 method argument(route handling method가 받기 전의 argument)이며, metadata는 현재 처리되는 method의 argument의 metadata이다. metadata 객체는 다음과 같은 속성들을 가진다.

export interface ArgumentMetadata {
  type: 'body' | 'query' | 'param' | 'custom';
  metatype?: Type<unknown>;
  data?: string;
}

이 속성들은 현재 처리되는 argument를 설명해준다.

<주의사항!>
typescript inteface는 transpilation 도중 사라진다. 즉, 만일 class가 아닌 interface로 선언된 method parameter의 type이면, metatype 값은 object이다.

Schema based validation

validation pipe를 좀 더 유용하게 만들어보자. CatsController의 create() method를 자세히 보면, service의 method를 실행하기 전에 POST 본문 객체가 유효한지 확인하고 싶을 것 이다.

@Post()
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

다음은 CreateCatDto이다.

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

create method에 대한 모든 request가 valid한 body를 포함하도록 보장하고 싶다. 그래서 createCatDto 객체의 3개의 member의 유효성 검사를 실시해야 한다. 물론 이러한 검사를 route handler method 내부에서 실시할 수 있다. 허나 이는 single responsibility principle(SRP) 을 위배 한다.

단일 책임 원칙(Single Responsibility Principle): 객체는 단 하나의 책임만 가져야 한다. 하나의 클래스는 하나의 기능을 담당 하여 하나의 책임을 수행하는데 집중되어야 있어야 한다는 의미한다. 한 객체에 책임이 많아질 수록 클래스 내부에서 서로 다른 역할을 수행하는 코드 끼리 강하게 결합될 가능성이 높아지게 되어 시스템이 복잡해질 수 있다. 

다른 접근법으로는 validator class를 만들고 유효성검사를 위임하는 것이다. 이 방법의 단점은 각 method의 시작 부분에서 이 validator 검사기를 호출해야 한다는 점이다.

validation middleware를 만드는 것은 어떤가? 이 방법이 작동할 수는 있지만, 불행하게도 application의 전체 context에 사용되는 generic middleware를 만드는 것이 불가능하다. 이는 middleware가 호출될 handler와 그 parameter를 포함한 execution context를 인지하지 못하기 때문이다.

middleware는 execution context를 알지 못한다는 것의 의미:
    미들웨어가 실행 컨텍스트를 알지 못한다는 것은, 미들웨어가 특정 요청을 처리하는 동안 어떤 컨트롤러나 메서드가 호출될 지, 그리고 그 메서드의 매개변수가 무엇인지 알지 못한다는 뜻이다. 미들웨어는 주로 요청과 응답 객체만을 처리하며, 어플리케이션의 특정 비즈니스 로직이나, 컨트롤러 메서드에 대한 구체적인 정보를 알지 못한다.

pipe는 nestjs에서 요청 데이터를 변환하고, 유효성 검사를 위해 설계된 도구이다. 따라서 유효성 검사를 위해 파이프를 사용하는 것이 적절하다. 이제 validation pipe를 정교하게 다듬어 보자.

Object schema validation

object의 validation을 위한 clean하고 DRY한 여러 방법이 있다. 첫 번째 방법은 schema-based validation을 사용하는 것이다.

DRY(Don't repeat yourself): 소프트웨어 개발 원칙 중 하나로, 동일한 코드나 로직을 반복하지 않도록 하는 중요한 개념이다.
schema-based: 데이터의 형식과 제약 조건을 정의하는 schema를 사용하여 데이터를 검증한다.
    schema는 데이터 구조, 필수 필드, 데이터 타입, 혀옹되는 값의 범위 등을 명확히 정의한다.

Zodlibrary는 readable API와 함께 schema를 만드는데 사용된다. Zod-based schema를 만드는 validation pipe를 만들자.

//Zod는 TS 및 JS에서 사용되는 schema 선언 및 validation 검사 라이브러리다. 
import { z } from 'zod';

// 스키마 정의
const userSchema = z.object({
  name: z.string(),
  age: z.number().min(18),
});

// 데이터 유효성 검사
const result = userSchema.safeParse({ name: "John", age: 25 });

if (!result.success) {
  console.error(result.error);
} else {
  console.log("Valid data:", result.data);
}

먼저 package를 설치해야 한다.

$ npm install --save zod

constructor argument로서 schema를 만드는 간단한 class를 만든다. 이 때 schema.parse() method를 적용하는데, 이는 incoming argument의 유효성을 검사한다.

앞서 언급한 대로, validation pipe는 값을 그대로 반환하거나 에러를 던진다.

다음 section에서는 어떻게 @UsePipes() 를 통해 controller method에 적절한 schema를 던지는가를 볼 것이다. 이렇게 하는 것은 reusable validation pipe를 전체 context를 걸쳐 적용하게 한다.

import { PipeTransform, ArgumentMetadata, BadRequestException } from '@nestjs/common';
import { ZodSchema } from 'zod';

export class ZodValidationPipe implements PipeTransform {
  // 생성자에서 ZodSchema 타입의 스키마를 받아와 저장한다.
  // 아래의 userSchema와 비교
  constructor(private schema: ZodSchema) {}

  // value: 검증할 입력 값, metadata: 매개변수에 대한 metadata를 제공
  transform(value: unknown, metadata: ArgumentMetadata) {
    try {
      // schema.parse를 사용하여 값을 검증하고 변환한다.
      const parsedValue = this.schema.parse(value);
      return parsedValue;
    } catch (error) {
      throw new BadRequestException('Validation failed');
    }
  }
}

// 사용 예시
import { z } from 'zod';

const userSchema = z.object({
  name: z.string().min(1),
  age: z.number().int().min(0),
  email: z.string().email(),
});


@Controller('users')
export class UsersController {
  @Post()
  create(@Body(new ZodValidationPipe(userSchema)) createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }
}

Binding validation pipes

앞서, 어떻게 transformation pipe(ParseIntpipe, 또는 Parse* )가 bind 되는지를 살펴보았다.

이번에는, method call level에서 pipe를 bind할 것이다. 현재 예시에서, ZodValidationPipe를 사용할 것이다.

1. ZodValidationPipe의 instance를 만든다.
2. Pipe의 class constructor에 context 별 Zod schema를 전달한다.
3. pipe랑 method랑 연결 한다.

import { z } from 'zod';

export const createCatSchema = z
  .object({
    name: z.string(),
    age: z.number(),
    breed: z.string(),
  })
  .required();

// createCatSchema의 스키마를 기반으로 Typescript 타입을 생성
export type CreateCatDto = z.infer<typeof createCatSchema>;

@UsePipes() decorator를 사용한다.

@Post()
@UsePipes(new ZodValidationPipe(createCatSchema))
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

<팁!>
@UsePipes() decorator는 @nestjs/common에서 가져온다.

<주의사항!>
zod 라이브러리는 tsconfig.json file에서 strictNullChecks 옵션이 필요하다.

Class validator

<주의사항!>
이번에 배우는 것은 Typescript에서 요구하는 것이다. 만일 vanilla JavaScript라면 필요없다.

validation technique에 대해 대체 구현을 살펴보자.
Nest는 class-validator 라이브러리에 잘 작동한다. 이는 decorator기반의 validate를 가능케 한다. decorator 기반의 유효성 검사는 Nest의 파이프 기능과 결합할 때 매우 강력하다. 이는 처리되는 속성 metatype에 접근할 수 있기 때문이다.

$ npm i --save class-validator class-transformer

패키지를 이용하면 CreateCatDto class에 몇 개의 decorator를 추가할 수 있다. 여기에는 몇 가지 장점이 있다. 별도의 유효성 검사를 위한 Class를 만들 필요가 없이 데이터를 검증할 수 있다.

import { IsString, IsInt } from 'class-validator';

export class CreateCatDto {
  @IsString()
  name: string;

  @IsInt()
  age: number;

  @IsString()
  breed: string;
}

<팁!>
class-validator decorate의 자세한 설명

import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';

@Injectable()
export class ValidationPipe implements PipeTransform<any> {
  // value: 검증할 입력값, metadata: 입력 값의 메타데이터(type 정보 등...)
  async transform(value: any, { metatype }: ArgumentMetadata) {
    // metatype이 없거나 기본 타입인 경우 검증하지 않고 값을 그대로 반환, 검증을 수행할 필요가 없음을 의미
    //     - metatype이 없다는 것은, 요청된 데이터의 타입 정보가 제공되지 않았음을 의미한다. NestJS에서 파이프는
    //         입력 값의 메타타입을 통해 어떤 타입을 변환해야 하는지, 그리고 어떤 검증을 수행해야 하는지를 결정한다.
    // toValidate(metatype) : 기본 타입(String, Boolean, Number, Array, Object)이 아닌 경우에만 검증을 수행하도록 함
    //    - toValidate method는 메타타입이 기본 타입(String, Boolean, Number, Array, Object)인지 확인
    if (!metatype || !this.toValidate(metatype)) {
      return value;
    }

    // class-transformer의 plainToInstance 함수를 사용하여 일반 JS객체('value')를 특정 클래스('metatype')의 인스턴스로 변환 
    const object = plainToInstance(metatype, value);
    // validate 함수를 사용하여 변환된 객체('object')의 유효성을 검사한다.
    // 유형성 검사에 실패하면, 유효하지 않은 필드와 관련된 오류 정보가 배열 형태로 저장된다.
    // 성공하면, errors 배열은 비어 있다.
    const errors = await validate(object);
    if (errors.length > 0) {
      throw new BadRequestException('Validation failed');
    }
    return value;
  }

  private toValidate(metatype: Function): boolean {
    const types: Function[] = [String, Boolean, Number, Array, Object];
    // types 배열에 포함되어 있으면 false를 반환하여 검증을 건너뛴다.
    // 포함되어 있지 않으면, true를 반환하여 검증을 수행
    return !types.includes(metatype);
  }
}

<팁!>
앞서 언급한 대로, ValidationPipe는 Nest에서 기본적으로 제공해주기에 별도의 generic validation pipe를 만들 필요가 없다. built-in ValidationPipe는 이번 쳅터에서 만든 sample보다 더 많은 option을 지닌다. 자세한 사항

우리는 위에서 class-transformer 라이브러리를 사용했는데, 이는 class-validator 라이브러리와 동일한 작성자가 만든 것이므로 이 두 라이브러리는 매우 잘 호환됩니다.

위의 코드에서 주목해야할 5개가 있다. 첫 번째로, transform() method는 async가 붙어있다. 이는 Nest에서는 synchronous와 asynchronous pipe 둘다 지원하기 때문이다. asynch method를 만들었는데, 이는 일부 class-validator validations는 Promises를 이용해서 async가 될 수 있기 때문이다.

두 번째로, destructuring을 통해 metatype를 ArgumentMetadata에서 추출했다. 이는 ArgumentMetadata의 전부를 뽑아내서 metatype 변수를 할당하는 추가 구문을 사용하는 것에 대한 간단한 표현이다.

세 번째로, helper function인 toValidate() 를 주목해야 한다. 현재 처리 중인 argument가 native JavaScript 타입일 경우, 유효성 검사 단계를 건너뛰는 역할을 한다. 이 타입들은 유효성 검사 decorator를 붙일 수 없으므로, 유효성 검사 단계를 거칠 필요가 없다.

네 번째로, class-transformer의 plainToInstance() 를 사용한다. 이는 일반 javascript argument object를 타입이 지정된 object로 바꿔준다. 그래서 validation을 검사할 수 있다. 반드시 이것을 해야하는 이유는 incoming post body object(network request에서 deserialized된)는 타입 정보를 가지고 있지 않기 때문이다.(이는 Express와 같은 기본 플랫폼이 작동하는 방식이다.) Class-validator은 앞서 DTO에서 정의 내린대로 validation decorator를 사용해야 하므로, 들어오는 본문을 단순한 일반 객체가 아닌 적절히 decorator가 적용된 object로 처리하기 위해 이 변환을 수행해야 한다.

마지막으로, 앞서 언급한 대로 이것은 validation pipe이기에, 바뀌지 않은 값, 혹은 에러를 던진다.

마지막 스탭은 ValidationPipe를 bind 하는 것이다. Pipe는 parameter-scoped, method-scoped, controller-scoped, global-scoped가 될 수 있다. 일찍이, Zod 기반의 validation pipe로, method 수준에서 binding 예를 봤다. 이번 아래의 예는, pipe instance를 route handler에 @Body() decorator 로 묶을 것이다. 그래서 pipe는 post body의 유효성 검사를 위해 호출될 것 이다.

@Post()
async create(
  @Body(new ValidationPipe()) createCatDto: CreateCatDto,
) {
  this.catsService.create(createCatDto);
}

parameter-scoped pipe는 validation logic이 오직 specified parameter에 적용될 때만 유용하다.

Global scoped pipes

ValidationPipe는 가능한 일반적으로 만들어 졌기에, 이를 global scoped 의 pipe로 설정하여 전체 application의 모든 route handler에 적용함으로써 그 유용성을 최대한 발휘할 수 있다.

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

hybrid apps의 경우에 useGlobalPipes() method는 gateway와 microservice에 대해 pipe를 설정하지 않는다. "표준"(non-hybrid) microservice 앱의 경우, useGlobalPipes()는 pipe를 전역적으로 mount한다.

Global pipe는 전체 application, 모든 controller, 모든 route handler에 사용된다.

Dependency Injection면에서는 (위의 예시 처럼 useGlobalPipes() 로) 어떤 module 밖에서 등록된 global pipes는 dependency를 주입하지 못한다. 왜냐하면 binding이 어떤 module의 밖에서 일어났기 때문이다. 이를 해결하기 위해서, module에서 바로 global pipe를 설정할 수 있다.

import { Module } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_PIPE,
      useClass: ValidationPipe,
    },
  ],
})
export class AppModule {}

<팁!>
pipe에 대해 이러한 접근으로 dependency injection을 수행할 때, 이 구성을 사용하는 module에 관계없이 pipe는 global하다. 어디서 수행되는가? pipe(위의 예제의 경우 ValidationPipe)가 정의된 모듈을 선택한다. 또한 useClass는 custom provider registration을 처리하는 유일한 방법은 아니다. 자세히

The built-in ValidationPipe

앞서 언급한 대로, ValidationPipe가 이미 Nest에서 제공하기 때문에 따로 generic validation pipe를 build할 필요가 없다.
내장된 ValidationPipe는 이번 쳅터에서 다룬 것보다 더 많은 옵션을 제공한다. 자세히

Transformation use case

유효성 검사는 커스텀 파이프의 유일한 사용 사례가 아니다.이 쳅터의 처음에서 pipe는 inputdata를 원하는 format으로 바꿀 수 있다고 했다. 이것이 가능한 것은 transform 함수에서 반환된 값은 이전의 argument 값을 덮어 씌우기 때문이다.

언제 유용한가? 가끔 client으로부터 전달된 data를 change할 필요가 있다. 예를 들어 string to integer, route handler method에 의해 다뤄지기 전에. 게다가, 어떤 required data filed가 missing됬을 때 이를 default value로 바꿀 필요가 있다. Transformation pipes가 processing function과 client request 또는 request handler 사이에 위치에서 이를 수행한다.

ParseIntPipe는 string을 integer value로 바꿀 수 있다.

import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParseIntPipe implements PipeTransform<string, number> {
  transform(value: string, metadata: ArgumentMetadata): number {
    // 10진법으로 변환
    const val = parseInt(value, 10); 
    if (isNaN(val)) {
      throw new BadRequestException('Validation failed');
    }
    return val;
  }
}

pipe랑 param을 묶을 수 있다.

@Get(':id')
async findOne(@Param('id', new ParseIntPipe()) id) {
  return this.catsService.findOne(id);
}

다른 유용한 transformation case는 request에서 공급된 id를 이용하여 DB에서 user entity에서 select하는 것이다.

// userEntity는 UserByIdPipe에 의해 처리된 결과로, UserEntity 타입의 객체이다.
@Get(':id')
findOne(@Param('id', UserByIdPipe) userEntity: UserEntity) {
  return userEntity;
}

다른 모든 transformation pipe와 마찬가지로, input value(an id)를 받아 출력 값(UserEntity object)을 반환한다는 점에 유의해야 한다. 이렇게 하면 반복되는 코드를 handler에서 공통 pipe로 추상화하여 선언적이고 DRY(중복 배제)하게 만들 수 있다.

Providing defaults

Parse* pipes 는 parameter의 값이 정의되어 있을 것으로 예상한다. pipe들은 null 혹은 undefined values를 받으면 exception을 던질 것 이다. endpoint에서 놓친 query string parameter value를 다루도록 하기 위해서, 이러한 값에 대해 작동하기 전에 default value를 제공해야 한다. DefaultValuePipe는 이러한 목적으로 제공된다. 간단히 @Query() decorator에서 DefaultValuePipe를 인스턴스화 해서 넣으면 된다.

@Get()
async findAll(
  @Query('activeOnly', new DefaultValuePipe(false), ParseBoolPipe) activeOnly: boolean,
  @Query('page', new DefaultValuePipe(0), ParseIntPipe) page: number,
) {
  return this.catsService.findAll({ activeOnly, page });
}

Exception filters

Nest에는 exception layer이 내장되어 있다. 이는 application의 전반에 걸쳐 모든 unhandled exception의 처리에 책임이 있다.
만일 개발자의 application code에 의해 발생되는, not handled한 exception이 발생할 때, 이것을 이 layer가 처리한다. 그리고 바로 자동적으로 적절하게 user-friendly response를 보낸다.

별도의 설치나 설정이 필요없이, 이러한 action은 built-in된 global exception filter에 의해 수행된다. 이러한 filter는 HttpException(혹은 이것의 subclass) type의 exception(예외)를 다룬다. 만일 unrecognized한 exception이 발생한다면(HttpException, HttpException에 의한 class가 둘다 아님), built-in된 exception filter가 다음과 같은 default JSON response를 일으킨다.

{
  "statusCode": 500,
  "message": "Internal server error"
}

<팁!>
global exception filter는 부분적으로 http-errors library를 지원한다. 기본적으로, statusCode 그리고 message 속성을 포함하는 모든 exception은 적절하게 채워서 response로 반환된다. (기본적으로 인식되지 못한 예외에 대한 InternalSererErrorException 대신)

Throwing standard exceptons

Nest는 @nestJs/common에서의 build-in HttpException class를 제공한다. 전형적인 HTTP REST/GraphQL API 기반 applications에 대해서, 특정한 error가 발생했을 때, standard한 HTTP response object를 보내는게 best이다.

예를 들어, CatsController에서의 findAll() method가 있다고 하자. 그리고 어떠한 reason으로 route handler가 exception을 throw했다고 하자. 다음과 같다.

@Get()
async findAll() {
  throw new HttpException('Forbidden', HttpStatus.FORBIDDEN);
}

<팁!>
@nestjs/common의 HttpStatus는 상태 정보를 담는 enum helper 이다.

만일 client가 endpoint에서 호출한다면, response는 다음과 같다.

{
  "statusCode": 403,
  "message": "Forbidden"
}

HttpException 생성자는 두 개의 argument를 담는데, 이는 response를 결정한다.

• response argument는 JSON response body를 정의한다. 이는 string 혹은 object가 될 수 있다.
• status argument는 HTTP status code를 결정한다.

기본적으로 JSON response body는 두 개의 속성을 지닌다.

• statusCode: status argument에 제공된 HTTP status code로 기본 설정된다.
• message: status에 기반한 HTTP error의 짧은 설명이다.

JSON response body의 message를 덮어 쓰기 위해서는, string을 response argument에 공급하면 된다.

JSON response body를 전부 덮기 위해서는, response argument에 object를 전달하면 된다. Nest는 객체를 serialize하고 JSON response body 형태로 반환할 것 이다.

두 번째 argument인 status는 반드시 유효한 HTTP status code를 넣어야 하다. 가장 최고의 방법은 @nestjs/common의 HttpStatus enum을 넣는 것이다.

optional한 세 번째 argument, option은 error의 cause을 전달하는데 사용된다.
이 cause object는 response object로 직렬화 되지 않지만, HttpException에 의해 발생한 내부 error에 대한 정보를 보여주는 logging의 목적으로 유용하다.

다음은 전체 response body와 에러의 원인을 제공하는 예제 코드이다.

@Get()
async findAll() {
  try {
    await this.service.findAll()
  } catch (error) {
    throw new HttpException({
      status: HttpStatus.FORBIDDEN,
      error: 'This is a custom message',
    }, HttpStatus.FORBIDDEN, {
      cause: error
    });
  }
}

그렇다면 response는 다음과 같다.

{
  "status": 403,
  "error": "This is a custom message"
}

Custom Exceptions

많은 경우에, custom exception을 작성할 필요가없다. 단지 built-in 되있는 Nest HTTP exception을 쓰면된다.
만일 customized exception을 만들 필요가 있다면 제일 좋은 방법은 HttpException class를 상속받는 자신만의 exception을 만드는 것이다. Nest는 exception을 인식하고, 자동으로 error responses를 관리할 것이다.

export class ForbiddenException extends HttpException {
  constructor() {
    super('Forbidden', HttpStatus.FORBIDDEN);
  }
}

ForbiddenException은 기본 HttpException을 확장하므로 내장된 예외 처리기와 원활하게 작동합니다. 따라서 이를 findAll() 메서드 내에서 사용할 수 있습니다.

@Get()
async findAll() {
  throw new ForbiddenException();
}

Built-in HTTP exceptions

Nest는 HttpException을 상속받은 standard exception 집합을 제공한다. 이들은 @nestjs/common pacakge에 있다.
다음은 대표적인 HTTP Exception들이다.

• BadRequestException
• UnauthorizedException
• NotFoundException
• ForbiddenException
• NotAcceptableException
• RequestTimeoutException
• ConflictException
• GoneException
• HttpVersionNotSupportedException
• PayloadTooLargeException
• UnsupportedMediaTypeException
• UnprocessableEntityException
• InternalServerErrorException
• NotImplementedException
• ImATeapotException
• MethodNotAllowedException
• BadGatewayException
• ServiceUnavailableException
• GatewayTimeoutException
• PreconditionFailedException

모든 built-in exception들은 모두 options parameter를 이용하여 error cause와 error description을 제공할 수 있다.

throw new BadRequestException('Something bad happened', { cause: new Error(), description: 'Some error description' })

{
  "message": "Something bad happened",
  "error": "Some error description",
  "statusCode": 400,
}

Exception filters

base(built-in) exception filter는 자동적으로 많은 경우들을 다루지만, exception layer을 모두 제어하기를 원할 수 있다. 예를 들어
동적인 요소들에 근거한 다른 JSON schema를 사용하거나 log를 붙이기를 원할 수 있다. Exception filters는 이러한 목적을 위해 디자인되었다. 이 filter들은 제어의 흐름과, client로 반환되는 response의 내용을 정확하게 제어할 수 있다.

HttpException class의 instance인 exception을 잡고, 이를 위한 사용자 정의 응답 로직을 구현하는 exception filter를 만들 것이다. 이것을 위해, 기본 플랫폼의 Request와 Response 객체에 접근할 필요가 있다. Request 객체에 접근하고, 원래의 url을 빼내고, 이를 log 정보에 포함시킬 것이다. Response 객체를 이용하여 응답을 직접 제어하고 response.json() method를 사용하여 응답을 전송할 것이다.

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

// @Catch(HttpExeception):  HttpException 타입의 예외를 잡아 처리하는 필터임을 지정한다.
@Catch(HttpException)
// HttpExceptionFilter는 ExceptionFilter interface를 구현한다. 이는 'catch' method를 포함한다.
export class HttpExceptionFilter implements ExceptionFilter {
  // catch() : ExceptionFilter의 일부로, 예외가 발생했을 때 이를 처리하는 메서드. 예외를 잡아내고, 적절하게 처리하여 클라이언트에게 응답을 반환하는 역할
  // exception: 발생한 HttpException 객체이다.
  // host: ArgumentsHost 객체로, 여러 유형의 요청 컨텍스트를 캡슐화한다.
  // 요청 컨텍스트: 특정 요청에 대한 정보를 포함하는 객체로, 요청의 전체 생명 주기 동안 관련 데이터를 캡슐화한다.
  //     다음과 같은 정보를 갖는다.
  //         1. HTTP 요청/응답 객체: Express나 Fastify의 요청 및 응답 객체
  //         2. WebSocket 데이터: WebSocket 연결 및 메시지 데이터
  //         3. RPC 요청: 원격 프로시저 호출에 대한 요청 데이터
  catch(exception: HttpException, host: ArgumentsHost) {
    // HTTP 컨텍스트로 전환하여 express의 request, response 객체를 가져온다.
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();
    // 예외 객체에서 HTTP 상태 코드를 가져온다.
    const status = exception.getStatus();

    // 상태 코드와 JSON 형식의 응답을 클라이언트에게 전송한다.
    response
      .status(status)
      .json({
        statusCode: status,
        timestamp: new Date().toISOString(),
        path: request.url,
      });
  }
}

<팁!>
모든 exception filter들은 모두 generic ExceptionFilter interface를 사용해야 한다. 이는 catch(exception: T, host: ArgumentHost) method에게 나타난 <T>를 제공해야한다. 여기서 T는 예외의 유형을 나타낸다.

<주의사항!>
만일 @nestjs/platform-fastify를 사용한다면, response.json() 대신 response.send()를 사용해야 한다.

@Catch(HttpException) decorator는 요구된 metadata와 exception filter를 묶어준다. exception filter는 Nest에게 이 특수한 filter는 HttpException 타입의 예외를 원한다고 말해줘야한다. @Catch() decorator는 한 개의 파라미터나, comma로 구분된 리스트를 받는다. 이는 한 번에 filter의 타입을 설정하도록 해준다.

Arguments Host

catch() 메서드의 parameter를 보자. exception parameter는 현재 처리되고 있는 exception object이다. host parameter는 ArgumentsHost 객체이다. ArgumentsHost는 강력한 utility object로, 나중에 execution context chapter*에서 더 자세히 설명할 것 이다. 이번 code sample에서는 원래의 요청 핸들러(예외가 발생한 controller)로 전달되는 Request 및 Response 객체에 대한 참조를 얻기 위해 이를 사용한다. 이 code sample에서는 _ArgumentsHost*_의 몇 가지 helper method를 사용하여 원하는 Reqeust 및 Response 객체를 가져왔다. ArgumentsHost

이 정도의 추상화(abstraction)를 사용하는 이유는 ArgumentsHost가 모든 context에서 작동하기 때문이다.(e.g. 지금 작업 중인 HTTP 서버 context뿐만 아니라, 마이크로서비스와 WebSockets도 포함된다.) execution context chapter에서는 ArgumentsHost와 그 helper 함수의 기능을 통해 모든 실행 컨텍스트에 대해 적절한 인자를 접근할 수 있는 방법을 살펴볼 것 이다. 이를 통해 모든 context에서 작동하는 일반적인 exception filter를 작성할 수 있다.

Binding filters

이제 우리의 HttpExceptionFilter를 CatsController의 create() method에 연결하자.

@Post()
@UseFilters(new HttpExceptionFilter())
async create(@Body() createCatDto: CreateCatDto) {
  throw new ForbiddenException();
}

<팁!>
@UseFilters()는 @nestjs/common에서 가져올 수 있다.

@UseFilter()는 하나의 filter instance를 받거나, comma로 구분된 filter instance를 받는다. 코드에는 위에 작성된 HttpExceptionFilter instance를 넣었다. 대신에 instance 대신 class를 전달하여 instance화 책임을 프레임워크에 맡기고, dependency injection을 가능케 할 수 있다.

@Post()
@UseFilters(HttpExceptionFilter)
async create(@Body() createCatDto: CreateCatDto) {
  throw new ForbiddenException();
}

<팁!>
가능하다면, instance 대신 class를 사용함으로써 filter를 적용하는 것을 선호하자. 이는 Nest가 전체 module에서 같은 class의 instance를 쉽게 재사용할 수 있기 때문이다. 곧, memory 사용에 있어 이점을 취한다.

위의 코드에서 method-scoped에서 HttpExceptionFilter는 오직 하나의 create() route handler가 적용됬다. exception filter들은 다른 수준에서 적용될 수 있다. controller, resolver, gateway, controller-scoped, global-scope 등등 예를 들어 controller에 적용하는 것은 아래와 같다.

@UseFilters(new HttpExceptionFilter())
export class CatsController {}

이 구성은 CatsController내에 정의된 모든 route handler에 대해 HttpExceptionFilter가 적용된다.

이를 global-scope filter로 만들자고하면, 다음과 같다.

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

<주의사항!>
useGlobalFilters() method는 gateway나 hybrid application에 대해 filter를 적용하지 못한다.

global-scopde filter는 모든 controller, route handler에 대해 application 전반적으로 사용된다. DI 측면에서 위의 useGlobalFilters() 와 같이, 어떤 모듈의 바깥에서 등록된 global filter은 dependency를 inject할 수 없다. 이는 any module의 context 바깥에서 완료됬기 때문이다. 이러한 문제를 해결하기 위해서는, any module에서 부터 바로 global-scope filter를 등록할 수 있다.

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: HttpExceptionFilter,
    },
  ],
})
export class AppModule {}

이러한 접근 방식을 사용하여 filter에 대해 dependency inject을 수행할 때, 이 구성이 사용되는 module에 상관없이 filter는 실제로 global이라는 점에 유의해야 한다. 이 작업은 어디에서 수행되는가? filter(위의 경우 HttpExceptionFilter)가 정의된 모듈을 선택해야 한다. 또한 useClass는 custom provider registration을 처리하는 유일한 방법은 아니다. 자세히

많은 filter들을 이 기술로 추가할 수 있다. 간다히 각 provider array에 추가하기만 하면 된다.

Catch everything

모든 unhandled exception을 catch하기 위해, @Catch() decorator의 parameter를 비워두면 된다.

아래의 코드는 플랫폼과 무관하다. 왜냐하면 response를 처리하기 위한 HTTP adapter를 사용하고 Request, Response 따위의 플랫폼 종속 객체를 쓰지 않기 때문이다.

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
} from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  // HttpAdapterHost를 주입받는다.
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}


  catch(exception: unknown, host: ArgumentsHost): void {
    // In certain situations `httpAdapter` might not be available in the
    // constructor method, thus we should resolve it here.
    // httpAdapter는 현재 애플리케이션에서 사용 중인 HTTP 서버 어댑터이다. 
    //    1. 요청 URL 가져오기: httpAdapter.getReqeustUrl(req)
    //    2. 응답 보내기: httpAdapter.replay(res, body, statusCode)
    const { httpAdapter } = this.httpAdapterHost;

    const ctx = host.switchToHttp();

    const httpStatus =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    // 응답으로 반환될 JSON 객체를 구성
    const responseBody = {
      statusCode: httpStatus,
      timestamp: new Date().toISOString(),
      // 현재 요청의 URL 경로를 얻기 위해 사용된다. 
      path: httpAdapter.getRequestUrl(ctx.getRequest()),
    };

    httpAdapter.reply(ctx.getResponse(), responseBody, httpStatus);
  }
}

<주의사항!>
다양한 예외 필터를 조합하여 사용할 때, 모든 예외를 잡는 필터와 특정 타입에 바인딩된 필터를 함께 사용하는 경우, "모든 예외를 잡는" 필터를 먼저 선언해야 한다. 이렇게 해야 특정 필터가 바인됭 타입의 예외를 올바르게 처리할 수 있다.

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { AllExceptionsFilter } from './filters/all-exceptions.filter';
import { SpecificExceptionFilter } from './filters/specific-exception.filter';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: AllExceptionsFilter,
    },
    {
      provide: APP_FILTER,
      useClass: SpecificExceptionFilter,
    },
  ],
})
export class AppModule {}

Inheritance

일반적으로, application 요구사항을 충족시키기 위해 완전하 사용자 정의된 exception filter를 만든다. 하지만, 간단히 built-in default global exception fileter를 확장하고, 특정 요소에 따라 동작을 재정의하고자 할 때가 있을 수 있다.

예외 처리를 기본 필터에 위임하려면, BaseExceptionFilter를 확장하고, 상속받은 catch() method를 호출해야 한다.
아래와 같은 방식으로 기본 전역 예외 필터를 확장하고 커스터마이징하여 애플리케이션의 요구 사항에 맞게 사용할 수 있다.

import { Catch, ArgumentsHost } from '@nestjs/common';
import { BaseExceptionFilter } from '@nestjs/core';

@Catch()
export class AllExceptionsFilter extends BaseExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    super.catch(exception, host);
  }
}

<주의사항!>
BaseExceptionFilter를 확장한 Method-scoped와 Controller-scoped filter는 new를 이용해 instance화 되면 안된다. 대신에 framework가 이들을 자동으로 instance화하도록 해야 한다.

Global filter는 base filter를 확장할 수 있다. 이는 두 가지 방법으로 된다.

첫 번째 방법은 custom global filter를 인스턴스화할 때 HttpAdapter를 주입하는 것이다.

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const { httpAdapter } = app.get(HttpAdapterHost);
  app.useGlobalFilters(new AllExceptionsFilter(httpAdapter));

  await app.listen(3000);
}
bootstrap();

두 번째 방법은 APP_FILTER를 사용하는 것이다.

import { Module } from '@nestjs/common';
import { APP_FILTER } from '@nestjs/core';
import { CustomGlobalExceptionFilter } from './custom-global-exception.filter';

@Module({
  providers: [
    {
      provide: APP_FILTER,
      useClass: CustomGlobalExceptionFilter, // 글로벌 필터로 설정
    },
  ],
})
export class AppModule {}

Middleware

Middleware는 route handler가 호출되기 전에 실행되는 함수이다. NestJs에서는 middleware는 Express middleware와 동일한 기능을 가진다.
NestJS에서 미들웨어는 요청과 응답 사이에 실행되는 함수. 요청을 처리하는 도중 특정 작업을 수행할 수 있게 한다.
http 요청과 응답 사이 즉 라우터 핸들러 이전에 호출되는 함수이다.
다시 말해서 클라이언트 요청을 라우터 핸들러가 받기전에 가로채서 다른 작업을 수행할 수 있다.

다음과 같은 특징들이 있다.

• 요청에 대한 검증, 로깅, 인증, 권한 체크, 캐싱 등의 작업을 수행할 수 있다.
• 다수의 미들웨어 등록을 토해 다양한 작업을 순차적으로 처리할 수 있다.
• next 함수 호출을 통해 미들웨어 체인을 연결한다. next 함수를 호출하면 다음 미들웨어가 실행되며, 호출하지 않으면 다음 미들웨어가 실행되지 않는다.
• NestJS는 전역 미들웨어(Global Middleware)와 로컬 미들웨어(Local Middleware)를 지원한다. 전역 미들웨어는 모든 요청과 응답에 적용되며, 로컬 미들웨어는 특정 라우터에만 적용된다.

Middleware는 전에 route handler라고 불리던 함수이다. Middleware 함수는 request 그리고 response 객체에 접근한다. 그리고 application의 request-response cycle 에서의 next() middleware 함수에 접근한다. next middleware 함수는 보통 변수명 next로 표기된다.

next() 는 middleware function에서 중요한 역할을 하는 callback 함수이다. 이는 다음 middleware function이나 route handler로 제어를 넘기는 역할을 한다. 구체적으로는 다음과 같은 역할을 한다.

1. 제어 흐름 유지: middleware function은 request와 response 객체에 접근할 수 있는데, next()를 호출하지 않으면 요청은 해당 middleware에서 멈추고, 이후의 middleware 함수나 route handler로 제어가 넘어가지 않는다.
2. middleware chain 형성: 여러 개의 middleware 함수가 존재할 때, next()를 사용하여 순서대로 미들웨어를 실행할 수 있다.
3. 오류 처리: next(err)의 형태로 오류가 발생했음을 알릴 수 있다. 이 경우 프레임워크에서 오류 처리 middleware를 찾아서 실행하게 된다.

Nest middleware은 기본적으로 express middleware와 동등하다. 다음의 설명은 공식적인 'express'의 docs에서 가져온 것으로 middleware의 capability가 담겨있다.

Middleware function은 다음의 task를 수행할 수 있다.
    1. 임의의 code들을 실행할 수 있다.
    2. request, response object들을 변경할 수 있다.
    3. request-response cycle을 끝낼 수 있다.
    4. stack에서 다음 middleware function을 호출할 수 있다.
    5. 현재 middleware function가 request-response cycle을 종료하지 못하면, 
        제어권을 다음 middleware function으로 넘기기 위해 반드시 next()를 호출해야한다.
        그렇지 않으면 request는 처리되지 않은 상태로 남게 된다.

custom Nest middleware는 함수로 구현하거나, @Injectable(). decorator가 있는 클래스로 구현할 수 있다. class의 경우 반드시 NestMiddleware interface를 구현해야 한다. 반면에 함수의 경우 다른 특별한 requirement는 없다. 이제 class method를 사용하여 간단한 middleware을 만들어보자

// 클래스 기반 미들웨어
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  // req: 요청 객체, res: 응답 객체, next: 다음 미들웨어를 호출
  // use method는 요청 정보를 출력하고, 응답 완료 후에는 응답 코드를 출력
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`Request...`);
    // next를 통해 현재 미들웨어의 처리가 완료되었음을 알리고, 다음 미들웨어로 제어를 전달한다.
    // 이를 호출하지 앟으면 요청 처리가 중단된다.
    next();
  }
}

// 함수 기반 미들웨어
import { Request, Response, NextFunction } from 'express';

export function LoggerMiddleware(req: Request, res: Response, next: NextFunction) {
  console.log(`Request...`);
  next();
}

주의사항
'Express'나 'Fastify' 는 middleware를 다르게 처리하고, 또한 다른 method signature를 제공한다. read More

method signature: 메서드의 정의에서 메서드의 이름과 매개변수 리스트의 조합을 의미한다. 이는 오버로딩과  관련이 있다.

Dependency injection

Nest의 middleware는 DI를 지원한다. provider와 controller와 같이, 같은 module안에서 inject dependencies가 가능하다. 유사하게, constructor을 통해 수행된다.

Applying middleware

@Module() decorator안에는 middleware를 위한 공간은 없다. 대신에 module class의 configure() method를 통해 설정할 수 있다.
middleware를 포함하는 Module은 반드시 NestModule interface를 구현해야 한다.

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
// middleware를 설정하기 위해 configure를 호출해야한다. 그러기 위해서는
// NestModule을 implements 해야한다.
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware) 
      .forRoutes('cats'); // cats 경로에 적용한다.
  }
}

위에서는 /cats route handler 를 위한 LoggerMiddleware를 설정했다. 또한 middleware를 특정 request method에 제한 할 수 있는데, 이를 위해 middleware를 구성할 때 route path와 request method가 포함된 객체를 forRoutes() method에 전달하여 middleware를 구성할 수 있다. 아래의 코드에서 우리는 request method type을 참고하기 위해 RequestMethod enum을 import 하고 있다.

import { Module, NestModule, RequestMethod, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes({ path: 'cats', method: RequestMethod.GET });
  }
}

<팁!>
configure() method는 async/await를 사용하여 asynchronous 하게 만들어졌다. configure() method는 NestJs 어플리케이션을 설정하는 데 사용되며, 이 method 안에서 비동기 작업을 수행할 수 있다. 예를 들어 db 연결 설정, 환경 변수 로드 등과 같은 작업을 configure() method 내부에서 비동기적으로 수행할 수 있다.

<주의사항>
express adapter를 사용할 때, NestJS app은 기본적으로 package body-parser를 통해 json과 urlencoded을 등록할 것이다. 그렇기에 만일 MiddlewareConsumer를 통해 middleware를 customize를 한다면, NestFactory.create() 로 application을 만들 때 global middleware를 bodyParser flag를 false로 함으로써 꺼야 한다.

Route wildcard

route base의 Pattern들 또한 지원된다. 예를 들어 wildcard로써 asterisk(*)가 사용되고 또 어떤 문자의 조합과 매칭된다.

forRoutes({ path: 'ab*cd', method: RequestMethod.ALL });

'ab*cd' route path는 'abcd', 'ab_cd', 'abecd' 과 매칭될 것이다. 이 밖에 ?, +, *, () 또한 route path에 사용된다. 그리고 이들은 regular expression의 짝이다. 단순히 hyphen(-), dot(.)은 문자로 해석된다.

<주의사항!>
fastify package는 path-to-regexp package의 최신버전을 사용한다. 이는 더 이상 asterisk(*)를 지원하지 않는다. 대신,반드시 parameters를 사용해야 한다.(e.g. '(.*)', :splat*))

Middleware consumer

MiddlewareConsumer은 helper class이다. 이는 middleware를 관리하기 위한 내장 method를 제공한다. 모든 method는 fluent style 로 chained 된다. forRoutes() method는 single string, multiple stirngs, a RouteInfo object, a controller class, 심지어 multiple controller classes를 값으로 받을 수 있다. 보통은 comma(,)로 구분된 controller의 리스트를 전달한다.

//fluent style: 각 메서드 호출이 자신을 반환하여 다음 메서드를 바로 호출할 수 있게하는 코드 기법

consumer
  .apply(LoggerMiddleware)
  .forRoutes('cats')
  .apply(AnotherMiddleware)
  .forRoutes('dogs');

아래의 코드는 CatsController의 모든 route handler에 대해 middleware인 LoggerMiddleware를 적용한다는 의미이다.

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';
import { CatsController } from './cats/cats.controller';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes(CatsController);// CatsController에 들어있는 route handler에 적용
  }
}

apply() method는 single middleware를 받거나, 여러 개의 argument를 받을 것이다. [middleware](https://docs.nestjs.com/middleware#multiple-middleware)

Excluding routes

때때로 middleware의 적용에서 특정한 route를 제외(exclude) 할 수 있다. exclude() method를 통해 쉽게 route를 제외할 수 있다. 이 method는 single string, multiple strings, 또는 route를 나타내는 Route Info object 를 인자로 받아 route를 제외한다.

consumer
  .apply(LoggerMiddleware)
  .exclude(
    { path: 'cats', method: RequestMethod.GET },
    { path: 'cats', method: RequestMethod.POST },
    'cats/(.*)',
  )
  .forRoutes(CatsController);

<팁!>
exclude() method는 path-to-regexp package를 이용한 wildcard parameter를 지원한다.

위의 예에서, LoggerMiddleware는 CatsController 내부에 정의된 모든 route들을 둘러싼다. excpet에 적혀있는 것을 빼고.

Functional middleware

앞의 LoggerMiddleware class는 단순한 기능만 넣었다. member, method, dependency 다 없다. 그렇다면 class 대신에 간단한 function으로 작성할 수 있는데 이러한 middleware type을 functional middleware라고 한다. class 기반의 logger middleware를 functional middleware로 다꾸면 다음과 같다.

import { Request, Response, NextFunction } from 'express';

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`Request...`);
  next();
};

AppModule에서 다음과 같이 사용한다.

consumer
  .apply(logger)
  .forRoutes(CatsController);

<팁!> 만일 별다른 dependency가 없다면 functional middleware를 사용를 고려해보라.

Multiple middleware

언급한 대로, 여러 개의 middleware를 묶기위해서는 단순히 comma로 구분한 list를 apply() method에 넣어라.

consumer.apply(cors(), helmet(), logger).forRoutes(CatsController);

Global middleware

만일 한 번에 구분된 모든 route에 middleware를 적용하고 싶다면, use() method를 사용하면 된다. 이는 INestApplication instance에 의해 지원된다.

const app = await NestFactory.create(AppModule);
app.use(logger);
await app.listen(3000);

global middleware에서 DI(Dependency Injection) 컨테이너에 접근하는 것이 불가능하다. 대신, app.use()를 사용할 때는 함수형 미들웨어를 사용할 수 있다. 또 다른 방법으로는 class 미들웨어를 사용하고, AppModule 내에서 .forRoutes('*')를 사용하여 모든 경로에 적용할 수 있다.

Modules

Module은 @Module() 의 주석이 달린 class이다. @Module() 은 Nest에게 application의 구조를 조직하는데 필요한 metadata를 제공한다.

@Module() : NestJS 어플리케이션의 구조를 정의하는 데 사용된다. 모듈은 특정 기능을 캡슐화하여 애플리케이션을 더 구조적으로 만들고, 유지 보수성을 높여준다. 

각 application은 적어도 한 개의 모듈, 즉 root module을 가진다.
root module은 application graph(Nest가 module을 resolve하고 또 provider간의 관계와 의존성을 해결하기 위해 사용하는 internal data structure)를 build 하기위한 Nest의 시작점이다. 이론적으로 매우 작은 application들은 단지 하나의 root module만을 가지지만, 일반적인 경우는 아니다. module은 component를 조직하는 효과적인 방법으로 강력히 권장된다. 즉, 대부분의 application에서 최종 아키텍처는 여러 모듈을 사용하여 구성된다. 각 모듈은 밀접하게 관련된 기능 집합을 캡슐화한다.

@Module() decorator은 한 개의 object를 가지고, object의 속성들은 module을 설명해준다.

module은 provider들을 기본적으로 캡슐화한다. NestJs의 모듈 시스템에서는 provider가 module 내에서 선언되고, 다른 module에서 사용하려면 export되어야 한다. 이는 module 간의 의존성을 명확하게 관리하고, 의도하지 않은 의존성 주입을 방지한다.

Feature modules

CatsController와 CatsService는 같은 application domain에 속한다. 둘은 긴밀히 관련되어 있기에, 이를 하나의 기능 모듈(feature module)로 이동하는 것이 합리적이다. feature module은 관련된 기능을 가진 code들을 묶고, 유지하고 명확한 경계를 세워준다. 이러한 방식은 복잡함을 해소하고 SOLID원칙을 고수하게 해준다. 특히 application이 커지고, team이 성장할때 더 중요해진다.

아래는 CatsModule이다.

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

@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class CatsModule {}

<팁!>
$ nest g module cats를 통해 간단히 만들 수 있다.

위에서 간단히 **cats.module.ts**안에서 **CatsModule**을 만들 수 있다. 그리고 관련된 파일들을 **cats** 디렉터리로 옮긴다. 마지막으로 해야할 것은 이 module을 root module에서 import 해온다.

import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule {}

src
    cats
        dto
            create-cat.dto.ts
        interfaces
            cat.interface.ts
        cats.controller.ts
        cats.module.ts
        cats.service.ts
    app.module.ts
    main.ts

Shared modules

NestJS에서 모듈은 기본적으로 SingleTon이다. 즉, 어플리케이션 내에서 모듈이 한 번만 인스턴스화되며, 이로 인해 여러 모듈 간에 동일한 provider instance를 쉽게 공유할 수 있다.

모든 module은 자동적으로 shared module이다. 한번 만들어두면 다른 module에서 재 사용 가능하다. 만일 CatsService의 instance를 다른 module 사이에서 공유하고 싶다고하자. 이를 위해서는 CatsService provider를 export에 추가해야 한다.

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

@Module({
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService]
})
export class CatsModule {}

이를 통해 다른 module에서 CatsModule를 import해서 CatsService에 접근 할 수 있다. 그리고 같은 instance를 다른 모든 module에서 import해서 사용할 수 있다.

Module re-exporting

NestJS에서는 내부 provider를 export할 수 있다. 또한 한 module 내에서 import한 것을 다시 export할 수 있다. 아래의 예시처럼 CommonModule은 CoreModule에서 import과 export를 둘 다 하고 있다. 이를 통해 모듈 간의 의존성을 보다 효과적으로 관리하고, 재사용성을 높일 수 있다.

@Module({
  imports: [CommonModule],
  exports: [CommonModule],
})
export class CoreModule {}

Dependency injection

module class는 provider를 inject할 수 있다. (e.g. 주로 설정 또는 초기화 작업을 위해 사용된다. )

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

@Module({
  controllers: [CatsController],
  providers: [CatsService],
})
export class CatsModule {
  constructor(private catsService: CatsService) {}
}

하지만 module class 그 자체는 provider로써 injected 될 수 없다. 왜냐하면 Circular dependency가 발생하기 때문이다.
https://docs.nestjs.com/fundamentals/circular-dependency

Global modules

만일 모든 곳에서 같은 module의 집합을 import해야한다면, 이는 꽤 tedius한 작업일 것 이다. Nest와는 달리 Angular providers는 global scope로 등록된다. 한번 정의되면, 어디에서든지 사용할 수 있다. 하지만 Nest는 provider들을 module 내부에서 캡슐화 한다. 그래서 캡슐화된 module을 import해야 사용할 수 있다.

만일 NestJS에서 어플리케이션 전체에서 기본적으로 사용할 수 있는 provider 세트를 제공하려면, module을 global module로 설정하면 된다. 이를 위해 @Global() 데코레이터를 사용한다. 글로벌 모듈로 설정된 모듈은 어플리케이션의 모든 모듈에서 자동으로 사용 가능하다.

import { Module, Global } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Global()
@Module({
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService],
})
export class CatsModule {}

@Global() decorator은 module을 global-scope로 만들어준다. Global module은 일반적으로 root module이나 core module에서 한 번만 등록해야 한다. 위의 경우 CatsService provider는 어디에서든지 사용할 수 있다. 만일 이를 사용하고 싶은 module이 있다면 굳이 CatsModule을 import 할 필요가 없다.

<팁!>
global module은 boilerplate를 줄이는데 유용지만, 모든것을 global하게 만드는 것은 좋은 설계가 아니다. 일반적으로 module의 API를 소비자에게 제공하는 가장 권장되는 방법은 imports 배열을 통해 명시적으로 module을 import 하는 것이다.

Dynamic modules

Nest module system은 dynamic module이라는 기능을 제공한다. 이는 동적으로 module을 customize할 수 있다. 동적 module은 provider를 동적으로 등록하고 구성할 수 있는 customizable module을 쉽게 생성할 수 있게 해준다.
https://docs.nestjs.com/fundamentals/dynamic-modules

다음은 DatabaseModule을 위한 dynamic module 정의이다.

import { Module, DynamicModule } from '@nestjs/common';
import { createDatabaseProviders } from './database.providers';
import { Connection } from './connection.provider';

// forRoot: 이 정적 메서드는 동적 모듈을 반환한다. 기본적으로 entity와 opton을 받아 DB 제공자를 생성한다.
// createDatabaseProviders 함수를 호출하여 DB 제공자들을 생성하고, 이를 proividers와 exports 배열에 추가한다.

@Module({
  providers: [Connection],
  exports: [Connection],
})
export class DatabaseModule {
  static forRoot(entities = [], options?): DynamicModule {
    const providers = createDatabaseProviders(options, entities);
    return {
      module: DatabaseModule,
      providers: providers,
      exports: providers,
    };
  }
}

<팁!>
forRoot() method은 동기 혹은 비동기적인 dynamic module을 반환한다.(i.e. promise)

이 module은 기본적으로 connection provider를 정의한다. 허나 추가적으로 (forRoot() method에 전달되는 entity나 option들에 의존하여) providers, repository들 따위를 드러내준다. dynamic module이 반환하는 속성들은 @Module() 데코레이터에 정의된 metadata를 덮어쓰기 않고 확장한다. 이것이 정적으로 선언된 connection provider와 dynamic하게 생성된 repository providers들이 이 모듈에서 export되는 방법이다.

만일 dynamic module을 global scope에서 등록하고자 한다면, globla 속성을 true로 설정한다.

{
  global: true,
  module: DatabaseModule,
  providers: providers,
  exports: providers,
}

DatabaseModule은 다음과 같은 방식으로 imported 될 수 있고 configured 될 수 있다.

import { Module } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';
import { User } from './users/entities/user.entity';

@Module({
  imports: [DatabaseModule.forRoot([User])],
})
export class AppModule {}

만일 DatabaseModule을 export하고자 한다면 다음과 같이 forRoot()를 생략한다.

import { Module } from '@nestjs/common';
import { DatabaseModule } from './database/database.module';
import { User } from './users/entities/user.entity';

@Module({
  imports: [DatabaseModule.forRoot([User])],
  exports: [DatabaseModule],
})
export class AppModule {}

Dynamic Module에서 더 자세히 다룰 것이다. working example 과 함께.

Provider

Provider는 Nest의 가장 근본적인 개념이다. 많은 basic한 Nest class들은 provider(service, repository, factory, helper...)로 다루어진다. Provider의 주된 개념은 dependency로서 Provider 주입(injected) 되는 것이다. NestJs에서 객체들은 다양한 관계를 형성할 수 있으며, 이러한 객체들을 "연결(wiring up)"하는 기능은 대부분 Nest 런타임 시스템에 위임될 수 있다.

provider: NestJS에서 Provider는 주입 가능한 서비스, 클래스, 값 또는 기타 의존성으로, 의존성 주입 시스템의 핵심 요소이다. 
제공자는 주로 서비스의 형태로 사용되며, 다양한 구성 요소 간에 재사용 가능한 로직을 캡슐화 한다.

Controller들은 HTTP request들을 다루고, 또 providers에게 복잡한 일들을 위임한다. Providers는 일반적인 JS class이다. 이는 module안에서 provider로서 선언된다.

NestJS는 객체 지향적으로 설계 및 의존성을 조작할 수 있는 기능을 제공하므로, SOLID 원칙을 따르는 것을 권장한다.

Services

Service는 보통 data의 storage, retrieval에 책임이 있다. 그리고 이는 Controller에 의해 사용된다.

import { Injectable } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';

@Injectable()
export class CatsService {
  private readonly cats: Cat[] = [];

  create(cat: Cat) {
    this.cats.push(cat);
  }

  findAll(): Cat[] {
    return this.cats;
  }
}

CLI의 $ nest g service cats command을 통해 쉽게 만들 수 있다.

CatService는 간단한 class, 하나의 property와 두 개의 method이다. 그리고 @Injectable() decorator을 사용한다. 이는 NestJS의 종속성 주입 시스템에서 클래스를 관리할 수 있게 해주는 메타데이터를 클래스에 부착한다.

@Injectable(): 이는 NestJs에서 Provider를 정의할 때 사용된다. 이 decorator는 class가 의존성 주입 시스템에 의해 관리될 수 있도록 지정한다.
    @Injectable() 데코레이터가 있는 클래스는 다른 클래스에 주입될 수 있으며, NestJs가 이를 관리하여 필요한 곳에 자동으로 주입한다.(IoC)

일단은, Cat interface를 사용하기에 아래와 같이 작성한다.

export interface Cat {
  name: string;
  age: number;
  breed: string;
}

이후 작성한 CatsService를 CatController에 가져온다.

import { Controller, Get, Post, Body } from '@nestjs/common';
import { CreateCatDto } from './dto/create-cat.dto';
import { CatsService } from './cats.service';
import { Cat } from './interfaces/cat.interface';

@Controller('cats')
export class CatsController {
  constructor(private catsService: CatsService) {}

  @Post()
  async create(@Body() createCatDto: CreateCatDto) {
    this.catsService.create(createCatDto);
  }

  @Get()
  async findAll(): Promise<Cat[]> {
    return this.catsService.findAll();
  }
}

CatsService는 class constructor에 의해 injected 되었다. 여기서 private 문법을 사용하였다. 이 shorthand는 catsService의 선언과 초기화를 동시에 해준다.

IoC(Inversion of Control)

Don't call us. We'll call you - Hollywood Principle

프레임워크를 적용하지 않은 경우를 생각해보자.
객체의 생명 주기 즉, 객체의 생성, 초기화, 소멸, 메서드 호출 등등을 클라이언트 구현 객체가 직접 관리한다. 또한 다른 사람이 작성한 외부 코드(라이브러리)를 호출하더라도 해당 코드의 호출 시험 역시 직접 사람이 관리한다.

하지만 NestJs와 같은 프레임워크를 사용할 때는 Controller, Service 같은 객체들의 동작을 직접 구현하기는 하지만, 해당 객체들이 어느 시점에서 호출될 지는 신경쓰지 않는다. 프레임워크가 요구하는대로 객체를 생성하면, 프레임워크가 해당 객체들을 가져다가 생성하고, 메서드를 호출하고 소멸시킨다. 즉 프로그램의 제어권이 역전된 것이다.

라이브러리를 사용하는 어플리케이션은 제어 흐름을 라이브러리에 내주지 않는다. 단지 필요한 시점에 라이브러리에 작성된 객체를 적재적소에 가져다 쓸 뿐이다. 하지만 프레임워크를 사용한 어플리케이션의 경우, 어플리케이션 코드에 작성한 객체들을 프레임워크가 필요한 시점에 가져다가 프로그램을 구동하기에 프로그램의 제어권이 프레임워크로 역전된다.

즉 IoC란, 메소드나 객체의 호출작업을 개발자가 결정하는 것이 아니라, 외부의 프레임워크나 라이브러리가 제어 흐름을 결정되는 것을 의미한다. 객체의 의존성을 역전시켜 객체 간의 결합도를 줄이고 유연한 코드를 작성할 수 있게 하여 가독성 및 코드 중복, 유집 보수를 편하게 할 수 있게 한다.

기존에는 다음과 순서로 객체가 만들어지고 실행되었다.

1. 객체 생성
2. 의존성 객체 생성: 클래스 내부에서 생성
3. 의존성 객체 메소드 호출

하지만 Spring, Nest에서는 다음과 같은 순서로 객체가 만들어지고 실행된다.

1. 객체 생성
2. 의존성 객체 주입: 스스로 만드는 것이 아니라 제어권을 프레임워크에게 위임하여 프레임워크가 만들어놓은 객체를 주입한다
3. 의존성 객체 메소드 호출

Nest가 모든 의존성 객체를 Nest가 실행될 때 다 만들어주고 필요한 곳에 주입시켜준다.

class B{
    //
}


class A{
  // 클래스 A가 클래스 B를 사용하기에 A는 B에 의존적
  // 그렇기에 B가 변하면 A도 변해야하는, 즉 영향을 미치는 관계 A -> Bf
    new b = new B()
}

이번에는 NestJs에서의 IoC를 살펴보자

import {Controller, Get} from '@nestjs/common'
import {AppService} from './app.service'

export class AppController{
    // 1. 사용하고 싶은 서비스 타입 객체를 미리 선언한다.
      private appService: AppService
      //  2. 생성자에서 실제로 사용할 서비스 객체를 직접 생성(binding)한다. 
    constructor(){
        this.appService = new AppService();
    }
  ...
}

위의 코드에서는 개발자가 사용하고 싶은 객체가 있으면 이것을 개발자가 생성부터 소멸까지 직접 관리해야 했다.
이렇게 하면 AppService가 변경이 되었을 때 개발자도 그에 맞춰 코드를 수정해야 한다.
IoC를 활용하면 객체의 생명주기 관리 자체를 외부에 위임한다.(이번의 경우 Nest.js IoC 컨테이너에 위임)

IoC는 모듈 간 결합도를 낮추기에 하나의 모듈이 변경되어도 다른 모듈들에는 영향을 최소화되어 웹 어플리케이션을 지속 가능하고 확장성 있게 해준다.

• 라이브러리
  • 제어권이 나에게 있다.
  • 내 코드가 필요할 때마다 내가 사용하고 싶은 라이브러리를 사용한다.
• 프레임워크
  • 제어권이 프레임워크에 있다.
  • 나의 코드를 프레임워크가 필요로 하는 경우에 프레임워크가 알아서 실행시킨다.

DI는 이러한 IoC를 수행하는 하나의 방법이며 Nest.js에서는 생성자를 통한 DI를 가장 기본적인 IoC테크닉으로 생각하고 있다.

    constructor(private readonly appService: AppService){} 

추가적으로 SOLID 원칙의 DIP(의존 역전 원칙) 를 같이 보면 확실히 더 이해가 될 것이다.

DI(Dependency injection)

Nest는 Dependency Injection으로 알려진 design pattern을 사용한다. Argular doumentation 참고

NestJS에서는 Typescript의 기능 덕분에 의존성을 매우 쉽게 관리할 수 있다. 의존성은 타입에 의해 자동으로 해결된다. 아래의 예제에서는 NestJS가 CatService의 인스턴스를 생성하여 catsService로 주입한다. 만약 이미 다른 곳에서 요청된 적이 있다면 기존의 싱글톤 인스턴스를 반환한다. 이러한 의존성은 컨트롤러의 생성자에 전달되거나 지정된 속성에 할당된다.

constructor(private catsService: CatsService) {}

Scopes

Provider은 application의 lifecycle과 동기화 되어있는 수명을 가진다. 이는 application이 bootstrap되었을 때, 모든 dependency가 해결되고, 즉 모든 provider는 인스턴스화 된다. 유사하게 만일 application이 shut down 될 때, 각 provider는 파괴된다. 하지만 provider의 lifetime을 요청 단위(request-scoped) 로 만들 수 있다.
https://docs.nestjs.com/fundamentals/injection-scopes

bootstrap: 어플리케이션을 시작하고 초기화하는 과정을 의미한다. 어플리케이션이 부트스트립되면, 모든 의존성이 해결되고 모든 제공자가 인스턴스화되어야 한다.
provider: NestJs의 어플리케이션에서 의존성을 주입할 수 있는 기본 구성 요소이다. 
    service, repository, factory, helper 등과 같은 클래스들이 provider로 사용된다.
singleton:  클래스의 인스턴스가 어플리케이션 전체에서 하나만 존재하도록 보장하는 디자인 패턴

Custom Providers

Nest는 Provider들의 관계를 정리해주는 IoC container를 가진다. 이 특징은 dependency injection feature의 근간이 된다. 하지만 지금까지 서술했던 것 보다 더 중요한게 있다. provider를 정의하는 몇 가지 방법이 있다. 기본적으로 클래스, 값, 또는 asynchronous 및 synchronous factories를 사용할 수 있다.
https://docs.nestjs.com/fundamentals/dependency-injection

Optional providers

때때로, 반드시 해결되지 않아도 되는 dependency가 있을 수 있다. 예를 들어, 클래스가 configuration object에 의존하지만, configuration object가 제공되지 않으면 기본 값을 사용해야 하는 경우가 있다. 이런 경우에, dependency가 optional 될 수 있다.
왜냐하면 configuration provider의 lack은 error로 취급되지 않기 때문이다.

provider가 optional임을 나타내기 위해, @Optional() decorator를 사용할 수 있다.

import { Injectable, Optional } from '@nestjs/common';

@Injectable()
export class SomeService {
  constructor(@Optional() private readonly configService?: ConfigService) {}

  getConfig() {
    if (this.configService) {
      return this.configService.getConfig();
    }
    return 'default config';
  }
}

//예2
import { Injectable, Optional, Inject } from '@nestjs/common';

@Injectable()
export class HttpService<T> {
  constructor(
    @Optional()
    @Inject('HTTP_OPTIONS') 
    private httpClient: T) {}
}

위의 코드(예2)에서는 HTTP_OPTIONS custom Token을 포함하기에 custom provider를 사용한다. 이전 예제들은 클래스의 생성자에서 constructor-base injection을 통해 dependency를 나타냈다.
https://docs.nestjs.com/fundamentals/custom-providers

custom provider: 기본 제공 provider 외에 개발자가 직접 정의한 provider
token: provider를 식별하는 데 사용되는 고유한 값이다. 문자열, simbol, class를 토큰으로 사용할 수 있다.

Property-based injection

지금까지는 constructor-based의 기술이였다. class의 constructor method를 통해 provider들이 주입되는 거였다. 이번에 서술할 property-based injection도 유용할 것이다. 예를 들어, top-level의 class가 하나의 혹은 여러개의 provider에 의존한다면,
sub-class들의 constructor의 super() 를 사용할 것인데 이는 매우 tedious하다. 대신에 @Inject() decorator를 사용할 수 있다.

import { Injectable, Inject } from '@nestjs/common';

@Injectable()
export class HttpService<T> {
  @Inject('HTTP_OPTIONS')
  private readonly httpClient: T;
}

주의사항
만일 class가 다른 class를 extend 하지 않는다면, constructor-based injection을 사용해야 한다. constructor는 명백하게 무슨 dependency들이 필요한지 나타내고, @Inject() 로 나타내는 것보다 더 나은 가시성을 제공한다.

Provider registration

provider CatsService, 그리고 이러한 service를 사용하는 CatsController를 가지고 있다. 그리고 이들을 injection을 위해 Nest에 등록해야한다. 이들 module file인 app.module.ts 통해 추가해야한다. 이들을 providers의 array를 @Module() decorator에 추가한다.

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

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

Nest는 이제 CatsController class의 의존성을 해결할 것이다.

현재 파일 구조는 다음과 같다.

src
    cats
            dto
                create-cat.dto.ts
            interface
                cat.interface.ts
            cats.controller.ts
            cats.service.ts
    app.module.ts
    main.ts

Manual Instantiation

지금까지, 어떻게 Nest에서 자동적으로 dependency들을 처리하는지를 다뤄왔다. 특정 상황에서는 built-in Dependency Injection system(어플리케이션의 클래스 간 의존성을 자동으로 관리하고 주입하는 메커니즘, IoC 컨테이너)에서 벗어나 수동으로 provider를 검색하거나 인스턴스화해야 할 수도 있다. 아래는 두 가지 주제를 간단히 설명한다.

기존의 instance, instance화가 된 provider를 얻기 위해서는 Module Reference를 사용할수 있다.(ModuleRef)
https://docs.nestjs.com/fundamentals/module-ref

import { ModuleRef } from '@nestjs/core';

@Injectable()
export class MyService {
  constructor(private readonly moduleRef: ModuleRef) {}

  async getDynamicProvider() {
    const provider = await this.moduleRef.create(SomeProvider);
    return provider;
  }
}

bootstrap() 함수에서 providers를 얻기 위해서는 Standalone application을 살펴 봐야한다.
https://docs.nestjs.com/standalone-applications

Controllers

Controllers는 들어오는(incoming) requests와 clinent로 나가는(returning) responses에 대한 책임을 가지고 있다.

Controller는 application에 대한 특정한 requests를 받는다. **routing** 메커니즘은 어떤 controller가 어떤 request를 받는지를 제어한다. 각 controller는 1개 이상의 route를 가진다. 그리고 route 마다 다양한 action들을 취한다.

routing: 클라이언트의 요청 URL을 기반으로 요청을 적절한 컨트롤러와 핸들러 함수에 매핑하는 과정이다.

basic한 controller를 만들기 위해, Class들과, Decorator들을 사용한다. Decorator들은 클래스에 필요한 metadata를 연관시키고, Nest가 routing map을 생성하여 요청을 해당 컨트롤러와 연결할 수 있게 해준다.

metaData: 
    데이터에 대한 정보를 설명하는 데이터. 여기서는 데코레이터를 통해 클래스나 메서드에 추가되는 정보를 의미한다.
routing map:
    클라이언트의 요청 URL을 특정 컨트롤러 메서드에 매핑하는 구조이다.

<팁!>
유효성 검사가 내장된 CRUD 컨트롤러를 빠르게 생성하려면, CLI의 CRUD 생성기를 사용할 수 있다. nest g resource [name]

Routing

아래의 코드는 @Controller() decorator를 사용한다. 이는 가장 기본적인 controller이다. 여기서 route path로 cats인 prefix를 설정한다. @Cotroller() decorator에 path prefix를 기입함으로써 간단히 관련된 routes를 group화 할 수 있다. 그리고 반복되는 코드를 최소화 할 수 있다. 예를 들어, 우리는 cat entity와 관련된 /cats route group들을 선택할 수 있다. 이 경우, @Controller() 데코레이터에 'cats' 경로 접두사를 지정하면 파일 내의 각 경로에 대해 경로 부분을 반복해서 작성할 필요가 없다.

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

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

<팁!>
CLI를 사용하여 controller를 만들고자 한다면, 간단히 $ nest g controller [name] 커멘드를 사용하면 된다.

findAll()에 붙어있는 @Get() HTTP request method decorator는 Nest에게 HTTP requests의 endpoint에 대한 handler를 만들어라고 명령한다. endpoint는 HTTP request method(위의 경우는 GET)와 route path에 대응된다.

이 때 routh path는 컨트롤러에 선언된 (선택적) prefix와 method의 decorator에 지정된 경로를 연결하여 결정된다. 예를 들어 @Controller에 'cats' 그리고 @Get(':id')라면 전체 path는 '/cats/:id'가 된다. 만일 prefix에 'cats'를 선언한다면, 더 이상 decoraotor에 어떤 path 정보를 기입할 필요가없다. Nest가 자동으로 map 'GET /cat' request를 handler에 mapping 할 것이다. 앞서 언급한 대로, path는 controller의 정보(prefix)와 requests method decorator의 정보를 포함한다. 그렇기에 'cats'와 prefix와 @Get('breed')가 존재한다면 route의 path는 'GET /cats/breed'가 된다.

위의 코드에서 만일 이 endpoint에서 만들어진 GET request가 호출된다면, Nest는 개발자가 만든 findAll() method로 route할 것이다. 이때 findAll()과 같은 method 이름은 개발자가 임의로 지정할 수 있다. path를 binding하기 위해 method를 선언해야 하지만, Nest는 method의 이름에 아무런 의미를 부여하지 않는다.

이 method는 정상 작동을 한다면 200의 status code와 관련된 response를 반환할 것이다.(위의 경우 단순한 string) 이를 이해하려면 Nest가 응답을 조작하는 두 가지 다른 옵션을 알아야 한다.

Method handler signature: 메서드의 매개변수와 반환 '타입'을 포함한 정의
native response handling method: Express나 Fastify와 같은 HTTP 서버 라이브러리가 제공하는 응답 처리 메서드로
    상태 코드 설정, 헤더 설정, 응답 본문 전송 등을 수행한다.
    e.g. 
    1. response.status(code): HTTP 응답 상태 코드를 설정
    2. response.send(body): 응답 본문을 전송한다.
    3. response.json(json): JSON 형식의 응답 본문을 전송한다.
    4. response.set(header, value): 응답 헤더를 설정한다.

// 상태코드의 변경
import { Controller, Get, HttpCode } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Get()
  @HttpCode(204)
  findAll() {
    return 'No Content';
  }
}

// Express를 기반의 @Res() 활용
import { Controller, Get, Res } from '@nestjs/common';
import { Response } from 'express';

@Controller('cats')
export class CatsController {
  @Get()
  findAll(@Res() response: Response) {
    const cats = ['cat1', 'cat2', 'cat3'];
    response.status(200).json(cats); // 상태코드 조작 가능
  }
}

주의할점
Nest는 @Res()나 @Next()의 사용을 감지한다. 이는 개발자가 library-specific option을 사용함을 나타낸다. 허나 만일 Standard approach와 동시에 사용한다면 Standard approach 접근 방식이 자동으로 비활성화되어 정상적으로 동작하지 않는다.
만일 두 가지 접근 방식을 동시에 사용하려면(e.g. cookie/header를 설정하기 위해 response 객체에 주입을 하되 나머지는 프레임워크에 맡기기 위해, 즉 응답 객체를 직접 조작하면서 나머지 응답 처리는 프레임워크에 맡기려면), @Res({passthough:true}) 데코레이터에서 'passthrough' 옵션을 'true'로 설정해줘야 한다.

Request object

Handler는 client의 request에 접근할 필요가 있다. Nest는 request object에 접근을 가능케한다. @Req() decorator를 주입함으로써 request object에 조작할 수 있다.

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';
  }
}

express의 타입 지정을 위해 (위의 예에서는 request:Request), @types/express package를 설치하면 된다.

request object는 HTTP request를 나타낸다. 그리고 request query string, parameters, HTTP headers, body 등을 가진다. 대부분의 경우에 이러한 속성을 수동으로 가져올 필요는 없다. 대신 @Body(), @Query()와 같은 전용 decorator를 통해 접근할 수 있다.

NestJS는 하위 HTTP 플랫폼(e.g. Express와 Fastify) 간의 타입 호환성을 위해, Nest는 @Res(), @Response() decorator를 제공한다. @Res()는 @Response()의 별칭이다. 둘 다 하위 native platform의 응답 객체 interface를 직접 노출한다. 만일 이 둘을 사용하면, 개발자는 하위 라이브러리(e.g. @types/express)에서 타입을 import 해야한다. 기억해야 할 것이 @Res()나 @Response()을 method handler에 주입한다는 것은, Nest가 response를 Library-specify mode로 처리함을 뜻한다. 곧, 개발자가 response의 관리에 책임이 있다는 것이다. 그렇기에 개발자는 반드시 response object를 사용하여 어떤 형태로든 응답을 반환해야 한다.(e.g. res.json(...), res.send(...)). 그렇지 않으면 HTTP 서버가 응답을 기다리며 멈추게 된다.

native platform: NestJS와 같은 프레임워크가 작동하는 기본 HTTP 서버 라이브러리를 의미한다. NestJS는 Express와 Fastify와 같은 HTTP 서버 라이브러리 위에서 동작할 수 있다. 이러한 라이브러리를 "native platform"이라고 부르며. 각각의 platform은 고유의 요청 및 응답 객체와 메서드를 제공한다.

method: 클래스 내에 정의된 함수, 객체 지향 프로그래밍에서 객체의 동작을 정의
method handler: 특정 HTTP 요청을 처리하는 함수, 주로 컨트롤러 클래스 내에서 정의된다.

Resources

앞에서 GET route, resoucres를 가져오는 endpoint를 정의내렸다. 이번에는 POST route, 새 record를 만드는 endpoint를 만들 것이다.

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

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

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

Nest는 standard한 HTTP method을 위한 decorator들을 제공한다.
Get, Post, Put, Delete, Patch, Options, Head 그리고 All, 이것은 모든 것들 다루는 endpoint이다.

Route wildcards

Pattern을 기반으로한 route도 지원한다. 예를 들어 *(asterisk)는 와일드 카드로 사용되며, 임의의 문자 조합과 일치한다.

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

@Controller('files')
export class FilesController {
  @Get('download/*')
  downloadFile() {
    return 'This action handles downloading files';
  }

  @Get('images/*')
  serveImage() {
    return 'This action serves images';
  }
}

이 밖에 ?, +, * 그리고 () 또한 route path에 쓰인다. 이는 정규 표현식(regular expression)과 유사하다. 하이픈(-), 점(.)은 문자열 기반 경로에서 문자 그대로 해석된다.

주의사항
route의 중간에서의 wildcard는 express에 의해서만 지원된다.

Status code

앞서 언급한 대로 201번인 POST를 제외한 나머지의 상태코드는 200이다. 이는 @HttpCode(...) 를 통해 handler level에서 조작할 수 있다. @nestjs/common package에서 import한다.

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

만일 상태 코드가 static하지 않고 다양한 요소에 의존한다면, library-specific response object(inject using @Res())를 사용하면 된다.

Headers

custom response header을 사용하기 위해서는 @Header() decorator이나, library-specific response object를 사용한다.( res.header() 을 통해 직접적으로) Header는 @nestjs/common package를 통해 import한다.

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

Redirection

redirection은 클라이언트가 요청한 URL을 다른 URL로 자동으로 전환시키는 웹 기술이다. 웹 서버 또는 어플리케이션은 클라이언트에게 HTTP 응답으로 특정 상태 코드와 새로운 URL을 보내어 클라이언트가 해당 URL로 이동하도록 유도한다.

response를 다른 URL로 redirection하기 위해서는, @Redirect() decorator를 사용하거나 library-specific response object의 res.redirect() 를 사용한다.
@Redirect() 는 두 가지 argument를 필요로 한다. url과 statusCode이다.(둘 다 optional) status의 default value는 302이다.

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

만일 개발자가 HTTP 상태 코드와 redirect URL을 동적으로 하고 싶다면, HttpRedirectResponse interface(@nest/common)을 사용한다.

method handler의 반환값이 존재한다면 @Redirect()의 값을 덮는다.

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

@Controller('example')
export class ExampleController {

  // 기본적으로 'https://default-url.com'로 302 상태 코드로 리다이렉트
  @Get('default-redirect')
  @Redirect('https://default-url.com', 302)
  defaultRedirect() {
    // 이 메서드가 반환하는 값이 없으므로, 데코레이터의 URL과 상태 코드가 사용됨
  }

  // 리다이렉션 URL과 상태 코드를 동적으로 변경
  @Get('dynamic-redirect')
  @Redirect('https://default-url.com', 302)
  dynamicRedirect() {
    return { url: 'https://dynamic-url.com', statusCode: 301 };
    // 반환 값이 있으면, 이 값이 데코레이터 인수를 덮어씀
  }
}

Route parameters

static path로 인한 Route는 만일 개발자가 request의 부분으로서 dynamic data를 받기에 부적절하다.
예를 들어 GET /cats/1에서의 id값 1이 있다. NestJs에서는 경로에 동적 매개변수 토큰을 추가하여 요청 URL의 해당 위치에서 동적 값을 얻을 수 있다. 이러한 경로 매개변수는 콜론(':')을 사용하여 정의 된다.
아래의 @Get()에 있는 route parameter token의 사용 예시이다. route parameter는 @Param() 을 통하여 접근할 수 있다. param()은 method signature을 통해 추가 된다.

method signature: 메서드의 이름, 매개변수 리스트, 반환 타입을 포함한 메서드의 정의를 나타낸다.

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


//TS-타입 지정
@Get(':id')
findOne(@Param() params: {id:string}): string {
  console.log(params.id);
  return `This action returns a #${params.id} cat`;
}

@Get(':id')
@Bind(Param())
findOne(params) {
  console.log(params.id);
  return `This action returns a #${params.id} cat`;
}
//Bind() 데코레이터는 여러 매개변수 데코레이터를 결합하여 하나의 매개변수 객체로 전달할 수 있게 해준다.

NestJS에서 경로를 선언할 때, 매개변수가 있는 경로는 반드시 정적 경로 뒤에 선언해야 한다. 이렇게 해야 매개변수가 있는 경로가 정적 경로를 향하는 트래픽을 가로채지 않기 때문이다. path mapping은 선언된 순서대로 이루어진다. 만약 parameter가 있는 path를 static path보다 먼저 선언하면, 모든 해당 path가 매개변수 경로로 매칭되어 static 경로가 동작하지 않게 된다.

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

@Controller('items')
export class ItemsController {
  @Get(':id')
  getItem(@Param('id') id: string): string {
    return `Item ID: ${id}`;
  }

  @Get('static')
  getStatic(): string {
    return 'This is a static route';
  }
}

잘못된 경우 : 매개변수가 있는 경로를 정적 경로보다 먼저 선언한 경우
'/items/static' 경로로 요청이 들어오면, 이 요청은 매개변수 경로 '@Get(':id')'로 매칭되어 id 파라미터로 인식된다.
따라서 getStatic() method는 호출되지 않는다.

     - 요청 URL: /items/static'
        - 결과: Item ID: static

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

@Controller('items')
export class ItemsController {
  @Get('static')
  getStatic(): string {
    return 'This is a static route';
  }

  @Get(':id')
  getItem(@Param('id') id: string): string {
    return `Item ID: ${id}`;
  }
}

올바른 경우 : 정적 경로를 매개변수가 있는 경로보다 먼저 선언한 경우
'/items/static' 경로로 요청이 들어오면, 정적 경로 '@Get('static')'가 먼저 매칭되므로, 'getStatic()' method 가 호출된다.
매개변수 경로 '@Get(':id')'는 다른 모든 경로를 처리한다.

    - 요청 URL: '/items/static'
        - 결과: 'This is a static route'
    - 요청 URL: '/items/123'
        - 결과: 'Item ID: 123'

@Param() 은 method parameter을 decorate되어, path parameter를 method 내부에서 해당 매개 변수의 속성으로 사용할 수 있게 한다. 이를 통해 요청 경로의 특정 매개변수를 쉽게 접근하고 사용할 수 있다. Param은 @nestjs/common package에서 import 한다.

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

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

Sub-Domain Routing

@Controller는 host 옵션을 가질 수 있다. 이를 통해 들어오는 요청의 HTTP 호스트가 특정 값과 일치해야 함을 요구할 수 있다. 이를 통해 특정 호스트에 대해 경로를 바인딩할 수 있다. 즉 특정 도메인에서만 api를 요청할 수 있도록 하는 것이다.

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

• 위의 경우 'admin.example.com' 호스트에 대해서만 'AdminController'의 path를 활성화 한다.
• '/' path로 들어오는 요청은 호스트가 'admin.example.com'인 경우에만 처리된다.

HTTP host: 웹 요청을 처리할 서버의 도메인 이름 또는 IP주소를 의미한다.
    웹 브라우저나 클라이언트는 서버에 요청을 보낼 때 요청 헤더의 호스트 정보를 포함시킨다.
    이 호스트 정보는 서버가 어떤 도메인에 대한 요청인지를 식별하는 데 사용된다.

주의사항
Fastify는 nested routers에 대한 지원의 부족으로 만일 sub-domain routing을 해야한다면, Express adapter을 대신 사용해야 한다.

route path와 유사하게, hosts option을 사용하면 host name에서의 dynamic value, host paramter token을 캡쳐할 수 있다. @HostParam() decorator을 통해 host parameter에 접근할 수 있다. method는 method signature로 사용되어야 한다.

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

@Controller({ host: ':subdomain.example.com' })
export class SubdomainController {
  @Get('user/:id')
  getUser(@HostParam('subdomain') subdomain: string, @Param('id') id: string) {
    return `This action returns user with id ${id} from the ${subdomain}.example.com subdomain`;
  }
}

Scopes

NestJS에서는 대부분의 리소스가 들어오는 모든 요청에 대해 공유된다. 이러한 점은 다른 프로그래밍 언어 배경을 가진 사람에게는 놀라울 것이다. DB에 대한 연결 풀, 전역 상태를 가진 singleton service 등이 이러한 예이다. 이는 Node.js가 request/response multi Threaded Stateless Model을 따르지 않기 때문이다. 따라서 singleton instance를 사용하는 것이 application에서 완전히 안전하다.

NestJS는 Node.js 기반으로 동작한다. 특히, NestJS는 다수의 요청을 처리할 때 대부분의 componenet를 공유한다.

componenet: 주로 모듈, 컨트롤러, 서비스, 미들웨어, 파이프, 필터, 가드 등을 의미한다. 
    이러한 컴포넌트는 NestJS 어플리케이션의 주요 빌딩 블록으로, 각 컴포넌트는 특정한 역할과 책임을 가지고 있다.
    1. module: 관련된 컴포넌트들을 그룹화하여 구성 요소를 조직화하는 단위. 
        모든 NestJS 어플리케이션은 최소 하나의 루트 모듈을 가지며, 어플리케이션의 구조를 정의
    2. controller: 컨트롤러는 들어오는 요청을 처리하고, 클라이언트에게 응답을 반환하는 역할을 한다. 
        주로 라우팅을 처리하며, 서비스 계층과 상호작용한다.
    3. service: 서비스는 비즈니스 로직과 데이터 접근을 담당한다. 일반적으로 싱글턴으로 동작하며, 
        컨트롤러나 다른 서비스에서 주입받아 사용
    4. middle: request가 controller에 도달하기 전에 처리되는 함수. loggin, authentication, request 변환 등 다양한 목적에 사용
    5. pipe: transformation과 validation을 담당한다. 요청 데이터가 컨트롤러 핸들러로 전달되기 전에 처리된다.
    6. filter: 필터는 예외를 처리하고, 사용자 정의 예외 응답을 생성할 수 있다.
    7. guard: 요청이 컨트롤러 라우트 핸들러에 도달하기 전에 실행되며, 주로 인증 및 권한 부여 로직을 포함한다.

• NestJS에서의 공유 컴포넌트

  1. database 연결 풀: 여러 요청이 동일한 데이터베이스 연결 풀을 사용한다. 이는 효율성을 높이고 자원 낭비를 줄인다.
     • DataBase Connection Pool: 다수의 DB 연결을 미리 생성해 두고, 요청이 있을 때 재사용할 수 있도록 관리하는 메커니즘. 이는 각 요청마다 새로운 DB 연결을 생성하는 대신, 미리 생성된 연결을 재사용하여 성능을 최적화하고 자원을 절약한다.
     • import { Module } from '@nestjs/common'; import { TypeOrmModule } from '@nestjs/typeorm'; import { AppService } from './app.service'; @Module({ imports: [ TypeOrmModule.forRoot({ type: 'mysql', host: 'localhost', port: 3306, username: 'test', password: 'test', database: 'test', entities: [__dirname + '/../**/*.entity{.ts,.js}'], synchronize: true, // 연결 풀 설정 extra: { connectionLimit: 10, // 연결 풀 크기 설정 }, }), ], providers: [AppService], }) export class AppModule {}
  2. 싱글턴 서비스: singleton 서비스는 어플리케이션 전역에서 단 하나의 instance로 존재하는 서비스이다. 대부분의 서비스는 싱글턴으로 동작하여 글로벌 상태를 유지할 수 있다. 즉 여러 요청 간에 동일한 인스턴스를 공유할 수 있음을 의미한다. 메모리 사용을 최적화하고, 반복적인 초기화 비용을 줄인다.
  3. 글로벌 상태: application 전역에서 공유되는 데이터나 설정을 의미한다. NestJS에서는 싱글턴 서비스를 통해 이러한 글로벌 상태를 관리할 수 있다. 즉 application 전역에서 상태를 공유하여 전역 설정이나 데이터를 중앙에서 관리할 수 있다.
  4. // 아래의 ConfigService는 어플리케이션 전역에서 설정 값을 관리한다. // 다른 서비스나 모듈에서 ConfigService를 주입받아 설정 값을 읽거나 쓸 수 있다. import { Injectable } from '@nestjs/common'; @Injectable() export class ConfigService { private config = { appName: 'NestJS Application', version: '1.0.0', }; getConfig(key: string) { return this.config[key]; } setConfig(key: string, value: any) { this.config[key] = value; } } @Module({ providers: [ConfigService], exports: [ConfigService], }) export class ConfigModule {}

• Node.js와 멀티스레딩:

  • Node.js는 요청/응답 모델에서 멀티스레드 상태 비저장 모델을 따르지 않는다. 대신, 단일 스레드 이벤트 루프를 사용하여 비동기적으로 요청을 처리한다. 이러한 특성으로 싱글턴 인스턴스를 사용하는 것이 안전하다.

• NestJS의 범위(Scopes):

  • NestJS에서는 서비스의 인스턴스 생성 방식을 제어하기 위해 다양한 범위를 제공한다. 각 범위는 서비스 인스턴스의 수명 주기와 범위를 정의한다.
  1. 기본 범위(Default Scope): 기본적으로 NestJS의 모든 서비스는 싱글턴으로 동작한다. 즉, 어플리케이션이 시작될 때 한 번 인스턴스화 되고, 모든 요청에서 동일한 인스턴스를 사용한다.
  2. @Injectable() export class MySingletonService { private count = 0; increment() { this.count++; } getCount() { return this.count; } }
  3. 요청 범위(Request Scope): 요청 범위의 서비스는 각 요청마다 새로운 인스턴스를 생성한다. 이렇게 하면 요청 간에 상태를 공유하지 않는다.
  4. import { Injectable, Scope } from '@nestjs/common'; @Injectable({ scope: Scope.REQUEST }) export class MyRequestScopedService { private count = 0; increment() { this.count++; } getCount() { return this.count; } }
  5. 트랜지언트 범위(Transient Scope): 트랜지언트 범위의 서비스는 주입될 때마다 새로운 인스턴스를 생성한다. 이를 주입받는 각 컴포넌트가 고유의 인스턴스를 가지게 함을 의미한다.
  6. import { Injectable, Scope } from '@nestjs/common'; @Injectable({ scope: Scope.TRANSIENT }) export class MyTransientService { private count = 0; increment() { this.count++; } getCount() { return this.count; } }

그러나 일부 경우에는 요청 기반의 라이프사이클이 바람직할 수 있다. 예를 들어, GraphQL application에서의 per-request caching. request tracking, multi-tenancy가 있다.

Multi Threaded Stateless Model: 각 요청이 별도의 스레드에 의해 처리되는 것
SingleTon: 특정 클래스의 인스턴스를 1개만 생성되는 것을 보장하는 디자인 패턴

request-cahcing: 요청별로 캐시를 관리하여 DB 요청을 줄일 수 있다.
request tracking: 각 요청마다 고유한 추적 ID를 생성하여 요청을 추적할 수 있다.
multi-tenancy: 하나의 소프트웨어 인스턴스가 여러 사용자를 동시에 서비스하는 아키텍쳐를 말함
    각 요청마다 다른 tenancy의 데이터를 처리할 수 있다. 
tenancy: 소프트웨어 application을 사용하는 개별 고객 또는 조직을 말한다.

Asynchronicity(비동기성)

Asynchronicity는 작업이 완료될 때까지 기다리지 않고 다음 작업을 수행하는 것을 말한다.
대부분의 data extraction의 경우 asynchronous하게 된다. 그렇기에 Nest에서는 async function을 제공한다.자세히

모든 async function은 Promise를 반환한다. 즉 비동기 작업을 수행할 때 연기된(deferred) 값을 반환할 수 있으며, nest는 이를 스스로 해결할 수 있다. 이는 Promise, async/await를 사용하여 비동적으로 처리되는 값을 반환할 수 있음을 의미한다.

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

위의 코드는 유효하다. 게다가 Nest route handler는 RxJS observable streams를 사용함으로써 더 강력하다. 이를 통해 비동기 데이터 흐름을 쉽게 관리할 수 있다. Nest는 내부적으로 observable에 자동으로 구독하고, 스트림이 완료되면 마지막으로 방출된 값을 클라이언트에게 반환한다.

RxJS: Reactive Extensions for JavaScript의 약자로, 비동기 및 이벤트 기반 프로그램을 쉽게 작성할 수 있도록 도와주는 라이브러리다. 

Observable: data stream을 나타내며, 시간이 지남에 따라 여러 값을 방출할 수 있다. 
    - 데이터가 도착했을 때 수행할 작업을 정의하는 구독자(subscriber)를 가질 수 있다.
Observer: Observable에서 방출된 데이터를 처리하는 콜백 함수의 모음. 보통 next, error, complete method를 가진다.
Subscription: Observable에 대해 구독을 시작하거나 중지하는 것을 관리한다.
Operators: Observable의 데이터 스트림을 변형하거나 필터링할 수 있는 함수들이다.

Observable은 RxJS(Reactive Extensions for JavaScript) 라이브러리에서 제공하는 핵심 개념 중 하나로, 비동기 데이터 스트림을 나타낸다. 'Observable'은 데이터의 흐름을 관리하고, 이를 구독(subscribe)하여 데이터가 발생할 때마다 반응할 수 있게 한다. 이를 통해 이벤트 기반의 비동기 프로그래밍을 쉽게 구현할 수 있다.

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

Request Payloads

이전의 POST Example은 any client params를 받지 못한다. 이를 @Body() decorator을 추가함으로써 고칠 수 있다.

먼저 DTO(Data Transfer Object) schema를 추가한다. DTO는 network를 거쳐 어떻게 보내는지를 정의한다. Typescript의 interface를 통해, 혹은 class로 DTO schema를 결정할 수 있다. 신기하게도 class 사용을 권장한다. 왜냐하면, Class들은 JavaScript ES6 standard의 부분이기에 compiled JavaScript의 안에서 real entities로 보존된다. 반면에 Typescript의 interface들은 transpilation 과정에서 삭제된다. 그리고 Nest는 runtime 과정에서 이를 언급하지 않는다. 이는 NestJs에서 중요한 의미를 가지는데, 특히 파이프(Pipe) 와 같은 기능이 런타임에 변수의 메타타입(metatype)에 접근할 수 있을 때 추가적인 가능성을 제공하기 때문이다.

compile: 한 언어로 작성된 소스 코드를 다른 언어로 변환하는 것을 의미한다.
    e.g. Java -> bytecode
         c -> assembly
transpile: 한 언어로 작성된 소스 코드를 비슷한 수준의 추상화를 가진 다른 언어로 변환하는 것
    e.g. es6 -> es5
         c++ -> c
         coffescript -> javascript

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

이는 3개의 간단한 속성을 가진다. 이후에 우리는 새로히 만들어진 DTO를 사용할 수 있다.

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

// TS
@Post()
@Bind(Body())
async create(createCatDto) {
  return 'This action adds a new cat';
}

ValidationPipe는 method handler로 전달되면 안되는 속성들을 filter해준다. 개발자는 acceptable한 properties들을 whitelist할 수 있다. 그리고 whilelist되지 못한 속성들을 자동으로 stripped 된다.자세히

Full resource error

아래의 경우 몇 개의 decorator를 이용해 만든 basic controller의 예이다. internal data에 접근하고 조작하기 위한 몇개의 method들이 담겨져 있다.

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() // HTTP 요청의 쿼리 매개변수를 추출하는 데 사용
  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는 위의 작업을 손쉽게 만들어주는, all the boilerplate code를 만들어주는 generator를 제공한다.자세히

Getting up and Running

위의 controller가 정의되었음에도 Nest는 CatsController의 존재를 알지못한다. 그렇기에 이 class의 instance를 만들지 못한다.

Controller는 항상 module에 속한다. @Module() decorator안의 controllers array에 class가 속해야 한다. 아직 예시에서는 AppModule을 제외한 나머지 module을 만들지 않았기에, 우리는 여기서 CatsController를 넣는다.

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

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

@Module() Decorator를 사용하여 MetaData를 module class에 첨부하였으며, 이제 Nest는 어떤 controller들이 mount되어야 하는지 쉽게 알 수 있다.

Library-Specific Approach

지금까지 Nest에서 responses들을 조작하는 기본적인 way들을 알아봤다. 두 번째 방법은 library-specific response object이다. response object를 inject하기 위해서, @Res() decorator를 사용해야한다.

//JS
import { Controller, Get, Post, Bind, Res, Body, HttpStatus } from '@nestjs/common';

@Controller('cats')
export class CatsController {
  @Post()
  @Bind(Res(), Body())
  create(res, createCatDto) {
    res.status(HttpStatus.CREATED).send();
  }

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

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

이러한 방식은 response object를 직접적으로 제어함(Header manipulation, library-specific features, ...)으로써 좀더 flexibility 하지만 이는 좀더 조심해서 사용해야한다. 일반적으로 상대적으로 덜 clear하고, 일부 단점이 존재한다. 무엇보다도 코드들이 platform-dependent 해진다. 예를 들어 Express에서 Fastify로 변경할 경우, 응답 객체의 API가 달라 코드 변경이 필요하다. 테스트가 복잡해진다. 응답 객체를 직접 mocking 해야하므로 테스트가 더 어려워 진다.

또한 compatibility를 잃을 것이다. 플랫폼 종속적인 접근 방식을 사용하면, interceptors와 @HttpCode(), @Header() decorator 등 Nest의 표준 응답 처리에 의존하는 기능들과의 호환성을 잃게 된다. 이럴 해결하기 위해, passthrough 옵션을 true로 설정할 수 있다.

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

이제 native response object와 interact를 할 수 있다. (e.g. set cookies, or headers).

첫 단추로 Nest의 가장 핵심 기능을 알아 볼 것이다. 가장 기본적인 CRUD에 대해 알아 보자.

Language

주로 TypeScript를 사용할 것이고, 또한 Node.js를 애착한다. 그렇기에 Nest는 Typescript과 pure Javascript 둘 다 양립가능하다. Nest는 가장 최근의 language feature들의 이점을 가져온다. 그래서 vanilla JavaScript와 함께 사용하기 위해 Nest는 Babel compier를 사용한다.

Vanilla JS: 외부의 라이브러리나 프레임워크를 이용하지 않는 순수 자바스크립트를 말한다.
    둘을 사용하지 않기에, 사용했을 때 보다 호환성이 좋다는 게 특징이다. 이런 특징은 디버그(Debug)를 할 때 유용하다. 

Babel Compiler: Javascript 코드를 컴파일하는 도구로, 최신 JS 문법과 기능을 이전 버전의 JS로 변환해준다. 
    이를 통해 최신 Javascript 기능을 지원하지 않는 구형 브라우저나 환경에서도 최신 코드를 사용할 수 있게 해준다.

Prerequisites

사용자의 OS에는 Node.js(version >= 16)이 설치되어야 한다.

Setup

새 프로젝트를 setting하는데는 Nest CLI를 이용하여 꽤 간단하다.

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

만일 TypeScript의 stricter한 feature set으로 설치하고자 한다면, --strict flag를 nest new command에 덧붙인다.

project-name 디렉토리가 만들어 질 것이며, node modules와 다른 boliderplate files들이 설치될 것이다. 그리고 src/ 디렉터리가 또한 만들어 질 것이며 아래와 같이 핵심 파일들이 있다.

src
    app.controller.spec.ts
    app.controller.ts
    app.module.ts
    app.service.ts
    main.ts

각 파일의 역할은 다음과 같다.

main.ts는 동기 함수, bootstrap이 포함되어 있다.

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

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

Nest Application instance를 만들기 위해, NestFactory class를 사용한다. NestFactory는 application instance를 만들기 위한 여러 개의 method를 제공한다. create()는 application object를 반환한다. 이는 INestApplication interface에 따라진다. main.ts에서는 HTTP listener를 시작하여 애플리케이션이 들어오면 HTTP 요청을 대기하도록 한다.

Nest CLI에 기반된 project는 초기 프로젝트 structure를 만든다. 이는 개발자들이 각 모듈의 관습을 따르도록 장려한다.

//기본적으로, 애플리케이션이 생성되는 동안 오류가 발생하면, 애플리케이션은 코드 1과 함께 종료된다. 이 기본 동작을 변경하여 오류를 발생시키도록하고 싶다면, `abortOnError` 옵션을 비활성화하면 된다.

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

async function bootstrap() {
  try {
    const app = await NestFactory.create(AppModule, { abortOnError: false });
    // abortOnError: 이 옵션을 사용하면 애플리케이션이 종료되지 않고 오류를 던진다.
    // abort: 중단하다.
    await app.listen(3000);
  } catch (error) {
    console.error('Error starting the application:', error);
  }
}
bootstrap();

Platform

Nest는 플랫폼 종속적이지 않은 프레임워크를 지향한다. Platform independence는 framework로써 NestJs는 코드의 재사용성을 높여준다. 즉, 특정 플랫폼에 종속되지 않기에, 한 번 작성한 논리적 모듈이나 컴포넌트를 다양한 애플리케이션에서 다시 사용할 수 있다. 이는 개발 생산성을 높이고, 유지보수를 용이하게 한다. 기술적으로, Nest는 adapter가 만들어지면 어떤 Node HTTP framework라도 작동한다.
두 개의 HTTP platform이 있다. express와 fastify가 있다.

플랫폼 독립적
1. 운영 체제 독립성: window, macOS, Linux...
2. 서버 프레임워크 독립성: Express, Fastify 등 다양한 HTTP 서버 프레임워크와 호환되어 사용할 수 있다.
3. 클라우드 플랫폼 독립성: 애플리케이션이 AWS, Google Cloud, Azure 등 다양한 클라우드 서비스 제공업체에서
    문제없이 배포되고 실행될 수 있다. 

Express: 웹 및 모바일 애플리케이션을 위한 일련의 강력한 기능을 제공하는 간결하고 
    유연한 Node.js 웹 애플리케이션 프레임워크이다. 즉 Node.js를 사용하여 쉽게 서버를 구성할 수 있게
    만든 클래스와 라이브러리의 집합체이다.

Fastify: Node.js를 위한 빠르면서도 오버헤드가 적은 웹 프레임워크이다.

어떤 플랫폼을 사용하든지, 이는 각자의 application interface를 나타낸다. 이는 각각 NestExpressApplication과 NestFastifyApplication 사용된다.

만일 NestFactory.create() method를 사용할 때, (아래와 같이) app 객체는 specifc platform에 맞는 method들을 가질 것이다. 하지만 실제로 해당 platform API에 접근하려는 경우가 아니면 타입을 지정할 필요는 없다. 즉 특정 platform의 API를 사용하고 싶다면 타입을 지정한다.

1. 기본 사용법(타입 지정 없음)

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

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

bootstrap();

2. 타입 지정(Express)

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { NestExpressApplication } from '@nestjs/platform-express';

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  app.set('trust proxy', 1); // Express 고유의 메서드 사용 예시
  await app.listen(3000);
}

bootstrap();

3. 타입 지정(Fastify)

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { NestFastifyApplication } from '@nestjs/platform-fastify';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(AppModule);
  app.register(require('fastify-cors')); // Fastify 고유의 메서드 사용 예시
  await app.listen(3000);
}

bootstrap();

Running the application

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

npm run start

<팁!>
만일 process의 build 속도(x20 times faster build)를 높이고자한다면, SWC builder 를 사용할 수 있다. -b swc flag를 start script에 추가하면된다. npm run start -- -b swc

위의 command는 HTTP server가 src/main.ts에 정의된 port에서 대기하도록 한다. application을 running하고 브라우저에서 'http://localhost:3000/' 접속하면 'Hello word!' 메시지를 볼 수 있다.

src의 파일을 바꿀 때 변경사항을 바로바로 확인하고 싶다면 아래의 command로 시작한다.

$ npm run start:dev

이 command는 file의 변경 사항을 자동으로 recompile하고 server를 reloading한다.

Linting and formatting

CLI는 개발함에 있어 최고의 여건을 마련해준다.
생성된 Nest projects linter과 formatter의 code가 함께 설치된다. 이는 각각 eslint와 prettier이다.

code linter: 코드의 일관성과 스타일을 유지하고, 잠재적인 오류를 발견하기 위해 코드 품질을 검사하는 도구이다. 
    Nest 프로젝트는 eslint가 사용된다.
code formatter: 코드의 형식을 자동으로 맞춰주는 도구이다. Nest 프로젝트에서는 prettier가 사용된다.

안정성(stability)와 확장성(extensibility)을 보장해주기 위해, eslint와 prettier package가 사용된다.
이는 공식적인 extenstions을 통해 정돈된 IDE 완성을 시켜준다.

headless 환경에서, IDE가 필요 없는 환경에서는 바로 사용할 수 있는 npm 스크립트를 제공한다.

# Lint and autofix with eslint
$ npm run lint

# Format with prettier
$ npm run format

• headless environment: IDE(통합 개발 환경)을 사용하지 않고, 주로 명령줄에서 작업하는 환경을 의미한다.
• npm script: package.json 파일에 정의된 명령어로, 프로젝트의 빌드, 테스트, lint 등의 작업을 자동화하는 데 사용된다.

{
  "scripts": {
    "start": "nest start",
    "start:dev": "nest start --watch",
    "start:prod": "node dist/main",
    "build": "nest build",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage",
    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
    "test:e2e": "jest --config ./test/jest-e2e.json"
  }
}