Nest.js Pipe

김민석·2026년 3월 13일

Pipe란

파이프는 @Injectable 데코레이터 주석이 달린 클래스.
파이프는 데이터 변형과 데이터 유효성 검사를 위해 사용됨
파이프는 컨트롤러에서 처리되는 인수에 대해 작동함.
즉 컨트롤러에 있는 메소드는 클라이언트에서 받아온 데이터를 pipe를 통해 유효성 및 변형 과정을 통과해야 작동할 수 있음. 통과하지 못하면 Error 발생

Pipe 사용법

크게 Handler-level-pipe,Parameter-level-pipe,Global-level-pipe가 있음.

Handler-level-pipe

하나의 핸들러(메서드)에 pipe를 적용하는 방법 @UsePipes()를 사용하면됨. 해당 핸들러의 모든 파라미터에 적용됨.

@Post()
@UsePipes(myPipe)
createBoard(@Body() createBoardDto : CreateBoardDto) {
	
}

CreateBoardDto안에 모든 파라미터에 적용됨.

Parameter-level-Pipes

특정 파라미터에게만 적용되는 파이프

@Post()
createBoard(@Body('title',myPipe)) {
	
}

해당 title 파라미터만 myPipe가 적용됨.

Global-Pipes

애플리케이션 전체의 파이프. 클라이언트에서 들어오는 모든 요청에 적용됨. main.ts에 적용하면됨.

app.useGlobalPipes(GlobalPipes);

Built-in Pipes

Nest.js에 기본적으로 사용할 수 있게 만들어 놓은 6가지 파이프

ValidationPipe
ParseIntPipe
ParseBoolPipe
ParseArrayPipe
ParseUUIDPipe
DefaultValuePipe

Pipe Validation

npm i class-validator class-transformer --save
두가지의 모듈을 설치함. class-validator, class-transformer

그 후 컨트롤러에 가면

@Post()

  createBoard(@Body() createBoardDto: CreateBoardDto): Board {
    return this.boardsService.createBoard(createBoardDto)
  }

이렇게 되어있따. 그래서 파라미터는 createboardDto에 존재하니까 createboardDto에 간다. 그 후 여기서 유효성 검사를 해준다. 우리는 IsNotEmpty를 써줄것이다

import { IsNotEmpty } from "class-validator";

export class CreateBoardDto {
  @IsNotEmpty()
  title: string;

  @IsNotEmpty()
  description: string;
}

이렇게 해준 후 핸들러 단위로 파이프 설정을 해줄 것이다.

@Post()
  @UsePipes(ValidationPipe)
  createBoard(@Body() createBoardDto: CreateBoardDto): Board {
    return this.boardsService.createBoard(createBoardDto)
  }

UsePipes와 ValidationPipe를 통해 사용할 수 있다. 이렇게 되면 우리는 IsNotEmpty를 사용했기 떄문에 클라이언트에서 빈값으로 title 혹은 description이 온다면 에러가 뜰 것이다.

에러처리

getBoardById(id: string): Board {
    const board = this.boards.find(board => board.id === id);
    if (!board) {
      throw new NotFoundException(`Board with id ${id} not found`);
    }
    return board;
  }

NotFoundException을 사용하여 예외 에러 처리

커스텀 파이프

@Injectable()
export class PositiveIntPipe implements PipeTransform {
  transform(value: number,metadata:ArgumentMetadata) {
    if (value <= 0) {
      throw new BadRequestException('양수만 가능합니다.');
    }
    console.log("meta",metadata);
    return value;
  }
}

커스텀 파이프를 만들때는 PipeTransform를 꼭 implements 해줘야됨. 그리고 모든 파이프는 transform이라는 메서드가 꼭 필요.

transform 메서드

첫번째 value는 처리가 된 값.
metadata는 인자에 대한 메타 데이터를 포함한 객체.

커스텀 파이프 구성

import { ArgumentMetadata, BadRequestException, PipeTransform } from "@nestjs/common";
import { BoardStatus } from "../boards.model";

export class BoardsStatusValidationPipe implements PipeTransform {

  readonly StatusOptions = [
    BoardStatus.PUBLIC,
    BoardStatus.PRIVATE
  ]

  transform(value: any, metadata: ArgumentMetadata) {
    value = value.toUpperCase();
    if (!this.isStatusValid(value)) {
      throw new BadRequestException(`{value} is not Status Options`)
    }
    return value;
  }

  private isStatusValid(status: any): boolean {
    const index = this.StatusOptions.indexOf(status);
    return index !== -1;
  }
}

위 커스텀 파이프는 변경되는 status의 유효성을 검사하는 것 . value로 받아온 status 값을 statusOption을 통해 isStatusValid 메서드로 가서 지정한 옵션중에 있는지 확인한다 없다면 에러를 반환하고 있다면 value를 반환해 허용해준다. 이러한 커스텀 파이프를 사용해 아래와 같이 파라미터 파이프 처럼 사용이 가능하다.

@Patch("/:id/status")
  updateBoardStatus(@Param("id") id: string, @Body('status', BoardsStatusValidationPipe) status: BoardStatus) {
    return this.boardsService.updateBoardStatus(id, status);
  }