معالجة الأخطاء على 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 أو قراءة محتوى بعد 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	لا يمكن تحديد هوية المتصل أو لا يتضمّن الطلب بيانات اعتماد مصادقة válida.
UNAVAILABLE	الخدمة غير متاحة. من المرجّح أنّ هذا الموقف هو حالة عابر يمكن تصحيحها من خلال إعادة المحاولة مع الانتظار. يُرجى العِلم أنّه قد لا يكون من الآمن دائمًا إعادة محاولة العمليات غير الثابتة.
UNIMPLEMENTED	العملية المطلوبة غير مفعَّلة أو متوافقة أو غير قابلة للتنفيذ في هذه الخدمة.
UNKNOWN	حدث خطأ غير معروف. يظهر الرمز UNKNOWN عند حدوث حالة خطأ لا يمكن تصنيفها باستخدام أي من رموز الخطأ الأخرى. على سبيل المثال، قد يتم عرض هذا الخطأ عندما لا تتضمّن قيمة الحالة التي تم تلقّيها من واجهة برمجة تطبيقات خارجية معلومات كافية عن السبب الأساسي.