[NestJS] DTO와 유효성 검사

| 서론

안녕하세요 팡일입니다.

 

Nest.js로 API를 개발하다 보면 단순히 기능을 구현하는 것뿐만 아니라, 클라이언트로부터 전달받는 데이터의 안정성과 신뢰성을 보장하는 것이 매우 중요하다는 것을 느끼게 됩니다.

 

특히 잘못된 데이터가 서버로 들어올 경우 예상치 못한 에러나 버그로 이어질 수 있기 때문에, 입력 데이터에 대한 검증(validation)은 필수적인 과정입니다.

 

Nest.js에서는 이러한 문제를 해결하기 위해 DTO(Data Transfer Object)와 Validation Pipe를 함께 사용하여 데이터 구조 정의 + 유효성 검사를 동시에 처리할 수 있습니다.

 

이번 글에서는 DTO의 개념부터 시작해서, class-validator를 활용한 유효성 검사, 그리고 ValidationPipe를 적용하는 방법까지 실제 코드와 함께 흐름 중심으로 정리해보겠습니다.

 

 

 

| DTO란?

1) 정의

DTO(Data Transfer Object)는 프로세스 간에 데이터를 전달하는 객체입니다. 계층 간(Controller, Service, Repository 등) 데이터 교환 시 사용되며, 데이터베이스의 로직을 포함하지 않고, 순수하게 데이터 자체의 구조(Shape)만을 정의합니다.

 

 

2) DTO를 사용하는 이유

• 데이터 구조의 명세화
  : 클라이언트가 어떤 데이터를 보내야 하는지 명확하게 정의할 수 있다.
• 코드의 가독성 및 유지보수
  : 어떤 필드가 필수인지, 어떤 타입인지 코드를 통해 즉시 파악할 수 있다.
• 타입 안정성
  : TypeScript의 타입 시스템을 활용하여 컴파일 단계에서 오류를 사전에 방지할 수 있다.

 

3) NestJS에서의 DTO 구현 (interface vs Class)

NestJS에서 DTO를 정의할 때, TypeScript의 interface 보다 Class 사용할 것을 강력히 권장합니다.

• interface : 트랜스파일링(Transpilation) 과정에서 제거되므로, 런타임에는 존재하지 않는다. 따라서 런타임에 동작하는 NestJS의 기능 (Pipe, Validation 등)이 참조할 수 없다.
• Class : 자바스크립트의 표준 기능이므로, 컴파일 후에도 실제 값으로 남아 있다. 이를 통해 NestJS는 런타임 파이프와 데코레이터를 통해 메타데이터를 참조하고 유효성 검사를 수행할 수 있다.

 

4) 예시

export class CreatePostDto {
  title: string;
  content: string;
  author: string;
  major: string;
}

 

 

 

| 파이프

1) 개념

Pipe는 @Injectable() 데코레이터가 달린 클래스로, PipeTransform 인터페이스를 구현합니다.

 

쉽게 말하면, NestJS의 요청 생명주기에서 클라이언트의 요청이 라우트 핸들러(Controller 메서드)에 도달하기 직전에 작동한다는 의미입니다.

 

 

2) 주요 역할

Pipe는 크게 두 가지 목적을 위해 사용됩니다.

• 변환 (Transformation) : 입력 데이터를 원하는 형식으로 변환한다. (예 : 문자열 '10'을 정수 10으로 변환)
• 유효성 검사(Validation Check) : 입력 데이터가 정해진 포맷에 맞는지 확인한다. 유효하다면 데이터를 그대로 전달하고, 그렇지 않다면 예외(Exception)를 발생시켜 처리를 중단한다.

 

| DTO와 Validation Pipe의 통합

DTo만으로는 데이터의 '타입'을 정의할 수 있지만, '값의 조건' (예: 비어있지 않음. 필수 값 설정, 최소 길이 등)은 강제할 수 없습니다. 이를 위해 DTO에 유효성 검사 규칙을 부여하고, Pipe를 통해 이를 실행합니다.

 

1) 필수 라이브러리

NestJS는 class-validator와 class-transformer 라이브러리와 완벽하게 통합됩니다.

• class-validator : 데코레이터 기반의 유효성 검사를 제공한다.
• class-tnrasformer : 일반 객체를 클래스의 인스턴스로 변환한다. 

 

 

2) 설치 명령어

npm install --save class-validator class-transformer

 

 

3) DTO에 Validation 데코레이터 적용

앞서 정의한 DTO에 제약 조건을 데코레이터 형태로 추가합니다.

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

export class CreatePostDto {
  @IsString()
  @IsNotEmpty()
  title: string;

  @IsString()
  @IsNotEmpty()
  content: string;

  @IsString()
  @IsNotEmpty()
  author: string;

  @IsString()
  @IsNotEmpty()
  major: string;
}

 

 

4) Controller에 VaildationPipe 적용

작성된 DTO를 컨트롤러에서 사용할 때 ValidationPipe를 연결합니다. 이 파이프는 요청 본문(Body)를 받아 CreatePostDto 클래스의 인스턴스로 변환한 뒤, 정의된 데코레이터 규칙을 검사합니다.

import { Controller, Post, Body, UsePipes, ValidationPipe } from '@nestjs/common';
import { CreatePostDto } from './dto/create-post.dto';

@Controller('board')
export class BoardsController {
  @Post()
  @UsePipes(new ValidationPipe()) // 해당 핸들러에 파이프 적용
  create(@Body() createPostDto: CreatePostDto) {
    // 이곳에 도달했다면 유효성 검사를 통과한 상태임이 보장됨
    return 'This action adds a new post';
  }
}

 

 

5) 전역 스코프 적용 (Global Pipe)

개별 핸들러마다 파이프를 적용하는 대신, 애플리케이션 전체에 적용하여 모든 요청에 대해 유효성 검사를 수행할 수도 있습니다.

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

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

  // 전역 파이프 설정
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true, // DTO에 정의되지 않은 속성은 자동으로 제거
      forbidNonWhitelisted: true, // 정의되지 않은 속성이 있으면 요청 자체를 막음
      transform: true, // 요청 데이터를 DTO의 타입으로 자동 변환
    }),
  );

  await app.listen(3000);
}

bootstrap();

 

 

 

| 예시

DTO(Data Transfer Object)를 사용하면 클라이언트로부터 전달받는 데이터의 형태를 엄격하게 검증할 수 있습니다.

 

특히 ValidationPipe를 적용하면, DTO에 정의되지 않은 값이나 잘못된 타입이 들어올 경우 자동으로 에러를 발생시킵니다.

 

1) 잘못된 DTO Request를 보낸 경우

 

위와 같이 잘못된 요청을 보낸 경우를 보면, author, major 값이 누락되었거나 타입이 맞지 않습니다.

• 이로 인해, 400 Bad Request 에러 발생하였고, 어떤 필드가 잘못되었는지 상세 메시지 반환합니다.

 

즉, DTO에서 정의한 조건을 하나라도 만족하지 않으면 요청 자체가 거부됩니다. 

 

 

2) 올바른 DTO Request를 보낸 경우

 

 

올바르게 보낸 경우에는 문제가 없음을 확인할 수 있습니다.

 

 

 

| 결론

이번 글에서는 DTO와 Validation Pipe를 활용하여 Nest.js에서 입력 데이터를 검증하는 방법을 정리해보았습니다.

 

DTO를 사용하면 데이터의 구조를 명확하게 정의할 수 있고, Validation Pipe와 class-validator를 함께 사용하면 잘못된 요청을 사전에 차단할 수 있는 안정적인 API를 만들 수 있습니다.

 

특히 DTO에 데코레이터만 추가해도 자동으로 유효성 검사가 수행된다는 점은 Nest.js의 큰 장점 중 하나라고 느꼈습니다.

 

또한 실제 테스트를 통해 확인해보면 조건을 만족하지 않는 요청은 400 에러와 함께 상세 메시지를 반환하기 때문에, 디버깅과 협업에도 큰 도움이 됩니다.

 

앞으로는 DTO를 기반으로 Swagger 문서화, 데이터 변환(transform), 그리고 DB 연동까지 확장하면서 보다 실제 서비스에 가까운 구조로 발전시켜보는 것이 다음 단계가 될 것 같습니다.