Kotlin Multiplatform: ما هو، shared module و expect/actual

ما هو Kotlin Multiplatform؟

Kotlin Multiplatform هي تقنية تجميع متعدد تتيح كتابة كود مشترك في Kotlin وتجميعه لمنصات مختلفة: JVM (Android)، LLVM (iOS، macOS، watchOS)، JavaScript (Web) والملفات الثنائية الأصلية (Linux، Windows). KMP ليست إطار عمل لواجهة المستخدم — إنها تحل مشكلة إعادة استخدام منطق الأعمال، وليس الواجهات.

تم بناء هيكل KMP حول shared module — وحدة Gradle تحتوي على commonMain بكود مستقل عن المنصة و source sets لكل هدف (androidMain، iosMain، desktopMain). وفقًا لبيانات JetBrains لعام 2025، يستخدم أكثر من 40% من مشاريع Kotlin الجديدة KMP لمشاركة الكود بين المنصات.

Kotlin Multiplatform Mobile (KMM) — الاسم السابق لسيناريو الهاتف المحمول iOS+Android. منذ Kotlin 2.1+، تم استبدال مصطلح KMM بـ Kotlin Multiplatform، حيث تجاوزت التقنية تطوير الهاتف المحمول. تستخدم Netflix و McDonald's و VMware KMP في الإنتاج لمشاركة الكود بين تطبيقات الهاتف المحمول.

آلية expect/actual: الهندسة المعمارية

Expect/actual — الآلية الرئيسية لـ KMP للعمل مع الكود الخاص بالمنصة. في commonMain يتم الإعلان عن تعريف expect (دالة، فئة، خاصية)، وفي كل source set خاص بالمنصة (androidMain، iosMain) يتم توفير تنفيذ actual. يتحقق المترجم من وجود actual لكل expect في كل منصة هدف.

// commonMain — إعلان واجهة برمجة تطبيقات المنصة
expect fun getPlatformName(): String

expect class PlatformContext(val appVersion: String)

// androidMain — actual لنظام Android
actual fun getPlatformName(): String = "Android \${Build.VERSION.SDK_INT}"

// iosMain — actual لنظام iOS
actual fun getPlatformName(): String =
    UIDevice.currentDevice.systemName

التسلسل الهرمي لل source sets في KMP يسمح بإنشاء مستويات وسيطة: على سبيل المثال، iosArm64Main (أجهزة iOS الفعلية) و iosSimulatorArm64Main (المحاكي) مع iosMain مشترك. كود commonMain متاح لجميع المنصات، بينما كود iosMain متاح فقط لأهداف iOS. هذا يقلل التكرار عندما يختلف التنفيذ ليس لكل منصة بل لمجموعة من المنصات.

من الناحية العملية، يتم استخدام expect/actual من أجل: الوصول إلى التخزين المحلي (SharedPreferences vs NSUserDefaults)، الشبكات (HttpEngine لكل منصة)، الوصول إلى نظام الملفات، التشفير والتحليلات. توصي JetBrains بتقليل عدد تعريفات expect/actual ونقل أكبر قدر ممكن من الكود إلى commonMain.

Shared module: الهيكل و Gradle

Shared module — وحدة Gradle قياسية مع الإضافة org.jetbrains.kotlin.multiplatform. تحتوي على كود مشترك في src/commonMain/kotlin/ وتنفيذات خاصة بالمنصة في src/androidMain/kotlin/ و src/iosMain/kotlin/. مشروع KMP يتضمن أيضًا androidApp و iosApp، والتي تعتمد على shared module.

// build.gradle.kts — shared module
plugins {
    kotlin("multiplatform")
    id("com.android.library")
}

kotlin {
    androidTarget()
    
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach {
        it.binaries.framework {
            baseName = "shared"
            isStatic = true
        }
    }

    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-core:3.1.0")
                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("io.ktor:ktor-client-okhttp:3.1.0")
            }
        }
        val iosMain by creating {
            dependencies {
                implementation("io.ktor:ktor-client-darwin:3.1.0")
            }
        }
    }
}

تكوين Gradle لـ KMP يتطلب الإعلان الصريح عن أهداف iOS — x64 (محاكي Intel)، arm64 (الأجهزة الفعلية) و simulatorArm64 (محاكي Apple Silicon). يتم إنشاء إطار Apple منفصل لكل هدف. يقوم الإضافة kotlin("multiplatform") تلقائيًا بتكوين التجميع لـ JVM و LLVM حسب الأهداف المعلنة.

Ktor و kotlinx.serialization — مكتبات KMP القياسية التي تدعم الكود المشترك. يوفر Ktor عميل HTTP مع محركات لكل منصة (OkHttp لنظام Android، Darwin لنظام iOS). تعمل kotlinx.serialization على جميع المنصات دون expect/actual بفضل تنفيذها متعدد المنصات في commonMain.

التكامل مع iOS عبر Kotlin/Native

Kotlin/Native — مترجم Kotlin للكود الأصلي عبر LLVM. بالنسبة لنظام iOS، يتم تجميع shared module في إطار Apple (.framework) الذي يتم توصيله عبر Xcode. استدعاء الكود المشترك من Swift/Objective-C يتم عبر رؤوس Objective-C المُنشأة، لذلك يجب أن تكون واجهة برمجة تطبيقات shared module متوافقة مع Objective-C.

قيود تكامل iOS: يتم تحويل مجموعات Kotlin (List، Map) إلى NSArray/NSDictionary. لا يتم تصدير الدوال ذات المعلمات الافتراضية — هناك حاجة إلى overloads. بالنسبة للدوال suspend، يتم إنشاء طرق قائمة على callback مع @ObjCName ودعم async/await بدءًا من Kotlin 2.0+.

// تطبيق iOS: استدعاء shared module من Swift
import shared

class ViewModel: ObservableObject {
    let repository = UserRepository()
    
    func loadUsers() {
        repository.fetchUsers(completionHandler: { result, error in
            if let users = result as? [User] {
                print("Users: \(users.count)")
            }
        })
    }
}

تكامل shared module في Xcode يتم عبر embed-and-framework — تتم إضافة .xcframework المُنشأ إلى مشروع Xcode. يمكن لإضافة Gradle تحديث الإطار تلقائيًا أثناء البناء عبر embedAndSignAppleFrameworkForXcode. للاختبار على المحاكي، يكفي ملف ثنائي iosSimulatorArm64 أو iosX64.

KMP مقابل Flutter مقابل React Native

يعتمد الاختيار بين KMP و Flutter و React Native على الأولوية: إعادة استخدام الكود أو التعدد الكامل للمنصات. يوفر KMP واجهة مستخدم أصلية على كل منصة ولكنه يتطلب قاعدتي كود للواجهة. يستخدم Flutter و React Native واجهة مستخدم واحدة لكنهما يضحيان بالأصالة.

متى تختار KMP: المشروع يتطلب واجهة مستخدم عالية الأداء (ألعاب، خرائط، رسوم متحركة)، يجب إعادة استخدام كود أصلي موجود، الفريق يعرف بالفعل Kotlin والمنصات الأصلية. متى تختار Flutter/RN: MVP أو شركة ناشئة بميزانية محدودة، فريق ذو ملف شخصي واحد، واجهة المستخدم لا تتطلب تخصيصًا أصليًا عميقًا.

أدوات ومكتبات KMP

النظام البيئي لأدوات KMP يشمل مكتبات لجميع طبقات التطبيق: الشبكات (Ktor)، التسلسل (kotlinx.serialization)، قاعدة البيانات (SQLDelight)، التنقل (Decompose)، حقن التبعية (Koin) وتخزين البيانات (multiplatform-settings). تدعم JetBrains Compose Multiplatform — إطار عمل UI في Kotlin يعمل على جميع المنصات.

// مستودع KMP مع SQLDelight + Ktor
class UserRepository(
    private val httpClient: HttpClient,
    private val db: AppDatabase
) {
    suspend fun syncUsers(): List<User> {
        val remote = httpClient.get("https://api.example.com/users")
            .body<List<UserDto>>()
        
        db.userQueries.replaceAll(remote.map { it.toDomain() })
        
        return db.userQueries.selectAll().executeAsList()
    }
}

Compose Multiplatform — إطار عمل UI لـ KMP مبني على Jetpack Compose. يسمح بكتابة واجهات في Kotlin لأنظمة Android و iOS و Desktop و Web. في 2025، وصل Compose Multiplatform إلى حالة مستقرة لنظامي Android و Desktop؛ هدف iOS في مرحلة beta. لمشاريع الإنتاج ذات واجهة المستخدم الأصلية، تظل ميزة KMP هي الفرق الرئيسي عن Flutter.