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

الفصل 2: استكشاف الأخطاء وإصلاحها وحل المشكلات

الأهداف​

  • تحديد وحل المشكلات الشائعة
  • استخدام أدلة استكشاف الأخطاء وإصلاحها للمشروع
  • إتقان تقنيات تصحيح الأخطاء في Spring Boot

المورد الرئيسي​

الوثائق الرسمية

جميع أدلة استكشاف الأخطاء وإصلاحها متاحة في المستودع:

** مجلد استكشاف الأخطاء وإصلاحها**

قائمة الأدلة المتاحة​

يحتوي مجلد استكشاف الأخطاء وإصلاحها على العديد من الأدلة المرقمة لمساعدتك:

الدليلالموضوعالوصف
01-xxالتكوين الأوليإعداد المشروع
10-xxقاعدة البياناتPostgreSQL, H2, الاتصالات
15-xxSpring Securityتكوين الأمان
20-xxJWTالرموز، المصادقة
25-xxAPI RESTنقاط النهاية، CORS
27Frontend Codespacesتكامل الواجهة الأمامية
28-xxالاختباراتاختبارات الوحدة والتكامل

المشاكل الشائعة والحلول​

1. خطأ في بدء التطبيق​

الأعراض​

***************************
APPLICATION FAILED TO START
***************************

الأسباب المحتملة والحلول​

قاعدة البيانات غير مهيأة:

# application.yml - تكوين H2 للتطوير
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  h2:
    console:
      enabled: true

المنفذ مستخدم بالفعل:

# التحقق من المنفذ
lsof -i :8080

# استخدام منفذ آخر
./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

2. خطأ 401 Unauthorized​

الأعراض​

{
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required"
}

الحل​

نقطة النهاية تتطلب رمز JWT. اتبع هذه الخطوات:

# 1. التسجيل (إذا كانت نقطة النهاية متاحة)
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

# 2. تسجيل الدخول للحصول على الرمز
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@test.com", "password": "password123"}'

# 3. استخدام الرمز المستلم
curl http://localhost:8080/api/admin/leads \
  -H "Authorization: Bearer VOTRE_TOKEN_JWT"

3. خطأ CORS​

الأعراض (في وحدة تحكم المتصفح)​

Access to fetch at 'http://localhost:8080/api/contact' from origin 
'http://localhost:3000' has been blocked by CORS policy

الحل​

تحقق من تكوين CORS في SecurityConfig.java:

@Bean
public CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration configuration = new CorsConfiguration();
    configuration.setAllowedOrigins(Arrays.asList("*"));
    configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE"));
    configuration.setAllowedHeaders(Arrays.asList("*"));
    
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", configuration);
    return source;
}

4. خطأ في التحقق​

الأعراض​

{
  "status": 400,
  "errors": {
    "email": "must be a valid email",
    "fullName": "must not be blank"
  }
}

الحل​

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

{
  "fullName": "الاسم الكامل",      // مطلوب
  "email": "email@valide.com",    // مطلوب، صيغة البريد الإلكتروني
  "company": "اختياري",         // اختياري
  "phone": "اختياري",           // اختياري
  "requestType": "INFO",          // مطلوب: INFO, QUOTE, SUPPORT, PARTNERSHIP, OTHER
  "message": "على الأقل 10 أحرف كحد أدنى لهذه الرسالة"  // مطلوب
}

5. مشكلة في قاعدة بيانات PostgreSQL​

الأعراض​

Connection to localhost:5432 refused

الحلول​

الخيار A - استخدام H2 في التطوير:

# application.yml
spring:
  profiles:
    active: dev
    
---
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:h2:mem:testdb

الخيار B - تشغيل PostgreSQL باستخدام Docker:

docker run -d \
  --name postgres-econtact \
  -e POSTGRES_DB=econtactdb \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:14-alpine

6. رمز JWT منتهي الصلاحية​

الأعراض​

{
  "status": 401,
  "error": "Token expired"
}

الحل​

إعادة تسجيل الدخول للحصول على رمز جديد:

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "votre@email.com", "password": "votremotdepasse"}'

7. خطأ 500 Internal Server Error​

التشخيص​

  1. التحقق من السجلات:
# في الطرفية حيث يعمل التطبيق
# تظهر تتبعات الأخطاء تلقائيًا
  1. تفعيل سجلات التصحيح:
# application.yml
logging:
  level:
    com.example.econtact: DEBUG
    org.springframework.security: DEBUG
  1. التحقق من وحدة تحكم H2:
    • URL: http://localhost:8080/h2-console
    • JDBC URL: jdbc:h2:mem:testdb

🛠️ أدوات تصحيح الأخطاء​

Postman / Insomnia​

استورد مجموعة Postman من المستودع لاختبار جميع نقاط النهاية بسهولة.

وحدة تحكم H2​

متاحة على http://localhost:8080/h2-console لفحص قاعدة البيانات.

سجلات Spring Boot​

# تفعيل السجلات التفصيلية
logging:
  level:
    root: INFO
    com.example.econtact: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG

Actuator (إذا كان مفعلًا)​

# التحقق من صحة التطبيق
curl http://localhost:8080/actuator/health

# رؤية beans المحملة
curl http://localhost:8080/actuator/beans

دليل محدد: الواجهة الأمامية مع Codespaces​

دليل أساسي

لدمج الواجهة الأمامية في بيئة Codespaces، راجع الدليل المفصل:

** 27-guide-formulaire-frontend-codespaces.md**

قائمة التحقق من تصحيح الأخطاء​

قبل طلب المساعدة، تحقق من:

  • سجلات الأخطاء في الطرفية
  • التكوين في application.yml
  • توفر قاعدة البيانات
  • صيغة البيانات المرسلة (JSON صالح)
  • وجود رمز JWT لنقاط النهاية المحمية
  • تكوين CORS للاتصالات الأمامية

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

الفصل 3: تكامل الواجهة الأمامية →

العودة إلى فهرس الوحدة