مدیریت خطا در Android

‫Kotlin از استثناهای بررسی‌شده پشتیبانی نمی‌کند. این کار مدیریت خطا را ساده و روان می‌کند، زیرا می‌توانید انتخاب کنید که فقط استثناهایی را مدیریت کنید که احتمالاً قابل‌بازیابی هستند. و ازآنجایی‌که لازم نیست هر استثنای ممکن را به‌طور صریح مدیریت کنید، کد شما کمتر درهم‌ریخته است و درنتیجه، بیشتر بر هدف اصلی خود متمرکز می‌ماند.

خطاهای قابل‌بازیابی مشکلاتی هستند که توسعه‌دهنده می‌تواند ازطرف خود به آن‌ها رسیدگی کند. برای مثال، اگر مدرک شناسایی استفاده‌شده در تماس معتبر نباشد، میانای برنامه‌سازی کاربردی HomeException را با پیام invalid data ارائه می‌دهد. توسعه‌دهنده برنامه می‌تواند انتخاب کند که آن شناسه را از حافظه نهان خود بردارد یا پیامی مثل «ساختار پیدا نشد» به کاربر نشان دهد.

نمونه‌ای از نحوه مدیریت خطای قابل‌بازیابی:

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

هر روشی در Home APIs می‌تواند HomeException را پرتاب کند، بنابراین توصیه می‌کنیم از بلوک try-catch برای گرفتن HomeException در همه تماس‌ها استفاده کنید.

هنگام مدیریت HomeException، error.code و error.message را بررسی کنید تا متوجه شوید چه مشکلی پیش آمده است. ممکن است کدهای خطای فرعی نیز وجود داشته باشد، بنابراین روش getSubErrorCodes() را فراخوانی کنید و نتیجه را بررسی کنید.

هرگونه استثنای مدیریت‌نشده منجر به ازکارافتادن برنامه شما خواهد شد.

جدول زیر معانی HomeException کدی را که ممکن است با آن‌ها مواجه شوید ارائه می‌دهد:

جدول: HomeException کدها

کد	معنی
ABORTED	عملیات لغو شد، معمولاً به‌دلیل مشکل هم‌زمان‌سازی مانند ناموفق بودن بررسی ترتیب‌دهنده یا لغو تراکنش.
ALREADY_EXISTS	نهادی که مشتری تلاش کرده است ایجاد کند، برای مثال فایل یا دایرکتوری، ازقبل وجود دارد.
API_NOT_CONNECTED	کارخواه تلاش کرد روشی را از یک API که نتوانست متصل شود فراخوانی کند. این اتفاق ممکن است زمانی رخ دهد که دستگاه آفلاین باشد یا از «میانای برنامه‌سازی کاربردی» که مشتری سعی کرده است با آن تماس بگیرد پشتیبانی نکند.
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	کیت توسعه نرم‌افزار بدون همه اطلاعات موردنیاز مقداردهی اولیه شده است. برای مثال، اگر مشتری تلاش کند TraitFactory را برای شناسه ویژگی معینی دریافت کند اما ویژگی هنگام مقداردهی اولیه «کیت توسعه نرم‌افزار» اضافه نشده باشد، این خطا ایجاد می‌شود. ببینید راه‌اندازی خانه در Android.
UNAUTHENTICATED	تماس‌گیرنده قابل‌شناسایی نیست یا درخواست دارای اطلاعات اعتباری اصالت‌سنجی معتبر نیست.
UNAVAILABLE	سرویس دردسترس نیست. این وضعیت احتمالاً گذرا است و با تلاش مجدد با تأخیر قابل‌اصلاح است. توجه داشته باشید که تلاش مجدد برای عملیات غیرتوان‌سپار همیشه ایمن نیست.
UNIMPLEMENTED	عملیات درخواستی در این سرویس پیاده‌سازی، پشتیبانی، یا فعال نشده است.
UNKNOWN	خطای ناشناس. وقتی وضعیت خطایی رخ می‌دهد که نمی‌تواند بااستفاده از هیچ‌یک از کدهای خطای دیگر طبقه‌بندی شود، UNKNOWN ظاهر می‌شود. برای مثال، این خطا ممکن است زمانی برگردانده شود که مقدار وضعیت دریافتی از یک API خارجی اطلاعات کافی درباره علت اصلی نداشته باشد.
WRITE_FAILED	نوشتن اجرا نشد. برای جزئیات بیشتر، کدهای خطای فرعی را بررسی کنید.