À propos de ce cours
Objectifs de la leçon
- Créer un décorateur de paramètre avec createParamDecorator.
- Passer une donnée à un décorateur de paramètre.
- Créer des décorateurs de métadonnées avec SetMetadata ou Reflector.createDecorator.
- Composer plusieurs décorateurs avec applyDecorators.
Paramètre, métadonnées, composition.
Rappel
Un décorateur est une fonction appliquée à une classe, une méthode, une propriété ou un paramètre (leçon 4.7). NestJS en fournit beaucoup (@Body(), @Param(), @UseGuards()…), et propose des fonctions pour créer les vôtres sans manipuler directement reflect-metadata.
1. Les décorateurs de paramètre
createParamDecorator(fabrique) crée un décorateur qui fournit une valeur à un paramètre du handler. La fabrique reçoit la donnée passée au décorateur ('role' dans @Utilisateur('role')) et l'ExecutionContext.
📄 src/common/decorators/utilisateur.decorator.ts
import { createParamDecorator, ExecutionContext, UnauthorizedException } from '@nestjs/common';
import { Request } from 'express';
export interface UtilisateurConnecte {
id: number;
nom: string;
role: 'admin' | 'formateur' | 'stagiaire';
}
// Simulation : l'utilisateur est décrit par des en-têtes (au chapitre 13, il viendra du jeton JWT)
export const Utilisateur = createParamDecorator(
(champ: keyof UtilisateurConnecte | undefined, ctx: ExecutionContext) => {
const req = ctx.switchToHttp().getRequest<Request>();
const id = req.header('x-utilisateur-id');
if (!id) throw new UnauthorizedException('Utilisateur non identifié');
const utilisateur: UtilisateurConnecte = {
id: Number(id),
nom: req.header('x-utilisateur-nom') ?? 'inconnu',
role: (req.header('x-role') ?? 'stagiaire') as UtilisateurConnecte['role'],
};
return champ ? utilisateur[champ] : utilisateur; // @Utilisateur('role') → seulement le rôle
},
);
📄 src/common/decorators/langue.decorator.ts
import { createParamDecorator, ExecutionContext } from '@nestjs/common';
import { Request } from 'express';
const LANGUES = ['fr', 'ar', 'en'];
// Langue préférée du client, déduite de l'en-tête Accept-Language
export const Langue = createParamDecorator((parDefaut: string = 'fr', ctx: ExecutionContext) => {
const entete = ctx.switchToHttp().getRequest<Request>().header('accept-language') ?? '';
const code = entete.slice(0, 2).toLowerCase();
return LANGUES.includes(code) ? code : parDefaut;
});
2. Les décorateurs de métadonnées et la composition
À la leçon 9.4, Reflector.createDecorator() a créé @Roles. La forme historique, encore très répandue, utilise SetMetadata(cle, valeur) et une clé sous forme de chaîne. applyDecorators() regroupe ensuite plusieurs décorateurs :
📄 src/common/decorators/auth.decorator.ts
import { applyDecorators, SetMetadata, UseGuards } from '@nestjs/common';
import { RolesGuard } from './roles.guard';
export const ROLES_CLE = 'roles';
// Décorateur COMPOSÉ : regroupe plusieurs décorateurs en un seul
export function Auth(...roles: string[]) {
return applyDecorators(
SetMetadata(ROLES_CLE, roles), // forme « classique » des métadonnées
UseGuards(RolesGuard),
);
}
📄 src/common/guards/roles.guard.ts
import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Request } from 'express';
import { ROLES_CLE } from './auth.decorator';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private readonly reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const roles = this.reflector.getAllAndOverride<string[]>(ROLES_CLE, [context.getHandler(), context.getClass()]) ?? [];
const role = context.switchToHttp().getRequest<Request>().header('x-role') ?? '';
if (roles.length && !roles.includes(role)) throw new ForbiddenException(`Réservé à : ${roles.join(', ')}`);
return true;
}
}
📄 src/profil.controller.ts
import { Body, Controller, Get, Post, ValidationPipe } from '@nestjs/common';
import { IsInt, Max, Min } from 'class-validator';
import { Auth } from './auth.decorator';
import { Langue } from './langue.decorator';
import { Utilisateur, UtilisateurConnecte } from './utilisateur.decorator';
const MESSAGES: Record<string, string> = { fr: 'Bienvenue', ar: 'مرحبا', en: 'Welcome' };
class Pagination {
@IsInt() @Min(1) page: number;
@IsInt() @Max(50) limite: number;
}
@Controller('profil')
export class ProfilController {
@Get()
profil(@Utilisateur() utilisateur: UtilisateurConnecte, @Langue() langue: string) {
return { message: `${MESSAGES[langue]} ${utilisateur.nom}`, utilisateur };
}
@Get('role')
role(@Utilisateur('role') role: string) {
return { role };
}
@Post('admin')
@Auth('admin')
admin(@Utilisateur('nom') nom: string, @Body(new ValidationPipe()) pagination: Pagination) {
return { action: 'réservée aux administrateurs', par: nom, pagination };
}
}
const sami = { 'x-utilisateur-id': '7', 'x-utilisateur-nom': 'Sami', 'x-role': 'formateur' };
await appel('GET', '/api/profil', { entetes: { ...sami, 'accept-language': 'ar-TN,ar;q=0.9' } });
await appel('GET', '/api/profil', { entetes: { ...sami, 'accept-language': 'de-DE' } });
await appel('GET', '/api/profil');
await appel('GET', '/api/profil/role', { entetes: sami });
await appel('POST', '/api/profil/admin', { entetes: sami, corps: { page: 1, limite: 10 } });
await appel('POST', '/api/profil/admin', { entetes: { ...sami, 'x-role': 'admin' }, corps: { page: 1, limite: 10 } });
await appel('POST', '/api/profil/admin', { entetes: { ...sami, 'x-role': 'admin' }, corps: { page: 0, limite: 100 } });
Résultat réellement obtenu :
GET /api/profil → 200 {"message":"مرحبا Sami","utilisateur":{"id":7,"nom":"Sami","role":"formateur"}}
GET /api/profil → 200 {"message":"Bienvenue Sami","utilisateur":{"id":7,"nom":"Sami","role":"formateur"}}
GET /api/profil → 401 {"message":"Utilisateur non identifié","error":"Unauthorized","statusCode":401}
GET /api/profil/role → 200 {"role":"formateur"}
POST /api/profil/admin → 403 {"message":"Réservé à : admin","error":"Forbidden","statusCode":403}
POST /api/profil/admin → 201 {"action":"réservée aux administrateurs","par":"Sami","pagination":{"page":1,"limite":10}}
POST /api/profil/admin → 400 {"message":["page must not be less than 1","limite must not be greater than 50"],"error":"Bad Request","statusCode":400}
Ce qu'il faut observer
@Langue()choisit l'arabe pourar-TNet revient au français (valeur par défaut) pour l'allemand, non pris en charge.- Un décorateur de paramètre peut lever une exception: sans en-tête, 401.
@Utilisateur('role')ne fournit qu'un champ : le handler reçoit directement ce dont il a besoin.@Auth('admin')équivaut à@SetMetadata('roles', ['admin'])+@UseGuards(RolesGuard): une seule ligne, impossible d'oublier l'une des deux parties.- Le corps reste validé par le
ValidationPipepassé à@Body().
Valider la valeur d'un décorateur de paramètre
Un décorateur de paramètre accepte des pipes, comme @Param(): @Utilisateur('id', ParseIntPipe) id: number. Attention, le ValidationPipe ignore par défaut les décorateurs personnalisés ; pour qu'il valide l'objet produit, il faut l'option validateCustomDecorators: true:
@Get()
profil(@Utilisateur(new ValidationPipe({ validateCustomDecorators: true })) utilisateur: UtilisateurDto) { … }
SetMetadata ou Reflector.createDecorator ?
SetMetadata(CLE, valeur) | Reflector.createDecorator<T>() | |
|---|---|---|
| Clé | une chaîne à exporter et partager | le décorateur lui-même sert de clé |
| Typage | à préciser à la lecture : get<string[]>(CLE, …) | automatique |
| Utilisation | @Roles('admin', 'formateur') (fonction à écrire) | @Roles(['admin', 'formateur']) |
| Disponibilité | toutes versions, très répandu | NestJS 10.2 et suivants, recommandé |
Activités
Activité 1 @AdresseIp
Créez un décorateur @AdresseIp() qui renvoie l'adresse IP du client, en tenant compte de l'en-tête x-forwarded-for (présent derrière un proxy comme Nginx) : on prend la première adresse de la liste.
Voir le corrigé
export const AdresseIp = createParamDecorator((_: unknown, ctx: ExecutionContext) => {
const req = ctx.switchToHttp().getRequest<Request>();
const transmis = req.header('x-forwarded-for');
return transmis ? transmis.split(',')[0].trim() : req.ip;
});
Attention : x-forwarded-for peut être falsifié par le client. On ne lui fait confiance que derrière un proxy maîtrisé (configuration trust proxy d'Express, chapitre 20).
Activité 2 @Pagination
Créez @Pagination() qui lit page et limite dans la query string et renvoie { page, limite, decalage } avec des valeurs par défaut (1 et 10), une limite maximale de 50 et une 400 si les valeurs ne sont pas des entiers positifs.
Voir le corrigé
export const Pagination = createParamDecorator((max: number = 50, ctx: ExecutionContext) => {
const q = ctx.switchToHttp().getRequest<Request>().query;
const page = q.page === undefined ? 1 : Number(q.page);
const limite = q.limite === undefined ? 10 : Number(q.limite);
if (!Number.isInteger(page) || page < 1 || !Number.isInteger(limite) || limite < 1 || limite > max) {
throw new BadRequestException(`page et limite doivent être des entiers positifs (limite ≤ ${max})`);
}
return { page, limite, decalage: (page - 1) * limite };
});
// @Get() lister(@Pagination(20) p: { page: number; limite: number; decalage: number })
Comparez avec la solution du chapitre 08 (DTO + ValidationPipe), plus déclarative et documentée automatiquement par Swagger (chapitre 14).
Activité 3 Un décorateur composé de documentation
Créez @RouteAdmin() qui combine : les rôles admin, le RolesGuard, et un en-tête de réponse Cache-Control: no-store (@Header()).
Voir le corrigé
export function RouteAdmin() {
return applyDecorators(
SetMetadata(ROLES_CLE, ['admin']),
UseGuards(RolesGuard),
Header('Cache-Control', 'no-store'),
);
}
Activité 4 Où lire l'utilisateur ?
Dans le TP 4, l'utilisateur courant était fourni par un provider de portée requête (ContexteUtilisateur). Réécrivez la création de tâche avec @Utilisateur('nom'). Quel est le gain ?
Voir le corrigé
create(@Body() dto: CreerTacheDto, @Utilisateur('nom') auteur: string) { return this.tachesService.create(dto, auteur); }. Le contrôleur n'injecte plus de provider de portée requête : il redevient un singleton, ainsi que tout ce qui en dépend (leçon 7.5). C'est l'approche recommandée, et celle du TP 6.
À retenir
- createParamDecorator((donnee, ctx) => valeur) : décorateur de paramètre, qui peut lever une exception.
- La donnée passée au décorateur (@Utilisateur('role')) permet de sélectionner une partie de la valeur.
- SetMetadata(cle, valeur) ou Reflector.createDecorator
() : étiqueter une route, lu par Reflector dans un guard. - applyDecorators(…) regroupe plusieurs décorateurs : @Auth('admin').
- ValidationPipe et décorateur personnalisé : option validateCustomDecorators: true.
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 !