Czym są DTOs w NestJS?

Question

Accepted Answer

**DTO (Data Transfer Object)** to klasa, która definiuje **kształt danych** wysyłanych do lub z Twojego API — zwykle strukturę ciała żądania. DTOs zapewniają bezpieczeństwo typów, służą jako jasna umowa dla punktów końcowych i (z dekoratorami walidacji) umożliwiają automatyczną walidację danych wejściowych.

## Definiowanie 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 to zwykła klasa opisująca oczekiwane dane, z **dekoratorami walidacji** (z `class-validator`) określającymi reguły, które musi spełniać każde pole.

## Używanie DTO w kontrolerze

```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` typuje ciało żądania i — z włączonym potokiem walidacji — automatycznie je waliduje przed uruchomieniem Twojej procedury obsługi.

## Włączanie automatycznej walidacji

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

Z `ValidationPipe`, NestJS automatycznie waliduje przychodzące ciała żądań względem dekoratorów DTO — zwracając błąd 400 ze szczegółami, jeśli walidacja się nie powiedzie, zanim Twój kod się uruchomi.

## DTOs vs Encje

```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.)
```

DTOs celowo różnią się od encji bazy danych — reprezentują to, co API akceptuje/zwraca, niezależnie od wewnętrznego przechowywania.

## Warianty i ponowne użycie

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

## Dlaczego to ważne

DTOs to ważny wzorzec NestJS, który przyznosi bezpieczeństwo typów, jasne umowy API i automatyczną walidację do Twoich punktów końcowych.

Definiują dokładnie, jakie dane punkt końcowy akceptuje (kształt żądania), dając Ci typowanie w czasie kompilacji i służąc jako samodokumentujące umowy.

Odpowiadając na to, w połączeniu z dekoratorami `class-validator` i `ValidationPipe`, umożliwiają **automatyczną walidację danych wejściowych** — źle sformułowane lub złośliwe żądania są odrzucane z jasnymi błędami *przed* dotarciem do Twojej logiki biznesowej, co jest niezbędne dla bezpieczeństwa i niezawodności (opcja `whitelist` również usuwa nieoczekiwane właściwości).

Zrozumienie DTOs, jak dodawać reguły walidacji, jak włączyć potok walidacji i ważna zasada **trzymania DTOs oddzielnie od encji bazy danych** (decentralizacja umowy API od wewnętrznego przechowywania) jest fundamentalne dla budowania bezpiecznych, dobrze ustrukturyzowanych, łatwych w utrzymaniu API NestJS.

DTOs pojawiają się praktycznie w każdym punkcie końcowym, który akceptuje dane wejściowe, czyniąc je codzienną, niezbędną wiedzą.