OkHttp مع Kotlin: دليل شامل مع أمثلة عملية

ما هو OkHttp ولماذا تحتاجه؟

OkHttp هي مكتبة HTTP قوية وفعالة لـ JVM (Java Virtual Machine) و Android و Kotlin/Native، تم تطويرها بواسطة شركة Square. توفر واجهة برمجة تطبيقات (API) سهلة لتنفيذ طلبات HTTP ومعالجة الردود. تعتبر OkHttp المعيار الفعلي للعمل مع الشبكة في نظام Android البيئي، وتُستخدم بنشاط في تطبيقات Kotlin من جانب الخادم.

لماذا تستخدم OkHttp بدلاً من الأدوات القياسية في Java (HttpURLConnection)؟

• البساطة والسهولة: واجهة برمجة تطبيقات (API) نظيفة وسلسة (fluent) يسهل قراءتها وكتابتها.
• الأداء العالي: دعم مدمج لـ HTTP/2، ضغط تلقائي للردود (gzip)، تجمع اتصالات (connection pooling)، وتخزين مؤقت.
• الموثوقية: إعادة طلب تلقائية عند فشل الشبكة، مقاومة لأخطاء DNS و TLS.
• المرونة: معترضات (interceptors) قابلة للتخصيص بسهولة لتسجيل الدخول، المصادقة، تعديل الطلبات والردود.
• قابلية الاختبار: إمكانية استبدال طبقة الشبكة باستخدام MockWebServer.

OkHttp مثالية لتطبيقات Android، عملاء REST API، الخدمات المصغرة، وأي مشاريع Kotlin أخرى تتطلب عملاً موثوقاً وسريعاً مع HTTP.

التثبيت

يتم توزيع OkHttp عبر Maven Central. للإضافة إلى مشروعك، استخدم نظام بناء Gradle (الأكثر شيوعاً لـ Kotlin).

لمشروع Android / Kotlin/JVM (build.gradle.kts):

dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    // للتسجيل (اختياري)
    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
}

لمشروع Android / Kotlin/JVM (build.gradle):

dependencies {
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.12.0'
}

لـ Maven (pom.xml):

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.12.0</version>
</dependency>

هام: تأكد من توافق إصدار OkHttp مع إصدار Kotlin الذي تستخدمه. يمكنك دائماً العثور على أحدث إصدار على MVNRepository.

بداية سريعة

أبسط مثال هو تنفيذ طلب GET والحصول على نص الرد.

import okhttp3.OkHttpClient
import okhttp3.Request
import java.io.IOException

fun main() {
    // 1. إنشاء عميل (عادةً واحد لكل تطبيق)
    val client = OkHttpClient()

    // 2. بناء الطلب
    val request = Request.Builder()
        .url("https://api.github.com/users/octocat")
        .build()

    // 3. تنفيذ الطلب بشكل متزامن (يُوقف الخيط الحالي)
    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) {
            throw IOException("رمز غير متوقع $response")
        }
        // 4. الحصول على نص الرد
        println(response.body?.string())
    }
}

الشرح:

1. OkHttpClient() — ينشئ مثيلاً للعميل. وهو آمن للاستخدام مع الخيوط المتعددة، لذا يُنصح بإنشاء مثيل واحد وإعادة استخدامه.
2. Request.Builder() — يستخدم نمط "الباني" (Builder) لتكوين الطلب.
3. client.newCall(request) — ينشئ استدعاءً جديداً (Call) يمكن تنفيذه بشكل متزامن (execute()) أو غير متزامن (enqueue()).
4. response.use { ... } — يضمن إغلاق موارد الرد (النص، الاتصال) بعد الاستخدام.
5. response.body?.string() — يقرأ نص الرد كسلسلة نصية. هام: يمكن قراءة النص مرة واحدة فقط.