ما هي DTOs في NestJS؟

Question

Accepted Answer

**DTO (Data Transfer Object)** هي فئة (class) تحدد **شكل البيانات** المرسلة إلى أو من واجهة برمجية (API) الخاصة بك — عادةً ما تكون بنية نص الطلب (request body). توفر DTOs سلامة النوع (type safety)، وتعمل كعقد واضح للنقاط النهائية (endpoints)، وتمكّن (مع مزخرفات التحقق) من التحقق التلقائي من المدخلات.

## تعريف DTO

```ts
import { IsEmail, IsString, MinLength, IsOptional, IsInt, Min } from "class-validator";

export class CreateUserDto {
  @IsEmail()                    // must be a valid email
  email: string;

@IsString()
  @MinLength(8)                 // password at least 8 chars
  password: string;

@IsOptional()                 // optional field
  @IsInt()
  @Min(0)
  age?: number;
}
```

DTO هي فئة عادية تصف البيانات المتوقعة، مع **مزخرفات التحقق** (من `class-validator`) التي تحدد القواعد التي يجب أن يستوفيها كل حقل.

## استخدام DTO في وحدة تحكم

```ts
@Post()
create(@Body() dto: CreateUserDto) {     // the body is typed AND validated as CreateUserDto
  // dto is guaranteed to be valid here (with the validation pipe enabled)
  return this.usersService.create(dto);
}
```

`@Body() dto: CreateUserDto` يحدد نوع نص الطلب و— مع تفعيل pipelined التحقق (validation pipe) — يتحقق منه تلقائياً قبل تشغيل معالج الطلب.

## تفعيل التحقق التلقائي

```ts
// main.ts — turn on the global validation pipe
app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // strip properties NOT in the DTO (security)
  forbidNonWhitelisted: true,   // reject requests with extra unknown properties
  transform: true,              // auto-transform payloads to DTO instances + convert types
}));
```

مع `ValidationPipe`، يقوم NestJS بالتحقق من الأجسام الواردة مقابل مزخرفات DTO تلقائياً — ويعيد خطأ 400 مع التفاصيل إذا فشل التحقق، قبل تشغيل الكود الخاص بك.

## DTOs مقابل Entities

```text
DTO    → the shape of data crossing the API boundary (request/response contract)
Entity → the database model (e.g. a TypeORM entity / Prisma model)
→ Keep them SEPARATE: the API contract shouldn't be coupled to the DB schema.
  (A CreateUserDto has password+email; the User entity has id, timestamps, etc.)
```

تختلف DTOs بقصد عن كيانات قاعدة البيانات (database entities) — فهي تمثل ما تقبله/ترجعه واجهة البرمجيات (API)، منفصلة عن التخزين الداخلي.

## الأشكال المختلفة وإعادة الاستخدام

```ts
import { PartialType } from "@nestjs/mapped-types";
// derive an UpdateUserDto where all fields are optional — no duplication
export class UpdateUserDto extends PartialType(CreateUserDto) {}
```

## لماذا يأتي هذا بأهمية

DTOs هي نمط مهم في NestJS يجلب سلامة النوع (type safety)، وعقود API واضحة، والتحقق التلقائي من المدخلات إلى نقاطك النهائية (endpoints).

فهي تحدد بالضبط البيانات التي تقبلها نقطة نهائية (شكل الطلب)، مما يمنحك الطباعة في وقت الترجمة (compile-time typing) وتعمل كعقود توثق ذاتها بنفسها.

بشكل حاسم، عند دمجها مع مزخرفات `class-validator` و`ValidationPipe`، فإنها تمكّن **التحقق التلقائي من المدخلات** — يتم رفض الطلبات المشوهة أو الضارة برسائل واضحة *قبل* الوصول إلى منطقك التجاري، وهو أمر ضروري للأمان والقوة (يقوم الخيار `whitelist` أيضاً بإزالة الخصائص غير المتوقعة).

فهم DTOs، وكيفية إضافة قواعد التحقق، وكيفية تفعيل pipelined التحقق، والمبدأ المهم **الحفاظ على فصل DTOs عن كيانات قاعدة البيانات** (فصل عقد API عن التخزين الداخلي) أمر أساسي لبناء واجهات برمجية NestJS آمنة وجيدة البنية وسهلة الصيانة.

تظهر DTOs في كل نقطة نهائية تقريباً تقبل المدخلات، مما يجعلها معرفة يومية وضرورية.