Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les DTO (Data Transfer Object)

Cette leçon présente les DTO (Data Transfer Object), les classes qui décrivent les données échangées entre le client et l'API. Une API sans DTO est d'abord exécutée pour montrer les dangers réels : ch...

0 chapitres 0 QCM Accès gratuit
Les DTO (Data Transfer Object)

À propos de ce cours

Cette leçon présente les DTO (Data Transfer Object), les classes qui décrivent les données échangées entre le client et l'API. Une API sans DTO est d'abord exécutée pour montrer les dangers réels : champs inconnus acceptés, types faux, identifiant et rôle écrasés. La leçon explique ensuite pourquoi un DTO est une classe et non une interface, montre qu'un DTO seul ne valide rien, présente l'organisation des fichiers et les conventions de nommage, puis le DTO de sortie qui empêche la fuite de données sensibles comme le mot de passe. Activités corrigées.

Objectifs de la leçon

  • Définir un DTO et son rôle dans une API.
  • Mesurer les risques d'une API qui accepte n'importe quel corps.
  • Écrire un DTO d'entrée sous forme de classe.
  • Comprendre qu'un DTO seul ne valide rien.
  • Écrire un DTO de sortie pour ne renvoyer que les champs publics.
Qu'est-ce qu'un DTO ?

Un DTO (Data Transfer Object, objet de transfert de données) est une classe qui décrit la forme exacte des données qui passent par une frontière de l'application : ce que le client a le droit d'envoyer (DTO d'entrée) et ce qu'il recevra (DTO de sortie). Il ne contient pas de logique : seulement des propriétés, et bientôt des règles de validation (leçon 8.4).

Rôle des DTO d'entrée et de sortie

Le DTO d'entrée filtre ce qui arrive, le DTO de sortie maîtrise ce qui part.

Le problème : une API sans contrat

Jusqu'ici, nos routes recevaient souvent @Body() body: any. Regardons ce qu'un client peut faire :

import { Body, Controller, Post } from '@nestjs/common';

@Controller('stagiaires')
export class StagiairesController {
  private readonly stagiaires: any[] = [];

  @Post()
  creer(@Body() body: any) {                       // ✗ aucun contrat : tout est accepté
    const stagiaire = { id: this.stagiaires.length + 1, role: 'stagiaire', ...body };
    this.stagiaires.push(stagiaire);
    return stagiaire;
  }
}
await appel('POST', '/api/stagiaires', { corps: { nom: 'Ben Ali', email: 'sami@exemple.tn' } });
await appel('POST', '/api/stagiaires', { corps: { nom: '', email: 'pas-un-email', age: 'dix-huit' } });
await appel('POST', '/api/stagiaires', { corps: { nom: 'Pirate', role: 'admin', id: 999 } });
await appel('POST', '/api/stagiaires', { corps: {} });

Résultat réellement obtenu :

POST /api/stagiaires → 201 {"id":1,"role":"stagiaire","nom":"Ben Ali","email":"sami@exemple.tn"}
POST /api/stagiaires → 201 {"id":2,"role":"stagiaire","nom":"","email":"pas-un-email","age":"dix-huit"}
POST /api/stagiaires → 201 {"id":999,"role":"admin","nom":"Pirate"}
POST /api/stagiaires → 201 {"id":4,"role":"stagiaire"}

Quatre réponses 201, quatre problèmes :

  1. Des données fausses sont enregistrées (nom vide, e-mail invalide, âge en lettres).
  2. Le client a écrasé le role et l'id calculés par le serveur, à cause de la décomposition ...body placée en dernier. C'est une faille classique, l'assignation de masse (mass assignment) : un utilisateur peut se donner le rôle administrateur.
  3. Un stagiaire sans aucun champ a été créé.
  4. Rien ne documente ce que la route attend : il faut lire le code.
Le DTO d'entrée

Par convention, les DTO sont rangés dans un dossier dto/ de la fonctionnalité, un fichier par DTO, nommé selon l'action : creer-stagiaire.dto.ts, modifier-stagiaire.dto.ts, filtre-stagiaires.dto.ts.

// src/stagiaires/dto/creer-stagiaire.dto.ts
export class CreerStagiaireDto {
  nom: string;
  prenom: string;
  email: string;
  groupe: string;
}
src/stagiaires/
├── dto/
│   ├── creer-stagiaire.dto.ts
│   ├── modifier-stagiaire.dto.ts
│   └── filtre-stagiaires.dto.ts
├── stagiaires.controller.ts
├── stagiaires.module.ts
└── stagiaires.service.ts
Classe ou interface ?

On pourrait écrire export interface CreerStagiaireDto { … }. Ce serait une erreur : une interface disparaît à la compilation (leçon 4.3). Une classe, elle, existe à l'exécution : NestJS peut la transmettre aux pipes (metadata.metatype, leçon 8.2), et class-validator peut y lire les règles de validation (leçon 8.4). Un DTO est toujours une classe.

Un DTO seul ne valide rien

Utilisons ce DTO dans le contrôleur et envoyons de mauvaises données :

import { Body, Controller, Post } from '@nestjs/common';
import { CreerStagiaireDto } from './creer-stagiaire.dto';

@Controller('stagiaires')
export class StagiairesController {
  @Post()
  creer(@Body() dto: CreerStagiaireDto) {
    return {
      recu: dto,
      estUneInstanceDuDto: dto instanceof CreerStagiaireDto,
      typeDuNom: typeof dto.nom,
    };
  }
}

Résultat réellement obtenu :

POST /api/stagiaires → 201 {"recu":{"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupe":"DEV101"},"estUneInstanceDuDto":false,"typeDuNom":"string"}
POST /api/stagiaires → 201 {"recu":{"nom":42,"role":"admin"},"estUneInstanceDuDto":false,"typeDuNom":"number"}

La seconde requête, avec nom: 42 et un champ role, est acceptée ! Et estUneInstanceDuDto vaut false: le handler reçoit l'objet JSON brut, pas une instance de la classe. Le type CreerStagiaireDto n'est qu'une indication pour le compilateur; il n'existe aucun contrôle à l'exécution.

À ce stade, le DTO sert à: documenter la route, guider l'autocomplétion et les vérifications de l'éditeur dans le service. Il ne protège pas encore l'API. C'est le rôle des pipes (leçon 8.2) et en particulier du ValidationPipe (leçon 8.4), qui lira des règles ajoutées sur ces mêmes classes.

Le DTO de sortie

Le même raisonnement vaut dans l'autre sens. Une entité contient souvent des champs qui ne doivent jamais sortir de l'API : mot de passe haché, notes internes, dates techniques.

📄 src/stagiaire.entity.ts

// Ce que le service manipule (et stockera en base au chapitre 11)
export interface Stagiaire {
  id: number;
  nom: string;
  prenom: string;
  email: string;
  motDePasseHache: string;      // ne doit JAMAIS sortir de l'API
  creeLe: Date;
}

📄 src/stagiaire-reponse.dto.ts

import { Stagiaire } from './stagiaire.entity';

// DTO de SORTIE : ce que le client a le droit de voir
export class StagiaireReponseDto {
  id: number;
  nomComplet: string;
  email: string;
  inscritDepuis: string;

  static depuis(s: Stagiaire): StagiaireReponseDto {
    const dto = new StagiaireReponseDto();
    dto.id = s.id;
    dto.nomComplet = `${s.prenom} ${s.nom.toUpperCase()}`;
    dto.email = s.email;
    dto.inscritDepuis = s.creeLe.toISOString().slice(0, 10);
    return dto;
  }
}

📄 src/stagiaires.controller.ts

import { Controller, Get, Param, ParseIntPipe } from '@nestjs/common';
import { StagiaireReponseDto } from './stagiaire-reponse.dto';
import { Stagiaire } from './stagiaire.entity';

const STAGIAIRES: Stagiaire[] = [
  { id: 1, nom: 'Ben Ali', prenom: 'Sami', email: 'sami@exemple.tn', motDePasseHache: '$2b$10$Xk…', creeLe: new Date('2026-09-15') },
];

@Controller('stagiaires')
export class StagiairesController {
  @Get('brut/:id')
  brut(@Param('id', ParseIntPipe) id: number) {
    return STAGIAIRES.find((s) => s.id === id);                       // ✗ fuite du mot de passe
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number): StagiaireReponseDto {
    return StagiaireReponseDto.depuis(STAGIAIRES.find((s) => s.id === id)!);   // ✓ DTO de sortie
  }
}

Résultat réellement obtenu :

GET /api/stagiaires/brut/1 → 200 {"id":1,"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","motDePasseHache":"$2b$10$Xk…","creeLe":"2026-09-15T00:00:00.000Z"}
GET /api/stagiaires/1 → 200 {"id":1,"nomComplet":"Sami BEN ALI","email":"sami@exemple.tn","inscritDepuis":"2026-09-15"}

La route « brute » expose le mot de passe haché : c'est une fuite de données. Le DTO de sortie, construit par une méthode statique depuis(), choisit explicitement les champs publics et peut même les mettre en forme (nom complet, date sans l'heure). Le chapitre 13 (authentification) présentera une variante automatique avec @Exclude() de class-transformer.

Conventions et bonnes pratiques
Bonne pratiquePourquoi
Un DTO par action (Creer…, Modifier…, Filtre…)les champs obligatoires et autorisés diffèrent selon l'action
Jamais de champ calculé par le serveur dans un DTO d'entrée (id, role, creeLe)empêche l'assignation de masse
Des classes, sans méthode métierle DTO décrit des données, la logique reste dans le service
Ne pas renvoyer directement l'entité si elle contient des champs sensiblesévite les fuites ; le DTO de sortie fixe le contrat de réponse
Le service reçoit le DTO, pas la requêteil reste indépendant de HTTP et facile à tester
Activités

Activité 1 Repérer les failles

Un contrôleur de notes contient @Post() ajouter(@Body() body: any) { return this.notes.ajouter({ valideParAdmin: false, ...body }); }. Citez trois requêtes malveillantes ou erronées que cette route acceptera.

Voir le corrigé

(1) { "valideParAdmin": true, … }: le client valide lui-même sa note (assignation de masse, car ...body est placé après). (2) { "valeur": 35 } ou { "valeur": "vingt" }: note hors barème ou de mauvais type. (3) {}: note sans stagiaire ni matière. On pourrait aussi citer un corps énorme avec des milliers de champs inutiles.

Activité 2 Écrire les DTO d'une ressource

Pour une ressource formations (code, intitulé, nombre d'heures, niveau, date de début), écrivez CreerFormationDto et FormationReponseDto. L'entité contient aussi id, creePar et budgetInterne, qui ne doit pas être publié.

Voir le corrigé
export class CreerFormationDto {
  code: string;
  intitule: string;
  heures: number;
  niveau: 'initiation' | 'perfectionnement';
  dateDebut: string;          // AAAA-MM-JJ
}

export class FormationReponseDto {
  id: number;
  code: string;
  intitule: string;
  heures: number;
  niveau: string;
  dateDebut: string;

  static depuis(f: Formation): FormationReponseDto {
    const { id, code, intitule, heures, niveau, dateDebut } = f;   // budgetInterne et creePar écartés
    return Object.assign(new FormationReponseDto(), { id, code, intitule, heures, niveau, dateDebut });
  }
}

id et creePar ne figurent pas dans le DTO d'entrée : ils sont fixés par le serveur.

Activité 3 Interface ou classe ?

Un collègue remplace export class CreerStagiaireDto par export interface CreerStagiaireDto et constate que « ça marche pareil ». A-t-il raison ? Que perdra-t-il à la leçon 8.4 ?

Voir le corrigé

Aujourd'hui, le comportement est identique car aucun pipe n'utilise le DTO. Mais à l'exécution, metadata.metatype vaudra Object au lieu de la classe : le ValidationPipe ne trouvera aucune règle et laissera tout passer, sans aucune erreur. De plus, on ne peut pas placer de décorateurs (@IsEmail()) dans une interface. Il faut garder une classe.

Activité 4 Corriger la fuite

Dans votre projet api-formation, ajoutez un champ motDePasseHache aux stagiaires, puis vérifiez avec votre fichier .http que GET /api/stagiaires/1 le renvoie. Corrigez avec un StagiaireReponseDto utilisé dans findAll et findOne.

Voir le corrigé
@Get()
findAll() {
  return this.stagiairesService.findAll().map((s) => StagiaireReponseDto.depuis(s));
}

Attention à écrire (s) => StagiaireReponseDto.depuis(s) plutôt que .map(StagiaireReponseDto.depuis): map transmet aussi l'index et le tableau en arguments. Ici ce serait sans conséquence, mais c'est une source fréquente de bugs.

À retenir

  • Un DTO décrit la forme des données échangées : DTO d'entrée (ce que le client envoie), DTO de sortie (ce qu'il reçoit).
  • Un DTO est une classe, jamais une interface : il doit exister à l'exécution.
  • Un DTO seul ne valide rien : il faudra un pipe (ValidationPipe, leçon 8.4).
  • Ne jamais accepter de champs calculés par le serveur (id, rôle) : risque d'assignation de masse.
  • Le DTO de sortie empêche la fuite de champs sensibles comme le mot de passe.

Cet article vous a-t-il aidé ?