NestJS Request Lifecycle (4) - Pipe

이전 글

• 2022.12.22 - [Backend/NestJS] - NestJS Request Lifecycle (0) - 개요
• 2022.12.22 - [Backend/NestJS] - NestJS Request Lifecycle (1) - Middleware
• 2022.12.23 - [Backend/NestJS] - NestJS Request Lifecycle (2) - Guard
• 2022.12.26 - [Backend/NestJS] - NestJS Request Lifecycle (3) - Interceptor

---

파이프

NestJS에서 파이프란 컨트롤러의 앞단에서 사용자의 요청에 대해 다음의 역할을 수행하는 생명주기를 의미한다.

• 변환: 사용자의 요청 속 데이터를 원하는 형태로 변경 후 컨트롤러에 넘겨준다.
• 검증: 사용자의 요청 속 데이터에 대해, 컨트롤러 단에 도달하기 전 검증을 수행하고 검증이 실패할 시 이를 컨트롤러 단에 넘기지 않고 바로 사용자에게 에러를 반환한다.

파이프의 존재 이유?

NestJS의 아키텍쳐에서 파이프가 따로 존재하는 이유는 바로 관심사 문제를 해결하기 위함이다. 파이프에서 수행하는 로직은 컨트롤러 내에 위치해도 되지만, 그럴 경우 컨트롤러의 관심사가 모호해질 수 있으며 비슷한 데이터의 검증에 대해 재사용성도 나빠진다. 따라서 NestJS에서는 메인 비즈니스 로직의 오염을 방지하고자 데이터 검증 관련 로직을 파이프에 분리하여 작성한다.

 

파이프 작성

NestJS에서는 기본적으로 아래 9종의 기본적으로 제공되는 파이프라인이 존재하고, 이를 활용하면 대부분의 변환, 검증 로직을 구현할 수 있다. (아래 파이프들의 세부적인 정보는 공식문서 참조)

• ValidationPipe
• ParseIntPipe
• ParseFloatPipe
• ParseBoolPipe
• ParseArrayPipe
• ParseUUIDPipe
• ParseEnumPipe
• DefaultValuePipe
• ParseFilePipe

 다만, 기본적으로 제공되는 파이프로는 서비스 로직을 구현하기 부족하다면 직접 커스텀 파이프를 생성해서 활용할 수도 있다.

커스텀 파이프 작성

커스텀 파이프를 작성하기 위해서는 NestJS의 PipeTransform을 상속한 클래스와 클래스 내 transform 메서드를 구현해야 한다.

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

@Injectable()
export class ValidationPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    return value; // 모든 value를 통과시키는 파이프
  }
}

위 예시는 공식문서의 모든 값을 통과시키는 파이프 예시이다. transform 메서드는 2개의 인자를 갖는다. 첫번째 인자인 value는 컨트롤러에서 처리되는 인자이고(다만 컨트롤러에 도달하지는 못한 상태), 두번째 인자인 metadata는 앞선 value의 메타데이터이다. 

커스텀 파이프에서의 예외 처리

파이프 내에서 발생하는 각종 에러들은 전부 NestJS의 필터 레이어 내에서 발생한다. 따라서 파이프 내에서 검증 로직이 실패하여 그에 따라 에러를 반환해도 NestJS의 필터가 잘 작동한다. 결과적으로 검증이 실패했을 때의 예외 처리는 필터 로직에 위임하고, 파이프 단에서는 에러 상황에 맞는 커스텀 에러를 던지기만 하면 된다.

NestJS에서 기본적으로 제공되는 파이프가 강력하고, 커스텀 파이프를 작성하는 방법은 공식문서에 잘 나와있기 때문에 이에 대해서는 다음의 링크를 참고바란다.

https://docs.nestjs.com/pipes#built-in-pipes

Documentation | NestJS - A progressive Node.js framework

 

파이프 적용

NestJS에서 파이프를 적용하는 방식은 크게 4가지가 존재한다.

1. 모듈 밖에 위치하는 전역 파이프
2. 모듈 내에 위치하는 전역 파이프
3. 컨트롤러 메서드(핸들러) 레벨에 작용하는 파이프
4. 메서드 파라미터(인자) 레벨에 작용하는 파이프

모듈 밖에 위치하는 전역 파이프

해당 방식을 위해서 NestJS 어플리케이션의 useGlobalPipes() 메서드를 이용할 수 있다. 이 방식은 모듈 밖에 파이프를 위치시키기 때문에 다른 모듈을 가져와 의존성을 추가하여 사용하거나, 혹은 반대의 경우가 불가능하다. 코드는 다음과 같이 작성한다.

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // 전역 파이프 설정, 기본 제공 파이프를 활용
  app.useGlobalPipes(new ValidationPipe());
  await app.listen(3000);
}
bootstrap();

해당 방식을 이용하기 위해서는 파이프 클래스의 인스턴스를 직접 인자로 추가해주어야 한다.

모듈 내에 위치하는 전역 파이프

해당 방식을 통하면 파이프 내에서 다른 모듈의 의존성을 주입하여 사용할 수 있다. 해당 방식은 메인 모듈과 연결된 어떤 모듈에서 주입이 되더라도 전역으로 동일하게 사용할 수 있기 때문에, 공식문서에서는 파이프가 생성된 모듈에서 바로 주입할 것을 추천하고 있다.

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

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

컨트롤러 메서드(핸들러) 레벨에서 작용하는 파이프

해당 방식은 NestJS의 @UsePipes() 데코레이터를 활용하는 방식이다. 이를 통하면 특정 핸들러에 들어오는 데이터에 파이프를 적용할 수 있다. 해당 방식은 데코레이터에 적용할 파이프 클래스를 넣거나 혹은 인스턴스를 넣는 방식으로 적용이 가능하다. 만약 클래스의 생성자의 인자를 통해 파이프의 역할을 정의해야 한다면, 인스턴스 방식을 활용할 수 있다.

import {
  Body,
  Controller,
  Post,
  UsePipes,
  ValidationPipe,
} from '@nestjs/common';
import { SignupDto } from '@auth/dto/signup.dto';
import { AuthService } from '@auth/auth.service';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('signup')
  @UsePipes(ValidationPipe) // 라우터 핸들러에 파이프 적용
  async signup(@Body() signupDto: SignupDto) {
    const signupResult = await this.authService.signup(signupDto);
    return signupResult;
  }
}

핸들러 파라미터(인자) 레벨에서 작용하는 파이프

해당 방식은 핸들러의 특정 파라미터에 대해서만 파이프를 적용하는 방식이다. NestJS에서 제공하는 각종 파라미터 데코레이터 (ex. @Body(), @Param(), @Query())나 혹은 NestJS의 customParamDecorator() 함수를 통해 만들어진 커스텀 데코레이터에 대해 적용된다. (이 때, customParamDecorator에 NestJS의 ValidationPipe를 적용하기 위해서는 설정으로 다음과 같이 작성해주어야 한다.)

@CustomParam(new ValidationPipe({ validateCustomDecorators: true }))

기존에 존재하는 파라미터 데코레이터를 사용하는 경우에는 다음과 같이 코드를 작성해주면 된다.

import {
  Body,
  Controller,
  Post,
  ValidationPipe,
} from '@nestjs/common';
import { SignupDto } from '@auth/dto/signup.dto';
import { AuthService } from '@auth/auth.service';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('signup')
  async signup(@Body(ValidationPipe) signupDto: SignupDto) {
    const signupResult = await this.authService.signup(signupDto);
    return signupResult;
  }
}

 

DTO 도입(Data Transfer Object)

NestJS 공식문서에서는 파이프의 활용에 DTO를 적용하는 방식을 설명하고 있다. 

여기에서 DTO란 Data Transfer Object의 약자로 클라이언트와 서버 간, 혹은 서버 내 각 레이어 간 데이터 통신 시 데이터의 구조를 강제하는 역할을 한다. DTO는 타입스크립트 인터페이스가 아닌 클래스로 선언되어야 하는데, 그 이유는 런타임에서도 계속 작동을 해야하기 때문이다. (인터페이스로 선언 시 실행 전 타입 체킹만을 도와줄 뿐 런타임에는 영향을 미치지 못한다.)

이를 통하면 파이프를 손쉽게 구현할 수 있다.

다음과 같이 DTO를 선언할 수 있다.

// signup.dto.ts
import { IsEmail, IsString } from 'class-validator';

export class SignupDto {
  @IsEmail() // email 검증을 위한 데코레이터
  readonly email: string;

  @IsString() // 문자열 검증을 위한 데코레이터
  readonly password: string;
}

이를 특정 컨트롤러의 메서드에 적용하여 파이프를 구현하기 위해서는 다음과 같이 작성할 수 있다.

import {
  Body,
  Controller,
  Post,
  ValidationPipe
} from '@nestjs/common';
import { SignupDto } from '@auth/dto/signup.dto';
import { AuthService } from '@auth/auth.service';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post('signup')
  @UsePipes(ValidationPipe)
  async signup(@Body() signupDto: SignupDto) {
    const signupResult = await this.authService.signup(signupDto);
    return signupResult;
  }
}

위와 같이 작성하면 SignupDto에서 작성한 구조대로 파이프 단에서 검증이 이루어진다.

만약 DTO를 이용하여 데이터의 변환도 수행하고 싶다면 아래와 같이 작성할 수 있다. 아래의 예시는 비밀번호를 숫자형으로 변환하여 입력 받을 때 이용할 수 있다.

import { Transform } from 'class-transformer';
import { IsEmail, IsNumber } from 'class-validator';

export class SignupDto {
  @IsEmail()
  readonly email: string;

  @Transform(({ value }) => Number(value)) // number형으로 변환 수행
  @IsNumber()
  readonly password: number;
}

이 때 이를 NestJS의 ValidationPipe를 통해 적용하기 위해서는 다음의 설정을 추가해주어야 한다.

// 클래스가 아닌 인스턴스로 설정을 추가하여 파이프 설정을 해주어야 함
// transform : true
// ValidationPipe에서 변환 작업까지 수행해줌(형변환, 기본값 설정)
new ValidationPipe({transform: true})