Bagaimanakah anda mencipta custom decorators?

Question

Accepted Answer

NestJS membolehkan anda mencipta **custom decorators** untuk merangkum logik yang boleh diguna semula — paling lazim **dekorator parameter** (untuk mengekstrak data daripada request) dan **dekorator metadata** (untuk melampirkan data yang dibaca oleh guards/interceptors). Ia mengekalkan kod DRY dan ekspresif.

## Custom dekorator parameter — mengekstrak data request

```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` membina satu dekorator parameter: fungsinya menerima `ExecutionContext`, mengekstrak data, dan memulangkan nilai untuk disuntik. Ini menggantikan akses berulang `@Req() req` + `req.user` dengan `@CurrentUser()` yang bersih dan boleh diguna semula.

## Dekorator parameter dengan argumen

```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
```

## Custom dekorator metadata (untuk dibaca oleh guards/interceptors)

```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));
  }
}
```

Gabungan `@Roles()` + `RolesGuard` — satu dekorator metadata yang dibaca oleh guard melalui `Reflector` — ialah corak kanonik untuk authorization berasaskan peranan (role-based).

## Mengarang dekorator

```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
```

## Mengapa ia penting

Mencipta custom decorators ialah satu teknik NestJS yang penting untuk mengekalkan kod DRY, ekspresif, dan boleh diselenggara. **Custom dekorator parameter** (`createParamDecorator`) membolehkan anda merangkum pengekstrakan data-request yang lazim (seperti `@CurrentUser()`) ke dalam anotasi yang bersih dan boleh diguna semula — jauh lebih baik daripada mengulangi `@Req() req` dan menggali objek request dalam setiap handler. **Custom dekorator metadata** (`SetMetadata`) ialah asas corak authorization NestJS: pendekatan standard `@Roles()` + `RolesGuard` (dibaca melalui `Reflector`) untuk kawalan akses berasaskan peranan bergantung sepenuhnya pada pemahaman dekorator metadata.

Dan **mengarang dekorator** (`applyDecorators`) membolehkan anda menggabungkan dekorator berkaitan (cth. satu `@Auth()` yang menerapkan guards dan metadata sekali gus) untuk penerapan yang ringkas dan konsisten.

Memahami cara mencipta semua ini ialah yang membolehkan anda membina API NestJS yang ekspresif dan idiomatik serta melaksanakan corak biasa (suntikan current-user, RBAC) mengikut cara yang dihasratkan oleh framework.

Ia mengangkat anda daripada sekadar menggunakan dekorator terbina kepada melanjutkan gaya deklaratif framework untuk keperluan aplikasi anda sendiri — satu kemahiran yang berharga dan kerap digunakan dalam projek NestJS sebenar.