المسارات وHttpRoutes
عرّف نقاط النهاية بأسلوب وظيفي
المسارات وHttpRoutes درس مجاني في Scala for Backend Engineering & Functional Programming على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Scala for Backend Engineering & Functional Programming، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Scala for Backend Engineering & Functional Programming 4 دروس في المجموع.
ما هي http4s
http4s هي مكتبة HTTP وظيفية بالكامل لـ Scala، مبنية على cats-effect وتدفقات fs2. الطلبات والاستجابات قيم غير قابلة للتغيير، وتُحتجز التأثيرات في نوع تأثير متعدد الأشكال مثل F[_] وIO.
بدلًا من تعديل servlet، تصف خدمة HTTP بوصفها دالة تحول طلبًا إلى استجابة اختيارية ذات تأثير.
نوع HttpRoutes
التجريد الأساسي هو HttpRoutes[F]، وهو اسم مستعار لـ Kleisli[OptionT[F, *], Request[F], Response[F]]. ويمثل OptionT مسارًا قد لا يطابق الطلب، فيعيد عدم وجود استجابة.
نادرًا ما تكتب هذا التوقيع يدويًا؛ بل تنشئ المسارات باستخدام الباني HttpRoutes.of ودالة جزئية.
import cats.effect.IO
import org.http4s._
import org.http4s.dsl.io._
val routes: HttpRoutes[IO] = HttpRoutes.of[IO] {
case GET -> Root / "hello" => Ok("hi")
}DSL الخاصة بـ http4s
يجلب استيراد DSL org.http4s.dsl.io._ مستخرجات الأنماط مثل GET وRoot وفاصل المسار /، إضافةً إلى منشئات الاستجابة مثل Ok وNotFound.
المسار هو PartialFunction[Request[F], F[Response[F]]]. والحالات التي لا تطابق الطلب تمر ببساطة إلى الحالة التالية.
import org.http4s.dsl.io._
HttpRoutes.of[IO] {
case GET -> Root => Ok("root")
case GET -> Root / "ping" => Ok("pong")
}مطابقة المسارات
تُقرأ أنماط المسارات من اليسار إلى اليمين. يمثّل Root الشرطة المائلة الافتتاحية، ويطابق كل / "segment" مقطعًا حرفيًا واحدًا من المسار.
يفصل السهم -> بين طريقة HTTP والمسار. لذلك يطابق GET -> Root / "users" الطلب GET /users.
HttpRoutes.of[IO] {
case GET -> Root / "users" => Ok("all users")
case GET -> Root / "users" / "me" => Ok("current user")
}متغيرات المسار
يلتقط الرابط المكتوب بحروف صغيرة مجردة في المسار ذلك المقطع باعتباره String. وهنا يربط id أي قيمة تظهر بعد /users/.
تكون المقاطع الملتقطة دائمًا سلاسل نصية؛ ويمكنك تحليلها بنفسك إلى أنواع أكثر تخصصًا، أو استخدام كائنات الاستخراج الموضحة لاحقًا.
HttpRoutes.of[IO] {
case GET -> Root / "users" / id =>
Ok(s"user $id")
}مستخرجات المسار المعيّنة النوع
توفر http4s مستخرجات مثل IntVar وLongVar، ولا تطابق إلا عندما يمكن تحليل المقطع إلى النوع المعني. ويؤدي المقطع غير الرقمي إلى الانتقال إلى الحالة التالية.
يمكنك تعريف مستخرجات مخصصة باستخدام unapply لأنواع المجال مثل UUID.
HttpRoutes.of[IO] {
case GET -> Root / "users" / IntVar(id) =>
Ok(s"numeric user $id")
}مطابقة الطرق
يمكن أن يكون مستخرج الطريقة قبل -> أيًا من GET وPOST وPUT وDELETE وPATCH وغيرها. ويصبح المسار نفسه مع طرق مختلفة حالات منفصلة.
إذا طابق المسار ولم تطابق الطريقة، فإن http4s تعيد تلقائيًا الاستجابة 405 Method Not Allowed.
HttpRoutes.of[IO] {
case GET -> Root / "items" => Ok("list")
case POST -> Root / "items" => Created("made")
case DELETE -> Root / "items" / IntVar(i) => NoContent()
}دمج المسارات
بما أن HttpRoutes[F] تشكّل SemigroupK، فإنك تؤلف مجموعات متعددة من المسارات باستخدام العامل <+>. وتفوز أول مجموعة تنتج استجابة.
يتيح لك ذلك تقسيم المسارات حسب الميزة إلى قيم منفصلة، ثم دمجها في مكان واحد.
import cats.syntax.semigroupk._
val all = userRoutes <+> itemRoutes <+> healthRoutesتحويل Routes إلى HttpApp
يحتاج الخادم إلى دالة كلية، لا دالة جزئية. ويُحوَّل HttpRoutes[F] إلى HttpApp[F] باستخدام .orNotFound، التي توفر 404 عندما لا يطابق أي مسار.
إن HttpApp[F] هو Kleisli[F, Request[F], Response[F]]، أي إنه يعيد استجابة دائمًا.
import org.http4s.HttpApp
val app: HttpApp[IO] = routes.orNotFoundتغليف Middleware
إن Middleware دوال من الشكل HttpRoutes[F] => HttpRoutes[F]، أو دوال تعمل على HttpApp. وهي تغلف الخدمة لإضافة التسجيل أو CORS أو gzip أو المصادقة دون المساس بمنطق المسارات.
من الأمثلة المضمّنة Logger وCORS وGZip من org.http4s.server.middleware.
import org.http4s.server.middleware.Logger
val logged = Logger.httpApp(logHeaders = true, logBody = false)(app)معاملات الاستعلام في المسارات
تُطابق معاملات الاستعلام باستخدام كائنات مطابقة توسّع QueryParamDecoderMatcher. وتظهر بعد :? في نمط المسار.
استخدم OptionalQueryParamDecoderMatcher للمعاملات التي قد تكون غائبة، إذ يعيد قيمة Option.
object NameParam extends QueryParamDecoderMatcher[String]("name")
HttpRoutes.of[IO] {
case GET -> Root / "hi" :? NameParam(n) => Ok(s"hi $n")
}تحقق سريع
اختبر مدى فهمك لتأليف المسارات.
مراجعة
أنشأت مسارات باستخدام HttpRoutes.of وDSL، وطابقت الطرق والمسارات، والتقطت المتغيرات باستخدام IntVar والمطابقات، وألّفت المجموعات باستخدام <+>.
المسارات جزئية؛ ويجعلها .orNotFound HttpApp كلية، بينما تغلف Middleware الخدمات لمعالجة الاهتمامات المشتركة.
تعلم Scala مع معلم ذكاء اصطناعي — مجانًا
اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.
- الدورات
- 39
- الدروس
- 143
الأسئلة الشائعة
هل درس «المسارات وHttpRoutes» مجاني؟
نعم — نص درس «المسارات وHttpRoutes» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Scala for Backend Engineering & Functional Programming، انتقل إلى CoddyKit PRO. تتضمن دورة Scala for Backend Engineering & Functional Programming 4 دروس في المجموع.
ماذا ستتعلم في «المسارات وHttpRoutes»؟
عرّف نقاط النهاية بأسلوب وظيفي تتمرن على Scala for Backend Engineering & Functional Programming مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Scala for Backend Engineering & Functional Programming؟
لا تُشترط خبرة سابقة. Scala for Backend Engineering & Functional Programming على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.
كم من الوقت يستغرق درس «المسارات وHttpRoutes»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Scala for Backend Engineering & Functional Programming هذا؟
نعم. كل درس في Scala for Backend Engineering & Functional Programming يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- المسارات وHttpRoutes
- الطلبات والاستجابات
- نقاط نهاية JSON
- تقديم التطبيق