Ktor Client في Kotlin: دليل شامل مع أمثلة

Ktor Client هي مكتبة قوية وخفيفة الوزن ومتعددة المنصات لإجراء طلبات HTTP بلغة Kotlin. طورتها شركة JetBrains، وهي جزء من نظام Ktor البيئي وتوفر واجهة برمجة تطبيقات غير متزامنة (Asynchronous) قائمة على Coroutines للتفاعل مع خوادم الويب. على عكس العديد من عملاء HTTP الآخرين، صُمم Ktor Client من البداية للعمل على عدة منصات: JVM وAndroid وiOS وmacOS وLinux وWindows وJavaScript (عبر Kotlin/JS). وهذا يجعله الخيار الأمثل لتطوير التطبيقات عبر المنصات باستخدام Kotlin Multiplatform (KMP).

لماذا تحتاج Ktor Client؟ في التطوير الحديث، لا يخلو أي تطبيق تقريبًا من التفاعل مع واجهات برمجة التطبيقات البعيدة (APIs). سواء كان تحميل البيانات من خدمة REST، أو إرسال النماذج، أو رفع الملفات، أو العمل مع WebSockets، فإن عميل HTTP هو أداة أساسية. يقدم Ktor Client ليس فقط إمكانيات أساسية لطلبات GET و POST، بل نظامًا بيئيًا كاملاً من الإضافات (Plugins) التي تتيح لك تخصيص التسلسل (JSON, XML, Protobuf)، والضغط، وتسجيل الدخول، والمصادقة، وإعادة المحاولة، وغيرها الكثير. ميزته الرئيسية هي الاعتماد الكامل على Coroutines في Kotlin، مما يضمن أداءً عاليًا وكودًا موجزًا بدون دوال رد نداء (Callbacks).

تتميز المكتبة ببنية معيارية (Modular). يمكنك إضافة فقط المكونات التي يحتاجها مشروعك فعليًا: العميل الأساسي، المحرك المحدد (مثل OkHttp لنظام Android/JVM أو Darwin لنظام iOS)، وأداة التسلسل، والإضافات الضرورية. وهذا يقلل من حجم التطبيق النهائي ويتجنب تعارض التبعيات. يتطور Ktor Client بنشاط، وله وثائق ممتازة، ويدعمه مجتمع Kotlin.

التثبيت

يتم توزيع Ktor Client عبر نظام البناء Gradle (أو Maven). نظرًا لأنه ليس حزمة Python، لا يتم استخدام الأمر pip install. فيما يلي التعليمات الدقيقة لإضافة التبعيات إلى ملف build.gradle.kts الخاص بك.

هام: يجب أن تكون إصدارات المكتبات متوافقة. يُوصى باستخدام أحدث إصدار ثابت من مستودع Maven Central الرسمي. وقت كتابة هذا المقال، الإصدار الحالي هو 2.3.12.

// build.gradle.kts (Gradle Kotlin DSL)

// 1. أضف المستودع (عادة ما يكون موجودًا بالفعل)
repositories {
    mavenCentral()
}

// 2. أضف التبعيات في كتلة dependencies
dependencies {
    // العميل الأساسي (إجباري)
    implementation("io.ktor:ktor-client-core:2.3.12")

    // المحرك (Engine) - اختر واحدًا من الخيارات التالية:
    // لنظام JVM (يستخدم Java HttpClient أو OkHttp)
    implementation("io.ktor:ktor-client-okhttp:2.3.12") // موصى به لـ Android/JVM
    // implementation("io.ktor:ktor-client-java:2.3.12") // بديل لـ JVM

    // لنظام iOS/macOS (Darwin الأصلي)
    // implementation("io.ktor:ktor-client-darwin:2.3.12")

    // لنظام JavaScript
    // implementation("io.ktor:ktor-client-js:2.3.12")

    // لنظام Windows/Linux (Curl)
    // implementation("io.ktor:ktor-client-curl:2.3.12")

    // الإضافات (اختيارية ولكنها مفيدة جدًا):
    // تسلسل JSON (Gson أو Kotlinx Serialization)
    implementation("io.ktor:ktor-client-content-negotiation:2.3.12")
    implementation("io.ktor:ktor-serialization-gson:2.3.12")
    // أو implementation("io.ktor:ktor-serialization-kotlinx-json:2.3.12")

    // تسجيل الدخول (Logging)
    implementation("io.ktor:ktor-client-logging:2.3.12")

    // للعمل مع WebSockets
    // implementation("io.ktor:ktor-client-websockets:2.3.12")
}

إذا كنت تستخدم Maven، فستكون التبعيات مماثلة. بعد إضافة التبعيات، قم بمزامنة المشروع (Sync Project with Gradle Files).