NestJS Enterprise Backend APIs · Pelajaran

Melampirkan Metadata dengan SetMetadata dan Reflector

Tentukan metadata tingkat rute dan baca kembali metadata tersebut di dalam penjaga dan pencegat melalui layanan Reflector.

Melampirkan Metadata dengan SetMetadata dan Reflector adalah pelajaran NestJS Enterprise Backend APIs gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar NestJS Enterprise Backend APIs, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus NestJS Enterprise Backend APIs mencakup 4 pelajaran total.

Bagian dari pelajaran ini belum diterjemahkan dan ditampilkan dalam bahasa Inggris.

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.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Melampirkan Metadata dengan SetMetadata dan Reflector” gratis?

Ya — teks lengkap “Melampirkan Metadata dengan SetMetadata dan Reflector” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus NestJS Enterprise Backend APIs, upgrade ke CoddyKit PRO. Kursus NestJS Enterprise Backend APIs mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Melampirkan Metadata dengan SetMetadata dan Reflector”?

Tentukan metadata tingkat rute dan baca kembali metadata tersebut di dalam penjaga dan pencegat melalui layanan Reflector. Kamu berlatih NestJS Enterprise Backend APIs dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai NestJS Enterprise Backend APIs?

Tidak diperlukan pengalaman sebelumnya. NestJS Enterprise Backend APIs di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Melampirkan Metadata dengan SetMetadata dan Reflector” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran NestJS Enterprise Backend APIs ini?

Ya. Setiap pelajaran NestJS Enterprise Backend APIs menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Membaca Konteks Permintaan dengan Dekorator Param
Melampirkan Metadata dengan SetMetadata dan Reflector
Menggabungkan Dekorator dengan applyDecorators
Dekorator Tingkat Kelas untuk Konfigurasi Lintas Fitur

← Kembali ke NestJS Enterprise Backend APIs