Come si creano i decoratori personalizzati?

Question

Accepted Answer

NestJS ti consente di creare **decoratori personalizzati** per incapsulare la logica riutilizzabile — più comunemente **decoratori di parametri** (per estrarre dati dalla richiesta) e **decoratori di metadati** (per allegare dati letti da guard/interceptor). Mantengono il codice DRY e espressivo.

## Decoratore di parametri personalizzato — estrai i dati della richiesta

```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` costruisce un decoratore di parametri: la sua funzione riceve l'`ExecutionContext`, estrae i dati e restituisce il valore da iniettare. Questo sostituisce l'accesso ripetitivo `@Req() req` + `req.user` con un pulito e riutilizzabile `@CurrentUser()`.

## Decoratore di parametri con argomenti

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

## Decoratore di metadati personalizzato (per guard/interceptor da leggere)

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

La combinazione `@Roles()` + `RolesGuard` — un decoratore di metadati che un guard legge tramite `Reflector` — è il pattern canonico per l'autorizzazione basata su ruoli.

## Composizione di decoratori

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

## Perché è importante

Creare decoratori personalizzati è una tecnica NestJS importante per mantenere il codice DRY, espressivo e manutenibile. **I decoratori di parametri personalizzati** (`createParamDecorator`) ti permettono di incapsulare l'estrazione comune di dati dalla richiesta (come `@CurrentUser()`) in annotazioni pulite e riutilizzabili — molto meglio che ripetere `@Req() req` e scavare nell'oggetto della richiesta in ogni handler. **I decoratori di metadati personalizzati** (`SetMetadata`) sono il fondamento dei pattern di autorizzazione di NestJS: l'approccio standard `@Roles()` + `RolesGuard` (letto tramite `Reflector`) per il controllo degli accessi basato su ruoli dipende interamente dalla comprensione dei decoratori di metadati.

E **la composizione di decoratori** (`applyDecorators`) ti consente di raggruppare decoratori correlati (ad es. un `@Auth()` che applica guard e metadati insieme) per un'applicazione concisa e coerente.

Capire come creare questi è ciò che ti permette di costruire API NestJS espressive e idiomatiche e implementare pattern comuni (iniezione dell'utente corrente, RBAC) nel modo previsto dal framework.

Ti eleva dal semplice utilizzo di decoratori integrati all'estensione dello stile dichiarativo del framework per le esigenze della tua applicazione — un'abilità preziosa e frequentemente applicata nei progetti NestJS reali.