📡 04. DTO와 검증 — 쓰레기 데이터는 입구 컷 (Garbage In, Error Out)

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 DTO와 class-validator — 철통 보안 문지기 🟡
• 🧩 내장 파이프와 유틸리티 🟢
• 🧪 따라해보기: 실전 회원가입 DTO 깎아보기
• 💼 베스트 프랙티스와 실무 팁
• 💥 에러 해결 카탈로그
• 🗂️ 치트시트
• 📝 마무리 퀴즈

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분

🧳 전제 지식 체크리스트

• 데코레이터(@) 문법의 기본 형태를 안다.
• 02장 컨트롤러에서 HTTP 본문을 가져오는 @Body() 사용법을 보았다.

🗺️ 이 문서의 흐름
데이터 검증의 필요성 → class-validator 설정과 사용법 → 파이프(Pipe)로 형변환하기 → 최신 방식인 Zod 연동 → 자주 겪는 에러

🎯 이 문서를 다 읽으면 할 수 있는 것

• 클라이언트가 보낸 데이터가 숫자인지, 이메일 형식인지 100% 보장하는 코드를 작성할 수 있다.
• 불필요한/악의적인 필드(admin: true 등)를 서버 입구에서 자동으로 걸러낼 수 있다.
• Zod 스키마를 이용해 DB 모델과 완벽하게 일치하는 DTO를 뽑아낼 수 있다.

🤔 왜 알아야 하는가

프론트엔드에서 아무리 폼(Form) 검증을 빡세게 해놔도, 해커나 악성 봇은 Postman 같은 툴로 서버 API에 직접 이상한 문자열을 꽂아 넣어.
만약 나이(age) 필드에 {"age": "백살"} 이라는 문자열이 그대로 DB에 들어가려고 한다면? 서버가 뻗거나 데이터베이스가 오염되겠지?
DTO와 파이프는 이런 "치명적인 쓰레기 데이터"를 컨트롤러에 도착하기도 전에 가차 없이 쳐내는 방어막 이야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?

DTO (Data Transfer Object) 는 깐깐한 고급 클럽의 입장 제한 규칙표 야.
"나이는 숫자여야 해. 이름은 무조건 2글자 이상이어야 해. 이메일 형식 아니면 입구 컷!"
ValidationPipe (유효성 검사 파이프) 는 그 규칙표를 들고 서 있는 덩치 큰 기도(문지기) 야.
손님(Request)이 오면 신분증(Body 데이터)을 쫙 훑어보고, 규칙표에 하나라도 어긋나면 "돌아가라(400 Bad Request)" 하고 문전박대해버려. 덕분에 클럽 안(컨트롤러와 서비스)은 항상 물이 깨끗하지!

🧩 DTO와 class-validator — 철통 보안 문지기 🟡

🎯 이 섹션을 읽고 나면:

• 전역 파이프 useGlobalPipes의 필수 설정 3가지를 설명할 수 있다.
• @Is... 계열 데코레이터를 자유롭게 조합할 수 있다.

🤔 잠깐, 먼저 생각해봐
TypeScript는 컴파일 타임에만 작동해. 실행 중(런타임)에 클라이언트가 몰래 JSON을 보내면 TypeScript의 interface는 그걸 막아줄 수 있을까?
(정답: 못 막아! 그래서 런타임에 살아남는 class와 데코레이터를 쓰는 거야.)

1단계: 전역 글로벌 파이프(기도) 세우기

프로젝트 전체에 단 한 번만 설정하면 돼. (main.ts)

import { ValidationPipe } from '@nestjs/common';
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,            // 1. 규칙표에 없는 속성은 스윽 무시/삭제해버림 (핵심 보안!)
    forbidNonWhitelisted: true, // 2. 규칙표에 없는 걸 보내면 아예 400 에러를 뱉음 (선택)
    transform: true,            // 3. 문자열 "1"을 알아서 숫자 1로 바꿔줌 (개꿀 기능)
  }));
  
  await app.listen(3000);
}

2단계: DTO 클래스(규칙표) 만들기

필요한 라이브러리를 설치하고(npm i class-validator class-transformer),
마자막으로 DTO 클래스를 만들어 데코레이터를 덕지덕지 붙여주면 끝!

import { IsEmail, IsString, Length, IsOptional, Min } from 'class-validator';
 
export class CreateUserDto {
  @IsEmail({}, { message: '제대로 된 이메일을 적어주세요!' })
  email: string;
 
  @IsString()
  @Length(2, 20)
  name: string;
 
  @IsOptional()  // 👈 안 보내도 상관없다는 뜻!
  @Min(14, { message: '14세 이상만 가입 가능합니다.' })
  age?: number;
}

이제 컨트롤러에서 @Body() dto: CreateUserDto 라고 적기만 하면, 컨트롤러 내부 코드부터는 dto.age가 100% 완벽한 숫자형이거나, 아니면 아예 존재하지 않는다는 것 을 맘 놓고 확신할 수 있어.

🧩 내장 파이프와 유틸리티 🟢

복잡한 객체 덩어리(@Body)는 DTO와 class-validator가 처리해 주지만, 단순한 URL 변수(@Param, @Query) 검사에는 내장 파이프(Built-in Pipe) 가 최고야.

대표적인 내장 파이프 4가지

1. ParseIntPipe: 문자열을 무조건 정수로 바꿈. 실패하면 400 에러!

   @Get(':id')
   findOne(@Param('id', ParseIntPipe) id: number) {}

2. ParseBoolPipe: "true", "false", "1", "0" 등을 깔끔한 불리언 타입으로.
3. ParseUUIDPipe: 문자열이 UUID 포맷인지 깐깐하게 검증.
4. DefaultValuePipe: 쿼리스트링이 안 넘어왔을 때 기본값 세팅.

   @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number

Mapped Types (코드 복붙 방지기)

회원가입 용 DTO(CreateDto)가 있는데, 정보 수정 용 DTO(UpdateDto)를 만들고 싶을 때, 내용물을 또 다 복붙해야 할까? NO!

import { PartialType } from '@nestjs/mapped-types';
 
// UpdateDto는 CreateDto와 똑같지만, 모든 필드가 '선택(Optional)'으로 바뀜!
export class UpdateUserDto extends PartialType(CreateUserDto) {}

이 외에도 필드 일부만 가져오는 PickType, 일부만 버리는 OmitType 등 강력한 상속 기능이 제공돼.

🧪 따라해보기: 실전 회원가입 DTO 깎아보기

요즘 대세인 Zod 라이브러리를 활용해 볼 거야.
NestJS의 전통적인 class-validator 대신, Drizzle 스키마와 100% 호환되는 nestjs-zod를 사용하는 현대적인 방식이지!

import { createZodDto } from 'nestjs-zod';
import { insertUserSchema } from '@repo/schema'; // Drizzle에서 자동 생성한 Zod 스키마
 
// 1. Zod 스키마에서 필요한 속성만 쏙 빼온다 (.pick)
const RegisterSchema = insertUserSchema.pick({
  email: true,
  password: true,
  name: true,
});
 
// 2. 알아서 완벽한 DTO 클래스로 둔갑!
export class RegisterDto extends createZodDto(RegisterSchema) {}
 
// ----- 컨트롤러 -----
@Post('register')
async register(@Body() dto: RegisterDto) {
  // dto.email, dto.password, dto.name 자동 완성 지원!
  // 무조건 검증된 안전한 데이터!
  return this.authService.register(dto);
}

✅ Drizzle + Zod의 압도적인 장점:
DB 테이블 구조(Schema)를 바꾸면? Zod 스키마도 알아서 바뀌고, DTO 클래스도 알아서 바뀌어! 클라이언트부터 DB까지 단일 진실 공급원(SSOT) 이 완성되는 짜릿한 경험을 할 수 있어.

💼 베스트 프랙티스와 실무 팁 🟡

1. 전역 whitelist: true는 목숨과도 같다.

클라이언트 맘대로 { "email": "a@a.com", "role": "admin" } 이렇게 role 필드를 강제로 쑤셔 넣으면 권한 탈취 버그가 터질 수 있어.
whitelist: true를 켜두면 DTO에 적혀 있지 않은 필드(role)는 문지기가 무참히 썰어버리고 안전한 데이터만 통과시켜줘.

2. 중첩된 객체 배열 검증

사용자가 "장바구니 배열"을 전송했다면, 각 배열 아이템도 일일이 검증해야 해.
이때는 @ValidateNested()가 필수야.

import { ValidateNested, Type } from 'class-transformer';
 
class OrderItemDto { ... }
 
class CreateOrderDto {
  // 1. 이거 배열인지 검사
  @IsArray() 
  // 2. 내부를 샅샅이 뒤져줄게!
  @ValidateNested({ each: true }) 
  // 3. 자바스크립트는 런타임에 배열 안의 타입을 모르니까 Type을 달아줘야 해!
  @Type(() => OrderItemDto) 
  items: OrderItemDto[];
}

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ Validation failed (numeric string is expected)

현상:

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

원인: 컨트롤러 파라미터에서 ParseIntPipe를 달아놨는데 클라이언트가 숫자가 아닌 글자(예: ?page=abc)를 보냈기 때문.

해결책:
내 코드가 잘못된 게 아니야. 방어에 성공한 거니까 프론트개발자에게 "숫자로 주세요~" 라고 말하면 돼.

❌ property 'nestedObject' should not exist (whitelist 에러)

원인:
전역 설정에 whitelist: true, forbidNonWhitelisted: true가 켜져 있는데, DTO 규칙에 명시되지 않은 이상한 속성을 클라이언트가 페이로드에 껴서 보냄.

해결책:
필요한 데이터가 맞다면 DTO 클래스에 속성을 추가해. (만약 굳이 검사할 필요 없는 자유형식 데이터라면 @IsOptional() 이라도 달아줘야 해)

🗂️ 치트시트 — 실무 요약 카드

📝 마무리 퀴즈

Q1. class-validator를 이용할 때 아래 설정 중, 해커가 악의적인 잉여 필드(isPaid: true 등)를 JSON에 섞어 보내는 것을 막기 위해 반드시 켜야 하는 옵션은?

app.useGlobalPipes(new ValidationPipe({
  __________: true
}));

• A) transform
• B) whitelist
• C) disableErrorMessages
• D) enableCors

✅ 정답: B

💡 설명: whitelist: true는 마치 화이트리스트(허가 명단) 기반 출입 통제와 같아. DTO에 이름이 안 적혀있는 데이터 필드는 조용히 폐기처분 해버려!

Q2. 문자열 형태의 쿼리스트링 ?limit=50 을 숫자인 50으로 안전하게 형 변환하면서 덤으로 문자인지 아닌지 유효성 검사까지 공짜로 해주는 마법 같은 내장 파이프는 무엇인가?

✅ 정답: ParseIntPipe
📌 핵심 기억법: 정수(Int)로 분석(Parse) 파이프!

Q3. 디버깅 퀴즈: 아래 코드에서 객체 배열 검증이 제대로 동작하지 않는 원인을 찾아봐.

import { IsArray, ValidateNested } from 'class-validator';
class TaskDto { @IsString() title: string; }
 
class CreateProjectDto {
  @IsArray()
  @ValidateNested({ each: true })
  tasks: TaskDto[];
}

테스트로 tasks: [{ title: 12345 }] 라고 숫자를 넣어서 보냈는데, 에러가 안 나고 통과해버린다?!

✅ 정답: @Type(() => TaskDto) 데코레이터를 빼먹었기 때문!
**설명:**TypeScript의 타입 정보는 컴파일 후 JS로 변하면 감쪽같이 사라져. 런타임에 도는 파이프 입장에선 저 tasks 배열 안의 원소가 TaskDto 객체가 맞는지 알 길이 없어. 무조건 명시적으로 @Type 데코레이터를 달아줘야 중첩 검증이 작동해!

🔗 더 알아보기

• NestJS - ValidationPipe (공식)
• class-validator 전체 규칙 목록
• 05. Drizzle ORM 심화 가이드