لمحة عن قواعد الاحتفاظ بالبيانات

عند تفعيل تحسين التطبيق باستخدام الإعدادات التلقائية، ينفّذ R8 عمليات تحسين شاملة من أجل زيادة مزايا الأداء إلى أقصى حد. يُجري المحسِّن R8 تعديلات كبيرة على الرمز، بما في ذلك إعادة تسمية الفئات والحقول والطرق ونقلها وإزالتها. إذا لاحظت أنّ هذه التعديلات تتسبّب في حدوث أخطاء، عليك تحديد الأجزاء التي يجب ألا يعدّلها R8 من خلال تعريفها في قواعد الاحتفاظ.

السيناريوهات الشائعة التي تتطلّب قواعد الاحتفاظ

يحدّد R8 جميع عمليات الاستدعاء المباشر في الرمز البرمجي ويحتفظ بها. ومع ذلك، لا يمكن لأداة R8 رصد الاستخدامات غير المباشرة للرموز البرمجية، ما قد يؤدي إلى إزالة رموز يحتاجها تطبيقك، وبالتالي حدوث أعطال. استخدِم قواعد الاحتفاظ بالبيانات لإخبار R8 بالحفاظ على الرموز التي يتم استخدامها بشكل غير مباشر. في ما يلي بعض الحالات الشائعة التي من المحتمل أن تحتاج فيها إلى قواعد الاحتفاظ:

  • الوصول إلى الرمز البرمجي باستخدام الانعكاس: لا يمكن لأداة R8 تحديد الحالات التي يتم فيها الوصول إلى الفئات أو الحقول أو الطرق باستخدام الانعكاس. على سبيل المثال، لا يمكن لبرنامج R8 تحديد طريقة بحث عن اسم باستخدام Class.getDeclaredMethod() أو تعليق توضيحي تم استرجاعه باستخدام Class.getAnnotation(). في هذه الحالات، قد يعيد R8 تسمية هذه الطرق والتعليقات التوضيحية أو يزيلها بالكامل، ما يؤدي إلى ظهور الخطأ ClassNotFoundException أو NoSuchMethodException في وقت التشغيل.
  • الرمز الذي يتم استدعاؤه من خلال واجهة Java الأصلية (JNI): عندما يستدعي الرمز الأصلي (C أو C++) طريقة Java أو Kotlin، أو عندما يستدعي رمز Java أو Kotlin رمز C++ باستخدام واجهة Java الأصلية (JNI)، يستند الاستدعاء إلى بحث ديناميكي عن اسم الطريقة. لا يمكن لـ R8 رؤية استدعاء الطريقة الديناميكية المستندة إلى السلسلة، وبالتالي قد تؤدي عمليات التحسين التي يجريها إلى تعطيل الرمز.

هذه القائمة ليست شاملة لجميع السيناريوهات التي تتطلّب قواعد الاحتفاظ، ولكنها تشمل معظم الحالات التي قد تحتاج فيها إلى قواعد الاحتفاظ.

كيفية إضافة قواعد الاحتفاظ إلى تطبيقك

عليك إضافة قواعدك إلى ملف proguard-rules.pro موجود في الدليل الجذري لوحدة تطبيقك. قد يكون الملف موجودًا، ولكن إذا لم يكن كذلك، عليك إنشاؤه. لتطبيق القواعد في الملف، يجب تعريف الملف في ملف build.gradle.kts (أو build.gradle) على مستوى الوحدة كما هو موضّح في الرمز التالي:

Kotlin

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // File with default rules provided by the Android Gradle Plugin
                getDefaultProguardFile("proguard-android-optimize.txt"),

                // File with your custom rules
                "proguard-rules.pro"
            )
           // ...
        }
    }
    // ...
}

Groovy

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true

            proguardFiles(
                // File with default rules provided by the Android Gradle Plugin
                getDefaultProguardFile('proguard-android-optimize.txt'),

                // File with your custom rules.
                'proguard-rules.pro'
            )
           // ...
        }
    }
    // ...
}

يتضمّن ملف الإنشاء تلقائيًا أيضًا ملف proguard-android-optimize.txt. يتضمّن هذا الملف قواعد مطلوبة لمعظم مشاريع Android، لذا عليك تركه في ملف الإصدار. يستند هذا الملف إلى الملف proguard-common.txt ويشارك المحتوى معه.

تحتوي التطبيقات الأكبر حجمًا عادةً على رموز برمجية في وحدات مكتبة متعددة. في مثل هذه الحالات، من الأفضل غالبًا وضع قواعد الإبقاء بجانب الرمز الذي تنطبق عليه ضمن وحدة المكتبة المحدّدة. يكمن الاختلاف الأساسي في الحفاظ على قواعد الاحتفاظ بالمكتبات في طريقة تعريف هذه القواعد ضمن ملف build.gradle.kts (أو build.gradle) الخاص بوحدة المكتبة. لمزيد من المعلومات، يمكنك الاطّلاع على التحسين لمؤلفي المكتبات.

إضافة قاعدة احتفاظ

عند إضافة قواعد الاحتفاظ، يمكنك تضمين خيارات عامة بالإضافة إلى تحديد قواعد الاحتفاظ الخاصة بك.

  • الخيارات العامة: الخيارات العامة هي توجيهات عامة تؤثر في طريقة عمل R8 على قاعدة الرموز البرمجية بأكملها. لمزيد من المعلومات، اطّلِع على الخيارات العامة.
  • قواعد الإبقاء: يجب تصميم قواعد الإبقاء بعناية للتأكّد من تحقيق التوازن المناسب بين زيادة تحسين الرمز إلى أقصى حد بدون إيقاف تطبيقك عن غير قصد. للتعرّف على بنية قواعد الإبقاء الخاصة بك، راجِع بنية قواعد الإبقاء.

الاحتفاظ بقواعد مؤلفي المكتبات

بعد التعرّف على الخيارات العامة وبنية قواعد الاحتفاظ، يمكنك الاطّلاع على التحسين لمؤلفي المكتبات للحصول على مزيد من التفاصيل.