Cosa sono i DTO in NestJS?

Question

Accepted Answer

Un **DTO (Data Transfer Object)** è una classe che definisce la **forma dei dati** inviati verso o ricevuti dalla tua API — in genere la struttura del corpo di una richiesta. I DTO forniscono type safety, fungono da contratto esplicito per gli endpoint e (con decoratori di validazione) abilitano la validazione automatica degli input.

## Definire un 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 è una classe semplice che descrive i dati attesi, con **decoratori di validazione** (da `class-validator`) che specificano le regole che ogni campo deve soddisfare.

## Utilizzare un DTO in un controller

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

Il `@Body() dto: CreateUserDto` tipizza il corpo della richiesta e — con la validation pipe abilitata — lo valida automaticamente prima che il tuo handler venga eseguito.

## Abilitare la validazione automatica

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

Con `ValidationPipe`, NestJS valida automaticamente i corpi in arrivo rispetto ai decoratori del DTO — restituendo un errore 400 con dettagli se la validazione fallisce, prima che il tuo codice venga eseguito.

## DTO vs Entity

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

I DTO differiscono intenzionalmente dalle entità del database — rappresentano ciò che l'API accetta/restituisce, disaccoppiato dall'archiviazione interna.

## Variazioni e riutilizzo

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

## Perché è importante

I DTO sono un pattern importante di NestJS che porta type safety, contratti API chiari e validazione automatica ai tuoi endpoint.

Definiscono esattamente quali dati un endpoint accetta (la forma della richiesta), fornendoti tipizzazione a tempo di compilazione e fungendo da contratti auto-documentanti.

Crucialmente, combinati con decoratori `class-validator` e `ValidationPipe`, abilitano **la validazione automatica degli input** — le richieste malformate o malevole vengono rifiutate con errori chiari *prima* di raggiungere la tua logica di business, il che è essenziale per la sicurezza e la robustezza (l'opzione `whitelist` rimuove anche proprietà inaspettate).

Comprendere i DTO, come aggiungere regole di validazione, come abilitare la validation pipe, e il principio importante di **mantenere i DTO separati dalle entità del database** (disaccoppiare il contratto API dall'archiviazione interna) è fondamentale per costruire API NestJS sicure, ben strutturate e mantenibili.

I DTO compaiono in praticamente ogni endpoint che accetta input, rendendoli conoscenza quotidiana ed essenziale.