NestJS — Node.js للمؤسسات

المتحكّمات: التعامل مع الطلبات

15 دقيقة الدرس 4 من 30

المتحكّمات: التعامل مع الطلبات

المتحكّمات هي نقطة دخول الطلبات الواردة. مهمّتها محدودة ومهمّة: استقبال الطلب، وتفويض العمل إلى خدمة، وإرجاع استجابة. إبقاء المتحكّمات نحيلة — توجيه فقط، بلا منطق عمل — من أهم العادات في NestJS.

تعريف متحكّم

المتحكّم صنف مُزخرَف بـ @Controller(). النص الذي تمرّره يصبح بادئة المسار لكل دالّة بداخله:

import { Controller, Get } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return 'This returns all users';
  }
}

هنا @Controller('users') + @Get() تُقابل GET /users.

مُزخرِفات طرق HTTP

لكل فعل HTTP مُزخرِف: @Get() و@Post() و@Put() و@Patch() و@Delete(). مرّر مقطع مسار لتمديد المسار:

@Controller('users')
export class UsersController {
  @Get()            // GET /users
  findAll() {}

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

  @Post()           // POST /users
  create() {}
}

قراءة معاملات المسار

تستخدم المقاطع الديناميكية صيغة :name في المسار والمُزخرِف @Param() لقراءتها:

import { Controller, Get, Param } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get(':id')                       // GET /users/42
  findOne(@Param('id') id: string) {
    return `User #${id}`;
  }
}

معاملات المسار دائمًا نصوص. قيمة مثل 42 تصل كنص '42'. تحويلها والتحقّق منها هو عمل الأنابيب (pipes)، وسنغطّيها لاحقًا في هذه الدورة.

معاملات الاستعلام وجسم الطلب

استخدم @Query() لسلسلة الاستعلام و@Body() لحمولة الطلب:

import { Controller, Get, Post, Query, Body } from '@nestjs/common';

@Controller('users')
export class UsersController {
  @Get()                            // GET /users?role=admin
  findAll(@Query('role') role: string) {
    return `Users with role ${role}`;
  }

  @Post()                           // POST /users  + JSON body
  create(@Body() body: { name: string; email: string }) {
    return body;
  }
}

فضّل المُزخرِفات على الطلب الخام. يستطيع NestJS حقن الطلب الأساسي بـ @Req()، لكنّ استخدام @Param() و@Query() و@Body() يُبقي معالجاتك مستقلّة عن الإطار، ومكتوبة الأنواع، وأسهل بكثير في الاختبار.

رموز الحالة والاستجابات

افتراضيًا يُعيد NestJS 200 (و201 لـ @Post()). تجاوزها بـ @HttpCode()، وأيّ شيء تُعيده يُسلسَل تلقائيًا إلى JSON:

import { Controller, Post, HttpCode } from '@nestjs/common';

@Controller('sessions')
export class SessionsController {
  @Post('login')
  @HttpCode(200)                    // تجاوز الافتراضي 201
  login() {
    return { token: 'abc123' };     // يُسلسَل إلى JSON تلقائيًا
  }
}

أبقِ المتحكّمات نحيلة. يجب ألّا يستعلم المتحكّم من قاعدة بيانات أو يرسل بريدًا أو يحتوي قواعد عمل. احقن خدمة واستدعِها. المتحكّمات النحيلة هي الفرق بين تطبيق سهل الصيانة وآخر متشابك.

الخلاصة

تربط المتحكّمات الطلبات بدوال المعالجة باستخدام @Controller() ومُزخرِفات أفعال HTTP، وتقرأ المدخلات بـ @Param() و@Query() و@Body(). القيم المُعادة تُسلسَل إلى JSON تلقائيًا. القاعدة الذهبية: المتحكّمات تُوجّه، والخدمات تعمل. تاليًا سنبني تلك الخدمات.