كيف تتعامل مع الاستثناءات في NestJS؟

Question

Accepted Answer

NestJS لديها **طبقة استثناءات مدمجة** تقوم تلقائياً بالتقاط الأخطاء غير المعالجة وتحويلها إلى استجابات HTTP مناسبة. تشير إلى الأخطاء برمي **استثناءات** (غالباً فئات استثناءات HTTP مدمجة)، و Nest تنسقها إلى استجابات JSON منظمة برمز الحالة الصحيح.

## رمي استثناءات HTTP مدمجة

```ts
import { NotFoundException, BadRequestException, UnauthorizedException } from "@nestjs/common";

@Get(":id")
findOne(@Param("id") id: string) {
  const user = this.usersService.findOne(id);
  if (!user) {
    throw new NotFoundException("User not found");   // → 404 with a JSON error body
  }
  return user;
}
```

NestJS توفر فئات استثناءات مرتبطة برموز حالة HTTP، ورمي واحدة ينتج عنها استجابة صحيحة ومنظمة تلقائياً:

```json
{ "statusCode": 404, "message": "User not found", "error": "Not Found" }
```

## استثناءات HTTP مدمجة شائعة

```text
BadRequestException        → 400
UnauthorizedException      → 401
ForbiddenException         → 403
NotFoundException          → 404
ConflictException          → 409
UnprocessableEntityException → 422
InternalServerErrorException → 500
```

هناك فئة لكل خطأ HTTP شائع — استخدم الفئة المناسبة للتواصل برمز الحالة الصحيح.

## رسائل مخصصة و HttpException العامة

```ts
// custom status + body via the base HttpException
throw new HttpException(
  { status: HttpStatus.FORBIDDEN, error: "custom message" },
  HttpStatus.FORBIDDEN,
);
```

## فئات استثناءات مخصصة

```ts
export class UserNotFoundException extends NotFoundException {
  constructor(id: string) {
    super(`User with id ${id} not found`);   // domain-specific, reusable
  }
}
throw new UserNotFoundException(id);
```

## الأخطاء غير المعالجة تصبح 500s

```text
If code throws a non-HttpException error (e.g. a plain Error or an unexpected
exception), NestJS's default exception filter catches it and returns a generic
500 Internal Server Error (without leaking internal details to the client).
```

## مرشحات الاستثناءات للتخصيص العام

```ts
// a custom exception filter customizes how errors are formatted/logged globally
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // log, format the response, etc.
  }
}
app.useGlobalFilters(new AllExceptionsFilter());   // apply app-wide
```

للحصول على تنسيق خطأ متسق أو تسجيل أو معالجة أخطاء غير HTTP، تستخدم **مرشحات الاستثناءات** (ميزة مرتبطة وأكثر تقدماً).

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

معالجة الاستثناءات الصحيحة ضرورية لبناء واجهات برمجية موثوقة، و طبقة الاستثناءات المدمجة في NestJS تجعلها نظيفة ومتسقة.
هم كيفية **رمي استثناءات HTTP** (`NotFoundException`, `BadRequestException`, إلخ) هو معرفة يومية — إنها الطريقة الاصطلاحية للإشارة إلى الأخطاء برموز الحالة الصحيحة واستجابات JSON منظمة وودية للعميل، بدون بناء استجابات خطأ يدويًا في كل معالج.

الإطار يقوم تلقائياً بالتقاط هذه وتنسيقها، ويحول بأمان الأخطاء غير المتوقعة إلى 500s عامة بدون تسرب التفاصيل الداخلية (مهم للأمان).

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

معالجة الأخطاء النظيفة والمتسقة هي علامة مميزة لرمز back-end عالي الجودة، مما يجعل هذا جانباً أساسياً وكثير الاستخدام من الإطار.