DTO, class-validator и pipes

DTO — это класс, а не интерфейс, потому что метаданные должны дожить до runtime

DTO (Data Transfer Object) описывает форму тела запроса, query или param. В Nest ты пишешь его как класс, никогда не как TypeScript interface. Причина конкретна: интерфейсы стираются при компиляции — в runtime их не существует, — а валидация Nest работает через чтение метаданных декораторов с объекта в runtime. Декоратору @IsEmail() на свойстве интерфейса не к чему привязаться после того, как типы стёрты. Класс переживает транспиляцию как настоящее значение, поэтому декораторы (и эмитнутые метаданные типов) на месте, когда pipe их спрашивает.

Каждое поле ты аннотируешь декораторами class-validator, которые объявляют его ограничения: @IsString, @IsEmail, @IsInt, @Min, @IsOptional, @ValidateNested и десятки других. DTO становится единым декларативным источником истины «как выглядит валидный запрос» — читаемым, переиспользуемым и тестируемым в изоляции.

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

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @Min(2) // длина строк — через @MinLength в реальном коде; @Min показан для чисел ниже
  name: string;

  @IsInt()
  @Min(18)
  age: number;

  @IsOptional()
  @IsString()
  bio?: string;
}

Pipe бежит до хендлера — и решает, что хендлер вообще увидит

Pipe — это класс с методом transform(), который Nest запускает на аргументе маршрута до того, как хендлер его получит. Pipes делают две работы: трансформацию (изменить форму или привести значение) и валидацию (проверить, бросить исключение при провале). Встроенный ValidationPipe — тот, что связывает DTO воедино: он читает метаданные class-validator с твоего DTO, валидирует входящий payload против них и при провале бросает BadRequestException — автоматический 400 со списком того, что не так. Хендлер запускается только на вводе, который уже прошёл.

Включаешь его один раз, глобально, в main.ts:

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,            // срезать свойства, которых нет в DTO
      forbidNonWhitelisted: true, // ...или отклонить запрос, если они появились
      transform: true,            // привести plain-объект к экземпляру DTO + привести примитивы
    }),
  );
  await app.listen(3000);
}
bootstrap();

Контроллер тогда просто объявляет DTO как тип аргумента @Body(). Кода валидации в контроллере нет — в этом и смысл:

import { Controller, Post, Body, Get, Param, ParseIntPipe } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UsersController {
  @Post()
  create(@Body() dto: CreateUserDto) {
    // dto уже провалидирован И является экземпляром CreateUserDto.
    // Неизвестные поля вроде `isAdmin` срезаны (или запрос отклонён).
    return this.users.create(dto);
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    // ParseIntPipe — встроенный pipe — приводит строковый param к числу
    // и отдаёт 400, если это не валидное целое. Здесь id — настоящее число.
    return this.users.findOne(id);
  }
}

Три опции, которые важны: whitelist, forbidNonWhitelisted, transform

Эти опции не косметика — две из них настоящий контроль безопасности.

• whitelist: true срезает любое свойство payload’а, у которого в DTO нет декоратора валидации. Лишний isAdmin: true из хука просто никогда не доходит до твоего сервиса.
• forbidNonWhitelisted: true (используй вместе с whitelist) идёт дальше: вместо тихого срезания неизвестных полей он отклоняет весь запрос с 400, перечисляя их. Это более жёсткая позиция — она вскрывает клиентов, шлющих поля, которые ты не принимаешь, а не тихо их роняет.
• transform: true делает две вещи. Он создаёт экземпляр класса DTO из plain JSON-объекта (через class-transformer), так что значение, которое получает хендлер, — настоящий экземпляр CreateUserDto, а не голый объект; методы и instanceof работают. Он также приводит примитивные типы: query-param ?age=18, пришедший строкой "18", становится числом 18, когда поле DTO типизировано как number.

Вместе whitelist + forbidNonWhitelisted — твоя защита от mass-assignment / over-posting — класса багов, где клиент задаёт поле (role, balance, isAdmin), которое сервер никогда не предполагал делать задаваемым с клиента. Валидация на границе — это то, что позволяет остальному приложению доверять своим вводам: как только pipe отработал, каждый слой ниже может считать DTO заведомо корректным.

Схема ниже — то, через что теперь проходит каждый запрос: pipe стоит между проводом и твоим хендлером.

Таблица делает разницу наглядной — тот же шумный payload, с pipe и без него:

Помимо ValidationPipe, Nest поставляет маленькие встроенные pipes для одиночных скалярных аргументов — ParseIntPipe, ParseUUIDPipe, ParseBoolPipe, ParseArrayPipe, — и ты можешь написать кастомный pipe, реализовав transform(value, metadata) из PipeTransform. Но для тел запросов правило держится: клади ограничения в DTO, а не в контроллер, и пусть один глобальный ValidationPipe их обеспечивает.