Jak NestJS wykorzystuje dekoratory?

Question

Accepted Answer

NestJS zbudowany jest wokół **dekoratorów TypeScript** — specjalnych adnotacji z prefiksem `@`, które dołączają **metadane** do klas, metod i parametrów. NestJS czyta te metadane (poprzez refleksję), aby w deklaratywny sposób wdrażać routing, wstrzykiwanie zależności, walidację i wiele więcej. Dekoratory są wszędzie w Nest.

## Dekoratory klasy — zdefiniuj rolę klasy

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

Dekoratory klasy deklarują, czym *jest* klasa w architekturze NestJS (kontroler, dostawca, moduł) i ją konfigurują.

## Dekoratory metody — mapuj trasy i zastosuj zachowanie

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

## Dekoratory parametru — wyodrębnij dane żądania

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

Dekoratory parametru deklaratywnie wyodrębniają dokładnie te dane, których potrzebujesz z żądania — bez ręcznego parsowania `req`.

## Dekoratory właściwości/walidacji (na DTO)

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

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

## Dlaczego dekoratory? Deklaratywne metadane

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

## Niestandardowe dekoratory

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

## Dlaczego to ważne

Dekoratory to definiująca cecha składni NestJS — cała struktura frameworku jest wokół nich zorganizowana, dlatego zrozumienie, jak działają, jest niezbędne do czytania i pisania dowolnego kodu NestJS.

Zapewniają one **deklaratywne**, oparte na metadanych podejście: zamiast imperatywnej konfiguracji, oznaczasz klasy, metody i parametry, aby deklarować routing (`@Controller`, `@Get`), wstrzykiwanie zależności (`@Injectable`), zachowanie przekrojowe (`@UseGuards`, `@UseInterceptors`) i walidację (`@IsEmail`) dokładnie tam, gdzie się zastosuj — zwięźle i czytelnie.

Ten mechanizm metadanych poprzez refleksję (ta sama idea stojąca za adnotacjami Angular i Java/Spring) umożliwia czystemu, ustrukturyzowanemu stylowi NestJS.

Rozpoznawanie kategorii (dekoratory klasy, metody, parametru, właściwości), znajomość powszechnych i umiejętność tworzenia niestandardowych dekoratorów to fundamentalna biegłość NestJS — dekoratory to sposób, w jaki wyrażane są prawie wszystkie funkcje, czyniąc je jedną z pierwszych i najważniejszych rzeczy do zrozumienia w frameworku.