カスタムデコレータはどのように作成しますか？

Question

Accepted Answer

NestJSでは、**カスタムデコレータ**を作成して再利用可能なロジックをカプセル化できます。最も一般的なのは**パラメータデコレータ**（リクエストからデータを抽出）と**メタデータデコレータ**（ガード/インターセプタが読み取るデータを添付）です。コードをDRYかつ表現的に保ちます。

## カスタムパラメータデコレータ — リクエストデータの抽出

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

// extract the authenticated user (attached to the request by an auth guard)
export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;        // return whatever you want injected
  },
);

// usage — clean and readable
@Get("profile")
getProfile(@CurrentUser() user: User) {     // instead of @Req() req and req.user
  return user;
}
```

`createParamDecorator`はパラメータデコレータを構築します。その関数は`ExecutionContext`を受け取り、データを抽出し、インジェクトする値を返します。これにより、繰り返し現れる`@Req() req` + `req.user`のアクセスが、クリーンで再利用可能な`@CurrentUser()`に置き換わります。

## 引数を持つパラメータデコレータ

```ts
// extract a specific property: @CurrentUser("email")
export const CurrentUser = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const user = ctx.switchToHttp().getRequest().user;
    return data ? user?.[data] : user;   // `data` is the argument passed to the decorator
  },
);
// @CurrentUser("email") email: string  → injects just user.email
```

## カスタムメタデータデコレータ（ガード/インターセプタが読み取る）

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

// a @Roles() decorator that ATTACHES metadata to a route
export const Roles = (...roles: string[]) => SetMetadata("roles", roles);

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

```ts
// a guard reads the metadata via Reflector
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}
  canActivate(ctx: ExecutionContext): boolean {
    const roles = this.reflector.get<string[]>("roles", ctx.getHandler());   // read it
    const { user } = ctx.switchToHttp().getRequest();
    return !roles || roles.some(r => user.roles?.includes(r));
  }
}
```

`@Roles()` + `RolesGuard`の組み合わせ — ガードが`Reflector`経由で読み取るメタデータデコレータ — はロールベースの認可の典型的なパターンです。

## デコレータの合成

```ts
import { applyDecorators } from "@nestjs/common";
// bundle multiple decorators into one reusable decorator
export function Auth(...roles: string[]) {
  return applyDecorators(SetMetadata("roles", roles), UseGuards(AuthGuard, RolesGuard));
}
// usage: @Auth("admin")  — applies metadata + guards in one decorator
```

## なぜ重要なのか

カスタムデコレータの作成は、コードをDRY、表現的、保守性の高い状態に保つための重要なNestJS技法です。**カスタムパラメータデコレータ**（`createParamDecorator`）により、一般的なリクエストデータ抽出（`@CurrentUser()`など）をクリーンで再利用可能なアノテーションにカプセル化できます。すべてのハンドラで`@Req() req`を繰り返してリクエストオブジェクトを掘り下げるよりもはるかに優れています。**カスタムメタデータデコレータ**（`SetMetadata`）はNestJSの認可パターンの基盤です。標準的な`@Roles()` + `RolesGuard`（`Reflector`経由で読み取る）によるロールベースアクセス制御のアプローチは、メタデータデコレータの理解に完全に依存しています。

そして**デコレータの合成**（`applyDecorators`）により、関連するデコレータ（例えば、ガードとメタデータを一緒に適用する`@Auth()`）をバンドルして、簡潔で一貫した適用が可能になります。

これらの作成方法を理解することで、表現力豊かでイディオマティックなNestJS APIを構築し、一般的なパターン（現在のユーザ注入、RBAC）をフレームワークの意図した方法で実装できます。

組み込みデコレータを使用するだけから、自分のアプリケーションのニーズに対してフレームワークの宣言的スタイルを拡張することへと進化させます。これは、実際のNestJSプロジェクトで価値があり、頻繁に適用されるスキルです。