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

1. ما هي Chucker ولماذا تحتاجها؟

Chucker هي مكتبة قوية لتصحيح أخطاء طلبات HTTP في تطبيقات Android، مكتوبة بلغة Kotlin. تتيح للمطورين اعتراض وتسجيل وفحص كل حركة مرور الشبكة التي تمر عبر عميل OkHttp مباشرة على الجهاز. على عكس التسجيل القياسي في Logcat، توفر Chucker واجهة رسومية سهلة الاستخدام على شكل شاشة منفصلة (Activity)، حيث يمكنك عرض الرؤوس (Headers)، محتوى الطلبات والردود، رموز الحالة، وقت التنفيذ، وأحجام البيانات.

الهدف الرئيسي من Chucker هو تبسيط عملية تصحيح أخطاء تفاعلات الشبكة. بدلاً من توصيل الجهاز بالكمبيوتر وتصفية السجلات، يمكن للمطور فتح التطبيق ورؤية جميع معاملات HTTP فوراً. هذا مفيد بشكل خاص عند الاختبار على أجهزة حقيقية، عندما يكون الوصول إلى ADB محدوداً، أو عند العمل مع فرق ضمان الجودة (QA) الذين يمكنهم تقديم لقطات شاشة للأخطاء تحتوي على معلومات مفصلة عن الطلب.

تدعم Chucker أيضاً التصفية حسب نوع المحتوى (JSON، XML، صور)، البحث عن طريق URL، عرض الأخطاء والاستثناءات، بالإضافة إلى تصدير السجلات إلى ملف. تقوم المكتبة تلقائياً بجمع معلومات عن أخطاء SSL، وانتهاء المهلة (Timeouts)، ومشاكل الشبكة الأخرى، مما يجعلها أداة لا غنى عنها لأي مطور Android يعمل مع REST APIs.

2. التثبيت

يتم توزيع Chucker عبر Maven Central. للتثبيت، يجب إضافة التبعيات إلى ملف build.gradle.kts (أو build.gradle) الخاص بوحدة التطبيق الخاصة بك.

ملاحظة هامة: المكتبة غير مخصصة للتثبيت عبر pip أو npm أو cargo. إنها مكتبة Android ويتم إضافتها عبر نظام بناء Gradle.

أمر الإضافة في ملف build.gradle.kts (Module: app):

// build.gradle.kts (Module: app)
dependencies {
    // مكتبة Chucker الأساسية (لإصدارات التصحيح فقط)
    debugImplementation("com.github.chuckerteam.chucker:library:4.0.0")

    // مكتبة No-Op (وهمية) لإصدارات الإصدار النهائي
    releaseImplementation("com.github.chuckerteam.chucker:library-no-op:4.0.0")
}

لـ Groovy (build.gradle):

// build.gradle (Module: app)
dependencies {
    debugImplementation 'com.github.chuckerteam.chucker:library:4.0.0'
    releaseImplementation 'com.github.chuckerteam.chucker:library-no-op:4.0.0'
}

شرح: استخدام debugImplementation يضمن أن Chucker ستكون متاحة فقط في إصدارات التصحيح. أما releaseImplementation مع إصدار library-no-op فيستبدل جميع استدعاءات Chucker بدوال فارغة، مما يمنع تسرب البيانات في الإصدار النهائي ولا يزيد من حجم ملف APK.

3. البداية السريعة — مثال عملي بسيط

بعد تثبيت المكتبة، يجب إنشاء OkHttpClient وإضافة المعترض (Interceptor) الخاص بـ Chucker إليه. ثم يتم استخدام هذا العميل لإنشاء Retrofit أو أي عميل HTTP آخر.

// MainActivity.kt
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.chuckerteam.chucker.api.ChuckerCollector
import com.chuckerteam.chucker.api.ChuckerInterceptor
import okhttp3.OkHttpClient
import okhttp3.Request

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // 1. إنشاء جامع لتخزين السجلات
        val collector = ChuckerCollector(this)

        // 2. إنشاء المعترض
        val chuckerInterceptor = ChuckerInterceptor.Builder(this)