كيف يستخدم NestJS الديكوريترز؟

Question

Accepted Answer

يتم بناء NestJS حول **ديكوريترز TypeScript** — تعليقات خاصة مع بادئة `@` ترفق **بيانات وصفية** بالفئات والدوال والمعاملات. يقرأ NestJS هذه البيانات الوصفية (عبر الانعكاس) لربط التوجيه وحقن التبعيات والتحقق من الصحة وغير ذلك بطريقة إعلانية. الديكوريترز موجودة في كل مكان في Nest.

## فئات الديكوريترز — تحديد دور الفئة

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

تعلن ديكوريترز الفئة ما هي الفئة *في* معمارية NestJS (متحكم، موفر، وحدة) وتعدها.

## ديكوريترز الدوال — ربط المسارات وتطبيق السلوك

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

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

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

تسحب ديكوريترز المعاملات بشكل إعلاني بالضبط البيانات التي تحتاجها من الطلب — بدون تحليل يدوي لـ `req`.

## ديكوريترز الخصائص/التحقق (على DTOs)

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

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

## لماذا الديكوريترز؟ البيانات الوصفية الإعلانية

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

## ديكوريترز مخصصة

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

## لماذا يهم

الديكوريترز هي الميزة النحوية المحددة لـ NestJS — يتم تنظيم الإطار بالكامل حولها، لذا فإن فهم كيفية عملها أمر ضروري لقراءة وكتابة أي كود NestJS.

توفر نهجًا **إعلانيًا** يعتمد على البيانات الوصفية: بدلاً من التكوين الإجباري، تقوم بتعليق الفئات والدوال والمعاملات للإعلان عن التوجيه (`@Controller`, `@Get`) وحقن التبعيات (`@Injectable`) والسلوك المتقاطع (`@UseGuards`, `@UseInterceptors`) والتحقق من الصحة (`@IsEmail`) في المكان الذي ينطبقون فيه — موجزة وسهلة القراءة.

آلية البيانات الوصفية عبر الانعكاس (الفكرة ذاتها خلف تعليقات Angular و Java/Spring) هي التي تمكن أسلوب NestJS النظيف والمنظم.

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