معالجة الأخطاء على Android

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

الأخطاء القابلة للاسترداد هي مشاكل يمكن للمطوّر حلّها من جهته. على سبيل المثال، إذا كان المعرّف المستخدَم في طلب البيانات غير صالح، ستعرض واجهة برمجة التطبيقات HomeException مع رسالة invalid data. يمكن لمطوّر التطبيق بعد ذلك إزالة رقم التعريف هذا من ذاكرة التخزين المؤقت أو عرض رسالة للمستخدم مثل "لم يتم العثور على البنية".

في ما يلي مثال على كيفية التعامل مع خطأ يمكن إصلاحه:

val result =
   try {
     homeManager.requestPermissions()
   } catch (e: HomeException) {
     PermissionsResult(
       PermissionsResultStatus.ERROR,
       "Got HomeException with error: ${e.message}",
     )
   }

يمكن لأي طريقة في واجهات برمجة التطبيقات Home عرض HomeException، لذا ننصحك باستخدام كتلة try-catch لرصد HomeException في جميع عمليات الاستدعاء.

عند التعامل مع HomeException، تحقَّق من الحقلَين code وmessage لمعرفة سبب حدوث الخطأ.

سيؤدي حدوث أي استثناءات لم تتم معالجتها إلى تعطُّل تطبيقك.

يوضّح الجدول التالي معاني رموز HomeException التي قد تواجهها:

الجدول: HomeException الرموز

الرمز	المعنى
ABORTED	تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل تعذُّر إجراء عملية التحقّق من التسلسل أو إلغاء المعاملة.
ALREADY_EXISTS	الكيان الذي حاول العميل إنشاءه، مثل ملف أو دليل، متوفّر مسبقًا.
API_NOT_CONNECTED	حاول العميل استدعاء طريقة من واجهة برمجة تطبيقات تعذّر الاتصال بها. يمكن أن يحدث ذلك عندما يكون الجهاز غير متصل بالإنترنت أو لا يتوافق مع واجهة برمجة التطبيقات التي حاول العميل طلبها.
CANCELLED	تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل.
DATA_LOSS	حدثت مشكلة في البيانات، إما فقدانها أو تلفها، ويتعذّر استرجاعها.
DEADLINE_EXCEEDED	انتهت المهلة قبل أن تتمكّن العملية من الاكتمال. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح.
FAILED_PRECONDITION	تم رفض العملية لأنّ النظام ليس في حالة مطلوبة لتنفيذ العملية. على سبيل المثال، قد تظهر لك هذه الرسالة إذا تم استدعاء الأمر stop الخاص بـ OvenCavityOperationalStateTrait على فرن متوقف، أو إذا حاولت تنفيذ عملية rmdir على عنصر ليس دليلاً.
INTERNAL	أخطاء داخلية وهذا يعني أنّه تم انتهاك بعض الثوابت التي يتوقّعها النظام الأساسي. رمز الخطأ هذا مخصّص للأخطاء الخطيرة.
INVALID_ARGUMENT	قدّم العميل وسيطة تقع خارج النطاق المتوقّع للقيم.
NOT_FOUND	لم يتم العثور على كيان مطلوب، مثل ملف أو دليل. في حال رفض الطلب لفئة كاملة من المستخدمين، مثل طرح ميزة تدريجيًا أو قائمة مسموح بها غير موثَّقة، يمكن استخدام NOT_FOUND. إذا تم رفض طلب بعض المستخدمين ضمن فئة من المستخدمين، مثل التحكّم في الوصول المستند إلى المستخدم، يجب استخدام PERMISSION_DENIED.
OUT_OF_RANGE	تمت محاولة تنفيذ العملية خارج النطاق الصالح، مثل البحث أو القراءة بعد end-of-file. على عكس INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة يمكن حلّها إذا تغيرت حالة النظام.
PERMISSION_DENIED	ليس لدى المتصل إذن بتنفيذ العملية المحددة. يجب عدم استخدام PERMISSION_DENIED مع عمليات الرفض الناتجة عن استنفاد بعض الموارد (استخدِم RESOURCE_EXHAUSTED مع هذه الأخطاء). يجب عدم استخدام PERMISSION_DENIED إذا تعذّر تحديد هوية المتصل (استخدِم UNAUTHENTICATED لهذه الأخطاء). لا يشير رمز الخطأ هذا إلى أنّ الطلب صالح أو أنّ العنصر المطلوب متوفّر أو يستوفي شروطًا مسبقة أخرى.
RESOURCE_EXHAUSTED	تم استنفاد بعض الموارد، ربما بسبب بلوغ الحصة المخصّصة لكل مستخدم أو نفاد المساحة في نظام الملفات بأكمله. على سبيل المثال، قد يحدث هذا الخطأ إذا تم استدعاء الأمر dispense الخاص بـ DispenseTrait على جهاز تغذية الحيوانات الأليفة ولكن لم يتبقَّ أي طعام في الوحدة.
SDK_INITIALIZATION_MISSING_INFO	تمت تهيئة حزمة SDK بدون جميع المعلومات المطلوبة. على سبيل المثال، يحدث هذا الخطأ إذا حاول العميل الحصول على TraitFactory لمعرّف سمة معيّن ولكن لم يتم تضمين السمة عند تهيئة حزمة تطوير البرامج (SDK). راجِع مقالة إعداد المنزل على Android.
UNAUTHENTICATED	لا يمكن تحديد هوية المتصل أو لا يتضمّن الطلب بيانات اعتماد مصادقة صالحة.
UNAVAILABLE	الخدمة غير متاحة. من المرجّح أنّ هذه الحالة عابرة ويمكن تصحيحها من خلال إعادة المحاولة مع التراجع. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة تنفيذ العمليات غير المتكرّرة.
UNIMPLEMENTED	لم يتم تنفيذ العملية المطلوبة أو إتاحتها أو تفعيلها في هذه الخدمة.
UNKNOWN	حدث خطأ غير معروف. يظهر الرمز UNKNOWN عند حدوث خطأ لا يمكن تصنيفه باستخدام أي من رموز الخطأ الأخرى. على سبيل المثال، قد يتم عرض هذا الخطأ عندما لا تتضمّن قيمة الحالة التي تم تلقّيها من واجهة برمجة تطبيقات خارجية معلومات كافية حول السبب الأساسي.