Como você cria decoradores personalizados?

Question

Accepted Answer

NestJS permite que você crie **decoradores personalizados** para encapsular lógica reutilizável — mais comumente **decoradores de parâmetro** (para extrair dados da requisição) e **decoradores de metadados** (para anexar dados lidos por guards/interceptors). Eles mantêm o código DRY e expressivo.

## Decorador de parâmetro personalizado — extrair dados da requisição

```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` constrói um decorador de parâmetro: sua função recebe o `ExecutionContext`, extrai dados e retorna o valor para injetar. Isso substitui o acesso repetitivo `@Req() req` + `req.user` por um `@CurrentUser()` limpo e reutilizável.

## Decorador de parâmetro com argumentos

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

## Decorador de metadados personalizado (para guards/interceptors lerem)

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

A combinação `@Roles()` + `RolesGuard` — um decorador de metadados que um guard lê via `Reflector` — é o padrão canônico para autorização baseada em funções.

## Compondo decoradores

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

## Por que isso importa

Criar decoradores personalizados é uma técnica importante do NestJS para manter o código DRY, expressivo e manutenível. **Decoradores de parâmetro personalizados** (`createParamDecorator`) permitem que você encapsule a extração comum de dados de requisição (como `@CurrentUser()`) em anotações limpas e reutilizáveis — muito melhor do que repetir `@Req() req` e investigar o objeto de requisição em cada handler. **Decoradores de metadados personalizados** (`SetMetadata`) são a base dos padrões de autorização do NestJS: a abordagem padrão `@Roles()` + `RolesGuard` (lida via `Reflector`) para controle de acesso baseado em funções depende inteiramente da compreensão de decoradores de metadados.

E **compor decoradores** (`applyDecorators`) permite que você agrupe decoradores relacionados (por exemplo, um `@Auth()` que aplica guards e metadados juntos) para aplicação concisa e consistente.

Compreender como criar estes é o que permite construir APIs NestJS expressivas e idiomáticas e implementar padrões comuns (injeção de usuário atual, RBAC) da forma pretendida pelo framework.

Elevá-lo de apenas usar decoradores built-in para estender o estilo declarativo do framework para as necessidades da sua própria aplicação — uma habilidade valiosa e frequentemente aplicada em projetos NestJS reais.