0Pricing
NestJS Enterprise Backend APIs · Leçon

Ajouter des métadonnées avec SetMetadata et Reflector

Définissez des métadonnées au niveau des routes et relisez-les dans les gardes et les intercepteurs via le service Reflector.

Ajouter des métadonnées avec SetMetadata et Reflector est une leçon NestJS Enterprise Backend APIs gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage NestJS Enterprise Backend APIs, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

Why Route Metadata?

In an enterprise NestJS API you often need to tag a route with extra information that guards, interceptors, or pipes can read later. Examples include required roles, permission flags, cache TTLs, or a flag that marks a route as public.

NestJS solves this with metadata reflection: you attach key/value data to a handler or controller class, then read it back at request time using the Reflector service. This keeps cross-cutting concerns out of your business logic.

  • SetMetadata — writes the metadata onto the route.
  • Reflector — reads it back inside guards/interceptors.

Attaching Metadata with SetMetadata

SetMetadata(key, value) is a decorator factory from @nestjs/common. You give it a string key and any value, and apply it to a controller method (or whole class).

Here we tag the findAll handler with a list of roles allowed to call it. The metadata is stored against the route handler but does nothing on its own until something reads it.

import { Controller, Get, SetMetadata } from '@nestjs/common';

@Controller('reports')
export class ReportsController {
  @Get()
  @SetMetadata('roles', ['admin', 'manager'])
  findAll() {
    return ['Q1 report', 'Q2 report'];
  }
}

Custom Decorators Wrap SetMetadata

Calling @SetMetadata('roles', [...]) inline everywhere is repetitive and easy to typo. The idiomatic pattern is to wrap it in a named custom decorator so the key lives in exactly one place.

Now controllers read clearly with @Roles('admin'), and the magic string 'roles' is encapsulated.

import { SetMetadata } from '@nestjs/common';

export const ROLES_KEY = 'roles';

export const Roles = (...roles: string[]) =>
  SetMetadata(ROLES_KEY, roles);

Using the Custom Decorator

With the Roles decorator defined, controllers become declarative. The handler simply states who may access it; the enforcement logic lives elsewhere in a guard.

Exporting a shared ROLES_KEY constant is important: the decorator and the guard must agree on the exact key string, otherwise the read returns undefined.

import { Controller, Delete, Param } from '@nestjs/common';
import { Roles } from './roles.decorator';

@Controller('users')
export class UsersController {
  @Delete(':id')
  @Roles('admin')
  remove(@Param('id') id: string) {
    return `Deleted user ${id}`;
  }
}

Reading Metadata with Reflector

The Reflector service (from @nestjs/core) reads metadata back at runtime. Inject it into a guard, then call reflector.get(key, target) where target is usually the route handler returned by context.getHandler().

If no metadata was set, get returns undefined, so guards typically treat that as 'no restriction' and allow the request.

import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from './roles.decorator';

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

  canActivate(context: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>(
      ROLES_KEY,
      context.getHandler(),
    );
    if (!roles) return true; // no @Roles => open route

    const req = context.switchToHttp().getRequest();
    return roles.includes(req.user?.role);
  }
}

getAllAndOverride for Handler + Class

Metadata can sit on the handler or the whole controller class. To merge both correctly, use getAllAndOverride: it scans an ordered list of targets and returns the first defined value. Put the handler first so a method-level decorator overrides a class-level one.

Pass [context.getHandler(), context.getClass()] as the targets array.

const roles = this.reflector.getAllAndOverride<string[]>(
  ROLES_KEY,
  [context.getHandler(), context.getClass()],
);

// Handler-level @Roles wins over class-level @Roles

getAllAndMerge for Combining Values

Sometimes you don't want override semantics — you want to combine metadata from both handler and class. getAllAndMerge concatenates arrays (or merges objects) from every target.

  • getAllAndOverride → first defined value wins.
  • getAllAndMerge → all values combined into one array/object.

Use merge when permissions accumulate; use override when the most specific level should fully replace broader ones.

// Class: @Roles('staff')  Handler: @Roles('admin')
const merged = this.reflector.getAllAndMerge<string[]>(
  ROLES_KEY,
  [context.getHandler(), context.getClass()],
);
// merged => ['admin', 'staff']

A Public Route Flag

A very common enterprise pattern is a global JwtAuthGuard that protects every route, plus an @Public() escape hatch for login or health-check endpoints. The decorator just sets a boolean flag.

The global guard reads that flag first and skips authentication when it is true.

import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Honoring the Public Flag in a Guard

Inside the global auth guard, read IS_PUBLIC_KEY with getAllAndOverride across handler and class. If it is true, short-circuit and allow the request before any JWT validation runs.

This is why metadata reflection is powerful: one decorator declaratively changes how an unrelated guard behaves.

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

  canActivate(context: ExecutionContext) {
    const isPublic = this.reflector.getAllAndOverride<boolean>(
      IS_PUBLIC_KEY,
      [context.getHandler(), context.getClass()],
    );
    if (isPublic) return true;
    return validateJwt(context); // your real check
  }
}

Reflector in Interceptors Too

Guards aren't the only consumers. Interceptors also receive an ExecutionContext, so they can read metadata the same way. A classic example is a per-route cache TTL.

Define a @CacheTtl(60) decorator with SetMetadata('cacheTtl', 60), then read it inside an interceptor to decide caching behavior dynamically.

@Injectable()
export class TtlInterceptor implements NestInterceptor {
  constructor(private reflector: Reflector) {}

  intercept(context: ExecutionContext, next: CallHandler) {
    const ttl = this.reflector.get<number>(
      'cacheTtl',
      context.getHandler(),
    ) ?? 30;
    console.log(`Caching for ${ttl}s`);
    return next.handle();
  }
}

Plain TypeScript: The Core Idea

Under the hood, Nest's reflection is just storing values in a map keyed by the function and a metadata key. Here is the same idea in plain, runnable TypeScript with no framework: a tiny store, a 'decorator' that writes, and a 'reflector' that reads with override semantics.

type Target = Function;
const store = new Map<Target, Map<string, unknown>>();

function setMeta(key: string, value: unknown, t: Target) {
  if (!store.has(t)) store.set(t, new Map());
  store.get(t)!.set(key, value);
}

function getAllAndOverride<T>(key: string, targets: Target[]): T | undefined {
  for (const t of targets) {
    const v = store.get(t)?.get(key);
    if (v !== undefined) return v as T;
  }
  return undefined;
}

function handler() {}
function controller() {}

setMeta('roles', ['staff'], controller);
setMeta('roles', ['admin'], handler);

const roles = getAllAndOverride<string[]>('roles', [handler, controller]);
console.log('Effective roles:', roles); // ['admin'] — handler wins

Quick Check

You apply @Roles('staff') on the controller class and @Roles('admin') on a specific handler. Inside the guard you want the handler-level value to fully replace the class-level value. Which Reflector call should you use?

Recap

You learned how to attach and read route-level metadata in NestJS:

  • SetMetadata(key, value) attaches data to a handler or class; wrap it in a named custom decorator (e.g. @Roles(), @Public()) and share the key via a constant.
  • Reflector.get reads metadata from a single target like context.getHandler().
  • getAllAndOverride scans [getHandler(), getClass()] and returns the first defined value — handler overrides class.
  • getAllAndMerge combines values from all targets instead of overriding.
  • Both guards and interceptors consume metadata the same way, enabling clean cross-cutting concerns like roles, public routes, and cache TTLs.

Questions Fréquemment Posées

La leçon « Ajouter des métadonnées avec SetMetadata et Reflector » est-elle gratuite ?

Oui — le texte complet de « Ajouter des métadonnées avec SetMetadata et Reflector » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours NestJS Enterprise Backend APIs, passe à CoddyKit PRO. Le cours NestJS Enterprise Backend APIs comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Ajouter des métadonnées avec SetMetadata et Reflector » ?

Définissez des métadonnées au niveau des routes et relisez-les dans les gardes et les intercepteurs via le service Reflector. Tu pratiques NestJS Enterprise Backend APIs avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer NestJS Enterprise Backend APIs ?

Aucune expérience préalable n'est requise. NestJS Enterprise Backend APIs sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Ajouter des métadonnées avec SetMetadata et Reflector » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon NestJS Enterprise Backend APIs ?

Oui. Chaque leçon NestJS Enterprise Backend APIs inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Lire le contexte d’une requête avec des décorateurs de paramètres
  2. Ajouter des métadonnées avec SetMetadata et Reflector
  3. Composer des décorateurs avec applyDecorators
  4. Décorateurs au niveau des classes pour une configuration transversale
← Retour à NestJS Enterprise Backend APIs