كيف تنشئ ديكوريتورز مخصصة؟

Question

Accepted Answer

يتيح لك NestJS إنشاء **ديكوريتورز مخصصة** لتغليف المنطق القابل لإعادة الاستخدام — وغالباً **ديكوريتورز المعاملات** (لاستخراج البيانات من الطلب) و**ديكوريتورز البيانات الوصفية** (لإرفاق البيانات التي تقرأها الحراس والمعترضات). إنها تحافظ على الكود جاف وتعبيري.

## ديكوريتور معاملات مخصص — استخراج بيانات الطلب

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

## لماذا يهم

إنشاء ديكوريتورز مخصصة هو تقنية NestJS مهمة للحفاظ على الكود جاف وتعبيري وسهل الصيانة. **ديكوريتورز المعاملات المخصصة** (`createParamDecorator`) تتيح لك تغليف استخراج بيانات الطلب الشائع (مثل `@CurrentUser()`) في تعليقات توضيحية نظيفة وقابلة لإعادة الاستخدام — أفضل بكثير من تكرار `@Req() req` والتنقيب في كائن الطلب في كل معالج. **ديكوريتورز البيانات الوصفية المخصصة** (`SetMetadata`) هي أساس أنماط التصريح في NestJS: نهج `@Roles()` + `RolesGuard` القياسي (المقروء عبر `Reflector`) للتحكم في الوصول القائم على الأدوار يعتمد بالكامل على فهم ديكوريتورز البيانات الوصفية.

و**تركيب الديكوريتورز** (`applyDecorators`) يتيح لك دمج ديكوريتورز مرتبطة (مثل `@Auth()` التي تطبق الحراس والبيانات الوصفية معاً) للتطبيق الموجز والمتسق.

فهم كيفية إنشاء هذه الأشياء هو ما يتيح لك بناء واجهات برمجة تطبيقات NestJS تعبيرية وأصلية وتنفيذ الأنماط الشائعة (حقن المستخدم الحالي، RBAC) بالطريقة المقصودة من الإطار — مهارة قيمة متكررة الاستخدام في مشاريع NestJS الحقيقية.

إنها ترفعك من مجرد استخدام الديكوريتورز المدمجة إلى توسيع النمط التصريحي للإطار لاحتياجات تطبيقك الخاص — مهارة قيمة وشائعة التطبيق في مشاريع NestJS الحقيقية.