expect/actual — الجوهر، كلمات KMM المفتاحية وكيف تعمل

ما هو expect/actual؟

expect/actual هي آلية تصريحية في Kotlin Multiplatform لتنفيذ البرمجة الموجهة للمنصة. تسمح بوصف API مرة واحدة في الوحدة المشتركة (expect) وتنفيذها بشكل منفصل لكل منصة (actual). بخلاف الواجهات، لا تنشئ expect/actual استدعاءات افتراضية — يربط المجمع تصريحات expect و actual في وقت الترجمة، مما يلغي التكلفة الإضافية للإرسال الديناميكي.

بدأت قصة expect/actual مع ظهور Kotlin Multiplatform في 2017. في البداية، كانت الآلية تسمى expect/actual declarations وكانت تجريبية. في Kotlin 1.2 تمت إضافة الأنوتاتات expect، وفي Kotlin 1.3 أصبح expect/actual مستقرًا للفئات والدوال. بمرور الوقت توسعت الآلية: أضاف Kotlin 1.6 دعم expect/actual للكائنات المرافقة، Kotlin 1.7 للفئات التعدادية، و Kotlin 2.0 لـ typealias.

السمة الرئيسية لـ expect/actual هي الأمان في وقت الترجمة. إذا أضاف المطور تصريح expect في commonMain ولكن نسي تقديم تنفيذ actual لـ iOS، سيصدر المجمع خطأً. هذا يمنع أخطاء وقت التنفيذ الشائعة في الأساليب التي تستخدم الانعكاس أو التحميل الديناميكي لكود المنصة.

كيف تعمل آلية expect/actual

تعمل آلية expect/actual على مستوى source set — نظام وحدات Kotlin Multiplatform. الكود المشترك المتاح لجميع المنصات يقع في source set commonMain. الكود المعتمد على المنصة يقع في iosMain و androidMain و macosMain وغيرها. تصرح كلمة expect في commonMain بـ API، بينما تقدم كلمة actual في source set المنصة التنفيذ. يربطهما المجمع في مرحلة توليد الكود، مستبدلًا استدعاء دالة expect بتنفيذ actual المقابل للمنصة المستهدفة.

تبدو هيكل التسلسل الهرمي لـ source set في مشروع KMM نموذجي كالآتي: commonMain يحتوي تصريحات expect، iosMain و androidMain يحتويان تنفيذات actual. عند الترجمة لـ iOS، يتم استخدام actual من iosMain، وعند الترجمة لـ Android يتم استخدام actual من androidMain. يمكن أن تكون source sets وسيطة (على سبيل المثال iosArm64Main لمعمارية محددة)، مما يسمح بتحسين التنفيذات لأجهزة مختلفة.

// commonMain — expect declaration
expect fun getPlatformName(): String

// androidMain — actual for Android
actual fun getPlatformName(): String = "Android"

// iosMain — actual for iOS
actual fun getPlatformName(): String = "iOS"

تحقق المجمع من تنفيذات actual

يتحقق مجمع Kotlin من عدة شروط عند العمل مع expect/actual. يجب أن يكون لكل تصريح expect تنفيذ actual لكل منصة نشطة. يجب أن تتطابق توقيع actual مع توقيع expect (يمكن للتعليق @OptionalExpectation تخفيف هذا المتطلب). يجب أن تكون محددات الوصول ونوع العودة والمعاملات متطابقة. ويتحقق المجمع أيضًا من عدم وجود تبادلات دورية بين تصريحات expect و actual.

أنواع expect/actual: الدوال، الفئات، الخواص

expect/actual تدعم عدة أنواع من التصريحات. الأكثر شيوعًا هي دوال expect/actual لعمليات المنصة، فئات expect/actual للكائنات التي تتطلب تنفيذًا أصليًا، وخواص expect/actual للثوابت والإعدادات. لكل نوع قواعد استخدام وقيود خاصة.

دوال expect/actual هي أبسط الأنواع وأكثرها شيوعًا. تستخدم لاستدعاء API المنصة مثل الحصول على الوقت أو قراءة الملفات أو إرسال طلبات HTTP. تستخدم فئات expect/actual لإنشاء كائنات تتفاعل مباشرة مع الكود الأصلي (على سبيل المثال للوصول إلى الكاميرا أو الموقع الجيوماني أو تخزين المفاتيح). خواص expect/actual (val) مناسبة لثوابت المنصة — اسم نظام التشغيل أو إصدار SDK أو مسار دليل النظام.

قيود expect/actual

لا يمكن استخدام جميع بنيات Kotlin مع expect/actual. لا يمكن لـ تصريح expect أن يحتوي على جسم — فقط توقيع. لا يمكن لفئة expect أن يكون لها منشئ بمعلمات (يجب أن يكون لها منشئ أساسي فارغ). لـ enum expect/actual، يجب أن تكون جميع الثوابت متطابقة في كل من expect و actual. يجب أن تكون خواص expect من نوع val (ليس var)، لأن تخزين الحالة في الوحدة المشتركة لخواص المنصة ليس له معنى.

أمثلة كود: من البسيط إلى المعقد

دعنا نستعرض أمثلة عملية لـ expect/actual من دوال بسيطة إلى فئات متكاملة. الحالة الأساسية هي الحصول على اسم المنصة لاستخدامه في واجهة المستخدم. تشمل الأمثلة الأكثر تعقيدًا الوصول إلى التخزين الأصلي والعمل مع خيوط المنصة.

// commonMain — expect class for secure storage
expect class PlatformStorage {
    fun save(key: String, value: String)
    fun get(key: String): String?
    fun remove(key: String)
}

// androidMain — actual on Android
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() }
}

في هذا المثال، تحدد فئة expect PlatformStorage عقد تخزين بسيط من نوع مفتاح-قيمة. في Android، تستخدم التنفيذ SharedPreferences، بينما في iOS تستخدم Keychain أو NSUserDefaults. بفضل expect/actual، يقوم منطق الأعمال في commonMain باستدعاء save/get/remove دون معرفة تنفيذ المنصة.

// iosMain — actual on iOS with Keychain
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

عند تصميم API expect/actual، يجب اتباع عدة مبادئ. قلل عدد تصريحات expect — كلما كان الكود المشترك أكبر، كانت الصيانة أسهل. استخدم expect/actual فقط لـ API التي تختلف حقيقيًا بين المنصات. باقي الكود، استخدم واجهات مع مصانع أو حقن التبعيات، وهو ما يبسط الاختبار.

يوصى بتجميع تصريحات expect حسب الوحدات الموضوعية، بدلاً من خلطها في ملف واحد. على سبيل المثال، Storage.kt لتصريحات expect التخزين، Platform.kt لدوال expect التي تعمل مع نظام التشغيل، و Analytics.kt لفئات expect التحليل. هذا يبسط التنقل وفهم سطح المنصة لمشروع KMM. يجب أن يكون كل ملف actual في source set المقابل: androidMain و iosMain و desktopMain وغيرها.

التنفيذات الافتراضية عبر expect fun مع actual fun حيث يستخدم actual كودًا مشتركًا هو نمط ضد الأنماط شائع. إذا لم يختلف تنفيذ المنصة عن الافتراضي، فلا حاجة لـ expect/actual. في مثل هذه الحالات، استخدم دالة بسيطة في commonMain. كما تجنب expect/actual لـ getters بسيطة — استخدم expect val مع ثوابت.

تنظيم الكود في المشروع

الهيكل المناسب لكود expect/actual أساسي لقراءة المشروع. يجب أن يكون لكل وحدة expect/actual نقطة دخول واحدة. مثال تنظيم: commonMain/kotlin/com/project/platform يحتوي تصريحات expect، androidMain/kotlin/com/project/platform يحتوي actual لـ Android، iosMain/kotlin/com/project/platform يحتوي actual لـ iOS. يجب أن تتطابق أسماء الملفات والحزم لـ expect و actual، لكي يتمكن المطور من العثور على التنفيذ المقابل بسرعة.

بدائل expect/actual في KMM

الواجهات مع مصنع المنصة هي البديل الرئيسي لـ expect/actual. بدلاً من فئة expect، يمكنك إعلان واجهة في commonMain وإنشاء فئات محددة في وحدات المنصة. يقوم مصنع أو حاوية حقن التبعيات بتوفير التنفيذ الصحيح في وقت التنفيذ. هذا النهج أنسب للاختبار، حيث يمكن محاكاة الواجهة.

حقن التبعيات (Koin, Kodein) هو نهج أكثر مرونة ولكن أقل كفاءة. يتم تكوين حاوية DI بشكل منفصل لكل منصة وتوفر تبعيات المنصة للكود المشترك. بخلاف expect/actual، يحدث الحقن في وقت التنفيذ، مما يسمح بتبادل التنفيذات للاختبار. من ناحية أخرى، لا تكتشف أخطاء تكوين DI إلا في وقت التنفيذ، وليس في وقت الترجمة.

يعتمد الاختيار بين expect/actual والبدائل على السياق. للكود الحاسم للأداء (محركات الألعاب، المعالجة الفورية)، expect/actual مفضل بسبب عدم وجود تكلفة إضافية. لـ منطق الأعمال (المستودعات، حالات الاستخدام)، من الأفضل استخدام واجهات مع DI لتبسيط الاختبار. نهج مجمع — expect/actual لعمليات المنصة منخفضة المستوى وواجهات لطبقة منطق الأعمال — يستخدم في معظم مشاريع KMM الإنتاجية.