Kotlin Multiplatform: چیست، shared module و expect/actual

Kotlin Multiplatform چیست؟

Kotlin Multiplatform — فناوری کامپایل متقابل که امکان نوشتن کد مشترک در Kotlin و کامپایل آن برای پلتفرم‌های مختلف را فراهم می‌کند: JVM (Android)، LLVM (iOS، macOS، watchOS)، JavaScript (Web) و باینری‌های بومی (Linux، Windows). KMP یک فریم‌ورک UI نیست — مشکل استفاده مجدد از منطق تجاری را حل می‌کند، نه رابط‌های کاربری.

معماری 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 (تابع، کلاس، property) اعلام می‌شود و در هر source set مختص پلتفرم (androidMain، iosMain) پیاده‌سازی actual. کامپایلر بررسی می‌کند که برای هر expect یک actual در هر پلتفرم هدف وجود داشته باشد.

// commonMain — اعلام API پلتفرمی
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 در مقابل 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 framework جداگانه تولید می‌شود. پلاگین `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 (.framework) کامپایل می‌شود که از طریق Xcode متصل می‌شود. فراخوانی کد مشترک از Swift/Objective-C از طریق هدرهای Objective-C تولید شده انجام می‌شود، بنابراین API 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 می‌تواند به طور خودکار framework را هنگام ساخت از طریق embedAndSignAppleFrameworkForXcode به‌روزرسانی کند. برای آزمایش بر روی شبیه‌ساز، باینری iosSimulatorArm64 یا iosX64 کافی است.

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

انتخاب بین KMP، Flutter و React Native به اولویت بستگی دارد: استفاده مجدد از منطق یا چندپلتفرمی کامل. KMP رابط کاربری بومی در هر پلتفرم ارائه می‌دهد اما نیاز به دو پایگاه کد برای رابط دارد. Flutter و React Native از یک UI واحد استفاده می‌کنند اما بومی بودن را قربانی می‌کنند.

چه زمانی KMP را انتخاب کنیم: پروژه نیاز به UI با عملکرد بالا دارد (بازی‌ها، نقشه‌ها، انیمیشن‌ها)، کد بومی موجود باید استفاده مجدد شود، تیم از قبل Kotlin و پلتفرم‌های بومی را می‌شناسد. چه زمانی Flutter/RN را انتخاب کنیم: MVP یا استارتاپ با بودجه محدود، تیم با یک پروفایل، UI نیاز به سفارشی‌سازی عمیق بومی ندارد.

ابزارها و کتابخانه‌های KMP

اکوسیستم ابزارهای KMP شامل کتابخانه‌هایی برای تمام لایه‌های برنامه است: شبکه (Ktor)، سریال‌سازی (kotlinx.serialization)، پایگاه داده (SQLDelight)، ناوبری (Decompose)، DI (Koin) و ذخیره داده (multiplatform-settings). JetBrains از Compose Multiplatform — فریم‌ورک UI در Kotlin که بر روی همه پلتفرم‌ها کار می‌کند — پشتیبانی می‌کند.

// Repository در 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 در مرحله بتا است. برای پروژه‌های تولیدی با UI بومی، مزیت KMP تفاوت اصلی با Flutter باقی می‌ماند.