دليل تعلم NestJS: المفاهيم الأساسية والعملية

NestJS Learning Guide: Core Concepts and Implementation

مرحباً بك في هذا الدليل التعليمي المخصص لمشروع Ads Analytics Platform. سنقوم هنا بشرح بنية البرنامج وكيفية تداخل مكوناته بأسلوب مبسط وموجه للمطورين.

🏗️ 1. البنية العامة (General Architecture)

تعتمد NestJS على بنية النماذج (Modules). كل ميزة في التطبيق (مثل الإعلانات أو التحليلات) يتم فصلها في "موديول" مستقل.

AppModule: هو الجذر (Root) الذي يربط كل الموديولات ببعضها.
Controller: هو المسؤول عن استقبال الطلبات (HTTP Requests) وإرجاع الردود.
Service (Provider): هنا يكمن "المنطق" (Logic)، مثل حساب الأرباح أو جلب البيانات من Meta API.

💉 2. حقن التبعيات (Dependency Injection)

يعتبر "حقن التبعيات" من أهم ميزات NestJS. بدلاً من أن يقوم الكائن بإنشاء تبعياته بنفسه (مثل استخدام new AnalyticsService())، يقوم المحرك (Nest IoC Container) بتمريرها له.

لماذا نستخدمه؟

سهولة الاختبار (Testing): يمكننا بسهولة استبدال الخدمة الحقيقية بواحدة وهمية (Mock) أثناء الاختبار.
برمجة نظيفة: فصل المهام وجعل الكود أقل تشابكاً.

مثال من المشروع: في MetaAdsController نقوم بحقن الـ MetaAdsService عبر الـ constructor:

constructor(private readonly metaAdsService: MetaAdsService) {}

📦 3. الكبسلة (Encapsulation)

في NestJS، كل موديول هو "صندوق مغلق" افتراضياً. إذا أردت استخدام خدمة من موديول في موديول آخر، يجب عليك:

تصديرها (Export) من الموديول الأصلي.
استيرادها (Import) في الموديول الجديد.

هذا يضمن أن المكونات لا تتداخل بشكل عشوائي، مما يسهل صيانة النظام الكبير.

🧬 4. الوراثة (Inheritance)

نستخدم الوراثة لتقليل تكرار الكود. على سبيل المثال، قد يكون لدينا "خطأ مخصص" يرث من HttpException الأساسي في NestJS.

مثال: مراقب الاستثناءات (Exception Filter) قد يرث ميزات معينة أو نستخدم الوراثة في DTOs (Data Transfer Objects) لمشاركة الحقول بين طلبات الإضافة والتعديل.

🔍 5. كيف يعمل المشروع الحالي؟

عندما تطلب المسار /api/meta/insights:

الطلب يمر عبر Middlewares (إن وجدت).
يصل إلى MetaAdsController.
الـ Controller ينادي الوظيفة المطلوبة في MetaAdsService.
الـ Service تقوم بالتواصل مع Meta API وتجري الحسابات.
النتيجة تعود كـ JSON للمستخدم.

Tip

نصيحة: دائماً ابدأ بتصميم موديول مستقل لكل ميزة جديدة لضمان قابلية التوسع (Scalability).

3.4 KiB Raw Blame History