انتقل إلى المحتوى الرئيسي

التحضيرات لإنشاء RestController

رسالة إلى المتعلمين​

قبل البدء في التمرين العملي لإنشاء RestController، من الضروري أن تأخذ الوقت الكافي لقراءة هذا القسم جيدًا. ليس الوقت الآن للبرمجة، بل للتحضير وفهم النظرية وراء ما سنقوم به.

1. ما هو خدمة الويب؟​

خدمة الويب هي مكون برمجي يسمح للتطبيقات بالتواصل فيما بينها عبر شبكة. تعرض وظائف أو بيانات يمكن لتطبيقات أخرى استهلاكها بإرسال طلبات HTTP واستقبال الردود.

بنية العميل-الخادم​

تدفق الاتصال​

2. التعليقات التوضيحية في Spring Boot​

التعليقات التوضيحية هي بيانات وصفية نضيفها إلى الكود لتحديد كيفية تصرف بعض الأجزاء. تسمح لـ Spring Boot بتكوين تطبيقك تلقائيًا.

التعليقات التوضيحية الرئيسية​

التعليق التوضيحيالدورمثال
@RestControllerيشير إلى أن الفئة هي وحدة تحكم REST التي تدير طلبات HTTP وتعيد الردود بتنسيق JSON أو XML@RestController public class CardController
@RequestMappingيربط عنوان URL الأساسي بفئة أو طريقة@RequestMapping("/cards")
@GetMappingيحدد أن الطريقة تستجيب لطلبات HTTP GET@GetMapping("/hello")
@PostMappingيحدد أن الطريقة تستجيب لطلبات HTTP POST@PostMapping("/create")
@PutMappingيحدد أن الطريقة تستجيب لطلبات HTTP PUT@PutMapping("/update")
@DeleteMappingيحدد أن الطريقة تستجيب لطلبات HTTP DELETE@DeleteMapping("/delete")

تسلسل التعليقات التوضيحية​

3. النموذج (Model) ووحدة التحكم (Controller)​

النموذج​

النموذج هو فئة Java تمثل كيان عمل. يحتوي على السمات والأساليب لإدارة البيانات.

مثال: نموذج Card

الكود Java المقابل:

public class Card {
    private int cardId;
    private int customerId;
    private String cardNumber;
    private String cardType;
    private int totalLimit;
    private int amountUsed;
    private int availableAmount;
    private String createDt;
    
    // Getters et Setters
}

وحدة التحكم​

وحدة التحكم هي فئة تدير الطلبات HTTP الواردة وتعيد الردود. تربط بين العميل ومنطق العمل.

مثال: وحدة التحكم CardController

الكود Java المقابل:

@RestController
@RequestMapping("/cards")
public class CardController {
    
    @GetMapping("/hello")
    public String helloCard() {
        return "Hello, Card!";
    }
    
    @GetMapping("/{id}")
    public Card getCard(@PathVariable int id) {
        // منطق لاسترجاع بطاقة
    }
    
    @PostMapping
    public Card createCard(@RequestBody Card card) {
        // منطق لإنشاء بطاقة
    }
}

بنية MVC مع Spring Boot​

4. المتطلبات التقنية​

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

التحقق من الأدوات​

1. Java Development Kit (JDK)​

الإصدار المطلوب: Java 17 أو أعلى

التحقق:

java -version

النتيجة المتوقعة:

java version "17.0.x" أو أعلى

2. Apache Maven​

الإصدار المطلوب: Maven 3.9 أو أعلى (موصى به للاستقرار)

التحقق:

mvn -version

النتيجة المتوقعة:

Apache Maven 3.9.x أو أعلى
Java version: 17.x.x

ملاحظة: يوفر Maven 3.9+ استقرارًا وتوافقًا أفضل مع Java 17+.

3. Visual Studio Code​

الإضافات المطلوبة:

  • Extension Pack for Java
  • Spring Boot Extension Pack

مخطط بيئة التطوير​

5. خطة التمرين العملي​

الهدف​

تعلم كيفية إنشاء وحدة تحكم REST لإدارة طلبات HTTP بإنشاء تطبيق Spring Boot كامل.

خطوات التمرين​

تفاصيل الخطوات​

الخطوة 1: تكوين المشروع​

استخدام Spring Initializr لإنشاء مشروع Spring Boot مع:

  • المشروع: Maven
  • اللغة: Java
  • إصدار Spring Boot: 3.x
  • التبعيات: Spring Web, Spring Boot DevTools

الخطوة 2: إنشاء النموذج​

إنشاء فئة Card في الحزمة model مع السمات اللازمة.

الخطوة 3: إنشاء وحدة التحكم​

إنشاء فئة CardController في الحزمة controller مع:

  • التعليق التوضيحي @RestController
  • التعليق التوضيحي @RequestMapping("/cards")
  • طرق مع @GetMapping, @PostMapping, إلخ.

الخطوة 4: التجميع والتشغيل باستخدام Maven​

أوامر Maven الأساسية:

الخيار 1: أوامر منفصلة

# تنظيف المشروع
mvn clean

# تجميع وتثبيت (بدون اختبارات)
mvn install -DskipTests

# تشغيل التطبيق
mvn spring-boot:run

الخيار 2: أمر مجمع (موصى به)

# كل شيء في أمر واحد
mvn clean install -DskipTests spring-boot:run

شرح الأوامر:

  • mvn clean : يحذف الملفات المجمعة السابقة
  • mvn install : يجمع المشروع وينشئ ملف JAR
  • -DskipTests : يتجاهل تنفيذ الاختبارات (أسرع للتطوير)
  • spring-boot:run : يشغل التطبيق Spring Boot

ملاحظة: الأمر المجمع أكثر فعالية لأنه ينفذ الدورة الكاملة في مرة واحدة.

الخطوة 6: الاختبار​

اختبار النقاط النهائية:

  • http://localhost:8080/cards/hello
  • استخدام Postman لاختبار الطرق الأخرى

6. هيكل مشروع Spring Boot​

7. دورة حياة طلب HTTP​

المفاهيم الرئيسية التي يجب تذكرها​

1. فصل المسؤوليات​

2. التعليقات التوضيحية في Spring Boot​

  • @RestController = @Controller + @ResponseBody (يعيد تلقائيًا JSON)
  • @RequestMapping يحدد المسار الأساسي
  • @GetMapping/@PostMapping/@PutMapping/@DeleteMapping تتوافق مع طرق HTTP

3. تنسيق الرد​

بشكل افتراضي، يقوم Spring Boot بتحويل الكائنات Java تلقائيًا إلى JSON بفضل Jackson.

الخاتمة​

قدمت لك هذه القراءة التحضيرية:

  • فهم لخدمات الويب وكيفية عملها
  • معرفة بالتعليقات التوضيحية الأساسية في Spring Boot
  • التمييز بين النموذج ووحدة التحكم
  • المتطلبات التقنية اللازمة
  • نظرة عامة على خطة التمرين العملي

أنت الآن جاهز للانتقال إلى التمرين العملي حيث ستقوم بإنشاء أول RestController لك!

مهم: إذا كان هناك شيء غير واضح، لا تتردد في إعادة قراءة هذا القسم أو طرح الأسئلة. الفهم النظري الجيد سيسهل بشكل كبير الممارسة.

التنقل​