Nasıl özel dekoratörler oluşturursunuz?

Question

Accepted Answer

NestJS, yeniden kullanılabilir mantığı kapsüllemek için **özel dekoratörler** oluşturmanıza izin verir — en yaygın olarak **parametre dekoratörleri** (isteğinden veri çıkarmak için) ve **metadata dekoratörleri** (guard'lar/interceptor'lar tarafından okunan veri eklemek için). Kodu DRY ve ifadeli tutar.

## Özel parametre dekoratörü — istek verilerini çıkar

```ts
import { createParamDecorator, ExecutionContext } from "@nestjs/common";

// extract the authenticated user (attached to the request by an auth guard)
export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;        // return whatever you want injected
  },
);

// usage — clean and readable
@Get("profile")
getProfile(@CurrentUser() user: User) {     // instead of @Req() req and req.user
  return user;
}
```

`createParamDecorator` bir parametre dekoratörü oluşturur: işlevi `ExecutionContext` alır, veri çıkarır ve inject edilecek değeri döndürür. Bu, tekrarlayan `@Req() req` + `req.user` erişimini temiz, yeniden kullanılabilir `@CurrentUser()` ile değiştirir.

## Argümanları olan parametre dekoratörü

```ts
// extract a specific property: @CurrentUser("email")
export const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const user = ctx.switchToHttp().getRequest().user;
    return data ? user?.[data] : user;   // `data` is the argument passed to the decorator
  },
);
// @CurrentUser("email") email: string  → injects just user.email
```

## Özel metadata dekoratörü (guard'lar/interceptor'lar okumak için)

```ts
import { SetMetadata } from "@nestjs/common";

// a @Roles() decorator that ATTACHES metadata to a route
export const Roles = (...roles: string[]) => SetMetadata("roles", roles);

// usage
@Roles("admin", "editor")
@Get("users")
listUsers() {}
```

```ts
// a guard reads the metadata via Reflector
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>("roles", ctx.getHandler());   // read it
    const { user } = ctx.switchToHttp().getRequest();
    return !roles || roles.some(r => user.roles?.includes(r));
  }
}
```

`@Roles()` + `RolesGuard` kombinasyonu — bir guard'ın `Reflector` aracılığıyla okuduğu metadata dekoratörü — rol tabanlı yetkilendirme için kanonik desendir.

## Dekoratörleri birleştirme

```ts
import { applyDecorators } from "@nestjs/common";
// bundle multiple decorators into one reusable decorator
export function Auth(...roles: string[]) {
  return applyDecorators(SetMetadata("roles", roles), UseGuards(AuthGuard, RolesGuard));
}
// usage: @Auth("admin")  — applies metadata + guards in one decorator
```

## Neden önemli

Özel dekoratörler oluşturmak, kodu DRY, ifadeli ve bakım yapılabilir tutmak için önemli bir NestJS tekniğidir. **Özel parametre dekoratörleri** (`createParamDecorator`), yaygın istek-veri çıkarımını (örneğin `@CurrentUser()`) temiz, yeniden kullanılabilir ek açıklamalar içine kapsüllemek için izin verir — her handler'da `@Req() req` tekrarlamaktan ve istek nesnesine girmekten çok daha iyi. **Özel metadata dekoratörleri** (`SetMetadata`), NestJS'nin yetkilendirme desenlerinin temelini oluşturur: standart `@Roles()` + `RolesGuard` (`Reflector` aracılığıyla okunan) rol tabanlı erişim kontrolü yaklaşımı tamamen metadata dekoratörleri anlaşılmasına bağlıdır.

Ve **dekoratörleri birleştirme** (`applyDecorators`), ilgili dekoratörleri (örneğin guard'lar ve metadata'yı birlikte uygulayan `@Auth()`) öz, tutarlı bir uygulamaya bağlamak için izin verir.

Bunları oluşturmayı anlamak, ifadeli, diyomatik NestJS API'leri oluşturmanıza ve yaygın desenleri (mevcut kullanıcı enjeksiyonu, RBAC) framework'ün amaçladığı şekilde uygulamanıza olanak sağlar.

Sizi sadece yerleşik dekoratörleri kullanmaktan kendi uygulamanızın gereklilikleri için framework'ün deklaratif stilini genişletmeye yükseltir — gerçek NestJS projelerinde sık uygulanır, değerli bir beceridir.