[Nest.js] Overview - Pipes, Guards

파이프

파이프는 @Injectable() 데코레이터가 적용된 클래스이며, PipeTransform 인터페이스를 구현합니다.

 

파이프는 일반적으로 두 가지 용도로 사용됩니다:

• 변환 (Transformation): 입력 데이터를 원하는 형태로 변환 (예: 문자열을 정수로 변환)
• 검증 (Validation): 입력 데이터를 평가하고, 유효하면 그대로 통과시키고, 그렇지 않으면 예외를 발생시킴

이 두 경우 모두, 파이프는 컨트롤러 라우트 핸들러에서 처리되는 인자에 적용합니다. Nest는 메서드가 호출되기 직전에 파이프를 개입시키며, 파이프는 메서드에 전달될 인자를 받아 이를 처리합니다. 변환 또는 검증 작업은 이 시점에서 수행되며, 그 후 라우트 핸들러는 (필요한 경우 변환된) 인자를 가지고 호출됩니다.

 

Nest는 즉시 사용할 수 있는 여러 가지 내장 파이프를 제공합니다. 또한, 사용자 정의 파이프도 직접 작성할 수 있습니다. 이 장에서는 내장 파이프를 소개하고 이를 라우트 핸들러에 바인딩하는 방법을 살펴본 후, 몇 가지 사용자 정의 파이프를 구현해 보며 처음부터 만드는 방법을 설명합니다.

힌트
파이프는 예외 처리 영역 (Exceptions Zone) 안에서 실행됩니다. 이는 파이프가 예외를 발생시킬 경우, 해당 예외가 전역 예외 필터나 현재 컨텍스트에 적용된 예외 필터에 의해 처리된다는 뜻입니다. 위 내용을 고려하면, 파이프에서 예외가 발생하면 컨트롤러 메서드는 이후 실행되지 않는다는 점이 분명해집니다. 이러한 구조는 외부에서 애플리케이션으로 들어오는 데이터를 시스템 경계에서 검증하기 위한 모범 사례 (Best Practice)를 제공합니다.

내장 파이프

Nest에는 기본적으로 제공되는 여러 파이프가 있습니다:

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

이들은 모두 @nestjs/common 패키지에서 export 됩니다.

 

간단한 예로 ParseIntPipe를 사용하는 방법을 살펴보겠습니다. 이 파이프는 변환 (transformation) 용도로 사용되며, 메서드 핸들러의 파라미터가 자바스크립트 정수로 변환되도록 보장합니다. 변환에 실패하면 예외가 발생합니다. 이 장의 후반부에서는 ParseIntPipe의 간단한 커스텀 구현 예제도 보여줄 예정입니다. 아래 예제 기술은 Parse* 파이프들 (ParseBoolPipe, ParseFloatPipe, ParseEnumPipe, ParseArrayPipe, ParseDatePipe, ParseUUIDPipe) 에도 동일하게 적용됩니다.

파이프 연결하기

파이프를 사용하려면, 해당 파이프 클래스의 인스턴스를 적절한 컨텍스트에 바인딩해야 합니다. ParseIntPipe 예제에서는 특정 라우트 핸들러 메서드에 파이프를 연결하고, 메서드가 호출되기 전에 파이프가 실행되도록 해야 합니다. 이 작업은 다음과 같은 구문으로 수행되며, 이를 "메서드 매개변수 수준에서 파이프를 바인딩한다"라고 부릅니다:

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

 

이것은 다음 두 가지 조건 중 하나가 반드시 참이 되도록 보장합니다: 첫째, findOne() 메서드에서 받은 파라미터가 this.catsService.findOne() 호출에서 기대하는 대로 숫자이거나, 둘째, 경로 핸들러가 호출되기 전에 예외가 발생하는 경우입니다.

 

예를 들어, 경로가 다음과 같이 호출된다고 가정해 보겠습니다:

GET localhost:3000/abc

 

Nest는 다음과 같은 예외를 발생시킵니다:

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

 

예외가 발생하면 fineOne() 메서드의 본문은 실행되지 않습니다.

 

위의 예제에서는 클래스 (ParseIntPipe)를 전달하고 있으며, 이는 인스턴스가 아니라 클래스를 전달함으로써 인스턴스화 책임을 프레임워크에 맡기고 의존성 주입 (Dependency Injection)을 가능하게 합니다. 파이프나 가드와 마찬가지로, 직접 인스턴스를 만들어 전달할 수도 있습니다. 직접 인스턴스를 전달하는 방식은 기본 내장 파이프의 동작을 옵션을 통해 커스터마이징 하고자 할 때 유용합니다.

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

 

다른 변환 파이프들 (모든 Parse* 파이프들)을 바인딩하는 방식도 유사합니다. 이러한 파이프들은 모두 라우트 파라미터, 쿼리 문자열 파라미터, 요청 본문 값의 유효성을 검사하는 문맥에서 동작합니다.

 

예를 들어, 쿼리 문자열 파라미터의 경우 다음과 같이 사용할 수 있습니다:

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

 

다음은 ParseUUIDPipe를 사용하여 문자열 파라미터를 파싱하고 UUID인지 검증하는 예시입니다.

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

힌트
ParseUUIDPipe()를 사용할 때 UUID 버전 3, 4 또는 5를 파싱 하게 됩니다. 특정 버전의 UUID만 허용하고 싶다면, 해당 버전을 파이프 옵션에 전달할 수 있습니다.

 

위에서는 다양한 Parse* 계열의 내장 파이프를 바인딩하는 예제를 살펴보았습니다. 유효성 검사 (Validation) 파이프는 이와는 조금 다르게 바인딩됩니다. 이에 대해서는 다음 섹션에서 설명합니다.

힌트
유효성 검사 파이프에 대한 다양한 예제는 Validation technique 섹션을 참고하세요.

커스텀 파이프

앞서 언급했듯이, 자신만의 커스텀 파이프를 만들 수 있습니다. Nest는 강력한 내장 ParseIntPipe와 ValidationPipe를 제공하지만, 커스텀 파이프가 어떻게 구성되는지 이해하기 위해 각각의 간단한 버전을 처음부터 만들어 보겠습니다.

 

우선 간단한 ValidationPipe부터 시작하겠습니다. 처음에는 입력 값을 받아 그대로 반환하는, 즉 항동 함수 (identity function)처럼 동작하게 만들 것입니다.

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

@Injectable()
export class ValidationPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    return value;
  }
}

힌트
PipeTransform<T, R>는 모든 파이프가 구현해야 하는 제네릭 인스턴스입니다. 이 인터페이스에서 T는 입력 값의 타입을, R은 transform() 메서드의 반환 타입을 나타냅니다.

 

모든 파이프는 PipeTransform 인터페이스를 만족시키기 위해 transform() 메서드를 구현해야 합니다. 이 메서드는 두 개의 매개변수를 가집니다:

• value: 현재 처리 중인 메서드 인자 (해당 인자가 라우트 핸들링 메서드에 전달되기 전의 값)
• metadata: 현재 처리 중인 메서드 인자의 메타데이터

metadata 객체는 다음과 같은 속성들을 가지고 있습니다:

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

 

이 속성들은 현재 처리 중인 인자에 대한 정보를 설명합니다:

type	인자의 위치를 나타냅니다. 예: @Body(), @Query(), @Param(), 또는 사용자 정의 파라미터 (자세한 내용은 여기 참고)
metatype	인자의 메타타입을 나타냅니다. 예: String. 참고로, 라우트 핸들러 메서드 시그니처에서 타입 선언을 생략하거나 일반 JavaScript를 사용할 경우 undefined가 됩니다.
data	데코레이터에 전달된 문자열입니다. 예: @Body('string') 에서 'string'. 데코레이터 괄호를 비워두면 undefined가 됩니다.

경고
TypeScript의 인터페이스는 트랜스파일 과정에서 사라지기 때문에, 메서드 파라미터의 타입이 클래스가 아니라 인터페이스로 선언되면 metatype 값은 Object가 됩니다.

스키마 기반 검증

우리의 Validation 파이프를 좀 더 유용하게 만들어 봅시다. 예를 들어, CatsController의 create() 메서드를 살펴보면, 서비스 메서드를 실행하기 전에 POST 본문 객체가 유효한지 확인하고 싶을 것입니다.

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

 

createCatDto 본문 파라미터에 집중해 봅시다. 이 파라미터의 타입은 CreateCatDto 입니다:

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

 

우리는 create 메서드에 들어오는 모든 요청이 유효한 본문 (body)을 포함하고 있는지를 보장하고자 합니다. 이를 위해 createCatDto 객체의 세 멤버를 검증해야 합니다. 이 작업을 라우트 핸들러 메서드 안에서 수행할 수도 있지만, 그렇게 하면 단일 책임 원칙 (SRP)을 위반하게 됩니다.

 

다른 접근 방식으로는 별도의 유효성 검사기 클래스 (validator class)를 만들어 해당 작업을 위임하는 방법이 있습니다. 하지만 이 방법은 각 메서드의 시작 부분에서 해당 유효성 검사기를 호출하는 것을 매번 기억해야 한다는 단점이 있습니다.

 

그러면 유효성 검사 미들웨어 (validation middleware)를 만들어보는 건 어떨까요? 가능하긴 하지만, 아쉽게도 NestJS에서는 애플리케이션 전역의 모든 컨텍스트에서 사용할 수 있는 제네릭 한 미들웨어를 만드는 것이 불가능합니다. 왜냐하면 미들웨어는 어떤 핸들러가 호출될지나 해당 핸들러의 파라미터에 대한 정보를 알 수 없기 때문입니다.

 

바로 이것이 파이프 (pipes)가 설계된 정확한 용례입니다. 따라서 이제 유효성 검사 파이프를 정교하게 개선해 보겠습니다.

객체 스키마 검증

객체 유효성 검사를 깔끔하고 중복 없이 (DRY) 수행할 수 있는 여러 가지 접근 방식이 있습니다. 그중 하나는 스키마 기반 유효성 검사 (schema-based validation)입니다. 지금부터 이 방식을 사용해 보겠습니다.

 

Zod 라이브러리를 활용하면 간단하고 읽기 쉬운 API로 스키마를 정의할 수 있습니다. 이제 Zod 기반 스키마를 사용하는 커스텀 Validation Pipe를 만들어 보겠습니다.

 

먼저 아래 명령어로 필요한 패키지를 설치하세요:

$ npm install --save zod

 

아래 코드 예제에서는 스키마를 생성자 인자로 받는 간단한 클래스를 생성합니다. 그런 다음 schema.parse() 메서드를 사용하여 전달된 스키마에 대해 들어온 인자를 검증합니다.

 

앞서 언급했듯이, 검증 파이프는 인자가 유효하면 값을 그대로 반환하고, 유효하지 않으면 예외를 던집니다.

 

다음 섹션에서는, @UsePipes() 데코레이터를 사용하여 특정 컨트롤러 메서드에 적절한 스키마를 공급하는 방법을 살펴봅니다. 이를 통해 우리가 의도했던 대로 검증 파이프를 다양한 컨텍스트에서 재사용할 수 있게 됩니다.

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

export class ZodValidationPipe implements PipeTransform {
  constructor(private schema: ZodSchema) {}

  transform(value: unknown, metadata: ArgumentMetadata) {
    try {
      const parsedValue = this.schema.parse(value);
      return parsedValue;
    } catch (error) {
      throw new BadRequestException('Validation failed');
    }
  }
}

검증 파이프 바인딩하기

앞서 우리는 ParseIntPipe와 같은 변환 파이프 (그리고 다른 Parse*  파이프들)를 바인딩하는 방법을 살펴보았습니다.

 

검증 파이프를 바인딩하는 방법도 매우 간단합니다.

 

이번 예제에서는 메서드 호출 수준에서 파이프를 바인딩하려고 합니다. 현재 예제에서는 ZodValidationPipe를 사용하기 위해 다음과 같은 작업이 필요합니다:

1. ZodValidationPipe 인스턴스를 생성합니다.
2. 파이프 생성자에 컨텍스트에 맞는 Zod 스키마를 전달합니다.
3. 해당 파이프를 메서드에 바인딩합니다.

Zod 스키마 예제:

import { z } from 'zod';

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

export type CreateCatDto = z.infer<typeof createCatSchema>;

 

우리는 아래와 같이 @UsePipes() 데코레이터를 사용하여 이를 수행합니다:

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

힌트
@UsePipes() 데코레이터는 @nestjs/common 패키지에서 가져옵니다.

경고
Zod 라이브러리를 사용하려면 tsconfig.json 파일에서 strictNullChecks 설정을 활성화해야 합니다.

클래스 검증기

경고
이 섹션의 기술들은 TypeScript를 필요로 하며, 애플리케이션이 순수 JavaScript로 작성된 경우에는 사용할 수 없습니다.

 

우리의 유효성 검사 기법에 대한 대체 구현 방법을 살펴보겠습니다.

 

Nest는 class-validator 라이브러리와 잘 연동됩니다. 이 강력한 라이브러리는 데코레이터 기반의 유효성 검사를 사용할 수 있게 해 줍니다. 데코레이터 기반의 유효성 검사는 특히 Nest의 파이프 기능과 결합되었을 때 매우 강력한데, 이는 처리 중인 속성의 메타타입에 접근할 수 있기 때문입니다. 시작하기에 앞서, 다음과 같은 패키지들을 설치해야 합니다:

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

 

이 패키지들이 설치되면, CreateCatDto 클래스에 몇 가지 데코레이터를 추가할 수 있습니다. 이 기법의 큰 장점 중 하나는 바로 여기에서 드러납니다: CreateCatDto 클래스가 우리의 POST body 객체에 대한 단일 진실의 원천 (single source of truth)으로 남는다는 점입니다 (따로 유효성 검사용 클래스를 만들 필요가 없습니다).

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

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

  @IsInt()
  age: number;

  @IsString()
  breed: string;
}

힌트
class-validator 데코레이터에 대해 더 알아보려면 여기에서 확인하세요.

 

이제 이러한 어노테이션을 사용하는 ValidationPipe 클래스를 생성할 수 있습니다.

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> {
  async transform(value: any, { metatype }: ArgumentMetadata) {
    if (!metatype || !this.toValidate(metatype)) {
      return value;
    }
    const object = plainToInstance(metatype, value);
    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];
    return !types.includes(metatype);
  }
}

힌트
다시 한번 말씀드리면, 이 장에서 보여준 기본적인 예제처럼 직접 일반적인 validation pipe를 만들 필요는 없습니다. Nest에서는 ValidationPipe를 기본적으로 제공합니다. 이 내장 ValidationPipe는 본 장에서 예제로 만든 것보다 더 다양한 옵션을 제공하며, 사용자 정의 pipe의 동작 방식을 설명하기 위해 단순하게 구성된 것입니다. 전체 세부사항과 다양한 예제는 여기에서 확인할 수 있습니다.

알림
위 예제에서는 class-transformer 라이브러리를 사용했으며, 이는 class-validator 라이브러리와 동일한 저자에 의해 개발되어 서로 잘 호환됩니다.

 

이 코드를 살펴봅시다. 먼저, transform() 메서드가 async로 표시되어 있다는 점에 주목하세요. Nest는 동기와 비동기 파이프를 모두 지원하기 때문에 이것이 가능합니다. 이 메서드를 async로 만든 이유는, class-validator의 일부 검증 작업이 비동기적으로 수행될 수 있기 때문입니다. (예: Promise를 사용하는 검증)

 

그다음으로, ArgumentMetadata 객체에서 metatype 필드만 추출하기 위해 구조 분해 할당을 사용합니다. 이는 ArgumentMetadata 전체를 받은 후 별도의 문장으로 metatype을 할당하는 방식보다 간결한 표현입니다.

 

이어서 toValidate()라는 헬퍼 함수에 주목하세요. 이 함수는 현재 처리 중인 인자가 기본 JavaScript 타입인 경우 유효성 검사를 생략하도록 합니다. 기본 타입에는 유효성 검사 데코레이터를 붙일 수 없기 때문에 검사할 이유가 없습니다.

 

그다음, class-transformer의 plainToInstance() 함수를 사용하여 일반 JavaScript 객체를 타입이 지정된 객체로 변환합니다. 네트워크 요청으로 역직렬화된 POST 바디 객체는 타입 정보가 없기 때문에 (Express의 플랫폼 동작 방식상 그렇습니다), 우리가 정의한 DTO 클래스에 선언된 유효성 검사 데코레이터를 적용하려면 이 변환이 반드시 필요합니다. 그래야 해당 객체를 단순한 일반 객체가 아닌 데코레이터가 부착된 클래스 인스턴스로 간주되어 유효성 검사를 수행할 수 있습니다.

 

마지막으로 다시 강조하자면, validation pipe는 유효한 경우 값을 그대로 반환하거나, 유효하지 않으면 예외를 던지는 것이 전부입니다.

 

이제 남은 단계는 ValidationPipe를 바인딩하는 것입니다. 파이프는 매개변수 스코프, 메서드 스코프, 컨트롤러 스코프 또는 전역 스코프에서 바인딩할 수 있습니다. 앞서 Zod 기반 파이프에서는 메서드 수준 바인딩 예시를 보았습니다. 아래 예제에서는 파이프 인스턴스를 @Body() 데코레이터에 바인딩하여, 요청 본문 (post body)의 유효성 검사를 수행합니다.

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

 

매개변수 스코프의 파이프는 검증 로직이 특정 매개변수 하나에만 관련될 때 유용합니다.

전역 스코프 파이프

전역 스코프 파이프는 ValidationPipe처럼 최대한 범용적으로 만들어진 파이프의 유용성을 극대화하기 위해 사용할 수 있으며, 이를 설정하면 애플리케이션 전역의 모든 라우트 핸들러에 자동으로 적용됩니다.

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

알림
하이브리드 애플리케이션의 경우 useGlobalPipes() 메서드는 게이트웨이와 마이크로서비스에는 파이프를 설정하지 않습니다. "표준" (하이브리드가 아닌) 마이크로서비스 애플리케이션에서는 useGlobalPipes()가 전역 파이프를 정상적으로 등록합니다.

 

전역 파이프는 애플리케이션 전체에 걸쳐 모든 컨트롤러와 라우트 핸들러에 사용됩니다.

 

의존성 주입 관점에서 보면, 어떤 모듈 외부에서 (useGlobalPipes()를 사용하여) 등록된 전역 파이프는 모듈 컨텍스트 밖에서 바인딩되었기 때문에 의존성을 주입받을 수 있습니다. 이 문제를 해결하기 위해, 다음과 같은 방식으로 모듈 내부에서 직접 전역 파이프를 설정할 수 있습니다:

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

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

힌트
이 방식으로 파이프에 대해 의존성 주입을 수행할 경우, 이 구성이 어떤 모듈에서 사용되든 상관없이 해당 파이프는 실제로는 전역 (global)입니다. 그렇다면 어디에서 이 작업을 수행해야 할까요? 위 예제에서처럼 파이프 (ValidationPipe)가 정의된 모듈에서 수행하는 것이 좋습니다. 또한 useClass는 커스텀 프로바이더를 등록하는 유일한 방법이 아니며, 이에 대한 더 많은 정보를 여기에서 확인할 수 있습니다.

내장 ValidationPipe

다시 한번 말씀드리지만, 범용적인 유효성 검사 파이프를 직접 만들 필요는 없습니다. Nest는 기본적으로 ValidationPipe를 내장하여 제공합니다. 내장된 ValidationPipe는 이 장에서 예시로 만든 기본 구현보다 훨씬 더 많은 옵션을 제공합니다. 이 장에서는 커스텀 파이프의 동작 방식을 설명하기 위해 단순한 샘플을 만든 것입니다. 전체 세부사항과 다양한 예제는 여기에서 확인할 수 있습니다.

변환 사용 사례

유효성 검사는 커스텀 파이프의 유일한 용도가 아닙니다. 이 장의 시작에서 언급했듯이, 파이프는 입력 데이터를 원하는 형식으로 변환 (transform) 하는 역할도 할 수 있습니다. 이는 transform() 함수에서 반환된 값이 해당 인자의 기존 값을 완전히 덮어쓰기 때문입니다.

 

이 기능은 언제 유용할까요? 때로는 클라이언트로부터 전달된 데이터를 라우트 핸들러에서 적절히 처리하기 전에 변환해야 하는 경우가 있습니다. 예를 들어, 문자열을 정수로 변환해야 할 수도 있고, 일부 필수 데이터 필드가 누락되었을 경우 기본값을 적용하고 싶을 수도 있습니다. 변환 파이프는 이러한 기능을 수행하기 위해 클라이언트 요청과 라우트 핸들러 사이에 처리 함수를 삽입하는 방식으로 동작합니다.

 

다음은 문자열을 정수로 파싱 하는 간단한 ParseIntPipe입니다. (위에서 언급했듯이, Nest는 더 정교한 내장 ParseIntPipe를 제공합니다. 이 예시는 단순한 커스텀 변환 파이프의 예입니다.)

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

 

그런 다음 아래와 같이 이 파이프를 특정 매개변수에 바인딩할 수 있습니다:

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

 

또 다른 유용한 변환 사례는 요청에 포함된 ID를 사용하여 데이터베이스에서 기존 사용자 엔티티를 조회하는 것입니다:

@Get(':id')
findOne(@Param('id', UserByIdPipe) userEntity: UserEntity) {
  return userEntity;
}

 

이 파이프의 구현은 독자에게 맡기지만, 다른 모든 변환 파이프와 마찬가지로 입력 값 (ID)을 받아 출력 값 (UserEntity 객체)을 반환한다는 점에 주목하세요. 이러한 방식은 핸들러에서 반복되는 보일러플레이트 코드를 공통 파이프로 추출함으로써 코드의 선언적 성격을 높이고 DRY 원칙을 지키는 데 도움이 됩니다.

기본값 제공하기

Parse* 파이프는 매개변수 값이 정의되어 있기를 기대합니다. null 또는 undefined 값을 받으면 예외를 발생시킵니다. 쿼리 문자열 매개변수 값이 누락된 경우에도 엔드포인트가 이를 처리할 수 있도록 하려면, Parse* 파이프가 동작하기 전에 주입할 기본값을 제공해야 합니다. 이를 위해 DefaultValuePipe를 사용합니다. 아래 예시와 같이, @Query() 데코레이터 안에서 관련된 Parse* 파이프 앞에 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 });
}

---

가드

가드는 @Injectable() 데코레이터가 붙은 클래스이며, CanActivate 인터페이스를 구현합니다.

 

가드는 하나의 책임만을 가집니다. 런타임에 특정 조건 (예: 권한, 역할, ACL 등)에 따라 요청을 해당 라우트 핸들러가 처리할 수 있는지 여부를 결정합니다. 이는 흔히 인가 (authorization)라고 불립니다. 인가 (authorization)와 자주 함께 사용되는 인증 (authentication)은 전통적인 Express 애플리케이션에서는 보통 미들웨어를 통해 처리해 왔습니다. 인증은 토큰 검증이나 요청 객체에 속성 추가 등 특정 라우트와 강하게 연관되지 않은 작업이기 때문에 미들웨어로 처리하기에 적절합니다.

 

하지만 미들웨어는 본질적으로 어떤 핸들러가 실행될지 모르는 상태에서 next()를 호출하기 때문에 "무지한 (dumb)" 존재입니다. 반면, 가드는 ExecutionContext 인스턴스에 접근할 수 있기 때문에 다음에 어떤 핸들러가 실행될지를 정확히 알고 있습니다. 가드는 예외 필터, 파이프, 인터셉터처럼 요청/응답 사이클의 정확한 지점에 처리 로직을 삽입할 수 있도록 설계되었으며, 선언적으로 사용할 수 있습니다. 이를 통해 코드의 중복을 줄이고 선언적인 스타일을 유지할 수 있습니다.

힌트
가드는 모든 미들웨어가 실행된 이후, 인터셉터나 파이프가 실행되기 전에 실행됩니다.

인가 가드

앞서 언급했듯이, 인가 (authorization)는 가드의 대표적인 사용 사례입니다. 특정 라우트는 오직 호출자 (일반적으로 인증된 사용자)가 충분한 권한을 가지고 있을 때만 접근 가능해야 합니다. 지금부터 만들 AuthGuard는 사용자가 이미 인증되었음을 전제로 하며, 요청 헤더에 토큰이 포함되어 있다고 가정합니다. 이 가드는 요청에서 토큰을 추출하고 검증한 후, 추출된 정보를 바탕으로 해당 요청을 진행할 수 있을지를 결정합니다.

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

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

힌트
애플리케이션에 실제 인증 (authentication) 메커니즘을 구현하는 방법이 궁금하다면, 이 장 (chapter)을 참고하세요. 보다 정교한 인가 (authorization) 예제를 보고 싶다면, 이 페이지를 확인해 보세요.

 

validateRequest() 함수 안의 로직은 필요에 따라 간단하거나 정교할 수 있습니다. 이 예제의 핵심은 가드 (guard)가 요청/응답 사이클에 어떻게 들어맞는지를 보여주는 것입니다.

 

모든 가드는 canActivate() 함수를 구현해야 합니다. 이 함수는 현재 요청이 허용되는지를 나타내는 불리언 값을 반환해야 합니다. 이 반환은 동기적일 수도 있고, 비동기 (Promise나 Observable) 일 수도 있습니다. Nest는 이 반환값을 사용해 다음 동작을 제어합니다:

• true를 반환하면 요청은 처리됩니다.
• false를 반환하면 Nest는 요청을 거부합니다.

실행 컨텍스트

canActivate() 함수는 하나의 인자, 즉 ExecutionContext 인스턴스를 받습니다. ExecutionContext는 ArgumentsHost를 상속합니다. ArgumentsHost는 예외 필터 장에서 이미 살펴본 바 있습니다. 위의 예제에서는 Request 객체에 대한 참조를 얻기 위해, 앞서 사용했던 ArgumentsHost의 동일한 헬퍼 메서드들을 그대로 사용하고 있습니다. 자세한 내용은 예외 필터 장의 Arguments host 섹션을 참조하세요.

 

ArgumentsHost를 상속함으로써 ExecutionContext는 현재 실행 프로세스에 대한 추가적인 세부 정보를 제공하는 새로운 헬퍼 메서드들도 포함하게 됩니다. 이러한 정보들은 다양한 컨트롤러, 메서드, 실행 컨텍스트에서 모두 동작할 수 있는 보다 범용적인 가드를 만들 때 유용하게 사용될 수 있습니다. ExecutionContext에 대해 더 알아보려면 ExecutionContext 문서를 참고하세요.

역할 기반 인증

특정 역할 (role)을 가진 사용자만 접근할 수 있도록 허용하는 좀 더 기능적인 가드 (guard)를 만들어봅시다. 우선은 기본적인 가드 템플릿으로 시작해서, 이후 섹션에서 점차 기능을 추가해 나가겠습니다. 지금 단계에서는 모든 요청을 허용하는 형태입니다.

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

가드 바인딩

파이프 (pipes)나 예외 필터 (exception filters)와 마찬가지로, 가드도 컨트롤러 범위 (controller-scoped), 메서드 범위 (method-scoped) 또는 전역 범위 (global-scoped)로 설정할 수 있습니다. 아래 예시는 @UseGuards() 데코레이터를 사용하여 컨트롤러 범위의 가드를 설정한 것입니다. 이 데코레이터는 하나의 인자 또는 쉼표로 구분된 여러 개의 인자를 받을 수 있어, 필요한 가드들을 한 번에 적용할 수 있습니다.

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

힌트
@UseGuards() 데코레이터는 @nestjs/common 패키지에서 import 됩니다.

 

위 예시에서 우리는 RolesGuard 클래스를 (인스턴스가 아닌) 전달했습니다. 이는 인스턴스화를 Nest 프레임워크에 맡기고 의존성 주입을 가능하게 합니다. 파이프나 예외 필터와 마찬가지로, 직접 생성한 인스턴스를 전달할 수도 있습니다.

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

 

위의 구조는 해당 컨트롤러에 선언된 모든 핸들러에 가드를 적용합니다. 가드를 특정 메서드에만 적용하고 싶다면 @UseGuards() 데코레이터를 메서드 수준에 지정하면 됩니다.

 

전역 가드를 설정하려면 Nest 애플리케이션 인스턴스의 useGlobalGuards() 메서드를 사용합니다:

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

알림
하이브리드 앱의 경우, useGlobalGuards() 메서드는 기본적으로 게이트웨이나 마이크로서비스에 대해 가드를 설정하지 않습니다 (이 동작을 변경하는 방법은 하이브리드 애플리케이션 문서를 참조하세요). "표준" (비하이브리드) 마이크로서비스 앱의 경우에는 useGlobalGuards()가 가드를 전역으로 설정합니다.

 

전역 가드는 애플리케이션 전체에 걸쳐 모든 컨트롤러와 모든 라우트 핸들러에 적용됩니다. 의존성 주입 (Dependency Injection) 측면에서 보면, 어떤 모듈 외부에서 (위의 예제처럼 useGlobalGuards()를 사용하여) 전역 가드를 등록하면, 모듈의 컨텍스트 외부에서 바인딩이 이루어지기 때문에 의존성을 주입할 수 없습니다. 이 문제를 해결하려면, 아래와 같은 방식으로 가드를 모듈 내부에서 직접 설정할 수 있습니다:

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

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

힌트
이 방식으로 가드에 대해 의존성 주입을 수행할 때, 이 구성이 어떤 모듈에서 사용되었는지에 관계없이 해당 가드는 전역 (Global) 가드가 된다는 점에 유의하세요. 이 작업은 가드 (위 예제에서는 RolesGuard)가 정의된 모듈에서 수행하는 것이 좋습니다. 또한, useClass는 커스텀 프로바이더 등록을 처리하는 유일한 방법이 아닙니다. 이에 대한 더 많은 정보는 여기에서 확인할 수 있습니다.

핸들러별 역할 설정하기

RolesGuard는 현재 작동 중이지만, 아직 그렇게 똑똑하진 않습니다. 가장 중요한 가드 기능인 실행 컨텍스트 (Execution Context)를 아직 제대로 활용하지 못하고 있죠. 현재 이 가드는 역할 (Role)에 대해 아무것도 모르고, 각 핸들러마다 허용된 역할이 무엇인지도 인식하지 못합니다. 예를 들어 CatsController는 경로마다 다른 권한 체계를 가질 수 있습니다. 일부는 관리자 (admin)만 접근할 수 있고, 다른 일부는 모두에게 열려 있을 수도 있죠. 그렇다면 어떻게 경로마다 역할을 유연하고 재사용 가능한 방식으로 매칭할 수 있을까요?

 

여기서 커스텀 메타데이터 (Custom Metadata)가 등장합니다 (자세히 알아보기) Nest는 Reflector.createDecorator 정적 메서드를 사용해 생성된 데코레이터 또는 내장된 @SetMetadata() 데코레이터를 통해 라우트 핸들러에 커스텀 메타데이터를 부착할 수 있는 기능을 제공합니다.

 

예를 들어, Reflector.createDecorator 메서드를 사용해서 핸들러에 메타데이터를 부착하는 @Roles() 데코레이터를 다음과 같이 만들 수 있습니다. Reflector는 Nest 프레임워크에서 기본적으로 제공되며 @nestjs/core 패키지에서 노출됩니다.

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

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

 

여기서 Roles 데코레이터는 string[] 타입의 인자를 받는 함수입니다.

 

이제 이 데코레이터를 사용하면, 단순히 해당 핸들러 위에 다음과 같이 주석을 달아주면 됩니다:

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

 

여기서는 create() 메서드 위에 Roles 데코레이터의 메타데이터를 부착하여, admin 역할을 가진 사용자만 이 경로에 접근할 수 있도록 지정한 것입니다.

 

또한, Reflector.createDecorator 메서드를 사용하는 대신, Nest에서 제공하는 내장 데코레이터인 @SetMetadata()를 사용할 수도 있습니다. 이에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

모두 결합하기

이제 다시 RolesGuard로 돌아가서 앞서 설명한 내용을 결합해 보겠습니다. 현재는 모든 요청을 허용하도록 항상 true를 반환하고 있지만, 우리는 현재 사용자에게 할당된 역할 (roles)과 현재 라우트에 요구되는 역할 (roles)을 비교해서 조건적으로 처리되도록 만들고자 합니다.

 

이를 위해, 현재 처리 중인 라우트에 설정된 역할 (커스텀 메타데이터)을 읽어야 하며, 이를 위해 다시 Reflector 헬퍼 클래스를 사용하게 됩니다.

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 {
    const roles = this.reflector.get(Roles, context.getHandler());
    if (!roles) {
      return true;
    }
    const request = context.switchToHttp().getRequest();
    const user = request.user;
    return matchRoles(roles, user.roles);
  }
}

힌트
Node.js 세계에서는 인증된 사용자 (user)를 request 객체에 첨부하는 것이 일반적인 관례입니다. 따라서 위의 예제 코드에서는 request.user가 사용자 인스턴스와 허용된 역할 정보를 담고 있다고 가정합니다. 실제 애플리케이션에서는 사용자 인증 가드나 미들웨어 내에서 이 연결을 직접 구현해야 합니다. 이 주제에 대한 자세한 내용은 해당 챕터를 참고하세요.

경고
matchRoles() 함수 내부의 로직은 필요에 따라 단순하거나 복잡하게 구성할 수 있습니다. 이 예제의 핵심 목적은 가드 (Guard)가 요청/응답 사이클에 어떻게 작동하는지를 보여주는 것입니다.

 

Execution context 장의 Reflection and metadata 섹션을 참고하면, Reflector를 컨텍스트에 따라 어떻게 활용할 수 있는지에 대한 자세한 내용을 확인할 수 있습니다.

 

권한이 부족한 사용자가 엔드포인트를 요청하면, Nest는 자동으로 다음과 같은 응답을 반환합니다:

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

 

주의할 점은, 내부적으로 가드가 false를 반환하면 프레임워크는 자동으로 ForbiddenException을 던집니다. 다른 오류 응답을 반환하고 싶다면, 직접 특정 예외를 던져야 합니다. 예를 들어:

throw new UnauthorizedException();

 

가드에서 발생한 모든 예외는 예외 처리 계층 (전역 예외 필터 및 현재 컨텍스트에 적용된 예외 필터)에 의해 처리됩니다.

힌트
실제 애플리케이션에서 권한 부여를 구현하는 예제를 찾고 있다면, 이 장을 확인하세요.

Reference

• Nest.js | Pipes
• Nest.js | Guards