Qu'est-ce que les DTOs dans NestJS ?

Question

Accepted Answer

Un **DTO (Data Transfer Object)** est une classe qui définit la **forme des données** envoyées vers ou depuis votre API — typiquement la structure du corps d'une requête. Les DTOs offrent la sécurité des types, servent de contrat clair pour les endpoints, et (avec les décorateurs de validation) permettent la validation automatique des entrées.

## Définir 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 est une classe simple décrivant les données attendues, avec des **décorateurs de validation** (de `class-validator`) spécifiant les règles que chaque champ doit satisfaire.

## Utiliser un DTO dans un contrôleur

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

Le `@Body() dto: CreateUserDto` type le corps de la requête et — avec le validation pipe activé — le valide automatiquement avant l'exécution de votre gestionnaire.

## Activer la validation automatique

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

Avec le `ValidationPipe`, NestJS valide automatiquement les corps entrants par rapport aux décorateurs du DTO — retournant une erreur 400 avec détails si la validation échoue, avant l'exécution de votre code.

## DTOs vs Entités

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

Les DTOs diffèrent intentionnellement des entités de base de données — ils représentent ce que l'API accepte/retourne, découplé du stockage interne.

## Variations et réutilisation

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

## Pourquoi c'est important

Les DTOs sont un pattern important de NestJS qui apporte la sécurité des types, des contrats API clairs, et la validation automatique à vos endpoints.

Ils définissent exactement quelles données un endpoint accepte (la forme de la requête), vous donnant le typage au moment de la compilation et servant de contrats auto-documentés.

Surtout, combinés avec les décorateurs `class-validator` et le `ValidationPipe`, ils permettent la **validation automatique des entrées** — les requêtes mal formées ou malveillantes sont rejetées avec des erreurs claires *avant* d'atteindre votre logique métier, ce qui est essentiel pour la sécurité et la robustesse (l'option `whitelist` supprime également les propriétés inattendues).

Comprendre les DTOs, comment ajouter des règles de validation, comment activer le validation pipe, et le principe important de **garder les DTOs séparés des entités de base de données** (découpler le contrat API du stockage interne) est fondamental pour construire des APIs NestJS sûres, bien structurées et maintenables.

Les DTOs apparaissent dans pratiquement tous les endpoints qui acceptent des entrées, les rendant des connaissances quotidiennes et essentielles.