expect/actual — mahiyyəti, KMM açar sözləri və necə işlədikləri

expect/actual nədir?

expect/actual — platforma yönümlü proqramlaşdırmanı həyata keçirmək üçün Kotlin Multiplatform-un deklarativ mexanizmidir. O, API-ni bir dəfə ümumi modulda (expect) təsvir etməyə və onu hər platforma üçün ayrıca (actual) həyata keçirməyə imkan verir. İnterfeyslərdən fərqli olaraq, expect/actual virtual çağırışlar yaratmır — kompilyator expect və actual bəyannamələrini kompilyasiya mərhələsində birləşdirir və bu da dinamik dispetçerizasiya üçən əlavə yükü aradan qaldırır.

expect/actual tarixi 2017-ci ildə Kotlin Multiplatform’un yaranması ilə başladı. Əvvəlcə mexanizm expect/actual declarations adlanırdı və eksperimental idi. Kotlin 1.2-də expect annotasiyaları əlavə edildi, Kotlin 1.3-də isə expect/actual siniflər və funksiyalar üçün stabilləşdi. Tədricən mexanizm genişləndi: Kotlin 1.6-də companion obyektləri üçün expect/actual dəstəyi, Kotlin 1.7-də — enum sinifləri üçün, Kotlin 2.0-da isə — typealias üçün əlavə edildi.

expect/actual’ın əsas xüsusiyyəti — kompilyasiya səviyyəsində təhlükəsizlik. Proqramçı commonMain-də expect bəyannaməsi əlavə etdikdə, lakin iOS üçün actual implementasiyanı unutduqda, kompilyator xəta verir. Bu, refleksiya və ya platforma kodunun dinamik yüklənməsi yanaşmaları üçün xarakterik olan runtime xətalarının qarşısını alır.

expect/actual mexanizmi necə işləyir

Mexanizm expect/actual source set — Kotlin Multiplatform modul sistemi səviyyəsində işləyir. Bütün platformalar üçün əlçatan ümumi kod commonMain source set-ində yerləşir. Platformadan asılı kod — iosMain, androidMain, macosMain və s. commonMain-də expect açar sözü API-ni bəyan edir, platforma source set-ində actual açar sözü isə implementasiyanı təmin edir. Kompilyator onları kod generasiyası mərhələsində birləşdirir və expect funksiyasının çağırışını hədəf platforma üçün müvafiq actual implementasiya ilə əvəz edir.

Tipik KMM layihəsində source set iyerarxiyası belədir: commonMain expect bəyannamələrini ehtiva edir, iosMain və androidMain actual implementasiyaları ehtiva edir. iOS üçün kompilyasiya zamanı iosMain-dən, Android üçün kompilyasiya zamanı isə androidMain-dən actual istifadə olunur. Source set’lər aralıq ola bilər (məsələn, müəyyən arxitektura üçün iosArm64Main), bu da müxtəlif cihazlar üçün implementasiyaları dəqiqləşdirməyə imkan verir.

// commonMain — expect bəyannaməsi
expect fun getPlatformName(): String

// androidMain — Android üçün actual
actual fun getPlatformName(): String = "Android"

// iosMain — iOS üçün actual
actual fun getPlatformName(): String = "iOS"

Kompilyatorun actual implementasiyaları yoxlaması

Kotlin kompilyatoru expect/actual ilə işlərkən bir neçə şərti yoxlayır. Hər expect bəyannaməsi hər aktiv platforma üçün actual implementasiyaya malik olmalıdır. actual bəyannaməsinin imzası expect imzası ilə uyğun olmalıdır (@OptionalExpectation annotasiyası bu tələbi yumşala bilər). Giriş modifikatorları, qaytarma tipi və parametrlər eyni olmalıdır. Kompilyator həmçinin expect və actual bəyannamələri arasında tsiklik asılılıqların olmamasını yoxlayır.

expect/actual növləri: funksiyalar, siniflər, xassələr

expect/actual bir neçə bəyannamə növünü dəstəkləyir. Platforma əməliyyatları üçün expect/actual funksiyaları, nativ implementasiya tələb edən obyektlər üçün expect/actual sinifləri və sabitlər və parametrlər üçün expect/actual xassələri ən çox istifadə olunur. Hər növün öz istifadə qaydaları və məhdudiyyətləri var.

expect/actual funksiyaları — ən sadə və geniş yayılmış növdür. Onlar vaxtı əldə etmək, faylları oxumaq və ya HTTP sorğuları göndɘrmɘk kimi platforma API-lɘrini çağırmaq üçün istifadə olunur. expect/actual sinifləri nativ kodla birbaşa qarşılıqlı əlaqədə olan obyektlɘr yaratmaq üçün tətbiq edilir (məsələn, kameraya, geolokasiyaya və ya açar saxlayıcıya giriş üçün). expect/actual xassələri (val) platforma sabitləri — OS adı, SDK versiyası və ya sistem kataloquna yol üçün uyğundur.

expect/actual məhdudiyyətləri

Kotlin-in bütün konstruksiyaları expect/actual ilə istifadə oluna bilməz. expect bəyannaməsi bədən ehtiva edə bilməz — yalnız imza. expect sinifi parametrləri olan konstruktora malik ola bilməz (boş əsas konstruktor olmalıdır). Enum expect/actual üçün bütün sabitlər expect və actual-da eyni olmalıdır. expect xassələri val (var deyil) olmalıdır, çünki platforma xassələri üçün ümumi modulda vəziyyətin saxlanmasının mənası yoxdur.

Kod nümunələri: sadədən mürəkkəbə

expect/actual-ın sadə funksiyalardan tam hüquqlu siniflərə qədər praktik nümunələrini nəzərdən keçirək. Əsas hal — interfeysdə istifadə üçün platforma adını əldə etmək. Daha mürəkkəb nümunələr nativ yaddaşa giriş və platforma axınları ilə işi əhatə edir.

// commonMain — təhlükəsiz yaddaş üçün expect sinifi
expect class PlatformStorage {
    fun save(key: String, value: String)
    fun get(key: String): String?
    fun remove(key: String)
}

// androidMain — Android-də actual
actual class PlatformStorage {
    private val prefs = AppContext.getSharedPreferences("secure", 0)

    actual fun save(key: String, value: String) { prefs.edit().putString(key, value).apply() }
    actual fun get(key: String): String? = prefs.getString(key, null)
    actual fun remove(key: String) { prefs.edit().remove(key).apply() }
}

Bu nümunədə PlatformStorage expect sinifi sadə açar-dəyər yaddaşının kontraktını müyyən edir. Android-də implementasiya SharedPreferences, iOS-da isə Keychain və ya NSUserDefaults istifadə edir. expect/actual sayəsində commonMain-dəki biznes məntiqi platforma implementasiyasını bilmədən save/get/remove çağırır.

// iosMain — iOS-da Keychain ilə actual
actual class PlatformStorage {
    actual fun save(key: String, value: String) {
        val query = mapOf<String, Any>(
            kSecClass to kSecClassGenericPassword,
            kSecAttrAccount to key,
            kSecValueData to value.encodeToByteArray()
        )
        SecItemAdd(query, null)
    }

    actual fun get(key: String): String? {
        val query = mapOf<String, Any>(
            kSecClass to kSecClassGenericPassword,
            kSecAttrAccount to key,
            kSecReturnData to true
        )
        val result = mutableMapOf<String, Any>()
        return if (SecItemCopyMatching(query, result) == errSecSuccess)
            result[kSecValueData]?.toString()
        else null
    }

    actual fun remove(key: String) {
        val query = mapOf<String, Any>(
            kSecClass to kSecClassGenericPassword,
            kSecAttrAccount to key
        )
        SecItemDelete(query)
    }
}

expect/actual ən yaxşı təcrübələri

expect/actual API-ni dizayn edərkən bir neçə prinsipə riayət edilməlidir. Minimuma endirin expect bəyannamələrinin sayını — nə qədər çox ümumi kod varsa, dəstək bir o qədər asandır. expect/actual-ı yalnız platformalarda həqiqətən fərqlənən API-lər üçün istifadə edin. Qalan kod üçün interfeysləri fabrikalarla və ya dependency injection ilə tətbiq edin, bu testi asanlaşdırır.

expect bəyannamələrinin mövzu modulları üzrə qruplaşdırılması tövsiyə olunur, bir faylda qarışdırmaq əvəzinə. Məsələn, yaddaş üçün Storage.kt, ƏƏ ilə iş üçün Platform.kt və analitika üçün Analytics.kt expect bəyannamələri. Bu, KMM layihəsinin platforma səthində naviqasiyanı və anlayışı asanlaşdırır. Hər actual fayl müvafiq source set-də olmalıdır: androidMain, iosMain, desktopMain və s.

Default implementasiyalar actual fun-un ümumi koddan istifadə etdiyi expect fun vasitəsilə — geniş yayılmış anti-nümunədir. Platforma implementasiyası default-dan fərqlənmirsə, expect/actual lazım deyil. Belə hallarda commonMain-də sadə funksiyadan istifadə edin. Həmçinin mənasız getterlər üçün expect/actual-dan çəkinin — sabitlərlə expect val istifadə edin.

Layihədə kodun təşkili

expect/actual kodunun düzgün strukturu layihənin oxunaqlılığı üçün vacibdir. Hər expect/actual modulu vahid giriş nöqtəsinə malik olmalıdır. Təşkilat nümunəsi: commonMain/kotlin/com/project/platform expect bəyannamələrini ehtiva edir, androidMain/kotlin/com/project/platform — Android üçün actual-ı, iosMain/kotlin/com/project/platform — iOS üçün actual-ı. Fayl və paket adları expect və actual üçün uyğun olmalıdır ki, proqramçı müvafiq implementasiyanı tez tapa bilsin.

KMM-də expect/actual alternativləri

Interfeyslər platforma fabrikası ilə — expect/actual-ın əsas alternatividir. expect sinifi əvəzinə commonMain-də interfeys bəyan edilə bilər və platforma modullarında konkret siniflər yaradıla bilər. Fabrika və ya dependency injection konteyneri runtime-da düzgün implementasiyanı təmin edir. Bu yanaşma test üçün daha uyğundur, çünki interfeysi mock etmək olar.

Dependency Injection (Koin, Kodein) — daha çevik, lakin az məhsuldar yanaşmadır. DI konteyneri hər platforma üçün ayrıca konfiqurasiya olunur və ümumi koda platforma asılılıqlarını təmin edir. expect/actual-dan fərqli olaraq, injection runtime-da baş verir, bu da test üçün implementasiyaları dəyişməyə imkan verir. Digər tərəfdən, DI konfiqurasiya xətaları yalnız işə salma zamanı aşkar edilir, kompilyasiya mərhələsində yox.

expect/actual və alternativlər arasında seçim kontekstdən asılıdır. Kritik məhsuldarlıq üçün (oyun mühərrikləri, real-time emal) sıfır runtime yükü səbəbindən expect/actual üstünlüklüdür. Biznes məntiqi üçün (repozitoriyalar, use-case’lər) testi asanlaşdırmaq üçün DI ilə interfeyslərdən istifadə etmək daha yaxşıdır. Kombinə edilmiş yanaşma — aşağı səviyyəli platforma əməliyyatları üçün expect/actual və biznes məntiqi təbəqəsi üçün interfeyslər — əksər production KMM layihələrində tətbiq olunur.