Les décorateurs NestJS (@Module, @Controller, @Injectable, @Get…)

Les familles de décorateurs

Au chapitre 04, vous avez appris qu'un décorateur enregistre des métadonnées lues par le framework. NestJS en fournit plusieurs dizaines, que l'on peut ranger en cinq familles :

Classe, amélioration, injection, route et paramètre : chaque décorateur a sa place.

Les décorateurs de route et de paramètre

Ils seront détaillés au chapitre 06. En voici l'essentiel, appliqué à un contrôleur de notes :

📄 src/notes.controller.ts

import {
  Body, Controller, Delete, Get, Header, HttpCode, HttpStatus, Ip, Param, Post, Query, Redirect,
} from '@nestjs/common';
import { ReserveA, UtilisateurCourant } from './common/decorateurs';

@Controller('notes')
export class NotesController {
  private notes = [{ id: 1, stagiaire: 'Ben Ali', valeur: 14 }];

  @Get()
  @Header('Cache-Control', 'no-store')
  findAll(@Query('min') min?: string, @UtilisateurCourant('nom') nom?: string) {
    const liste = this.notes.filter((n) => n.valeur >= Number(min ?? 0));
    return { demandePar: nom, liste };
  }

  @Post()
  @ReserveA('formateur', 'admin')
  create(@Body() body: { stagiaire: string; valeur: number }, @UtilisateurCourant() auteur: object) {
    const note = { id: this.notes.length + 1, ...body };
    this.notes.push(note);
    return { note, auteur };
  }

  @Delete(':id')
  @HttpCode(HttpStatus.NO_CONTENT)       // 204 : pas de corps
  @ReserveA('admin')
  remove(@Param('id') id: string) {
    this.notes = this.notes.filter((n) => n.id !== Number(id));
  }

  @Get('aide')
  @Redirect('https://docs.nestjs.com', 302)
  aide() {}

  @Get('client')
  client(@Ip() ip: string) {
    return { ip };
  }
}

• @Query('min') lit ?min=10 dans l'URL ; @Param('id') lit :id; @Body() lit le corps JSON.
• @Header('Cache-Control', 'no-store') ajoute un en-tête à la réponse.
• @HttpCode(HttpStatus.NO_CONTENT) remplace le statut par défaut (200, ou 201 pour POST).
• @Redirect(url, 302) renvoie une redirection.
• @UtilisateurCourant et @ReserveA sont des décorateurs personnalisés, écrits ci-dessous.

Créer un décorateur de paramètre : createParamDecorator

Dans ce contrôleur, plusieurs méthodes ont besoin de l'utilisateur qui fait la requête. Plutôt que de lire @Req() et de décoder l'en-tête dans chaque méthode, on crée un décorateur de paramètre. Pour l'exemple, l'utilisateur est transmis dans un en-tête X-Utilisateur: nom:role (au chapitre 13, il viendra d'un jeton JWT vérifié).

📄 src/common/decorateurs.ts

import {
  applyDecorators, CanActivate, createParamDecorator, ExecutionContext, ForbiddenException,
  Injectable, SetMetadata, UseGuards,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Request } from 'express';

// 1. Décorateur de paramètre : lit l'utilisateur dans l'en-tête X-Utilisateur
export const UtilisateurCourant = createParamDecorator(
  (champ: 'nom' | 'role' | undefined, ctx: ExecutionContext) => {
    const req = ctx.switchToHttp().getRequest<Request>();
    const [nom, role] = String(req.headers['x-utilisateur'] ?? 'anonyme:visiteur').split(':');
    const utilisateur = { nom, role };
    return champ ? utilisateur[champ] : utilisateur;
  },
);

// 2. Métadonnée : rôles autorisés
export const ROLES = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES, roles);

// 3. Guard qui lit cette métadonnée avec le Reflector
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>(ROLES, ctx.getHandler());
    if (!roles) return true;
    const req = ctx.switchToHttp().getRequest<Request>();
    const role = String(req.headers['x-utilisateur'] ?? '').split(':')[1];
    if (!roles.includes(role)) throw new ForbiddenException(`Réservé à : ${roles.join(', ')}`);
    return true;
  }
}

// 4. Composition : un seul décorateur pour plusieurs
export const ReserveA = (...roles: string[]) => applyDecorators(Roles(...roles), UseGuards(RolesGuard));

• createParamDecorator((data, ctx) => …): data est l'argument passé au décorateur ('nom' dans @UtilisateurCourant('nom')), ctx donne accès à la requête. La valeur renvoyée devient la valeur du paramètre.
• SetMetadata(clé, valeur) attache une métadonnée à la méthode ; Roles(...) n'est qu'un raccourci.
• Le guard lit cette métadonnée avec le Reflector (injecté par NestJS) et ctx.getHandler() (la méthode visée).
• applyDecorators(...) combine plusieurs décorateurs en un seul : @ReserveA('admin') remplace @Roles('admin') + @UseGuards(RolesGuard).

Réponses réelles de l'application :

Requêtes envoyées (méthode, URL, en-tête X-Utilisateur) et réponses :

GET /notes?min=10 [sami:stagiaire] → 200 {"demandePar":"sami","liste":[{"id":1,"stagiaire":"Ben Ali","valeur":14}]} no-store
POST /notes [sami:stagiaire] → 403 {"message":"Réservé à : formateur, admin","error":"Forbidden","statusCode":403}
POST /notes [hajji:formateur] → 201 {"note":{"id":2,"stagiaire":"Gharbi","valeur":12},"auteur":{"nom":"hajji","role":"formateur"}}
DELETE /notes/1 [hajji:formateur] → 403 {"message":"Réservé à : admin","error":"Forbidden","statusCode":403}
DELETE /notes/1 [directeur:admin] → 204
GET /notes [-] → 200 {"demandePar":"anonyme","liste":[{"id":2,"stagiaire":"Gharbi","valeur":12}]} no-store
GET /notes/aide [-] → 302 Found. Redirecting to https://docs.nestjs.com

Les décorateurs d'injection : @Inject et @Optional

@Injectable()
export class ExportService {
  constructor(
    @Inject(PARAMETRES_OPTIONS) private readonly options: ParametresOptions,   // jeton (leçon 5.3)
    @Optional() private readonly journal?: JournalService,                     // peut être absent
  ) {}

  exporter() {
    this.journal?.ecrire('Export', 'export lancé');   // ?. car le service est facultatif
    return `Export ${this.options.etablissement}`;
  }
}

Sans @Optional(), l'absence de JournalService empêcherait l'application de démarrer ; avec, NestJS injecte undefined.

Les décorateurs d'amélioration : où les placer ?

@Controller('notes')
@UseGuards(AuthGuard)                 // toutes les routes du contrôleur
export class NotesController {
  @Post()
  @UseGuards(RolesGuard)              // en plus, pour cette route seulement
  @UsePipes(new ValidationPipe())
  @UseInterceptors(JournalInterceptor)
  create(@Body() dto: CreerNoteDto) {}
}

// main.ts : pour toute l'application
app.useGlobalGuards(new AuthGuard());

Le même enrichisseur peut s'appliquer à trois niveaux : global, contrôleur ou route. La leçon suivante montre dans quel ordre ils s'exécutent.

Activités

import { Controller, createParamDecorator, ExecutionContext, Get, Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { Request } from 'express';

export const Langue = createParamDecorator((parDefaut: string | undefined, ctx: ExecutionContext) => {
  const req = ctx.switchToHttp().getRequest<Request>();
  const valeur = req.headers['accept-language']?.split(',')[0]?.slice(0, 2);
  return valeur && ['fr', 'ar', 'en'].includes(valeur) ? valeur : (parDefaut ?? 'fr');
});

const messages: Record<string, string> = { fr: 'Bienvenue', ar: 'مرحبا', en: 'Welcome' };

@Controller('accueil')
class AccueilController {
  @Get()
  accueil(@Langue('fr') langue: string) {
    return { langue, message: messages[langue] };
  }
}

Accept-Language: ar-TN,ar;q=0.9 → {"langue":"ar","message":"مرحبا"}
Accept-Language: en-US → {"langue":"en","message":"Welcome"}
Accept-Language: de-DE → {"langue":"fr","message":"Bienvenue"}
Accept-Language: (absent) → {"langue":"fr","message":"Bienvenue"}

export const EST_PUBLIC = 'estPublic';
export const Public = () => SetMetadata(EST_PUBLIC, true);

@Injectable()
export class ConnexionGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(ctx: ExecutionContext): boolean {
    const estPublic = this.reflector.getAllAndOverride<boolean>(EST_PUBLIC, [ctx.getHandler(), ctx.getClass()]);
    if (estPublic) return true;
    const req = ctx.switchToHttp().getRequest<Request>();
    if (!req.headers['x-utilisateur']) throw new UnauthorizedException('Connexion requise');
    return true;
  }
}

// main.ts
app.useGlobalGuards(new ConnexionGuard(app.get(Reflector)));

// Dans un contrôleur
@Public()
@Get('catalogue')
catalogue() { … }

export const RouteAdmin = (chemin: string) =>
  applyDecorators(Delete(chemin), HttpCode(HttpStatus.NO_CONTENT), Roles('admin'), UseGuards(RolesGuard));

@Controller('notes')
export class NotesController {
  @RouteAdmin(':id')
  remove(@Param('id') id: string) { … }
}

@Get(':id')
findOne(@Req() req: Request, @Res() res: Response) {
  const id = parseInt(req.params.id);
  const role = (req.headers['x-utilisateur'] as string).split(':')[1];
  if (role !== 'admin') return res.status(403).send('Interdit');
  res.status(200).json(this.service.findOne(id));
}