class-validator & class-transformer pour des DTOs robustes
Utilisez les flèches, cliquez ou glissez pour naviguer
1. Comprendre pourquoi valider
Sécurité, intégrité des données, expérience utilisateur
2. Installer class-validator & class-transformer
Les deux piliers de la validation par décorateurs
3. Créer des DTOs avec décorateurs
@IsNotEmpty, @IsEmail, @MinLength et bien d'autres
4. Valider automatiquement les requêtes
Middleware réutilisable pour toutes les routes
5. Retourner des erreurs lisibles
422 Unprocessable Entity avec messages clairs
Rappel API REST — pourquoi valider maintenant
Le chaînon manquant entre les routes et la base de données
Le problème : données invalides
Démonstration des failles et des crashs évitables
Qu'est-ce qu'un DTO
La forme attendue des données — contrat entre client et serveur
Démo class-validator
Décorateurs @IsNotEmpty, @IsEmail, @MinLength
class-transformer : plainToInstance
Pourquoi le body JSON n'est pas une instance de classe
Live coding : middleware générique
Un middleware réutilisable pour toutes les routes
On a des routes, des contrôleurs, une base de données...
Mais on a oublié une étape cruciale : la validation
app.post('/api/users', async (req, res) => {
// req.body.name ?? req.body.email ??
// On insère directement sans vérifier... 😱
const
user = await User.create(req.body);
res.status(201).json(user);
});
❌ Aucune vérification → crash ou faille de sécurité
🛡️
Sécurité
Empêcher les injections et données malveillantes
📦
Intégrité
Garantir que la base contient des données valides
👤
UX
Messages d'erreur clairs pour le client
🔑 Le mantra : NE JAMAIS faire confiance au client
😵 Crash serveur
Email manquant → Cannot read property of undefined
🗄️ Base de données corrompue
String passée à un champ numérique → SQL Injection ou NaN
👾 Faille de sécurité
Champs non filtrés → l'utilisateur peut injecter isAdmin: true
// Exemple concret : requête POST malveillante
// POST /api/users
{ "name": "", "email": "pas-un-email", "isAdmin": true }
❌ Sans validation
// req.body = { name: "" }
User.create(req.body)
// INSERT INTO users (name) VALUES ('')
// Donnée vide en base !
✅ Avec validation
// req.body = { name: "" }
validate(CreateUserDto, req.body)
// { statusCode: 422, message: "name ne doit pas être vide" }
// Donnée refusée !
💡 La validation est un filet de sécurité à l'entrée de chaque route
Data Transfer Object
Un DTO décrit la forme attendue des données entrantes
C'est le contrat entre le client et le serveur
Il ne contient QUE les champs envoyés par le client
Pas de id, pas de createdAt, pas de updatedAt
export class CreateUserDto {
name: string;
email: string;
password: string;
}
✅ Inclus dans le DTO
❌ PAS dans le DTO
🎯 Le DTO = ce que le client DOIT envoyer, ni plus ni moins
❌ Interface TypeScript
interface CreateUserDto {
name: string;
email: string;
}
⚠️ Disparaît à la compilation !
Pas de décorateurs, pas d'exécution
✅ Classe
export class CreateUserDto {
@IsNotEmpty()
name!: string;
@IsEmail()
email!: string;
}
✅ Reste après compilation !
Les décorateurs fonctionnent à l'exécution
💡 Les décorateurs sont une fonctionnalité d'exécution — les classes sont nécessaires
npm install class-validator class-transformer
⚠️ reflect-metadata est OBLIGATOIRE
Sans lui, les décorateurs ne fonctionnent pas. Vérifiez qu'il est importé dans votre point d'entrée :
// Dans src/index.ts ou app.ts — EN PREMIER !
import 'reflect-metadata';
// Ensuite seulement vos imports
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';
Un décorateur = une règle de validation
@IsNotEmpty()
Champ non vide
@IsEmail()
Format email valide
@MinLength(8)
Min 8 caractères
@IsNumber()
Doit être un nombre
@IsOptional()
Champ facultatif
@Min(0)
Valeur minimale
Plus de 30 décorateurs disponibles
@IsDate, @IsBoolean, @Matches, @MaxLength, @ArrayNotEmpty, etc.
import { IsNotEmpty, IsEmail, MinLength, IsOptional } from 'class-validator';
export class CreateUserDto {
@IsNotEmpty({ message: 'Le nom est requis' })
name!: string;
@IsEmail({}, { message: 'Email invalide' })
email!: string;
@MinLength(8, { message: '8 caractères minimum' })
password!: string;
@IsOptional()
@MinLength(2)
bio?: string;
}
🔑 Chaque décorateur peut avoir un message personnalisé !
Par défaut les messages sont en anglais. Personnalisez-les !
❌ Message par défaut
"name should not be empty"
"email must be an email"
✅ Message personnalisé
"Le nom est requis"
"Format d'email invalide"
@IsNotEmpty({ message: 'Le nom est requis' })
@IsEmail({}, { message: 'Format d\\'email invalide' })
@MinLength(8, { message: 'Le mot de passe doit faire au moins 8 caractères' })
Transformer du JSON brut en instance de classe
Le body de la requête est un plain object
Pas une instance de votre classe DTO
Les décorateurs ne fonctionnent pas sur un plain object !
❌ req.body (plain object)
{ "name": "Alice" }
{ } — objet littéral JSON
Pas de méthode, pas de décorateur
typeof req.body.__proto__ !== CreateUserDto
✅ Après plainToInstance
CreateUserDto { name: 'Alice' }
CreateUserDto — vraie instance
Métadonnées des décorateurs accessibles
instance instanceof CreateUserDto === true
🔑 plainToInstance(CreateUserDto, req.body) convertit le JSON brut en instance
Créer un middleware de validation générique
Un seul middleware, toutes les routes
On passe le DTO en paramètre, le middleware fait le reste
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';
import { Request, Response, NextFunction } from 'express';
import { ClassConstructor } from 'class-transformer';
export function validationMiddleware<T extends object>(
dtoClass: ClassConstructor<T>,
source: 'body' | 'query' | 'params' = 'body'
) {
return async (req: Request, res: Response, next: NextFunction) => {
⚡ Le middleware est un factory function : il prend un DTO et retourne un middleware Express
const dtoInstance = plainToInstance(dtoClass, req[source]);
const errors = await validate(dtoInstance);
if (errors.length > 0) {
return res.status(422).json({
statusCode: 422,
message: 'Validation échouée',
errors: errors.map(e => ({
field: e.property,
constraints: Object.values(e.constraints ?? {})
}))
});
}
req[source] = dtoInstance; // Remplace par l'instance
next();
};
}
import { CreateUserDto } from './dto/create-user.dto';
import { validationMiddleware } from './middleware/validation.middleware';
app.post(
'/api/users',
validationMiddleware(CreateUserDto), // ✅ Validation automatique
async (req, res) => {
// Ici req.body est une instance valide de CreateUserDto
const user = await User.create(req.body);
res.status(201).json(user);
}
);
✅ Une ligne par route → validation garantie pour toute l'API
Quand la validation échoue, le client reçoit :
// HTTP 422 Unprocessable Entity
{
"statusCode": 422,
"message": "Validation échouée",
"errors": [
{ "field": "name", "constraints": ["Le nom est requis"] },
{ "field": "email", "constraints": ["Format d'email invalide"] },
{ "field": "password", "constraints": ["8 caractères minimum"] }
]
}
💡 Le format structuré permet au client d'afficher chaque erreur à côté du champ concerné
❌ Oublier reflect-metadata
Les décorateurs ne fonctionnent pas → validate() retourne toujours []
✅ import 'reflect-metadata' en premier dans le point d'entrée
❌ Oublier plainToInstance
valider req.body directement → les décorateurs ne sont pas activés
✅ Toujours passer par plainToInstance(DtoClass, req.body) avant validate()
❌ Confondre 400 et 422
400 Bad Request = JSON mal formé (parsing error)
422 Unprocessable Entity = JSON valide mais données invalides
✅ 400 est géré par Express, 422 par votre middleware
❌ Valider manuellement dans chaque contrôleur
if (!req.body.name) { res.status(400).json(...) } // À éviter
✅ Le middleware centralise toute la validation
❌ Mettre l'id ou createdAt dans le DTO
class UserDto { id: number; name: string; createdAt: Date; } // Faille !
✅ Le DTO ne contient QUE ce que le client peut/envoye
❌ Oublier de typer correctement les champs
@IsString() // Important pour le type à l'exécution
✅ Combinez TypeScript + décorateurs pour une double protection
🛡️ Ne JAMAIS faire confiance aux données du client
Tout valider à l'entrée — sécurité, intégrité, UX
plainToInstance
Convertir le JSON brut en instance de classe
validate()
Vérifier les décorateurs de l'instance
✅ 422 + messages lisibles → meilleure expérience client
⚡ Middleware générique = validation réutilisable partout
DTO
Classe qui décrit la forme attendue des données
Décorée avec des règles de validation
class-validator
Décorateurs : @IsNotEmpty, @IsEmail, etc.
30+ règles de validation
class-transformer
plainToInstance() convertit le JSON
Nécessaire pour activer les décorateurs
Middleware
Générique et réutilisable
Retourne 422 avec erreurs structurées
⚠️ N'oubliez pas reflect-metadata et plainToInstance !
Valider les données entrantes, c'est protéger votre application
Rappel : NE JAMAIS faire confiance au client
DTO + class-validator + class-transformer = API robuste