Ce sunt DTO-urile în NestJS?

Question

Accepted Answer

Un **DTO (Data Transfer Object)** este o clasă care definește **forma datelor** trimise către sau primite de la API-ul tău — de obicei structura unui corp de cerere. DTO-urile oferă siguranță de tip, servesc ca contract clar pentru endpoint-uri, și (cu decoratori de validare) permit validarea automată a intrărilor.

## Definirea unui 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;
}
```

Un DTO este o clasă simplă care descrie datele așteptate, cu **decoratori de validare** (din `class-validator`) specificând regulile pe care trebuie să le satisfacă fiecare câmp.

## Utilizarea unui DTO într-un controler

```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` tipizează corpul cererii și — cu validation pipe activat — validează automat înainte ca handler-ul tău să se execute.

## Activarea validării automate

```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
}));
```

Cu `ValidationPipe`, NestJS validează corpurile în sosire pe baza decoratorilor DTO-ului automat — returnând o eroare 400 cu detalii dacă validarea eșuează, înainte ca codul tău să se execute.

## DTO-uri vs Entități

```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-urile diferă deliberat de entitățile de bază de date — ele reprezintă ce acceptă/returnează API-ul, decuplate de stocarea internă.

## Variații și reutilizare

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

## De ce este important

DTO-urile sunt un model important în NestJS care aduce siguranță de tip, contracte API clare și validare automată la endpoint-urile tale.

Ele definesc exact ce date acceptă un endpoint (forma cererii), oferindu-ți tipizare la compile-time și servind ca contracte self-documenting.

Crucial, combinate cu decoratori `class-validator` și `ValidationPipe`, permit **validarea automată a intrărilor** — cererile malformate sau rău intenționate sunt respinse cu erori clare *înainte* de a ajunge la logica ta de business, ceea ce este esențial pentru securitate și robustețe (opțiunea `whitelist` elimină, de asemenea, proprietățile neașteptate).

Înțelegerea DTO-urilor, cum să adaugi reguli de validare, cum să activezi validation pipe-ul, și principiul important de a **menține DTO-urile separate de entitățile de bază de date** (decuplarea contractului API-ului de stocarea internă) este fundamental pentru construirea de API-uri NestJS sigure, bine structurate și ușor de întreținut.

DTO-urile apar în practic orice endpoint care acceptă intrări, făcând-le cunoștințe zilnice, esențiale.