NestJS Enterprise Backend APIs · Lektion

Metadaten mit SetMetadata und Reflector anhängen

Definieren Sie Metadaten auf Routenebene und lesen Sie sie innerhalb von Guards und Interceptors über den Reflector-Service aus

Metadaten mit SetMetadata und Reflector anhängen ist eine kostenlose NestJS Enterprise Backend APIs-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des NestJS Enterprise Backend APIs-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der NestJS Enterprise Backend APIs-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

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.

Häufig gestellte Fragen

Ist die Lektion „Metadaten mit SetMetadata und Reflector anhängen“ kostenlos?

Ja — der vollständige Text von „Metadaten mit SetMetadata und Reflector anhängen“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des NestJS Enterprise Backend APIs-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der NestJS Enterprise Backend APIs-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Metadaten mit SetMetadata und Reflector anhängen“?

Definieren Sie Metadaten auf Routenebene und lesen Sie sie innerhalb von Guards und Interceptors über den Reflector-Service aus Du übst NestJS Enterprise Backend APIs mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um NestJS Enterprise Backend APIs zu starten?

Keine Vorkenntnisse erforderlich. NestJS Enterprise Backend APIs auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Metadaten mit SetMetadata und Reflector anhängen“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser NestJS Enterprise Backend APIs-Lektion Code schreiben und ausführen?

Ja. Jede NestJS Enterprise Backend APIs-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

Request-Context mit Param-Dekoratoren auslesen
Metadaten mit SetMetadata und Reflector anhängen
Dekoratoren mit applyDecorators kombinieren
Dekoratoren auf Klassenebene für Querschnittskonfiguration

← Zurück zu NestJS Enterprise Backend APIs