커스텀 decorator는 어떻게 만드나요?

Question

Accepted Answer

NestJS는 재사용 가능한 로직을 캡슐화하기 위해 **커스텀 decorator**를 만들 수 있게 합니다 — 가장 흔하게는 **파라미터 decorator**(request에서 데이터 추출)와 **메타데이터 decorator**(guard/interceptor가 읽는 데이터 부착)입니다. 이들은 코드를 DRY하고 표현력 있게 유지합니다.

## 커스텀 파라미터 decorator — 요청 데이터 추출

```ts
import { createParamDecorator, ExecutionContext } from "@nestjs/common";

// 인증된 사용자 추출 (인증 guard가 request에 부착함)
export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;        // 주입하고 싶은 것을 반환
  },
);

// 사용 — 깔끔하고 읽기 쉬움
@Get("profile")
getProfile(@CurrentUser() user: User) {     // @Req() req와 req.user 대신
  return user;
}
```

`createParamDecorator`는 파라미터 decorator를 만듭니다: 그 함수는 `ExecutionContext`를 받아 데이터를 추출하고 주입할 값을 반환합니다. 이는 반복적인 `@Req() req` + `req.user` 접근을 깔끔하고 재사용 가능한 `@CurrentUser()`로 대체합니다.

## 인수를 받는 파라미터 decorator

```ts
// 특정 속성 추출: @CurrentUser("email")
export const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const user = ctx.switchToHttp().getRequest().user;
    return data ? user?.[data] : user;   // `data`는 decorator에 전달된 인수
  },
);
// @CurrentUser("email") email: string  → user.email만 주입
```

## 커스텀 메타데이터 decorator (guard/interceptor가 읽기 위한 것)

```ts
import { SetMetadata } from "@nestjs/common";

// 라우트에 메타데이터를 부착하는 @Roles() decorator
export const Roles = (...roles: string[]) => SetMetadata("roles", roles);

// 사용
@Roles("admin", "editor")
@Get("users")
listUsers() {}
```

```ts
// guard가 Reflector를 통해 메타데이터를 읽음
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>("roles", ctx.getHandler());   // 읽기
    const { user } = ctx.switchToHttp().getRequest();
    return !roles || roles.some(r => user.roles?.includes(r));
  }
}
```

`@Roles()` + `RolesGuard` 조합 — guard가 `Reflector`를 통해 읽는 메타데이터 decorator — 은 역할 기반 인가의 정석적인 패턴입니다.

## decorator 조합하기

```ts
import { applyDecorators } from "@nestjs/common";
// 여러 decorator를 하나의 재사용 가능한 decorator로 묶음
export function Auth(...roles: string[]) {
  return applyDecorators(SetMetadata("roles", roles), UseGuards(AuthGuard, RolesGuard));
}
// 사용: @Auth("admin")  — 메타데이터 + guard를 하나의 decorator로 적용
```

## 왜 중요한가

커스텀 decorator를 만드는 것은 코드를 DRY하고, 표현력 있고, 유지보수 가능하게 유지하는 중요한 NestJS 기법입니다. **커스텀 파라미터 decorator**(`createParamDecorator`)는 일반적인 요청 데이터 추출(`@CurrentUser()` 같은)을 깔끔하고 재사용 가능한 어노테이션으로 캡슐화하게 합니다 — 모든 핸들러에서 `@Req() req`를 반복하고 request 객체를 파고드는 것보다 훨씬 낫습니다. **커스텀 메타데이터 decorator**(`SetMetadata`)는 NestJS 인가 패턴의 기초입니다: 역할 기반 접근 제어를 위한 표준 `@Roles()` + `RolesGuard`(`Reflector`를 통해 읽음) 접근은 전적으로 메타데이터 decorator를 이해하는 데 의존합니다.

그리고 **decorator 조합**(`applyDecorators`)은 관련 decorator(예: guard와 메타데이터를 함께 적용하는 `@Auth()`)를 묶어 간결하고 일관된 적용을 가능하게 합니다.

이들을 만드는 방법을 이해하면 표현력 있고 관용적인 NestJS API를 구축하고 일반적인 패턴(현재 사용자 주입, RBAC)을 프레임워크가 의도한 방식으로 구현할 수 있습니다.

이는 단순히 내장 decorator를 사용하는 것에서 프레임워크의 선언적 스타일을 자신의 애플리케이션 요구에 맞게 확장하는 것으로 끌어올립니다 — 실제 NestJS 프로젝트에서 가치 있고 자주 적용되는 기술입니다.