Что такое DTO в NestJS?

Question

Accepted Answer

**DTO (Data Transfer Object)** — это класс, который определяет **форму данных**, отправляемых в API или получаемых из API — обычно структуру тела запроса. DTO обеспечивают безопасность типов, служат четким контрактом для endpoints и (с декораторами валидации) позволяют автоматическую валидацию входных данных.

## Определение DTO

```ts
import { IsEmail, IsString, MinLength, IsOptional, IsInt, Min } from "class-validator";

export class CreateUserDto {
  @IsEmail()                    // must be a valid email
  email: string;

@IsString()
  @MinLength(8)                 // password at least 8 chars
  password: string;

@IsOptional()                 // optional field
  @IsInt()
  @Min(0)
  age?: number;
}
```

DTO — это простой класс, описывающий ожидаемые данные, с **декораторами валидации** (из `class-validator`), которые задают правила, которым должно удовлетворять каждое поле.

## Использование DTO в контроллере

```ts
@Post()
create(@Body() dto: CreateUserDto) {     // the body is typed AND validated as CreateUserDto
  // dto is guaranteed to be valid here (with the validation pipe enabled)
  return this.usersService.create(dto);
}
```

`@Body() dto: CreateUserDto` типизирует тело запроса и — при включенном validation pipe — автоматически валидирует его перед выполнением вашего обработчика.

## Включение автоматической валидации

```ts
// main.ts — turn on the global validation pipe
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // strip properties NOT in the DTO (security)
  forbidNonWhitelisted: true,   // reject requests with extra unknown properties
  transform: true,              // auto-transform payloads to DTO instances + convert types
}));
```

С помощью `ValidationPipe` NestJS автоматически валидирует входящие тела запросов согласно декораторам DTO — возвращая ошибку 400 с деталями при ошибке валидации, до запуска вашего кода.

## DTO vs Entities

```text
DTO    → the shape of data crossing the API boundary (request/response contract)
Entity → the database model (e.g. a TypeORM entity / Prisma model)
→ Keep them SEPARATE: the API contract shouldn't be coupled to the DB schema.
  (A CreateUserDto has password+email; the User entity has id, timestamps, etc.)
```

DTO намеренно отличаются от сущностей базы данных — они представляют то, что API принимает/возвращает, отделены от внутреннего хранилища.

## Вариации и переиспользование

```ts
import { PartialType } from "@nestjs/mapped-types";
// derive an UpdateUserDto where all fields are optional — no duplication
export class UpdateUserDto extends PartialType(CreateUserDto) {}
```

## Почему это важно

DTO — это важный паттерн NestJS, который привносит безопасность типов, четкие API контракты и автоматическую валидацию в ваши endpoints.

Они определяют ровно то, какие данные принимает endpoint (форму запроса), обеспечивая вам типизацию на этапе компиляции и служа самодокументирующимися контрактами.

Критически важно, что в сочетании с декораторами `class-validator` и `ValidationPipe`, они обеспечивают **автоматическую валидацию входных данных** — неправильно сформированные или вредоносные запросы отклоняются с четкими ошибками *перед* попаданием в вашу бизнес-логику, что критически важно для безопасности и надежности (опция `whitelist` также удаляет неожиданные свойства).

Понимание DTO, как добавлять правила валидации, как включать validation pipe и важный принцип **разделения DTO и сущностей базы данных** (разделение API контракта и внутреннего хранилища) — это основа для построения безопасных, хорошо структурированных, поддерживаемых NestJS APIs.

DTO появляются практически в каждом endpoint, который принимает входные данные, делая их ежедневными, необходимыми знаниями.