기술과 산업/언어 및 프레임워크

NestJS 마스터 시리즈 11화. 파이프(Pipe) – 요청 데이터의 정제와 전처리 전략

B컷개발자 2025. 5. 7. 01:02
728x90

“검증과 전처리는 컨트롤러가 아닌 파이프가 해야 한다”

 

NestJS의 Pipe 시스템을 통해 요청 데이터를 정제하고 가공하는 방법을 소개합니다. ValidationPipe, TransformPipe, 커스텀 Pipe 구현 전략까지 실무 중심으로 설명합니다.

 

 

요청 데이터를 다루는 책임, 어디까지 맡길 것인가

 

API를 설계하다 보면 다음과 같은 질문이 반복된다.

 

  • 클라이언트가 보낸 문자열을 숫자로 바꿔야 할까?
  • 유효하지 않은 ID는 컨트롤러에서 거를까?
  • 중복된 데이터 변환 로직을 어떻게 제거할까?

 

NestJS에서는 이 모든 고민을 Pipe를 통해 해결할 수 있다.

 

 

Pipe란 무엇인가

 

NestJS에서 Pipe는 요청 핸들러에 전달되기 직전의 데이터를 다루는 컴포넌트다.

두 가지 핵심 기능을 가진다:

 

  1. 데이터 유효성 검사 (Validation)
  2. 데이터 변환 (Transformation)

 

 

기본 구조 – Pipe 인터페이스

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

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

 

  • PipeTransform 인터페이스를 구현하고, transform() 메서드를 통해 데이터를 가공한다.
  • 실패 시에는 예외를 throw하여 요청 자체를 차단할 수 있다.

 

 

내장 파이프 예시

 

NestJS는 다음과 같은 유용한 파이프를 기본 제공한다:

파이프설명

ValidationPipe class-validator 기반 유효성 검사 수행
ParseIntPipe 문자열을 정수로 변환
ParseBoolPipe 문자열을 불리언으로 변환
DefaultValuePipe 기본값 설정
ParseUUIDPipe UUID 형식 검사 및 변환

 

 

 

실전 예제 – URL 파라미터를 숫자로 변환

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

 

  • 클라이언트가 문자열 "10"을 보내더라도, 컨트롤러에서는 숫자 10으로 전달된다.
  • 잘못된 값이면 자동으로 400 에러 반환

 

 

ValidationPipe – DTO와 함께 유효성 검사 자동화

@Post()
create(@Body(new ValidationPipe()) createUserDto: CreateUserDto) {
  return this.usersService.create(createUserDto);
}

또는 전역 등록:

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
);

옵션 설명:

 

  • whitelist: DTO에 정의되지 않은 속성 제거
  • forbidNonWhitelisted: 허용되지 않은 속성 포함 시 에러 반환
  • transform: 요청 데이터를 DTO 타입으로 자동 변환

 

 

커스텀 파이프 – 복잡한 비즈니스 로직도 대응 가능

@Injectable()
export class UppercasePipe implements PipeTransform {
  transform(value: string): string {
    return value.toUpperCase();
  }
}

사용 예시:

@Get()
search(@Query('keyword', UppercasePipe) keyword: string) {
  return this.searchService.find(keyword);
}

 

  • 모든 키워드 입력을 대문자로 자동 변환
  • 컨트롤러 로직은 순수하게 유지

 

 

파이프 vs 인터셉터 – 언제 어떤 걸 쓰나?

기능파이프인터셉터

요청 데이터 가공 O X
유효성 검사 O X
응답 데이터 가공 X O
비즈니스 흐름 제어 X O

 

  • 파이프는 데이터 전처리 도구,
  • 인터셉터는 흐름 제어 도구라고 보면 된다.

 

 

마무리 인사이트

 

NestJS의 Pipe는 단순한 유효성 검사를 넘어서, 요청 데이터의 입구에서부터 구조적 품질을 보장하는 장치다.

모든 API는 결국 입력을 잘 다루는 것에서 시작된다.

 

  • 유효하지 않은 입력은 파이프에서 차단하고
  • 형이 맞지 않는 값은 파이프에서 변환하며
  • 컨트롤러는 비즈니스 로직에 집중할 수 있어야 한다

 

“좋은 API는, 나쁜 입력을 컨트롤러에 들여보내지 않는다”

 

 

다음 회차 예고

 

NestJS 마스터 시리즈 12화. 모듈 간 의존성 순환 문제와 해결 전략

Circular Dependency 문제를 인식하고 해결하는 구조적 설계 기법을 다룹니다.

 

728x90