O que são decoradores e como são usados?

Question

Accepted Answer

Um **decorador** é uma declaração especial (`@name`) que adiciona comportamento ou metadados a uma classe, método, propriedade ou parâmetro. É uma função que o tempo de execução chama com o alvo decorado, permitindo envolvê-lo ou anotá-lo declarativamente.

```ts
// A simple method decorator that logs calls
function log(target: any, key: string, desc: PropertyDescriptor) {
  const original = desc.value;
  desc.value = function (...args: any[]) {     // wrap the original method
    console.log(`calling ${key} with`, args);
    return original.apply(this, args);
  };
}

class Service {
  @log
  fetch(id: number) { return { id }; }
}
new Service().fetch(1); // logs "calling fetch with [1]" then runs
```

O decorador recebeu o descritor do método e o substituiu por um envoltório — comportamento transversal (logging, cache, timing) sem tocar no corpo do método.

## Onde você os vê com mais frequência: frameworks

```ts
@Controller("users")          // NestJS — declares a route controller
export class UsersController {
  @Get(":id")                 // maps GET /users/:id
  findOne(@Param("id") id: string) { return id; } // param decorator injects the route param
}

@Entity()                     // TypeORM — maps a class to a DB table
class User { @Column() name: string; }
```

NestJS, Angular, TypeORM e class-validator são construídos em torno de decoradores para DI, roteamento, mapeamento ORM e validação.

## Dois tipos (importante)

```json
{ "experimentalDecorators": true, "emitDecoratorMetadata": true }
```

Os **decoradores herdados (experimentais)** acima são aqueles em que Nest/Angular/TypeORM dependem hoje. Há também os **decoradores TC39 Stage-3** mais novos (TS 5+) com uma assinatura diferente, que são o padrão futuro — mas a maioria dos frameworks existentes ainda usa a forma herdada.

## Por que isso importa

Decoradores habilitam meta-programação limpa e declarativa — a base de servidores frameworks e ORMs.

Conhecer tanto o mecanismo (uma função envolvendo um alvo) quanto a divisão legado-vs-padrão é essencial para trabalhar no ecossistema NestJS/Angular.