Android 上的錯誤處理

Kotlin 不支援受檢例外狀況。這可簡化錯誤處理程序，因為您可以選擇只處理可能復原的例外狀況。此外，您不必明確處理所有可能的例外狀況，因此程式碼會更簡潔，能更專注於主要用途。

可復原的失敗是指開發人員可以自行解決的問題。舉例來說，如果呼叫中使用的 ID 無效，API 會擲回 HomeException，並顯示 invalid data 訊息。應用程式開發人員可以選擇從快取中移除該 ID，或向使用者顯示「找不到住家結構體」等訊息。

以下舉例說明如何處理可復原的失敗：

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

Home API 中的任何方法都可能擲回 HomeException，因此建議您使用 try-catch 區塊，在所有呼叫中擷取 HomeException。

處理 HomeException 時，請檢查其 error.code 和 error.message 欄位，瞭解發生什麼錯誤。此外，也可能會有子錯誤代碼，因此請呼叫 getSubErrorCodes() 方法並檢查結果。

任何未處理的例外狀況都會導致應用程式當機。

下表列出您可能會遇到的 HomeException 程式碼含義：

資料表：HomeException codes

程式碼	意義
ABORTED	作業已取消，通常是排序工具檢查失敗、交易取消等並行問題所造成。
ALREADY_EXISTS	用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。
API_NOT_CONNECTED	用戶端嘗試從無法連線的 API 呼叫方法。如果裝置離線或不支援用戶端嘗試呼叫的 API，就可能發生這種情況。
CANCELLED	作業已取消 (通常由呼叫端取消)。
COMMAND_FAILED	無法執行指令。詳情請查看子錯誤代碼。
CURSOR_WINDOW_NOT_SUPPORTED	呼叫的方法使用 CursorWindow，但目前情境未啟用或不支援 CursorWindow。
DATA_LOSS	發生無法復原的資料遺失或損毀。
DEADLINE_EXCEEDED	已超過期限，但作業尚未完成。針對會變更系統狀態的作業，即便作業順利完成也有可能會傳回這個錯誤。
DECOMMISSIONING_INELIGIBLE	裝置不符合停用資格，因此無法停用。
FAILED_PRECONDITION	系統未處於執行作業所需的狀態，因此作業遭拒。舉例來說，如果對已停止的烤箱呼叫 OvenCavityOperationalStateTrait 的 stop 指令，就可能會收到這則訊息。
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 指令，但裝置中沒有食物，就可能擲回這項錯誤。 這也可能是因為超出 Home API 專案配額。詳情請參閱「配額管理」。
SDK_INITIALIZATION_MISSING_INFO	SDK 初始化時缺少部分必要資訊。 舉例來說，如果用戶端嘗試取得指定特徵 ID 的 TraitFactory，但初始化 SDK 時未納入該特徵，就會擲回這項錯誤。請參閱「在 Android 上初始化住家」。
UNAUTHENTICATED	無法識別呼叫端，或要求不含有效的驗證憑證。
UNAVAILABLE	服務無法使用，這極有可能是暫時情況，並能透過重試來修正。請注意，重試非冪等作業不一定安全。
UNIMPLEMENTED	這項服務未實作、支援或啟用要求的作業。
UNKNOWN	發生不明錯誤，如果發生無法使用任何其他錯誤代碼分類的錯誤狀況，就會顯示 UNKNOWN。舉例來說，如果從外部 API 收到的狀態值缺乏根本原因的充分資訊，就可能傳回這項錯誤。
WRITE_FAILED	寫入作業無法執行。詳情請查看子錯誤代碼。