معالجة الأخطاء على 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، راجِع الحقلَين error.code و error.message لمعرفة الخطأ الذي حدث. قد تكون هناك رموز أخطاء فرعية أيضًا، لذا استدعِ طريقة getSubErrorCodes() وتحقّق من النتيجة.

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

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

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

الرمز	المعنى
ABORTED	تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل تعذُّر التحقّق من التسلسل أو إلغاء المعاملة.
ALREADY_EXISTS	الكيان الذي حاول العميل إنشاءه، مثل ملف أو دليل، متوفّر مسبقًا.
API_NOT_CONNECTED	حاول العميل استدعاء طريقة من واجهة برمجة تطبيقات تعذّر الاتصال بها. يمكن أن يحدث ذلك عندما يكون الجهاز غير متصل بالإنترنت أو لا يتوافق مع واجهة برمجة التطبيقات التي حاول العميل طلبها.
CANCELLED	تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل.
COMMAND_FAILED	تعذّر تنفيذ الأمر. راجِع رموز الخطأ الفرعية للحصول على مزيد من التفاصيل.
CURSOR_WINDOW_NOT_SUPPORTED	تم استدعاء طريقة تستخدم CursorWindow، ولكن CursorWindow غير ممكّن أو غير مدعوم في السياق الحالي.
DATA_LOSS	حدثت مشكلة في البيانات، إما فقدانها أو تلفها، ويتعذّر استرجاعها.
DEADLINE_EXCEEDED	انتهت المهلة قبل أن تتمكّن العملية من الاكتمال. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح.
DECOMMISSIONING_INELIGIBLE	تعذّر إيقاف الجهاز نهائيًا لأنّه غير مؤهَّل لذلك.
FAILED_PRECONDITION	تم رفض العملية لأنّ النظام ليس في حالة مطلوبة لتنفيذ العملية. على سبيل المثال، قد تظهر لك هذه الرسالة إذا تم استدعاء الأمر stop الخاص بالجهاز OvenCavityOperationalStateTrait على فرن تم إيقافه مسبقًا.
INTERNAL	أخطاء داخلية وهذا يعني أنّه تم انتهاك بعض الثوابت التي يتوقّعها النظام الأساسي. رمز الخطأ هذا مخصّص للأخطاء الخطيرة.
INVALID_ARGUMENT	قدّم العميل وسيطة تقع خارج النطاق المتوقّع للقيم.
INVALID_DATA_HOLDER	حامل البيانات غير صالح.
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 عند حدوث خطأ لا يمكن تصنيفه باستخدام أي من رموز الخطأ الأخرى. على سبيل المثال، قد يتم عرض هذا الخطأ عندما لا تتضمّن قيمة الحالة التي تم تلقّيها من واجهة برمجة تطبيقات خارجية معلومات كافية بشأن السبب الأساسي.
WRITE_FAILED	فشلت عملية الكتابة. راجِع رموز الخطأ الفرعية للحصول على مزيد من التفاصيل.