اتّباع أفضل الممارسات

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

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

يجب أن تكون قواعد الاحتفاظ بالبيانات المحدّدة جيدًا دقيقة قدر الإمكان وأن تلتزم بالأنماط التالية:

• بالنسبة إلى مواصفات الفئة، حدِّد دائمًا فئة معيّنة أو صنف أساسي أو فئة مشروحة إذا أمكن، كما هو موضّح في الأمثلة التالية:

  -keepclassmembers class com.example.MyClass {
    void someSpecificMethod();
  }
  

  -keepclassmembers ** extends com.example.MyBaseClass {
    void someSpecificMethod();
  }
  

  -keepclassmembers @com.example.MyAnnotation class ** {
    void someSpecificMethod();
  }
  

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

  على سبيل المثال، يوضّح المقتطف التالي كيف يمكنك الاحتفاظ بالفئة MyClass، بالإضافة إلى فئات أخرى تمّت إضافة التعليق التوضيحي @com.example.DisplayComponent إليها:

  // In the source code
  @com.example.DisplayComponent
  class MyClass { /* ... */ }
  
  // In the keep rules
  -keep @com.example.DisplayComponent class * {*;}
  

  ننصحك بتسمية التعليقات التوضيحية بحيث توفّر سياقًا مفيدًا لسبب الاحتفاظ بأجزاء من الرمز البرمجي. على سبيل المثال، يمكنك استخدام @DisplayComponent لتطبيق تتطلّب فيه مكوّنات العرض الاحتفاظ ببعض الأجزاء.

• ويجب الإفصاح عن مواصفات العضو كلما أمكن ذلك، والإشارة فقط إلى أجزاء الفئة التي يجب الاحتفاظ بها لكي يعمل التطبيق. ننصح بعدم تطبيق قاعدة على فئة بأكملها من خلال تحديد نطاق العضو الاختياري على أنّه { *; } ما لم تكن هناك حاجة ماسة إلى ذلك.

  -keepclassmembers com.example.MyClass {
    void someSpecificMethod();
    void @com.example.MyAnnotation *;
  }
  

• في حال استخدام الخيار العام repackageclasses، تجنَّب تحديد اسم الحزمة الاختياري. يؤدي ذلك إلى إنشاء ملفات DEX أصغر حجمًا لأنّه يتم حذف بادئة الحزمة في أسماء الفئات المُعاد تجميعها.

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

  لإجراء انعكاس في الرمز البرمجي الخاص بك، يمكنك استخدام Jetpack Keep لإنشاء قواعد keep يسهل الحفاظ عليها. يتم وضع كل تعليق توضيحي على الرمز الذي ينفّذ الانعكاس، لذا عند تغيير هذا الرمز، عليك تعديل التعليق التوضيحي أو إزالته في المكان نفسه. بهذه الطريقة، لا تحتفظ القواعد بالرمز البرمجي الذي لم يعُد تطبيقك يعكسه. وتضع أداة Lint أيضًا علامة على الاستدعاءات الانعكاسية التي لم يتم وضع تعليقات توضيحية عليها.

• ننصحك باستخدام -assumenosideeffects أو -convertchecknotnull كلما أمكن ذلك لتحسين عمليات التحقّق من القيم الفارغة، لأنّ ذلك قد يقلّل بشكل كبير من حجم ملف DEX الخاص بتطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع القواعد الإضافية.

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

-keepclassmembers class com.example.pkg.** { *; }

ما يجب تجنُّبه

تتضمّن بنية قاعدة الاحتفاظ العديد من الخيارات، ولكن للحصول على مزايا أداء مستدامة وقابلة للقياس، ننصح بعدم استخدام ما يلي:

• لا تستخدِم قواعد الاحتفاظ على مستوى الحزمة، مثل -keep class com.example.pkg.** { *; } على المدى الطويل. ويمكن استخدامها مؤقتًا لتجنُّب المشاكل عند إعداد R8. لمزيد من المعلومات، يُرجى الاطّلاع على حصر نطاق التحسين. بشكل عام، يجب توخي الحذر عند استخدام أحرف البدل، والتأكّد من الاحتفاظ فقط بالرمز البرمجي الذي تحتاج إليه.
• تجنَّب قدر الإمكان المكتبات التي تقترح عليك نسخ قواعد الاحتفاظ ولصقها عند استخدامها، خاصةً قواعد الاحتفاظ على مستوى الحزمة. يجب أن تتجنّب المكتبات المصمَّمة لتقديم أداء جيد على Android استخدام الانعكاس قدر الإمكان وتضمين قواعد الاحتفاظ بالمستهلكين عند الضرورة.
• تجنَّب استخدام عامل الانعكاس ! في قواعد الاحتفاظ لأنّه قد يؤدي إلى تطبيق قاعدة على كل فئة في تطبيقك تقريبًا بدون قصد.

إذا لم تتمكّن من اتّباع هذه القواعد، من المحتمل أنّك تستخدم الكثير من الانعكاسات المفتوحة، وعليك تجنُّب الانعكاس أو تجنُّب المكتبة التي تستخدم الانعكاس (راجِع دراسة حالة Gson).