Kaip sukurti pasirinktinius decoratorius?

Question

Accepted Answer

NestJS leidžia sukurti **pasirinktinius decoratorius**, kurie inkapsuliatina perinaudojamą logiką — dažniausiai **parametrų decoratorius** (duomenims iš užklausos ištraukti) ir **metaduomenų decoratorius** (duomenims, kurie skaitomi guards/interceptors, prisegti). Jie išlaiko kodą sausą ir išraiškingą.

## Pasirinktas parametro decoratorius — duomenų iš užklausos ištraukimas

```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` konstruoja parametro decoratorių: jo funkcija gauna `ExecutionContext`, ištraukia duomenis ir grąžina vertę, kurią reikia injektuoti. Tai keičia pasikartojantį `@Req() req` + `req.user` prieigą į švarų, perinaudojamą `@CurrentUser()`.

## Parametro decoratorius su argumentais

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

## Pasirinktas metaduomenų decoratorius (guards/interceptors skaitymui)

```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` kombinacija — metaduomenų decoratorius, kurį sargas skaito per `Reflector` — yra kanoninė šablono forma, skirta vaidmenimis paremtai autorizacijai.

## Decoratorių komponavimas

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

## Kodėl tai svarbu

Pasirinkto decoratorių kūrimas yra svarbi NestJS technika kodui sausam, išraiškingam ir lengvam palaikyti. **Pasirinkti parametrų decoratoriai** (`createParamDecorator`) leidžia inkapsuliatinti įprastą užklausos duomenų ištraukimą (tokį kaip `@CurrentUser()`) į švarų, perinaudojamą anotacijų — daug geriau nei kartoti `@Req() req` ir vėliau kasytis į užklausos objektą kiekviename valdiklyje. **Pasirinkti metaduomenų decoratoriai** (`SetMetadata`) yra NestJS autorizacijos šablonų pagrindas: standartinis `@Roles()` + `RolesGuard` (skaitytas per `Reflector`) metodas vaidmenimis paremtai prieigos kontrolei visiškai priklauso nuo metaduomenų decoratorių supratimo.

Ir **decoratorių komponavimas** (`applyDecorators`) leidžia susumuoti susijusius decoratorius (pvz. `@Auth()`, kuris taiko guards ir metaduomenis kartu) trumpam, nuosekliam taikymui.

Supratimas, kaip sukurti šiuos, yra tai, kas leidžia jums kurti išraiškingus, idiomatinius NestJS API ir įgyvendinti bendrus šablonus (dabartinio naudotojo injektavimą, RBAC) su jais numatytu būdu.

Tai suteikia jums galią — nuo paprasčiausio naudotų dekoratoriaus naudojimo prie savosios deklaratyvios stiliaus kitimo — vertingas, dažnai taikomos įgūdis realūs NestJS projektuose.