Come utilizza NestJS i decoratori?

Question

Accepted Answer

NestJS è costruito intorno ai **decoratori di TypeScript** — annotazioni speciali con prefisso `@` che allegano **metadati** a classi, metodi e parametri. NestJS legge questi metadati (tramite reflection) per configurare il routing, l'iniezione delle dipendenze, la validazione e altro in modo dichiarativo. I decoratori sono ovunque in Nest.

## Decoratori di classe — definire il ruolo di una 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 {}
```

I decoratori di classe dichiarano cosa *è* una classe nell'architettura di NestJS (controller, provider, modulo) e la configurano.

## Decoratori di metodo — mappare le rotte e applicare il 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() {}
```

## Decoratori di parametro — estrarre i dati della richiesta

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

I decoratori di parametro estraggono in modo dichiarativo esattamente i dati di cui hai bisogno dalla richiesta — niente parsing manuale di `req`.

## Decoratori di proprietà/validazione (su DTO)

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

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

## Perché i decoratori? Metadati dichiarativi

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

## Decoratori personalizzati

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

## Perché è importante

I decoratori sono la caratteristica sintattica che definisce NestJS — l'intero framework è organizzato intorno ad essi, quindi comprendere come funzionano è essenziale per leggere e scrivere qualsiasi codice NestJS.

Forniscono un approccio **dichiarativo**, guidato dai metadati: invece di una configurazione imperativa, annoti classi, metodi e parametri per dichiarare il routing (`@Controller`, `@Get`), l'iniezione delle dipendenze (`@Injectable`), il comportamento trasversale (`@UseGuards`, `@UseInterceptors`) e la validazione (`@IsEmail`) esattamente dove si applicano — conciso e leggibile.

Questo meccanismo di metadati tramite reflection (la stessa idea dietro Angular e le annotazioni Java/Spring) è quello che consente allo stile pulito e strutturato di NestJS.

Riconoscere le categorie (decoratori di classe, metodo, parametro, proprietà), conoscere quelli comuni e essere in grado di creare decoratori personalizzati è una competenza fondamentale di NestJS — i decoratori sono il modo in cui quasi tutte le funzionalità sono espresse, rendendoli una delle prime e più importanti cose da comprendere nel framework.