Comment créer des décorateurs personnalisés ?

Question

Accepted Answer

NestJS vous permet de créer des **décorateurs personnalisés** pour encapsuler la logique réutilisable — le plus couramment des **décorateurs de paramètres** (pour extraire des données de la requête) et des **décorateurs de métadonnées** (pour attacher des données lues par les guards/intercepteurs). Ils maintiennent le code DRY et expressif.

## Décorateur de paramètre personnalisé — extraire les données de la requête

```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` construit un décorateur de paramètre : sa fonction reçoit `ExecutionContext`, extrait les données, et retourne la valeur à injecter. Cela remplace l'accès répétitif `@Req() req` + `req.user` par un `@CurrentUser()` propre et réutilisable.

## Décorateur de paramètre avec arguments

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

## Décorateur de métadonnées personnalisé (pour que les guards/intercepteurs le lisent)

```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 combinaison `@Roles()` + `RolesGuard` — un décorateur de métadonnées qu'un guard lit via `Reflector` — est le pattern canonical pour l'autorisation basée sur les rôles.

## Composer des décorateurs

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

## Pourquoi c'est important

Créer des décorateurs personnalisés est une technique importante de NestJS pour maintenir le code DRY, expressif et maintenable. Les **décorateurs de paramètres personnalisés** (`createParamDecorator`) vous permettent d'encapsuler l'extraction courante de données de requête (comme `@CurrentUser()`) en annotations propres et réutilisables — bien mieux que de répéter `@Req() req` et fouiller dans l'objet de requête dans chaque handler. Les **décorateurs de métadonnées personnalisés** (`SetMetadata`) sont le fondement des patterns d'autorisation de NestJS : l'approche standard `@Roles()` + `RolesGuard` (lue via `Reflector`) pour le contrôle d'accès basé sur les rôles dépend entièrement de la compréhension des décorateurs de métadonnées.

Et **composer des décorateurs** (`applyDecorators`) vous permet de regrouper les décorateurs connexes (par ex. un `@Auth()` qui applique guards et métadonnées ensemble) pour une application concise et cohérente.

Comprendre comment créer ceux-ci est ce qui vous permet de construire des APIs NestJS expressives et idiomatiques et d'implémenter les patterns courants (injection de l'utilisateur actuel, RBAC) de la manière prévue par le framework.

Cela vous élève du simple usage des décorateurs intégrés à l'extension du style déclaratif du framework pour les besoins de votre propre application — une compétence précieuse et fréquemment appliquée dans les vrais projets NestJS.