Scala for Backend Engineering & Functional Programming · درس

بناء RESTful APIs باستخدام Play

صمّم نقاط نهاية RESTful ونفّذها، وتولَّ معالجة الطلبات، وأدر بيانات JSON باستخدام وحدات التحكم في Play

الدرس 2 من 311 خطوة

بناء RESTful APIs باستخدام Play درس مجاني في Scala for Backend Engineering & Functional Programming على CoddyKit. هذا هو الدرس 2 من أصل 3. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Scala for Backend Engineering & Functional Programming، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Scala for Backend Engineering & Functional Programming 3 دروس في المجموع.

مقدمة إلى واجهات Play REST API

مرحبًا بكم! في هذا الدرس، سنتعمق في بناء واجهات RESTful API باستخدام Scala Play Framework. إن REST (نقل الحالة التمثيلية) نمط معماري واسع الاستخدام لتصميم التطبيقات المتصلة بالشبكة.

تتيح واجهة RESTful API لأنظمة البرامج المختلفة التواصل فيما بينها عبر الإنترنت، وعادةً ما تستخدم طرق HTTP القياسية مثل GET وPOST وPUT وDELETE لتنفيذ عمليات على الموارد.

وحدات تحكم Play وإجراءاته

في Play، تتولى وحدات التحكم معالجة طلبات HTTP الواردة. ووحدة التحكم هي كائن أو صنف في Scala يحتوي على طرق الإجراءات.

تكون كل طريقة إجراء مسؤولة عن معالجة نوع محدد من الطلبات (مثل جلب البيانات أو إنشاء عنصر جديد) وإعادة استجابة HTTP.

تعريف المسارات في Play

يستخدم Play ملف conf/routes لتعيين طلبات HTTP الواردة إلى طرق إجراءات محددة في وحدات التحكم. وهنا تعرّفون نقاط النهاية لواجهة API الخاصة بكم.

الصيغة الأساسية لإدخال مسار هي: HTTP_METHOD /path controllers.ControllerName.actionMethod(parameters).

تنفيذ نقطة نهاية GET

لننشئ نقطة نهاية GET بسيطة تعيد تحية. في تطبيق Play حقيقي، ستكون هذه النقطة داخل وحدة تحكم. أما هنا، فنحاكي المنطق داخل طريقة main.

حاولوا تشغيل هذا المثال:

object GreetingController {
  // This method simulates a Play controller action
  def sayHello(): String = {
    "Hello from your Play API!"
  }
  
  def main(args: Array[String]): Unit = {
    // Simulate receiving a request and calling the action
    val apiResponse = sayHello()
    println(s"Simulated API Response: $apiResponse")
  }
}

استخراج معلمات المسار

غالبًا ما تحتاجون إلى استخراج قيم ديناميكية من مسار URL، مثل معرّف عنصر. وتُسمى هذه القيم معلمات المسار.

تعرّفون هذه المعلمات في ملف routes باستخدام النقطتين الرأسيتين (:). وفي إجراء وحدة التحكم، تعلنون عنها كمعلمات للطريقة.

object UserController {
  // This action takes an 'id' as a path parameter
  def getUser(id: Int): String = {
    s"Fetching user details for ID: $id"
  }
  
  def main(args: Array[String]): Unit = {
    // Simulate a request to /users/123
    val userIdFromRequest = 123
    val apiResponse = getUser(userIdFromRequest)
    println(s"Simulated API Response: $apiResponse")
  }
}

أجسام الطلبات وJSON

عند إنشاء الموارد أو تحديثها، يرسل العملاء البيانات في جسم الطلب. وبالنسبة إلى واجهات RESTful API، تكون هذه البيانات دائمًا تقريبًا بتنسيق JSON (JavaScript Object Notation).

يوفر Play دعمًا ممتازًا لتحليل أجسام طلبات JSON وتحويلها إلى أصناف case في Scala.

بناء نقطة نهاية POST

لنحاكِ نقطة نهاية POST تستقبل جسمًا بتنسيق JSON. في تطبيق Play حقيقي، ستستخدمون مكتبة JSON الخاصة بـ Play لتحليل الطلب. أما في هذا المثال القابل للتشغيل، فسنتحقق من محتوى نصي بسيط.

حاولوا تشغيل هذا المثال:

object ItemController {
  // Simulate processing a JSON request body
  def createItem(jsonBody: String): String = {
    // In a real Play app: Json.parse(jsonBody).as[ItemCaseClass]
    if (jsonBody.contains("name") && jsonBody.contains("price")) {
      s"Item successfully created! Data: $jsonBody"
    } else {
      "Error: Invalid JSON format. 'name' and 'price' expected."
    }
  }
  
  def main(args: Array[String]): Unit = {
    // Simulate a POST request with a JSON body
    val validJson = """{"name": "Smartphone", "price": 799.99}"""
    println(s"Valid JSON Response: ${createItem(validJson)}")
    
    val invalidJson = """{"product": "Tablet"}"""
    println(s"Invalid JSON Response: ${createItem(invalidJson)}")
  }
}

معالجة PUT وDELETE

بالإضافة إلى GET وPOST، تستخدم واجهات RESTful API عادةً ما يلي:

PUT: لتحديث مورد موجود. ويتطلب عادةً معلمة مسار (المعرّف) وجسم طلب (البيانات المحدّثة).
DELETE: لإزالة مورد. ويتطلب عادةً معلمة مسار فقط (المعرّف).

تتشابه أنماط تعريف المسارات والوصول إلى المعلمات والأجسام في PUT وDELETE مع POST وGET.

إعادة استجابات JSON

بعد معالجة الطلب، تحتاج واجهة API عادةً إلى إرسال استجابة، وغالبًا ما تكون بتنسيق JSON. ويسهّل Play إنشاء كائنات JSON وإرسالها.

في وحدة التحكم، ستستخدمون عادةً Ok(Json.toJson(yourCaseClass)). أما هنا، فنحاكي إنشاء سلسلة JSON.

object ResponseGenerator {
  // Simulate a case class for the response data
  case class ApiResponse(status: String, message: String)

  // Simulate converting the case class to a JSON string
  def buildJsonResponse(response: ApiResponse): String = {
    s"""{"status": "${response.status}", "message": "${response.message}"}"""
  }

  def main(args: Array[String]): Unit = {
    val successResponse = ApiResponse("success", "Data retrieved successfully")
    println(s"Simulated JSON Output:\n${buildJsonResponse(successResponse)}")

    val errorResponse = ApiResponse("error", "Item not found")
    println(s"Simulated JSON Output:\n${buildJsonResponse(errorResponse)}")
  }
}

اختبار مطابقة المسارات

ما تعريف المسار في Play الذي سيطابق بشكل صحيح طلب GET /api/products/123 ويمرّر 123 إلى إجراء وحدة التحكم باعتباره قيمة من النوع Int؟

أجب عليها في الدرس التفاعلي

مراجعة والخطوات التالية

أحسنتم! لقد تعلّمتم أساسيات بناء واجهات RESTful API باستخدام Play Framework:

فهم مبادئ RESTful وطرق HTTP.
كيفية معالجة وحدات التحكم والإجراءات في Play للطلبات.
تعريف المسارات في واجهة API لربط عناوين URL بإجراءات وحدات التحكم.
استخراج معلمات المسار من عناوين URL.
التعامل مع أجسام طلبات JSON لعمليتي POST وPUT.
إنشاء استجابات JSON وإرجاعها.

قد تستكشفون بعد ذلك دمج قواعد البيانات مع تطبيق Play الخاص بكم!

البدء مجانًا

تعلم Scala مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات: 39
الدروس: 143

ابدأ التعلم مجانًا عرض الدورة الكاملة

الأسئلة الشائعة

هل درس «بناء RESTful APIs باستخدام Play» مجاني؟

نعم — نص درس «بناء RESTful APIs باستخدام Play» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Scala for Backend Engineering & Functional Programming، انتقل إلى CoddyKit PRO. تتضمن دورة Scala for Backend Engineering & Functional Programming 3 دروس في المجموع.

ماذا ستتعلم في «بناء RESTful APIs باستخدام Play»؟

صمّم نقاط نهاية RESTful ونفّذها، وتولَّ معالجة الطلبات، وأدر بيانات JSON باستخدام وحدات التحكم في Play تتمرن على Scala for Backend Engineering & Functional Programming مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Scala for Backend Engineering & Functional Programming؟

لا تُشترط خبرة سابقة. Scala for Backend Engineering & Functional Programming على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 3.

كم من الوقت يستغرق درس «بناء RESTful APIs باستخدام Play»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Scala for Backend Engineering & Functional Programming هذا؟

نعم. كل درس في Scala for Backend Engineering & Functional Programming يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

أساسيات Play Framework
بناء RESTful APIs باستخدام Play
تكامل قواعد البيانات باستخدام Slick/Doobie

← العودة إلى Scala for Backend Engineering & Functional Programming