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

TP2.1 - تطبيق "Greeting" باستخدام Spring Boot

الأهداف​

سيمكنك هذا العمل العملي من:

  • إنشاء مشروعك الأول باستخدام Spring Boot مع Spring Initializr
  • تكوين Visual Studio Code لتطوير Spring Boot
  • إنشاء وحدة تحكم REST بسيطة
  • فهم هيكل مشروع Spring Boot
  • حل المشاكل الشائعة عند البدء

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

قبل البدء، تأكد من تثبيت:

  • JDK 17 أو أعلى
  • Visual Studio Code
  • الملحقات المطلوبة لـ VS Code:
    • Extension Pack for Java
    • Spring Boot Extension Pack
    • Maven for Java
  • Maven 3.9+ (موصى به للاستقرار)

التحقق من المتطلبات الأساسية​

# التحقق من Java
java -version

# التحقق من Maven
mvn -version

الجزء 1: إنشاء المشروع باستخدام Spring Initializr​

الخطوة 1.1: الوصول إلى Spring Initializr​

افتح متصفحك وانتقل إلى: https://start.spring.io/

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

قم بتكوين مشروعك باستخدام الإعدادات التالية:

المعلمةالقيمة
ProjectMaven
LanguageJava
Spring Boot3.2.0 (أو أحدث إصدار مستقر)
Groupcom.example
Artifactgreeting
Namegreeting
Package namecom.example.demo
PackagingJar
Java17

الخطوة 1.3: إضافة التبعيات​

انقر على "Add Dependencies" وأضف:

  • Spring Web - لإنشاء تطبيقات ويب REST

مهم: لهذا العمل العملي، نحن نضيف فقط Spring Web. لا تضف:

  • Spring Data JPA
  • PostgreSQL Driver
  • Lombok

(سنرى هذه التبعيات في الأعمال العملية التالية)

الخطوة 1.4: توليد المشروع​

  1. انقر على زر Generate
  2. سيتم تنزيل ملف ZIP: greeting.zip
  3. فك ضغط هذا الملف في مساحة العمل الخاصة بك (على سبيل المثال: C:\workspace\greeting)

الجزء 2: فتح المشروع في VS Code​

الخطوة 2.1: فتح المشروع​

  1. شغل Visual Studio Code
  2. القائمة: File → Open Folder
  3. اختر المجلد greeting المفكوك
  4. سيقوم VS Code باكتشاف مشروع Maven تلقائيًا

الخطوة 2.2: انتظار التهيئة​

سيقوم VS Code بـ:

  • تنزيل تبعيات Maven
  • تكوين مشروع Java
  • فهرسة الملفات

ملاحظة: قد يستغرق الأمر بضع دقائق في المرة الأولى.

الخطوة 2.3: هيكل المشروع​

يجب أن ترى الهيكل التالي:

greeting/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/demo/
│   │   │       └── GreetingApplication.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
├── pom.xml
└── README.md

الجزء 3: إنشاء الفئات​

الخطوة 3.1: إنشاء فئة Greeting​

  1. في VS Code، انقر بزر الماوس الأيمن على src/main/java/com/example/demo
  2. اختر New File
  3. سم الملف: Greeting.java

كود فئة Greeting:

package com.example.demo;

public class Greeting {

    private Long id;
    private String content;
    
    public Greeting(Long id, String content) {
        super();
        this.id = id;
        this.content = content;
    }
    
    public Long getId() {
        return id;
    }
    
    public String getContent() {
        return content;
    }
    
    public void setId(Long id) {
        this.id = id;
    }
    
    public void setContent(String content) {
        this.content = content;
    }
}

الخطوة 3.2: إنشاء فئة GreetingController​

  1. في نفس المجلد، أنشئ ملفًا جديدًا: GreetingController.java

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

package com.example.demo;

import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();
    
    @GetMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }
}

الجزء 4: التحقق من pom.xml​

الخطوة 4.1: فتح pom.xml​

افتح ملف pom.xml وتحقق من التبعيات.

التبعيات المتوقعة (فقط 2):

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

الخطوة 4.2: شرح التبعيات​

التبعيةالدور
spring-boot-starter-webيوفر كل ما يلزم لإنشاء تطبيقات ويب REST (Tomcat، Spring MVC، Jackson)
spring-boot-starter-testيوفر أدوات الاختبار (JUnit، Mockito، إلخ)

الخطوة 4.3: إذا كان لديك تبعيات إضافية​

إذا قمت بإضافة عن طريق الخطأ:

  • spring-boot-starter-data-jpa
  • postgresql
  • lombok

احذفها من pom.xml لتجنب الأخطاء.

لماذا؟ هذه التبعيات تتطلب تكوينًا إضافيًا (قاعدة بيانات، إلخ) لا نقوم به في هذا العمل العملي.

الجزء 5: التجميع والتنفيذ​

الخطوة 5.1: تنظيف وتجميع باستخدام Maven​

الخيار A: عبر الطرفية المدمجة في VS Code

  1. افتح الطرفية: Terminal → New Terminal
  2. نفذ الأوامر:
mvn clean
mvn install

الخيار B: عبر ملحق Maven

  1. افتح عرض Maven (أيقونة Maven في الشريط الجانبي)
  2. قم بتوسيع مشروعك
  3. انقر بزر الماوس الأيمن على clean → Run
  4. انقر بزر الماوس الأيمن على install → Run

الخطوة 5.2: تشغيل التطبيق​

الخيار A: عبر الطرفية

mvn spring-boot:run

الخيار B: عبر VS Code

  1. افتح GreetingApplication.java
  2. انقر على Run فوق طريقة main
  3. أو اضغط على F5

الخطوة 5.3: التحقق من التشغيل​

يجب أن ترى في وحدة التحكم:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::

...
Started GreetingApplication in X.XXX seconds

الخادم يبدأ على المنفذ 8080 افتراضيًا.

الجزء 6: اختبار التطبيق​

الخطوة 6.1: اختبار في المتصفح​

افتح متصفحك واختبر الروابط التالية:

الاختبار 1:

http://localhost:8080/greeting?name=Armstrong

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

{
  "id": 1,
  "content": "Hello, Armstrong!"
}

الاختبار 2:

http://localhost:8080/greeting?name=François

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

{
  "id": 2,
  "content": "Hello, François!"
}

الاختبار 3:

http://localhost:8080/greeting?name=Patrick

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

{
  "id": 3,
  "content": "Hello, Patrick!"
}

الخطوة 6.2: ملاحظة العداد​

قم بتحديث الصفحة عدة مرات ولاحظ:

  • يتم زيادة المعرف مع كل استدعاء
  • يتم الاحتفاظ بالعداد في الذاكرة أثناء تشغيل التطبيق

الخطوة 6.3: اختبار باستخدام Postman (اختياري)​

إذا كان لديك Postman مثبتًا:

  1. أنشئ طلبًا جديدًا GET
  2. URL: http://localhost:8080/greeting?name=VotreNom
  3. انقر على Send

الجزء 7: حل المشاكل​

المشكلة 1: خطأ في التشغيل - تبعيات مفقودة​

العَرَض:

Failed to configure a DataSource: 'url' attribute is not specified

السبب: ربما لديك spring-boot-starter-data-jpa في pom.xml الخاص بك

الحل:

افتح pom.xml و احذف هذه التبعيات إذا كانت موجودة:

<!-- يجب الحذف -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

ثم أعد التشغيل:

mvn clean install
mvn spring-boot:run

المشكلة 2: المنفذ 8080 مستخدم بالفعل​

العَرَض:

Port 8080 was already in use.

السبب: تطبيق آخر يستخدم بالفعل المنفذ 8080.

الحل 1: تغيير المنفذ

افتح src/main/resources/application.properties وأضف:

server.port=8081

أو إذا كنت تستخدم application.yml:

server:
  port: 8081

ثم اختبر باستخدام: http://localhost:8081/greeting?name=Test

الحل 2: إنهاء العملية التي تستخدم المنفذ 8080

على Windows:

  1. العثور على العملية:
netstat -ano | findstr :8080

  1. لاحظ PID (معرف العملية) في العمود الأخير

  2. إنهاء العملية (كمسؤول):

taskkill /F /PID <numéro_du_PID>

على macOS/Linux:

  1. العثور على العملية:
lsof -i :8080
  1. إنهاء العملية:
kill -9 <PID>

المشكلة 3: ملحقات VS Code مفقودة​

العَرَض: VS Code لا يكتشف مشروع Java

الحل:

  1. افتح علامة تبويب الملحقات (Ctrl + Shift + X)
  2. قم بتثبيت هذه الملحقات:
    • Extension Pack for Java (Microsoft)
    • Spring Boot Extension Pack (VMware)
    • Maven for Java (Microsoft)
  3. أعد تشغيل VS Code

المشكلة 4: Maven غير معترف به​

العَرَض:

'mvn' is not recognized as an internal or external command

الحل:

  1. قم بتنزيل Maven: https://maven.apache.org/download.cgi
  2. أضف Maven إلى PATH النظام الخاص بك
  3. أعد تشغيل الطرفية
  4. تحقق: mvn -version

الجزء 8: أسئلة الفهم​

الأسئلة​

  1. ما الذي تفعله التعليمة @RestController؟

  2. ما الفرق بين @RestController و @Controller؟

  3. ماذا يعني @GetMapping("/greeting")؟

  4. لماذا نستخدم AtomicLong بدلاً من Long بسيط؟

  5. ما الذي تفعله @RequestParam(value="name")؟

  6. لماذا يرد التطبيق تلقائيًا بصيغة JSON؟

  7. على أي منفذ يبدأ التطبيق افتراضيًا؟

  8. ماذا يحدث إذا نسينا المعلمة ?name= في الرابط؟

الإجابات المتوقعة​

(لإكمالها من قبل الطالب)

الجزء 9: تمارين إضافية​

التمرين 1: إضافة معلمة اختيارية​

قم بتعديل وحدة التحكم بحيث تكون المعلمة name اختيارية بقيمة افتراضية "World".

تلميح: استخدم defaultValue في @RequestParam

التمرين 2: إضافة طريقة جديدة​

أنشئ طريقة جديدة في وحدة التحكم:

  • URL: /greeting/time
  • تعيد: تحية مع الوقت الحالي

التمرين 3: تعديل القالب​

قم بتغيير القالب لإرجاع "Bonjour, %s!" بدلاً من "Hello, %s!"

التمرين 4: إضافة نقطة نهاية للصحة​

أنشئ نقطة نهاية /health التي تعيد ببساطة "OK"

التسليمات​

لتسليمها (حسب تعليمات معلمك):

  1. كود المصدر الكامل (مشروع ZIP)
  2. لقطات شاشة تظهر:
  3. وثيقة الإجابات على أسئلة الفهم
  4. التمارين المكتملة (إذا طُلبت)

معايير التقييم​

المعيارالنقاط
المشروع تم إنشاؤه بشكل صحيح باستخدام Spring Initializr10%
الفئات Greeting و GreetingController كاملة وتعمل30%
التطبيق يبدأ بدون أخطاء20%
الاختبارات ناجحة في المتصفح20%
الإجابات على أسئلة الفهم10%
التمارين الإضافية (مكافأة)10%
المجموع100%

موارد إضافية​

الوثائق​

دروس فيديو​

الأدوات​

لقطات شاشة مرجعية​

وثائق مع لقطات شاشة مفصلة:

راجع مجلد Google Drive التالي لرؤية لقطات شاشة كاملة لكل خطوة من خطوات العمل العملي:

📸 لقطات شاشة لمشروع Greeting

المحتوى المتاح:

  • وثيقة PDF مع لقطات شاشة مشروحة
  • وثيقة Word مع تعليمات مرئية
  • أمثلة للنتائج المتوقعة

ملاحظة: هذه اللقطات تستخدم STS (Spring Tool Suite)، لكن المفاهيم والنتائج متطابقة مع VS Code.

الخطوات التالية​

بمجرد إكمال هذا العمل العملي، ستكون جاهزًا لـ:

  • TP2: الاتصال بقاعدة بيانات باستخدام JPA
  • TP3: إنشاء API CRUD كامل
  • TP4: التأمين باستخدام Spring Security

ملاحظات هامة​

أفضل الممارسات:

  • دائمًا نفذ mvn clean قبل mvn install
  • أوقف التطبيق (Ctrl + C) قبل إعادة التشغيل
  • تحقق من أن المنفذ خالٍ قبل البدء
  • احفظ عملك بانتظام

المساعدة:

إذا واجهت مشاكل:

  1. راجع قسم "حل المشاكل"
  2. تحقق من السجلات في وحدة التحكم
  3. ابحث عن الخطأ في Stack Overflow
  4. اتصل بمعلمك

عمل جيد وبرمجة موفقة!

العودة إلى الوحدة 2