Kotlin Academy · درس

التوجيه والمعاملات ذات الأنواع

عرّف المسارات باستخدام معاملات المسار والاستعلام واجمعها مع كتل route.

التوجيه والمعاملات ذات الأنواع درس مجاني في Kotlin Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Kotlin Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

أساسيات التوجيه في Ktor

التوجيه في Ktor هو إضافة تُثبَّت عبر install(Routing) { ... } أو الاختصار routing { ... }. وتُعرَّف المسارات باستخدام دوال أساليب HTTP: get وpost وput وdelete وpatch.

routing {
    get("/hello") { call.respondText("Hello!") }
    post("/items") { /* handle POST */ }
}

معلمات المسار

عرّف معلمة مسار باستخدام {name}. ويمكنك الوصول إليها عبر call.parameters["name"]. وتكون القيمة دائمًا من النوع String?:

get("/users/{id}") {
    val id = call.parameters["id"] ?: return@get call.respondText("Missing id", status = HttpStatusCode.BadRequest)
    call.respondText("User: $id")
}

مقاطع المسار الاختيارية

اجعل مقطعًا اختياريًا بإضافة ?: {name?}. إذا كان المقطع غير موجود، تُرجع call.parameters["name"] القيمة null.

get("/posts/{slug?}") {
    val slug = call.parameters["slug"]
    if (slug == null) call.respondText("All posts")
    else call.respondText("Post: $slug")
}

تحويل المعلمات إلى أنواع محددة

حوّل معلمات المسار إلى قيم ذات أنواع محددة باستخدام دوال الامتداد على Parameters. يوفر Ktor دوال مساعدة مضمّنة، أو يمكنك كتابة دوالك الخاصة:

get("/items/{id}") {
    val id = call.parameters["id"]?.toLongOrNull()
        ?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid id")
    call.respondText("Item #$id")
}

معلمات الاستعلام

يمكنك الوصول إلى معلمات سلسلة الاستعلام عبر call.request.queryParameters["key"]. وتتوافر القيم المتعددة للمفتاح نفسه عبر getAll("key"):

get("/search") {
    val q = call.request.queryParameters["q"] ?: ""
    val page = call.request.queryParameters["page"]?.toIntOrNull() ?: 1
    call.respondText("Search: $q, page $page")
}

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

جمّع المسارات المرتبطة تحت بادئة مشتركة باستخدام route("/prefix") { ... }. يقلل ذلك من التكرار ويجعل شجرة التوجيه سهلة القراءة:

route("/api/v1") {
    route("/users") {
        get { /* list users */ }
        get("/{id}") { /* get user by id */ }
        post { /* create user */ }
    }
}

تنظيم المسارات في دوال

استخرج مجموعات المسارات إلى دوال امتداد على Route للحفاظ على إعداد توجيه نموذجي:

fun Route.userRoutes() {
    route("/users") {
        get { /* ... */ }
        post { /* ... */ }
        get("/{id}") { /* ... */ }
    }
}

// In Application module:
routing { userRoutes() }

معالجة جسم الطلب

استقبل جسم الطلب كنص أو وحدات بايت أو كائن أُزيل تسلسله (ويتطلب ذلك إضافة ContentNegotiation). استخدم call.receive() لإزالة التسلسل إلى نوع محدد:

post("/users") {
    val user = call.receive<UserDto>()
    call.respond(HttpStatusCode.Created, user)
}

إرسال الاستجابات باستخدام رموز الحالة

استخدم call.respond(status, body) للتحكم الكامل، أو استخدم الدوال المريحة call.respondText() وcall.respondFile() وcall.respond(HttpStatusCode.NotFound):

get("/users/{id}") {
    val user = userRepo.find(call.parameters["id"])
    if (user == null) call.respond(HttpStatusCode.NotFound)
    else call.respond(user)
}

مسارات البدل وTailcard

استخدم * لمقطع بدل واحد، واستخدم {...} (‏tailcard) لمطابقة بقية المسار باعتبارها معلمة واحدة:

get("/static/{path...}") {
    val filePath = call.parameters.getAll("path")?.joinToString("/") ?: ""
    call.respondText("Serving: $filePath")
}

أولويات المسارات

يقيّم Ktor المسارات حسب ترتيب تعريفها. ينبغي تعريف المسارات الأكثر تحديدًا قبل مسارات البدل. وعندما يتطابق مساران، يفوز التطابق الأول.

تحقق سريع

كيف تجمع عدة مسارات تحت بادئة URL مشتركة في Ktor؟

مراجعة: التوجيه والمعلمات محددة النوع

أهم النقاط:

عرّف المسارات باستخدام get وpost وغيرهما داخل routing { }
معلمات المسار: {name} — يُمكن الوصول إليها عبر call.parameters["name"]
معلمات الاستعلام: call.request.queryParameters["key"]
جمّع المسارات باستخدام route("/prefix") { } واستخرجها إلى دوال امتداد على Route
استقبل أجسامًا محددة النوع باستخدام call.receive() (ويتطلب ذلك ContentNegotiation)

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

هل درس «التوجيه والمعاملات ذات الأنواع» مجاني؟

نعم — نص درس «التوجيه والمعاملات ذات الأنواع» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Kotlin Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ماذا ستتعلم في «التوجيه والمعاملات ذات الأنواع»؟

عرّف المسارات باستخدام معاملات المسار والاستعلام واجمعها مع كتل route. تتمرن على Kotlin Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Kotlin Academy؟

لا تُشترط خبرة سابقة. Kotlin Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «التوجيه والمعاملات ذات الأنواع»؟

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

هل يمكنني كتابة وتشغيل أكواد في درس Kotlin Academy هذا؟

نعم. كل درس في Kotlin Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

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

إعداد مشروع Ktor: ‏embeddedServer ووحدات Application
التوجيه والمعاملات ذات الأنواع
تفاوض المحتوى وkotlinx.serialization
إضافات المصادقة: JWT وSession

← العودة إلى Kotlin Academy