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

Valider les données avec class-validator et class-transformer (ValidationPipe)

Cette leçon met en place la validation automatique des données avec le ValidationPipe de NestJS et les bibliothèques class-validator et class-transformer. Elle présente l'installation, les décorateurs...

0 chapitres 0 QCM Accès gratuit
Valider les données avec class-validator et class-transformer (ValidationPipe)

À propos de ce cours

Cette leçon met en place la validation automatique des données avec le ValidationPipe de NestJS et les bibliothèques class-validator et class-transformer. Elle présente l'installation, les décorateurs de validation les plus utiles (chaînes, nombres, e-mail, listes, expressions régulières, champs facultatifs, tableaux, objets imbriqués), les messages personnalisés, la validation de la query string avec conversion de type, et compare par l'exécution les options whitelist, forbidNonWhitelisted et transform. Elle montre aussi comment reformater les erreurs avec exceptionFactory. Activités corrigées.

Objectifs de la leçon

  • Installer et activer le ValidationPipe global.
  • Décrire les règles d'un DTO avec les décorateurs de class-validator.
  • Valider les objets imbriqués, les tableaux et la query string.
  • Choisir les options whitelist, forbidNonWhitelisted et transform.
  • Personnaliser les messages et le format des erreurs.
Installation
npm install class-validator class-transformer
  • class-validator fournit des décorateurs (@IsEmail(), @Length()…) que l'on place sur les propriétés du DTO, et une fonction qui vérifie un objet.
  • class-transformer transforme l'objet JSON brut en instance de la classe DTO (sans quoi class-validator ne trouverait pas les règles) et sait convertir des types.

Fonctionnement du ValidationPipe

Transformation en instance, puis validation des règles déclarées sur la classe.

Activer le ValidationPipe global

📄 src/main.ts

import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix('api');
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,              // supprime les propriétés sans décorateur
      forbidNonWhitelisted: true,   // … ou plutôt refuse la requête
      transform: true,              // le handler reçoit une instance du DTO, types convertis
    }),
  );
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Global, il s'applique à tous les arguments typés par une classe. Pour un paramètre typé string ou number, il n'a pas de règles à vérifier et ne fait rien (sauf conversion si transform est activé).

Un DTO avec ses règles

📄 src/stagiaires/dto/creer-stagiaire.dto.ts

import { Type } from 'class-transformer';
import {
  ArrayMaxSize, IsArray, IsDateString, IsEmail, IsIn, IsInt, IsNotEmpty, IsOptional, IsString,
  Length, Matches, Max, Min, ValidateNested,
} from 'class-validator';

export const GROUPES = ['DEV101', 'DEV102', 'RES201'] as const;

export class AdresseDto {
  @IsString()
  @IsNotEmpty()
  ville: string;

  @Matches(/^\d{4}$/, { message: 'Le code postal doit contenir 4 chiffres' })
  codePostal: string;
}

export class CreerStagiaireDto {
  @IsString()
  @Length(2, 50, { message: 'Le nom doit contenir entre $constraint1 et $constraint2 caractères' })
  nom: string;

  @IsString()
  @IsNotEmpty({ message: 'Le prénom est obligatoire' })
  prenom: string;

  @IsEmail({}, { message: "L'adresse e-mail n'est pas valide" })
  email: string;

  @IsIn(GROUPES, { message: `Le groupe doit être l'un de : ${GROUPES.join(', ')}` })
  groupe: string;

  @IsInt()
  @Min(16)
  @Max(60)
  age: number;

  @IsOptional()
  @Matches(/^\+216 ?\d{8}$/, { message: 'Le téléphone doit avoir la forme +216XXXXXXXX' })
  telephone?: string;

  @IsOptional()
  @IsDateString({}, { message: 'La date de naissance doit être au format AAAA-MM-JJ' })
  dateNaissance?: string;

  @IsOptional()
  @IsArray()
  @ArrayMaxSize(5)
  @IsString({ each: true })
  competences?: string[];

  @IsOptional()
  @ValidateNested()
  @Type(() => AdresseDto)
  adresse?: AdresseDto;
}

Points à remarquer :

  • Toute propriété doit porter au moins un décorateur: avec whitelist, une propriété sans décorateur est considérée comme non autorisée.
  • message personnalise le texte ; $constraint1, $constraint2 (et $value, $property) sont remplacés automatiquement.
  • @IsOptional() rend un champ facultatif : s'il est absent, les autres règles ne sont pas vérifiées ; s'il est présent, elles le sont.
  • { each: true } applique la règle à chaque élément du tableau.
  • Pour l'objet imbriqué adresse, il faut les deux décorateurs : @Type(() => AdresseDto) pour que class-transformer crée une instance d'AdresseDto, @ValidateNested() pour que class-validator la vérifie.
CatégorieDécorateurs
Présence@IsNotEmpty(), @IsOptional() (si absent ou null, les autres règles sont ignorées), @IsDefined()
Types@IsString(), @IsInt(), @IsNumber(), @IsBoolean(), @IsDate(), @IsArray(), @IsObject()
Chaînes@Length(min, max), @MinLength(), @MaxLength(), @Matches(regex), @IsEmail(), @IsUrl(), @IsUUID(), @IsDateString(), @IsPhoneNumber('TN')
Nombres@Min(), @Max(), @IsPositive(), @IsNumber({ maxDecimalPlaces: 2 })
Listes de valeurs@IsIn([...]), @IsEnum(MonEnum)
Tableaux@ArrayMinSize(), @ArrayMaxSize(), @ArrayUnique(), { each: true } sur toute règle pour l'appliquer à chaque élément
Objets imbriqués@ValidateNested() + @Type(() => SousDto) (class-transformer)
Un DTO pour la query string

La query string ne contient que du texte. Pour obtenir des nombres, on utilise @Type(() => Number) de class-transformer, et l'initialisation de la propriété fournit la valeur par défaut :

📄 src/stagiaires/dto/filtre-stagiaires.dto.ts

import { Type } from 'class-transformer';
import { IsIn, IsInt, IsOptional, Max, Min } from 'class-validator';

export class FiltreStagiairesDto {
  @IsOptional()
  @IsIn(['DEV101', 'DEV102', 'RES201'])
  groupe?: string;

  @IsOptional()
  @Type(() => Number)          // la query string ne contient que du texte : on convertit
  @IsInt()
  @Min(1)
  page: number = 1;

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(50)
  limite: number = 10;
}

📄 src/stagiaires/stagiaires.controller.ts

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

@Controller('stagiaires')
export class StagiairesController {
  @Post()
  creer(@Body() dto: CreerStagiaireDto) {
    return { valide: true, instance: dto.constructor.name, dto };
  }

  @Get()
  lister(@Query() filtre: FiltreStagiairesDto) {
    return { filtre, typePage: typeof filtre.page };
  }
}
Les résultats
const ok = { nom: 'Ben Ali', prenom: 'Sami', email: 'sami@exemple.tn', groupe: 'DEV101', age: 19 };
  await appel('POST', '/api/stagiaires', { corps: ok });
  await appel('POST', '/api/stagiaires', { corps: { nom: 'B', prenom: '', email: 'sami', groupe: 'DEV999', age: 15.5 } });
  await appel('POST', '/api/stagiaires', { corps: { ...ok, telephone: '22 123 456', adresse: { ville: 'Sfax', codePostal: '30' }, competences: ['HTML', 42] } });
  await appel('POST', '/api/stagiaires', { corps: { ...ok, telephone: '+21622123456', adresse: { ville: 'Sfax', codePostal: '3000' }, competences: ['HTML', 'CSS'] } });
  await appel('POST', '/api/stagiaires', { corps: { ...ok, role: 'admin' } });
  await appel('POST', '/api/stagiaires', { corps: { ...ok, age: '19' } });
  await appel('GET', '/api/stagiaires?groupe=DEV102&page=2');
  await appel('GET', '/api/stagiaires');
  await appel('GET', '/api/stagiaires?limite=500');

Résultat réellement obtenu :

POST /api/stagiaires → 201 {"valide":true,"instance":"CreerStagiaireDto","dto":{"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupe":"DEV101","age":19}}
POST /api/stagiaires → 400 {"message":["Le nom doit contenir entre 2 et 50 caractères","Le prénom est obligatoire","L'adresse e-mail n'est pas valide","Le groupe doit être l'un de : DEV101, DEV102, RES201","age must not be less than 16","age must be an integer number"],"error":"Bad Request","statusCode":400}
POST /api/stagiaires → 400 {"message":["Le téléphone doit avoir la forme +216XXXXXXXX","each value in competences must be a string","adresse.Le code postal doit contenir 4 chiffres"],"error":"Bad Request","statusCode":400}
POST /api/stagiaires → 201 {"valide":true,"instance":"CreerStagiaireDto","dto":{"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupe":"DEV101","age":19,"telephone":"+21622123456","competences":["HTML","CSS"],"adresse":{"ville":"Sfax","codePostal":"3000"}}}
POST /api/stagiaires → 400 {"message":["property role should not exist"],"error":"Bad Request","statusCode":400}
POST /api/stagiaires → 400 {"message":["age must not be greater than 60","age must not be less than 16","age must be an integer number"],"error":"Bad Request","statusCode":400}
GET /api/stagiaires?groupe=DEV102&page=2 → 200 {"filtre":{"groupe":"DEV102","page":2,"limite":10},"typePage":"number"}
GET /api/stagiaires → 200 {"filtre":{"page":1,"limite":10},"typePage":"number"}
GET /api/stagiaires?limite=500 → 400 {"message":["limite must not be greater than 50"],"error":"Bad Request","statusCode":400}

Analyse :

  1. Données correctes : instance vaut CreerStagiaireDto grâce à transform.
  2. Toutes les erreurs sont renvoyées en une fois, dans un tableau message: le client peut corriger tout son formulaire d'un coup. Les règles avec l'option message affichent le texte français ; les autres gardent le message anglais par défaut (age must not be less than 16).
  3. Les erreurs de l'objet imbriqué sont préfixées par le nom du champ parent (adresse.) ; { each: true } signale l'élément 42 de competences.
  4. Les champs facultatifs valides sont acceptés.
  5. role n'existe pas dans le DTO : refusé grâce à forbidNonWhitelisted. L'assignation de masse de la leçon 8.1 est bloquée.
  6. age: "19" (chaîne) est refusé : dans un corps JSON, le client doit envoyer le bon type. transform ne convertit pas les types sans instruction.

Requêtes 7 à 9 : dans la query string, page a bien été converti en nombre par @Type(() => Number), les valeurs par défaut s'appliquent, et @Max(50) limite la taille des pages.

Comparer les options

Deux de ces requêtes, avec new ValidationPipe() sans aucune option :

Sans options :

POST /api/stagiaires → 201 {"valide":true,"instance":"Object","dto":{"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupe":"DEV101","age":19,"role":"admin"}}
GET /api/stagiaires?page=2 → 200 {"filtre":{"page":"2"},"typePage":"string"}

Le champ role passe, l'objet reçu n'est pas une instance du DTO (Object), et page reste une chaîne "2" sans valeur par défaut pour limite. Avec seulement whitelist: true:

Avec whitelist seulement :

POST /api/stagiaires → 201 {"valide":true,"instance":"Object","dto":{"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupe":"DEV101","age":19}}

role a disparu silencieusement. Le choix entre whitelist seul (tolérant) et forbidNonWhitelisted (strict, l'erreur est signalée au client) dépend de votre API ; la seconde option aide les développeurs du client à repérer leurs fautes de frappe.

OptionEffetRecommandation
whitelistretire les propriétés sans décorateurtoujours
forbidNonWhitelistedrépond 400 si une propriété inconnue est envoyéesouvent (API internes, pédagogie)
transforminstance du DTO, @Type() appliqué, paramètres simples convertistoujours
transformOptions: { enableImplicitConversion: true }convertit automatiquement selon le type TypeScript, sans @Type()pratique pour les query strings, mais "abc" devient NaN et "false" devient true: prudence
stopAtFirstErrorune seule erreur par propriétéselon le besoin
disableErrorMessagesmasque le détail des erreursrarement : les clients ont besoin des messages
Reformater les erreurs avec exceptionFactory

Un tableau de messages est pratique à afficher, mais un formulaire veut savoir quel champ est en erreur. exceptionFactory reçoit les erreurs détaillées de class-validator et renvoie l'exception de votre choix :

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
    exceptionFactory: (erreurs: ValidationError[]) =>
      new BadRequestException({
        statusCode: 400,
        message: 'Données invalides',
        erreurs: Object.fromEntries(erreurs.map((e) => [e.property, Object.values(e.constraints ?? {})])),
      }),
  }),
);

Résultat réellement obtenu :

POST /api/stagiaires → 400 {"statusCode":400,"message":"Données invalides","erreurs":{"nom":["Le nom doit contenir entre 2 et 50 caractères"],"prenom":["Le prénom est obligatoire"],"email":["L'adresse e-mail n'est pas valide"]}}

Le TP 5 complète cette fonction pour traiter aussi les objets imbriqués (adresse.codePostal).

Activités

Activité 1 Un DTO de note

Écrivez CreerNoteDto: stagiaireId (entier positif), matiere (parmi SQL, JS, PHP, Anglais), valeur (nombre entre 0 et 20, au plus 2 décimales), coefficient (entier de 1 à 5, facultatif), commentaire (facultatif, 200 caractères au plus). Messages en français.

Voir le corrigé
export class CreerNoteDto {
  @IsInt({ message: "L'identifiant du stagiaire doit être un entier" })
  @IsPositive()
  stagiaireId: number;

  @IsIn(['SQL', 'JS', 'PHP', 'Anglais'], { message: 'Matière inconnue' })
  matiere: string;

  @IsNumber({ maxDecimalPlaces: 2 }, { message: 'La note doit être un nombre (2 décimales au plus)' })
  @Min(0, { message: 'La note minimale est 0' })
  @Max(20, { message: 'La note maximale est 20' })
  valeur: number;

  @IsOptional()
  @IsInt()
  @Min(1)
  @Max(5)
  coefficient?: number;

  @IsOptional()
  @IsString()
  @MaxLength(200)
  commentaire?: string;
}

Activité 2 Valider un tableau d'objets

Une route POST /api/notes/lot reçoit { "notes": [ … ] }, un tableau de 1 à 30 CreerNoteDto. Écrivez le DTO. Que se passe-t-il si vous oubliez @Type()?

Voir le corrigé
export class CreerLotNotesDto {
  @IsArray()
  @ArrayMinSize(1)
  @ArrayMaxSize(30)
  @ValidateNested({ each: true })
  @Type(() => CreerNoteDto)
  notes: CreerNoteDto[];
}

Sans @Type(), les éléments restent des objets simples, sans les règles de CreerNoteDto. Vérifié sur NestJS 11 avec whitelist: { "notes": [{ "valeur": "x" }] } est accepté (201) et le handler reçoit { "notes": [[]] }! La note invalide n'est pas signalée et les données sont silencieusement détruites. Retenez la paire @ValidateNested() + @Type().

Activité 3 La query string

Créez FiltreNotesDto: matiere facultative, min et max (nombres de 0 à 20, facultatifs), tri (asc ou desc, défaut desc). Testez ?min=10&max=15 et vérifiez dans le handler que typeof filtre.min vaut number.

Voir le corrigé
export class FiltreNotesDto {
  @IsOptional()
  @IsIn(['SQL', 'JS', 'PHP', 'Anglais'])
  matiere?: string;

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(0)
  @Max(20)
  min?: number;

  @IsOptional()
  @Type(() => Number)
  @IsNumber()
  @Min(0)
  @Max(20)
  max?: number;

  @IsOptional()
  @IsIn(['asc', 'desc'])
  tri: 'asc' | 'desc' = 'desc';
}

Activité 4 Expérimenter les options

Dans votre projet, remplacez temporairement la configuration par new ValidationPipe({ transform: true, transformOptions: { enableImplicitConversion: true } }). Envoyez ?page=abc et ?actif=false (avec @IsOptional() @IsBoolean() actif?: boolean). Qu'observez-vous ?

Voir le corrigé

page=abc devient NaN, qui est refusé par @IsInt() (le message n'est pas très clair). actif=false devient… true: la conversion implicite applique Boolean("false"), et toute chaîne non vide est vraie. Pour les booléens de la query string, il faut un @Transform(({ value }) => value === 'true') explicite. C'est pourquoi on préfère @Type() et des conversions explicites.

À retenir

  • npm install class-validator class-transformer, puis app.useGlobalPipes(new ValidationPipe({...})).
  • Les règles se déclarent par des décorateurs sur les propriétés du DTO ; chaque propriété doit en avoir au moins un.
  • @IsOptional() pour un champ facultatif ; { each: true } pour les tableaux ; @ValidateNested() + @Type() pour les objets.
  • whitelist + forbidNonWhitelisted bloquent les champs inconnus ; transform donne une instance typée.
  • Query string : @Type(() => Number) et valeurs par défaut sur les propriétés.
  • exceptionFactory permet de renvoyer les erreurs groupées par champ.

Cet article vous a-t-il aidé ?