كيف يعمل التوجيه (Routing) في NestJS؟

Question

Accepted Answer

**التوجيه (Routing)** في NestJS يعتمد على **المُزخرِفات (Decorators)**: تقوم بربط مسارات URL وطرق HTTP بطرق المتحكم (Controller) باستخدام المُزخرِفات. بادئة المسار تأتي من `@Controller()` والمسار المحدد + فعل HTTP من مُزخرِفات الطريقة مثل `@Get()` — يتم دمجها لتكوين المسار الكامل.

## كيف يتم تكوين المسارات

```ts
@Controller("users")          // PREFIX: all routes start with /users
export class UsersController {
  @Get()                       // GET /users
  findAll() {}

@Get("active")               // GET /users/active
  findActive() {}

@Get(":id")                  // GET /users/:id (dynamic parameter)
  findOne(@Param("id") id: string) {}

@Post()                      // POST /users
  create(@Body() dto: CreateUserDto) {}

@Put(":id")                  // PUT /users/:id
  update(@Param("id") id: string, @Body() dto: UpdateUserDto) {}

@Delete(":id")               // DELETE /users/:id
  remove(@Param("id") id: string) {}
}
```

بادئة المتحكم + مسار مُزخرِف الطريقة تتحد: `@Get(":id")` داخل `@Controller("users")` → `GET /users/:id`. لكل فعل HTTP مُزخرِف خاص به (`@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`).

## معاملات المسار والاستعلامات

```ts
@Get(":id")
example(
  @Param("id") id: string,        // path param: /users/123 → id = "123"
  @Query("sort") sort: string,    // query: /users?sort=name → sort = "name"
  @Query() allQuery: any,         // the whole query object
) {}
```

## المسارات المتداخلة والمسارات الجزئية

```ts
@Controller("users")
export class UsersController {
  @Get(":id/posts")              // GET /users/:id/posts (nested resource)
  getUserPosts(@Param("id") id: string) {}

@Get("search/*")               // wildcard matching
  search() {}
}
```

## ترتيب المسارات مهم

```ts
@Get("active")    // ✅ specific route FIRST
findActive() {}
@Get(":id")        // dynamic route AFTER — else "active" would match :id
findOne() {}
```

يجب الإعلان عن المسارات المحددة (الثابتة) قبل المسارات الديناميكية (`:param`)، وإلا فقد يقوم المسار الديناميكي بالتقاطها.

## البادئة العامة وإصدار الإصدار

```ts
app.setGlobalPrefix("api/v1");   // all routes become /api/v1/...
// NestJS also supports API versioning (URI, header, media-type based)
```

تنطبق بادئة عامة (على سبيل المثال `/api/v1`) على جميع المسارات — الشيء الشائع في اتفاقيات API.

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

التوجيه أساسي — فهو يحدد هيكل عنوان URL لـ API الخاص بك وهو كيفية وصول كل طلب إلى المعالج الصحيح.

فهم **التوجيه القائم على المُزخرِفات في NestJS** (بادئة `@Controller` مدمجة مع مُزخرِفات الطريقة `@Get`/`@Post`/إلخ. لتكوين المسارات الكاملة، و`@Param`/`@Query` لاستخراج البيانات) هو معرفة أساسية يومية — فهو كيفية بناء كل نقطة نهاية (endpoint)، والأسلوب التصريحي يحافظ على نظافة التوجيه وقابليته للقراءة مقارنة بتسجيل المسار اليدوي.

معرفة التفاصيل العملية — دمج البادئات والمسارات، ومعالجة معاملات المسار والاستعلامات، ومسارات الموارد المتداخلة، وأهمية **ترتيب المسارات** (الثابت قبل الديناميكي)، والبادئات العامة/إصدار الإصدار لاتفاقيات API — ضروري لبناء REST APIs منظمة جيدًا في NestJS.

التوجيه والمتحكمات ومُزخرِفات المعاملات معًا تشكل الأساس لمعالجة الطلبات في الإطار، مما يجعل هذا مادة أساسية ويجب أن يعرفها أي مطور NestJS.