التوثيق الشامل لإطار عمل NestJS

NestJS هو إطار عمل مفتوح المصدر لتطوير تطبيقات الخلفية (Backend) باستخدام Node.js. تم إطلاقه في عام 2017 على يد كامل ميسكو (Kamil Myśliwiec)، وسرعان ما اكتسب شعبية كبيرة في مجتمع المطورين.

لماذا NestJS؟

يتميز NestJS بأنه يدمج بين قوة Express.js (أو Fastify) وفلسفة تصميم Angular. هذا يعني أنه يستفيد من سرعة ومرونة Express.js، مع توفير بنية تنظيمية قوية مستوحاة من Angular.

المميزات الرئيسية

• الهيكلية الموجهة: يوفر NestJS بنية واضحة للتطبيق، مما يجعل التطوير فريقيًا أكثر فعالية.
• TypeScript بشكل أساسي: مبني على TypeScript، مما يوفر أنظمة إدخال قوية وأدوات تطوير محسّنة.
• حقن التبعية (Dependency Injection): يستخدم نمط حقن التبعية لإنشاء علاقات بين الكائنات وفصل المسؤوليات.
• تعدد البروتوكولات: يدعم REST و GraphQL و WebSockets و Microservices وغيرها.
• قابلية الاختبار: صُمم ليكون قابلاً للاختبار بشكل كامل، مع دعم اختبارات الوحدة والتكامل.
• مجتمع نشط: يتمتع بمجتمع نشط ومتنامي ودعم جيد.

المفاهيم الأساسية

يعتمد NestJS على ثلاثة مفاهيم رئيسية تشكل نواة أي تطبيق:

المتطلبات الأساسية

قبل البدء في استخدام NestJS، تأكد من تثبيت المتطلبات التالية على جهازك:

• Node.js (الإصدار 12 أو أحدث): يمكن تحميله من nodejs.org
• npm أو Yarn: npm يأتي مع Node.js، أو يمكنك تثبيت Yarn من خلال npm install -g yarn

تثبيت CLI

الطريقة المفضلة للبدء مع NestJS هي استخدام Nest CLI، وهي أداة سطر أوامر تساعدك في إنشاء وتطوير تطبيقات NestJS:

npm install -g @nestjs/cli

إنشاء مشروع جديد

بعد تثبيت Nest CLI، يمكنك إنشاء مشروع جديد بالأمر التالي:

nest new project-name

سيطلب منك CLI اختيار مدير الحزم الذي تريد استخدامه (npm، Yarn، أو pnpm). هذا الاختيار لا يؤثر على وظائف المشروع، ولكنه يحدد أداة إدارة الحزم التي ستستخدم للمشروع.

تشغيل التطبيق

بعد إنشاء المشروع، انتقل إلى مجلد المشروع وقم بتشغيل التطبيق:

cd project-name
npm run start:dev

سيبدأ تشغيل الخادم على المنفذ 3000 افتراضياً. يمكنك الوصول إلى التطبيق من خلال المتصفح على العنوان: http://localhost:3000

عند إنشاء مشروع جديد باستخدام Nest CLI، يتم إنشاء هيكل ملفات افتراضي. دعنا نتعرف على الملفات والمجلدات الرئيسية وأهميتها:

project-name/
├── src/                       # مجلد المصدر الرئيسي
│   ├── app.controller.spec.ts # ملف اختبار المتحكم
│   ├── app.controller.ts      # المتحكم الرئيسي
│   ├── app.module.ts          # الوحدة الرئيسية
│   ├── app.service.ts         # الخدمة الرئيسية
│   └── main.ts                # نقطة الدخول الرئيسية للتطبيق
├── test/                      # مجلد اختبارات e2e
├── node_modules/              # الوحدات المثبتة
├── nest-cli.json              # إعدادات CLI
├── package.json               # إعدادات المشروع والتبعيات
├── tsconfig.json              # إعدادات TypeScript
├── tsconfig.build.json        # إعدادات بناء TypeScript
└── README.md                  # توثيق المشروع

شرح الملفات الرئيسية

1. src/main.ts

هذا هو نقطة الدخول الرئيسية للتطبيق. يحتوي على دالة bootstrap التي تقوم بإنشاء مثيل لتطبيق NestJS وتشغيله.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  // إنشاء مثيل من تطبيق NestJS
  const app = await NestFactory.create(AppModule);
  // تشغيل التطبيق على المنفذ 3000
  await app.listen(3000);
}
bootstrap();

2. src/app.module.ts

هذا هو الوحدة الرئيسية للتطبيق. تقوم بتجميع جميع المكونات (المتحكمات والخدمات) وتوفير نقطة دخول واحدة لهيكل التطبيق.

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

3. src/app.controller.ts

هذا هو المتحكم الرئيسي. المتحكمات مسؤولة عن التعامل مع الطلبات HTTP وإرجاع الاستجابات للعميل.

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

4. src/app.service.ts

هذه هي الخدمة الرئيسية. الخدمات تحتوي على منطق الأعمال في التطبيق وتُستخدم لفصل هذا المنطق عن المتحكمات.

import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

هيكل مشروع موصى به للتطبيقات الكبيرة

للتطبيقات الأكبر حجمًا، يُفضَّل تنظيم الملفات حسب الميزات أو الوحدات:

src/
├── main.ts
├── app.module.ts
├── common/                  # مكونات مشتركة (filters, pipes, guards, interceptors)
│   ├── filters/
│   ├── pipes/
│   └── guards/
│   └── interceptors/
├── config/                  # إعدادات التطبيق
├── modules/                 # المكونات المختلفة للتطبيق
│   ├── users/
│   │   ├── dto/
│   │   ├── entities/
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   └── users.module.ts
│   ├── products/
│   │   ├── dto/
│   │   ├── entities/
│   │   ├── products.controller.ts
│   │   ├── products.service.ts
│   │   └── products.module.ts
├── database/                # إعدادات قاعدة البيانات
└── utils/                   # أدوات مساعدة

الوحدات هي العنصر الأساسي في بنية تطبيق NestJS. تساعد في تنظيم كود التطبيق وفصل المسؤوليات. كل تطبيق يحتاج على الأقل وحدة جذر واحدة (AppModule).

تعريف الوحدة

يتم تعريف الوحدة باستخدام واصم @Module() الذي يأخذ كائن إعدادات يحتوي على أربع خصائص رئيسية:

import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  imports: [],          // الوحدات المستوردة
  controllers: [UsersController],  // المتحكمات التي تنتمي لهذه الوحدة
  providers: [UsersService],       // مزودو الخدمات التي تنتمي لهذه الوحدة
  exports: [UsersService],         // مزودو الخدمات التي يمكن استخدامها خارج هذه الوحدة
})
export class UsersModule {}

مثال عملي لهيكل الوحدات

لنأخذ مثالاً لتطبيق به وحدة للمستخدمين ووحدة للمنتجات:

// app.module.ts
import { Module } from '@nestjs/common';
import { UsersModule } from './modules/users/users.module';
import { ProductsModule } from './modules/products/products.module';

@Module({
  imports: [UsersModule, ProductsModule],
})
export class AppModule {}

// modules/users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // تصدير الخدمة للاستخدام في وحدات أخرى
})
export class UsersModule {}

// modules/products/products.module.ts
import { Module } from '@nestjs/common';
import { ProductsController } from './products.controller';
import { ProductsService } from './products.service';
import { UsersModule } from '../users/users.module';

@Module({
  imports: [UsersModule], // استيراد وحدة المستخدمين للاستفادة من خدماتها
  controllers: [ProductsController],
  providers: [ProductsService],
})
export class ProductsModule {}

الوحدات العالمية

يمكنك إنشاء وحدات عالمية تكون متاحة تلقائياً للتطبيق بأكمله دون الحاجة لاستيرادها في كل وحدة. مثال:

import { Module, Global } from '@nestjs/common';
import { ConfigService } from './config.service';

@Global()  // جعل الوحدة عالمية
@Module({
  providers: [ConfigService],
  exports: [ConfigService],
})
export class ConfigModule {}

المتحكمات مسؤولة عن التعامل مع الطلبات الواردة وإرجاع الاستجابات للعميل. تستخدم لتحديد مسارات API وطرق الطلب ومعالجتها.

تعريف المتحكم

يتم تعريف المتحكم باستخدام واصم @Controller():

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { User } from './interfaces/user.interface';

@Controller('users')  // المسار الأساسي: /users
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()  // GET /users
  findAll(): User[] {
    return this.usersService.findAll();
  }

  @Get(':id')  // GET /users/:id (مثلاً /users/123)
  findOne(@Param('id') id: string): User {
    return this.usersService.findOne(id);
  }

  @Post()  // POST /users
  create(@Body() createUserDto: CreateUserDto): User {
    return this.usersService.create(createUserDto);
  }
}

واصمات طرق HTTP

NestJS يوفر واصمات لجميع طرق HTTP الشائعة:

واصمات المعلمات

للوصول إلى معلمات مختلفة من الطلب، توفر NestJS عدة واصمات:

import { Controller, Get, Post, Body, Param, Query, Headers, Req } from '@nestjs/common';
import { Request } from 'express';

@Controller('example')
export class ExampleController {
  @Get('params/:id')
  withParams(@Param('id') id: string): string {
    return `معلمة المسار: ${id}`;
  }

  @Get('query')
  withQuery(@Query('name') name: string): string {
    return `معلمة الاستعلام: ${name}`;
  }

  @Post()
  withBody(@Body() body: any): string {
    return `جسم الطلب: ${JSON.stringify(body)}`;
  }

  @Get('headers')
  withHeaders(@Headers('user-agent') userAgent: string): string {
    return `ترويسة المستخدم: ${userAgent}`;
  }

  @Get('request')
  withRequest(@Req() request: Request): string {
    return `كائن الطلب الكامل متاح هنا`;
  }
}

أنواع الاستجابات

هناك عدة طرق للتعامل مع الاستجابات في NestJS:

import { Controller, Get, Post, HttpCode, Header, Redirect, Res } from '@nestjs/common';
import { Response } from 'express';

@Controller('responses')
export class ResponsesController {
  @Get('standard')
  standard(): string {
    return 'استجابة قياسية';  // استجابة نصية مع رمز 200
  }

  @Get('object')
  object(): object {
    return { message: 'استجابة كائن' };  // يتم تحويلها تلقائيًا إلى JSON
  }
  
  @Post('status')
  @HttpCode(201)  // تغيير رمز الحالة إلى 201
  status(): string {
    return 'تم إنشاء العنصر';
  }
  
  @Get('headers')
  @Header('Cache-Control', 'none')  // إضافة ترويسة مخصصة
  headers(): string {
    return 'استجابة مع ترويسات مخصصة';
  }
  
  @Get('redirect')
  @Redirect('https://nestjs.com', 301)  // إعادة توجيه مع رمز 301
  redirect() {}
  
  @Get('custom')
  custom(@Res() res: Response) {
    return res
      .status(202)
      .header('Custom-Header', 'Value')
      .send('استجابة مخصصة بالكامل');
  }
}

مزودو الخدمات هم المفهوم الأساسي في NestJS. يمكن اعتبار الكثير من الصفوف الأساسية في NestJS كمزودي خدمات: الخدمات، المخازن، الأنظمة، وغيرها. الفكرة الأساسية لمزود الخدمة هو أنه يمكن حقنه كتبعية، مما يعني أن الكائنات يمكن أن تنشئ علاقات مختلفة مع بعضها البعض.

تعريف مزود الخدمة

يتم تعريف مزود الخدمة عادةً باستخدام واصم @Injectable():

import { Injectable } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';

@Injectable()
export class CatsService {
  private readonly cats: Cat[] = [];

  create(cat: Cat) {
    this.cats.push(cat);
  }

  findAll(): Cat[] {
    return this.cats;
  }
  
  findOne(id: string): Cat {
    return this.cats.find(cat => cat.id === id);
  }
}

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

لكي يعرف NestJS عن مزود الخدمة، يجب تسجيله في وحدة:

import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService],  // تسجيل مزود الخدمة
})
export class CatsModule {}

هناك طرق مختلفة لتسجيل مزودي الخدمات:

@Module({
  providers: [
    // الطريقة القياسية (اختصار للطريقة التالية)
    CatsService,
    
    // الطريقة الصريحة
    {
      provide: CatsService,
      useClass: CatsService,
    },
    
    // استخدام رمز مخصص
    {
      provide: 'CATS_SERVICE',
      useClass: CatsService,
    },
    
    // استخدام قيمة
    {
      provide: 'API_KEY',
      useValue: 'my-api-key',
    },
    
    // استخدام مصنع
    {
      provide: 'DATABASE_CONNECTION',
      useFactory: () => {
        // منطق معقد لإنشاء اتصال بقاعدة البيانات
        return dbConnection;
      },
    },
    
    // مصنع مع تبعيات
    {
      provide: 'CONFIG_SERVICE',
      useFactory: (userService: UsersService) => {
        // منطق يعتمد على UsersService
        return new ConfigService(userService);
      },
      inject: [UsersService],  // تبعيات المصنع
    },
  ],
})
export class AppModule {}

استخدام مزود الخدمة

بعد تسجيل مزود الخدمة، يمكن حقنه في المتحكمات أو مزودي خدمات آخرين:

// حقن باستخدام المنشئ (constructor)
import { Controller, Get } from '@nestjs/common';
import { CatsService } from './cats.service';
import { Cat } from './interfaces/cat.interface';

@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get()
  findAll(): Cat[] {
    return this.catsService.findAll();
  }
}

// حقن باستخدام @Inject() (للرموز النصية)
import { Controller, Get, Inject } from '@nestjs/common';
import { Cat } from './interfaces/cat.interface';

@Controller('cats')
export class CatsController {
  constructor(@Inject('CATS_SERVICE') private readonly catsService) {}

  @Get()
  findAll(): Cat[] {
    return this.catsService.findAll();
  }
}

الخدمات في NestJS هي نوع من مزودي الخدمات المسؤولة عن منطق الأعمال والتفاعل مع مصادر البيانات. تساعد في فصل منطق الأعمال عن المتحكمات، وتجعل التطبيق أكثر قابلية للاختبار والصيانة.

إنشاء خدمة مع معاملات متعددة

مثال لخدمة تتعامل مع المستخدمين:

import { Injectable, NotFoundException } from '@nestjs/common';
import { User } from './interfaces/user.interface';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';

@Injectable()
export class UsersService {
  private users: User[] = [];

  create(createUserDto: CreateUserDto): User {
    const id = Date.now().toString(); // إنشاء معرف بسيط
    const newUser: User = {
      id,
      ...createUserDto,
      createdAt: new Date(),
    };
    
    this.users.push(newUser);
    return newUser;
  }

  findAll(): User[] {
    return this.users;
  }

  findOne(id: string): User {
    const user = this.users.find(user => user.id === id);
    
    if (!user) {
      throw new NotFoundException(`المستخدم بالمعرف ${id} غير موجود`);
    }
    
    return user;
  }

  update(id: string, updateUserDto: UpdateUserDto): User {
    const userIndex = this.users.findIndex(user => user.id === id);
    
    if (userIndex === -1) {
      throw new NotFoundException(`المستخدم بالمعرف ${id} غير موجود`);
    }
    
    const updatedUser = {
      ...this.users[userIndex],
      ...updateUserDto,
      updatedAt: new Date(),
    };
    
    this.users[userIndex] = updatedUser;
    return updatedUser;
  }

  remove(id: string): void {
    const userIndex = this.users.findIndex(user => user.id === id);
    
    if (userIndex === -1) {
      throw new NotFoundException(`المستخدم بالمعرف ${id} غير موجود`);
    }
    
    this.users.splice(userIndex, 1);
  }
}

حقن الخدمات في خدمات أخرى

يمكن حقن الخدمات في خدمات أخرى، مما يسمح بتصميم منطق أعمال معقد ومنظم:

import { Injectable } from '@nestjs/common';
import { LoggerService } from '../logger/logger.service';
import { UsersRepository } from './users.repository';

@Injectable()
export class UsersService {
  constructor(
    private readonly logger: LoggerService,
    private readonly usersRepository: UsersRepository,
  ) {}

  async findById(id: string) {
    this.logger.log(`البحث عن المستخدم بالمعرف: ${id}`);
    const user = await this.usersRepository.findById(id);
    
    if (!user) {
      this.logger.warn(`لم يتم العثور على المستخدم بالمعرف: ${id}`);
      return null;
    }
    
    return user;
  }
}

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

كيفية عمل حقن التبعية في NestJS

يعتمد NestJS على ثلاثة مفاهيم رئيسية لحقن التبعية:

• مزودو الخدمات (Providers): كائنات يمكن حقنها في مكونات أخرى كتبعيات
• المستهلكون (Consumers): المكونات التي تستهلك الخدمات (مثل المتحكمات)
• حاوية الحقن (IoC Container): نظام الـ NestJS الذي يدير ويحقن التبعيات

مثال عملي

فيما يلي مثال كامل يوضح كيفية عمل حقن التبعية:

// cats.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class CatsService {
  private cats = [];
  
  findAll() {
    return this.cats;
  }
  
  create(cat) {
    this.cats.push(cat);
    return cat;
  }
}

// cats.controller.ts
import { Controller, Get, Post, Body } from '@nestjs/common';
import { CatsService } from './cats.service';

@Controller('cats')
export class CatsController {
  // حقن CatsService من خلال المنشئ (constructor)
  constructor(private readonly catsService: CatsService) {}
  
  @Get()
  findAll() {
    // استخدام الخدمة المحقونة
    return this.catsService.findAll();
  }
  
  @Post()
  create(@Body() cat) {
    return this.catsService.create(cat);
  }
}

// cats.module.ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  controllers: [CatsController],
  providers: [CatsService], // تسجيل الخدمة كمزود
})
export class CatsModule {}

أنواع مزودي الخدمات

NestJS يدعم عدة أنواع من مزودي الخدمات:

@Module({
  providers: [
    // قيمة - استخدام صنف
    CatsService,
    
    // توفير رمز ل useClass
    {
      provide: CatsService,
      useClass: CatsService,
    },
    
    // توفير واجهة أو رمز نصي
    {
      provide: 'CATS_SERVICE',
      useClass: CatsService,
    },
    
    // توفير قيمة ثابتة
    {
      provide: 'API_KEY',
      useValue: 'secret_key_12345',
    },
    
    // توفير قيمة عبر مصنع (Factory)
    {
      provide: 'CONNECTION',
      useFactory: () => {
        return createConnection();
      },
    },
    
    // مصنع مع حقن تبعيات
    {
      provide: 'USERS_REPOSITORY',
      useFactory: (connection: Connection) => {
        return connection.getRepository(User);
      },
      inject: ['CONNECTION'], // مزودو الخدمات المطلوبين للمصنع
    },
    
    // توفير قيمة عبر خدمة أخرى موجودة
    {
      provide: 'CACHED_CATS',
      useExisting: CatsService,
    },
  ],
})
export class AppModule {}

البرمجيات الوسيطة (Middleware) هي وظائف يتم تنفيذها قبل معالج المسار. لديها حق الوصول إلى كائنات الطلب (request) والاستجابة (response) ودالة next() في دورة طلب واستجابة الخادم.

إنشاء برمجية وسيطة

يمكن إنشاء برمجية وسيطة بتنفيذ واجهة NestMiddleware:

import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`طلب ${req.method} على المسار: ${req.url}`);
    console.log(`موجه من: ${req.ip}`);
    
    // هام: يجب استدعاء next() لمتابعة سلسلة المعالجة
    next();
  }
}

برمجية وسيطة وظيفية

يمكن أيضًا إنشاء برمجية وسيطة كدالة بسيطة:

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`طلب ${req.method} على المسار: ${req.url}`);
  next();
}

تطبيق البرمجية الوسيطة

لتطبيق البرمجية الوسيطة، يجب تنفيذ واجهة NestModule في الوحدة:

import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { LoggerMiddleware } from './common/middleware/logger.middleware';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(LoggerMiddleware)
      .forRoutes('cats'); // تطبيق على جميع مسارات /cats
  }
}

تطبيق أكثر تحديدًا

يمكن تطبيق البرمجية الوسيطة بشكل أكثر تحديدًا على مسارات وطرق HTTP معينة:

import { RequestMethod } from '@nestjs/common';

configure(consumer: MiddlewareConsumer) {
  consumer
    .apply(LoggerMiddleware)
    .forRoutes(
      { path: 'cats', method: RequestMethod.GET },
      { path: 'cats/:id', method: RequestMethod.DELETE }
    );
}

استبعاد مسارات

يمكن استبعاد مسارات معينة من تطبيق البرمجية الوسيطة:

consumer
  .apply(LoggerMiddleware)
  .exclude(
    { path: 'cats', method: RequestMethod.POST },
    { path: 'cats/:id', method: RequestMethod.PATCH }
  )
  .forRoutes('cats');

تطبيق برمجيات وسيطة متعددة

يمكن تطبيق عدة برمجيات وسيطة معًا:

consumer
  .apply(cors(), helmet(), LoggerMiddleware)
  .forRoutes('cats');

برمجيات وسيطة عالمية

لتطبيق برمجية وسيطة على جميع المسارات في التطبيق، يمكن استخدام طريقة use() في مثيل التطبيق:

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { logger } from './common/middleware/logger.middleware';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.use(logger); // تطبيق البرمجية الوسيطة على جميع المسارات
  await app.listen(3000);
}
bootstrap();

مرشحات الاستثناءات في NestJS تسمح بالتحكم في معالجة الاستثناءات التي تحدث أثناء تنفيذ الطلبات، مما يتيح تخصيص استجابات الخطأ وتنسيقها.

الاستثناءات المدمجة

توفر NestJS عدة استثناءات مدمجة تغطي سيناريوهات HTTP الشائعة:

import {
  BadRequestException,
  UnauthorizedException,
  NotFoundException,
  ForbiddenException,
  InternalServerErrorException
} from '@nestjs/common';

// أمثلة على استخدام الاستثناءات المدمجة
throw new BadRequestException('بيانات غير صالحة');
throw new UnauthorizedException('غير مصرح به');
throw new NotFoundException('المورد غير موجود');
throw new ForbiddenException('محظور الوصول');
throw new InternalServerErrorException('خطأ في الخادم');

إنشاء مرشح استثناءات مخصص

لإنشاء مرشح استثناءات مخصص، يجب تنفيذ واجهة ExceptionFilter:

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Request, Response } from 'express';

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    const status = exception.getStatus();
    const message = exception.message || 'حدث خطأ';
    
    // تنسيق مخصص للاستجابة
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: message,
    });
  }
}

تطبيق مرشح الاستثناءات

يمكن تطبيق مرشح الاستثناءات بعدة طرق:

1. على مستوى المعالج

import { Controller, Get, UseFilters } from '@nestjs/common';
import { HttpExceptionFilter } from './http-exception.filter';

@Controller('cats')
export class CatsController {
  @Get()
  @UseFilters(HttpExceptionFilter)
  findAll() {
    throw new Error('طريقة غير مكتملة');
  }
}

2. على مستوى المتحكم

import { Controller, UseFilters } from '@nestjs/common';
import { HttpExceptionFilter } from './http-exception.filter';

@Controller('cats')
@UseFilters(HttpExceptionFilter)
export class CatsController {
  // جميع معالجات المسارات في هذا المتحكم ستستخدم المرشح
}

3. على مستوى التطبيق

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { HttpExceptionFilter } from './http-exception.filter';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalFilters(new HttpExceptionFilter());
  await app.listen(3000);
}
bootstrap();

التقاط عدة أنواع من الاستثناءات

يمكن للمرشح التقاط عدة أنواع من الاستثناءات:

@Catch(HttpException, BadRequestException, NotFoundException)
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // معالجة الاستثناء
  }
}

التقاط جميع الاستثناءات

لالتقاط جميع الاستثناءات، استخدم @Catch() بدون وسيطات:

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();
    
    // التحقق من نوع الاستثناء
    let status = 500;
    let message = 'حدث خطأ داخلي في الخادم';
    
    if (exception instanceof HttpException) {
      status = exception.getStatus();
      message = exception.message;
    }
    
    response.status(status).json({
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      message: message,
    });
  }
}

الأنابيب (Pipes) في NestJS هي فئات تعالج البيانات المنقولة بين العميل والمعالجات. لها وظيفتان رئيسيتان: التحويل (transformation) والتحقق (validation).

الأنابيب المدمجة

توفر NestJS عدة أنابيب مدمجة:

• ValidationPipe: للتحقق من صحة البيانات المستلمة
• ParseIntPipe: لتحويل القيمة إلى عدد صحيح
• ParseFloatPipe: لتحويل القيمة إلى عدد عشري
• ParseBoolPipe: لتحويل القيمة إلى قيمة منطقية
• ParseArrayPipe: لتحويل القيمة إلى مصفوفة
• ParseUUIDPipe: للتحقق من أن القيمة هي UUID صالح
• DefaultValuePipe: لتوفير قيمة افتراضية

استخدام الأنابيب المدمجة

مثال على استخدام الأنابيب المدمجة:

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

@Controller('cats')
export class CatsController {
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    // id سيكون عدد صحيح، وإلا يتم رمي استثناء BadRequestException
    return `هذا القط رقم ${id}`;
  }
  
  @Get()
  findAll(
    @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number,
    @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number
  ) {
    // استخدام DefaultValuePipe لتوفير قيم افتراضية
    return `عرض القطط، الصفحة ${page} بحد ${limit} قطة`;
  }
}

إنشاء أنبوب مخصص

يمكن إنشاء أنبوب مخصص بتنفيذ واجهة PipeTransform:

import { PipeTransform, Injectable, ArgumentMetadata, BadRequestException } from '@nestjs/common';

@Injectable()
export class PositiveIntPipe implements PipeTransform {
  transform(value: string, metadata: ArgumentMetadata): number {
    // تحويل القيمة إلى عدد
    const val = parseInt(value, 10);
    
    // التحقق من أنها عدد صحيح موجب
    if (isNaN(val) || val <= 0) {
      throw new BadRequestException('يجب أن تكون القيمة عددًا صحيحًا موجبًا');
    }
    
    return val;
  }
}

• implements PipeTransform: تنفيذ واجهة PipeTransform مع تحديد الأنواع
• transform(value, metadata): الطريقة الإلزامية التي تتلقى القيمة ومعلومات وصفية
• parseInt(value, 10): تحويل القيمة إلى عدد صحيح
• isNaN(val) || val <= 0: التحقق من أن القيمة عدد صحيح موجب
• throw new BadRequestException(): رمي استثناء في حالة فشل التحقق
• return val: إرجاع القيمة المحولة

@Get(':id')
findOne(@Param('id', PositiveIntPipe) id: number) {
  return this.catsService.findOne(id);
}

npm install --save class-validator class-transformer

import { IsString, IsInt, IsEmail, Min, Max, Length } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @Length(2, 20)
  readonly name: string;

  @IsInt()
  @Min(18)
  @Max(100)
  readonly age: number;

  @IsEmail()
  readonly email: string;
}

// لتمكين التحقق على مستوى التطبيق
import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe());
  await app.listen(3000);
}
bootstrap();

@Post()
create(@Body() createUserDto: CreateUserDto) {
  // سيتم التحقق من البيانات تلقائيًا
  // إذا كان هناك خطأ في التحقق، سيتم رمي استثناء BadRequestException
  return this.usersService.create(createUserDto);
}

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true, // إزالة الخصائص غير المحددة في الـ DTO
    forbidNonWhitelisted: true, // رمي استثناء إذا كانت هناك خصائص غير محددة
    transform: true, // تحويل البيانات الواردة تلقائيًا إلى النوع المحدد
    transformOptions: {
      enableImplicitConversion: true, // تحويل الأنواع تلقائيًا
    },
    disableErrorMessages: false, // تعطيل رسائل الخطأ في الإنتاج
    validationError: {
      target: false, // عدم إضافة الكائن المستهدف في رسالة الخطأ
      value: true, // إضافة قيمة الخاصية غير الصالحة
    },
  }),
);