Como o NestJS usa decoradores?

Question

Accepted Answer

NestJS é construído em torno de **decoradores TypeScript** — anotações especiais com prefixo `@` que anexam **metadados** a classes, métodos e parâmetros. O NestJS lê esses metadados (via reflexão) para conectar roteamento, injeção de dependência, validação e muito mais de forma declarativa. Decoradores estão em todo lugar no Nest.

## Decoradores de classe — defina o papel de uma classe

```ts
@Controller("users")     // this class is a CONTROLLER, prefix /users
export class UsersController {}

@Injectable()            // this class is a PROVIDER (injectable)
export class UsersService {}

@Module({ ... })         // this class is a MODULE
export class UsersModule {}
```

Decoadores de classe declaram o que uma classe *é* na arquitetura do NestJS (controlador, provedor, módulo) e a configuram.

## Decoradores de método — mapeie rotas e aplique comportamento

```ts
@Get()                   // GET request handler
@Post()                  // POST handler
@Get(":id")              // GET /users/:id
@HttpCode(204)           // set the response status code
@UseGuards(AuthGuard)    // apply a guard to this route
@UseInterceptors(LoggingInterceptor)
findAll() {}
```

## Decoradores de parâmetro — extraia dados de solicitação

```ts
findOne(
  @Param("id") id: string,       // route parameter
  @Query("sort") sort: string,   // query string
  @Body() dto: CreateUserDto,    // request body
  @Headers("auth") auth: string, // header
) {}
```

Decoadores de parâmetro extraem declarativamente exatamente os dados que você precisa da solicitação — sem análise manual de `req`.

## Decoradores de propriedade/validação (em DTOs)

```ts
export class CreateUserDto {
  @IsEmail()                     // validation rules (class-validator)
  email: string;

@IsString()
  @MinLength(8)
  password: string;
}
```

## Por que decoradores? Metadados declarativos

```text
Decorators attach METADATA that NestJS reads at runtime (via reflection) to:
  ✓ Register routes (@Get, @Controller)
  ✓ Wire dependency injection (@Injectable, @Inject)
  ✓ Apply guards/interceptors/pipes (@UseGuards, etc.)
  ✓ Validate input (@IsEmail, @IsString)
→ Behavior is declared WHERE it applies, concisely and readably.
```

## Decoradores personalizados

```ts
// you can create your own — e.g. extract the current user from the request
export const CurrentUser = createParamDecorator((data, ctx) =>
  ctx.switchToHttp().getRequest().user
);
// usage: findProfile(@CurrentUser() user: User) {}
```

## Por que isso importa

Decoadores são a característica sintática definidora do NestJS — o framework inteiro é organizado em torno deles, portanto, entender como funcionam é essencial para ler e escrever qualquer código NestJS.

Eles fornecem uma abordagem **declarativa** e orientada por metadados: em vez de configuração imperativa, você anota classes, métodos e parâmetros para declarar roteamento (`@Controller`, `@Get`), injeção de dependência (`@Injectable`), comportamento transversal (`@UseGuards`, `@UseInterceptors`) e validação (`@IsEmail`) exatamente onde se aplicam — conciso e legível.

Este mecanismo de metadados via reflexão (a mesma ideia por trás das anotações Angular e Java/Spring) é o que permite o estilo limpo e estruturado do NestJS.

Reconhecer as categorias (decoradores de classe, método, parâmetro, propriedade), conhecer os comuns e ser capaz de criar decoradores personalizados é fluidez fundamental do NestJS — decoradores são como quase todas as funcionalidades são expressas, tornando-as uma das primeiras e mais importantes coisas a entender no framework.