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

Créer un décorateur personnalisé (createParamDecorator, SetMetadata)

Cette leçon apprend à créer ses propres décorateurs NestJS. Les décorateurs de paramètre, créés avec createParamDecorator, extraient une valeur de la requête : un utilisateur courant avec sélection d'...

0 chapitres 0 QCM Accès gratuit
Créer un décorateur personnalisé (createParamDecorator, SetMetadata)

À propos de ce cours

Cette leçon apprend à créer ses propres décorateurs NestJS. Les décorateurs de paramètre, créés avec createParamDecorator, extraient une valeur de la requête : un utilisateur courant avec sélection d'un champ (@Utilisateur('role')) et une langue préférée avec valeur par défaut (@Langue()). Les décorateurs de métadonnées (SetMetadata et Reflector.createDecorator) étiquettent les routes pour les guards. applyDecorators regroupe plusieurs décorateurs en un seul (@Auth('admin')). Sept requêtes exécutées valident chaque cas, y compris la validation d'un corps à côté d'un décorateur personnalisé. Activités corrigées.

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.

Trois sortes de décorateurs personnalisés

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 pour ar-TN et 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 ValidationPipe passé à @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 partagerle 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épanduNestJS 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é ?