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

Moshi هي مكتبة حديثة لتسلسل وإلغاء تسلسل بيانات JSON، طورتها شركة Square. مكتوبة بلغة Kotlin وJava، لكنها موجهة بشكل أساسي لمطوري Kotlin. توفر Moshi طريقة قوية وآمنة وفعالة لتحويل الكائنات إلى JSON والعكس، بأقل قدر من الكود المتكرر.

لماذا تحتاج Moshi؟ في تطوير التطبيقات الحديثة، التعامل مع JSON جزء أساسي: تبادل البيانات مع REST API، تخزين الإعدادات، نقل الرسائل بين المكونات. تحل Moshi عدة مشاكل رئيسية: التحويل التلقائي لفئات Kotlin إلى JSON (والعكس) دون الحاجة لكتابة محللات يدويًا؛ تحديد الأنواع بدقة مما يمنع أخطاء وقت التشغيل؛ دعم الكائنات غير القابلة للتغيير (data class) والفئات المختومة (sealed classes)؛ إمكانية التخصيص عبر المحولات (Adapters). مقارنة بـ Gson أو Jackson، تقدم Moshi واجهة برمجة أنظف، وتكاملًا أفضل مع Kotlin (مثل دعم أمان القيم الفارغة والقيم الافتراضية)، وحجم مكتبة أصغر.

Moshi مفيدة بشكل خاص في المشاريع التي تعتمد على الأداء وسلامة الأنواع. تُستخدم بنشاط في تطوير Android (بما في ذلك مع Retrofit و OkHttp)، وفي تطبيقات الخادم على Ktor، وفي أي مشروع Kotlin يتطلب التعامل مع JSON. تدعم المكتبة الانعكاس (Reflection) عبر وحدة moshi-kotlin وتوليد الكود (Code Generation) عبر moshi-kotlin-codegen، مما يتيح لك الاختيار بين سهولة الاستخدام والأداء.

2. التثبيت

يتم توزيع Moshi عبر Maven Central. للتثبيت، أضف التبعيات إلى ملف build.gradle.kts (Gradle) أو pom.xml (Maven).

Gradle (Kotlin DSL)

// build.gradle.kts
dependencies {
    // المكتبة الأساسية
    implementation("com.squareup.moshi:moshi:1.15.1")
    
    // وحدة Kotlin (الانعكاس)
    implementation("com.squareup.moshi:moshi-kotlin:1.15.1")
    
    // توليد الكود (اختياري، لتحسين الأداء)
    ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.1")
    // أو kapt("com.squareup.moshi:moshi-kotlin-codegen:1.15.1")
}

Gradle (Groovy)

// build.gradle
dependencies {
    implementation 'com.squareup.moshi:moshi:1.15.1'
    implementation 'com.squareup.moshi:moshi-kotlin:1.15.1'
    ksp 'com.squareup.moshi:moshi-kotlin-codegen:1.15.1'
}

Maven

<dependency>
    <groupId>com.squareup.moshi</groupId>
    <artifactId>moshi</artifactId>
    <version>1.15.1</version>
</dependency>
<dependency>
    <groupId>com.squareup.moshi</groupId>
    <artifactId>moshi-kotlin</artifactId>
    <version>1.15.1</version>
</dependency>

ملاحظة مهمة: إذا كنت تستخدم توليد الكود، لا تنسَ إضافة إضافة KSP (Kotlin Symbol Processing) أو KAPT. بالنسبة لـ KSP، أضف في plugins:

plugins {
    id("com.google.devtools.ksp") version "1.9.22-1.0.17"
}

3. البداية السريعة

مثال عملي بسيط يوضح التسلسل وإلغاء التسلسل الأساسيين.

import com.squareup.moshi.Moshi
import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory

// 1. تعريف data class
data class User(
    val name: String,
    val age: Int,
    val email: String?
)

fun main() {
    // 2. إنشاء كائن Moshi مع مصنع Kotlin
    val moshi = Mosh