ما هي الـ Pipes وكيف يعمل التحقق من الصحة؟

Question

Accepted Answer

**الـ Pipes** هي فئات تقوم بـ **تحويل أو التحقق من** بيانات الإدخال قبل وصولها إلى معالج المسار. تعمل على معاملات أساليب المتحكم — إما بتحويلها (مثل string → number) أو التحقق منها (رفض البيانات غير الصحيحة). التحقق من الصحة في NestJS مبني على الـ pipes.

## Transformation pipes المدمجة

```ts
@Get(":id")
findOne(@Param("id", ParseIntPipe) id: number) {    // transforms "5" (string) → 5 (number)
  // id is guaranteed to be a number; non-numeric input → 400 error automatically
  return this.usersService.findOne(id);
}
// other built-ins: ParseBoolPipe, ParseUUIDPipe, ParseArrayPipe, DefaultValuePipe
```

تقوم Transformation pipes بتحويل الإدخال إلى النوع الصحيح (معاملات المسار والـ query دائماً نصوص)، وتفشل مع 400 إذا لم يكن التحويل ممكناً.

## ValidationPipe — التحقق التلقائي من DTO

```ts
// enable globally in main.ts
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // remove properties not declared in the DTO
  forbidNonWhitelisted: true,   // throw if unknown properties are present
  transform: true,              // turn plain objects into DTO instances, convert types
}));
```

```ts
// with a DTO using class-validator decorators:
export class CreateUserDto {
  @IsEmail() email: string;
  @MinLength(8) password: string;
}

@Post()
create(@Body() dto: CreateUserDto) {   // ValidationPipe validates the body automatically
  // if invalid → 400 with details, BEFORE this runs
}
```

تقرأ `ValidationPipe` ديكوريتورات `class-validator` في DTO وتتحقق من البيانات الواردة تلقائياً — وترجع خطأ 400 مفصل عند الفشل، بحيث يستقبل معالجك بيانات صحيحة فقط.

## كيف تناسب الـ pipes في تدفق الطلب

```text
Request → ...middleware/guards/interceptors... → PIPES (transform/validate) → Handler
Pipes run JUST BEFORE the route handler, operating on its method arguments.
```

## Custom pipes

```ts
@Injectable()
export class TrimPipe implements PipeTransform {
  transform(value: any) {
    return typeof value === "string" ? value.trim() : value;   // custom transformation
  }
}
// usage: @Body(TrimPipe) ...
```

تطبق `PipeTransform`'s `transform()` لمنطق التحقق/التحويل المخصص.

## تطبيق الـ pipes على مستويات مختلفة

```ts
@UsePipes(new ValidationPipe())      // method or controller level
@Param("id", ParseIntPipe)            // parameter level
app.useGlobalPipes(new ValidationPipe())   // global (most common for validation)
```

## لماذا يهم هذا

الـ Pipes هي ميزة رئيسية في NestJS للتعامل الآمن مع الإدخال، وهي أساس **نظام التحقق** في الإطار العمل.

فهمها ضروري لأن كل endpoint في API تقريباً يحتاج للتحقق من الإدخال وتحويله: تضمن transformation pipes (`ParseIntPipe` وغيرها) أن المعاملات من النوع الصحيح، و — الأهم — تمنحك **`ValidationPipe`** مع DTOs تحققاً تلقائياً وإعلانياً من طلبات الـ bodies مقابل قواعد `class-validator`، رافضة الإدخال غير الصحيح أو الضار مع أخطاء واضحة *قبل* وصوله لمنطقك التجاري.

هذا حرج لكل من الأمان (التحقق/تنظيف الإدخال غير الموثوق، إزالة الخصائص غير المتوقعة) والمتانة (المعالجات تستقبل بيانات صحيحة فقط).

معرفة كيفية تفعيل global validation pipe مع خيارات معقولة (`whitelist`, `transform`)، استخدام transformation pipes المدمجة، وكتابة custom pipes أمر أساسي لبناء NestJS APIs آمنة وحسنة التنظيم — الـ pipes والتحقق مفاهيم يومية يجب معرفتها في الإطار العمل.