À propos de ce cours
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.
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. messagepersonnalise 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égorie | Dé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 :
- Données correctes :
instancevautCreerStagiaireDtogrâce àtransform. - 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'optionmessageaffichent le texte français ; les autres gardent le message anglais par défaut (age must not be less than 16). - Les erreurs de l'objet imbriqué sont préfixées par le nom du champ parent (
adresse.) ;{ each: true }signale l'élément42decompetences. - Les champs facultatifs valides sont acceptés.
rolen'existe pas dans le DTO : refusé grâce àforbidNonWhitelisted. L'assignation de masse de la leçon 8.1 est bloquée.age: "19"(chaîne) est refusé : dans un corps JSON, le client doit envoyer le bon type.transformne 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.
| Option | Effet | Recommandation |
|---|---|---|
whitelist | retire les propriétés sans décorateur | toujours |
forbidNonWhitelisted | répond 400 si une propriété inconnue est envoyée | souvent (API internes, pédagogie) |
transform | instance du DTO, @Type() appliqué, paramètres simples convertis | toujours |
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 |
stopAtFirstError | une seule erreur par propriété | selon le besoin |
disableErrorMessages | masque le détail des erreurs | rarement : 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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !