Kotlin Academy · درس

إعداد مشروع Ktor: ‏embeddedServer ووحدات Application

أنشئ تطبيق Ktor أوليًا واضبط Netty وعرّف وحدات التطبيق.

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

ما هو Ktor؟

Ktor هو إطار عمل JetBrains غير المتزامن المبني باستخدام Kotlin لإنشاء الخوادم والعملاء. وهو مبني على coroutines، ويعتمد على الإضافات، ولا يحتوي على سلوك سحري: إذ يجب تثبيت كل ميزة تحتاج إليها صراحةً. تطبيقات Ktor هي برامج Kotlin عادية — ولا تتطلب حاوية DI.

إضافة تبعيات Ktor

أضف محرك الخادم الأساسي (يُعد Netty الأكثر شيوعًا) ومكتبة خادم Ktor الأساسية إلى ملف build.gradle.kts:

dependencies {
    implementation("io.ktor:ktor-server-core:2.3.12")
    implementation("io.ktor:ktor-server-netty:2.3.12")
    implementation("ch.qos.logback:logback-classic:1.5.6") // logging
}

embeddedServer: نقطة الدخول الدنيا

أبسط طريقة لبدء خادم Ktor هي استخدام embeddedServer. مرّر مصنع المحرك والمنفذ وكتلة إعداد:

import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.routing.*
import io.ktor.server.response.*

fun main() {
    embeddedServer(Netty, port = 8080) {
        routing {
            get("/") { call.respondText("Hello, Ktor!") }
        }
    }.start(wait = true)
}

وحدات التطبيق

في المشاريع الأكبر، قسّم الإعداد إلى وحدات — وهي دوال امتداد على Application. تثبّت الوحدة الإضافات وتسجّل المسارات. وهذا يجعل قاعدة التعليمات البرمجية أسهل للاختبار وإعادة التركيب:

fun Application.configureRouting() {
    routing {
        get("/health") { call.respondText("OK") }
    }
}

fun Application.configureSerialization() {
    install(ContentNegotiation) { json() }
}

استدعاء الوحدات من main

استدعِ دوال الوحدات داخل كتلة embeddedServer لتركيبها معًا:

fun main() {
    embeddedServer(Netty, port = 8080) {
        configureRouting()
        configureSerialization()
        configureSecurity()
    }.start(wait = true)
}

application.conf (إعداد HOCON)

البديل عن embeddedServer هو استخدام ملف application.conf (بتنسيق HOCON) والتشغيل عبر EngineMain. يحدد ملف الإعداد وحدة الدخول والمنفذ:

# application.conf
ktor {
    deployment { port = 8080 }
    application {
        modules = [ com.example.ApplicationKt.module ]
    }
}

EngineMain مقابل embeddedServer

استخدم embeddedServer عندما تريد التحكم الكامل من داخل التعليمات البرمجية (وهو مناسب جدًا للاختبار والتطبيقات البسيطة). واستخدم EngineMain مع application.conf عندما تريد إعدادًا خاصًا بالبيئة من دون إعادة التجميع.

كائن ApplicationCall

يتلقى كل معالج طلب كائن ApplicationCall. ويوفر الوصول إلى الطلب (call.request) والاستجابة (call.response)، كما يوفر دوال مساعدة مثل call.respondText() وcall.respond().

البيئة والتسجيل

يمكنك الوصول إلى إعدادات البيئة داخل الوحدة عبر environment.config. ويستخدم التسجيل SLF4J؛ أضف ملف logback.xml إلى src/main/resources/ لإعداد مستويات التسجيل وتنسيق المخرجات.

إعادة التحميل الفوري أثناء التطوير

يدعم Ktor إعادة التحميل الفوري أثناء التطوير عبر علامة وضع development. فعّلها في application.conf أو برمجيًا: embeddedServer(Netty, port = 8080, developmentMode = true) { ... }.

اصطلاح بنية المشروع

تخطيط نموذجي لمشروع Ktor:

Application.kt — نقطة الدخول main()
plugins/ — ملف واحد لكل دالة امتداد لـ Application (Routing وSerialization وAuth وغير ذلك)
routes/ — تعريفات المسارات مجمعة حسب المجال
models/ — فئات البيانات

تحقق سريع

ما الغرض من دالة وحدة Application في Ktor؟

مراجعة: إعداد مشروع Ktor

أهم النقاط:

يُعد embeddedServer(Engine, port) { ... }.start(wait=true) أبسط نقطة دخول
قسّم الإعداد إلى دوال امتداد للوحدة Application
استخدم EngineMain مع application.conf للإعداد الخارجي
يتعامل كل معالج طلب مع ApplicationCall للوصول إلى الطلب والاستجابة
جمّع المسارات في حزمة routes/ لتسهيل الصيانة

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

هل درس «إعداد مشروع Ktor: ‏embeddedServer ووحدات Application» مجاني؟

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

ماذا ستتعلم في «إعداد مشروع Ktor: ‏embeddedServer ووحدات Application»؟

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

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

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

كم من الوقت يستغرق درس «إعداد مشروع Ktor: ‏embeddedServer ووحدات Application»؟

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

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

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

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

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

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