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 時，請檢查其 code 和 message 欄位，瞭解錯誤所在。

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

下表說明您可能會遇到的 HomeException 代碼：

表格：HomeException codes
程式碼 意義
ABORTED 作業已取消，原因通常是排序器檢查失敗或交易取消等並行問題。
ALREADY_EXISTS 用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。
API_NOT_CONNECTED 用戶端嘗試呼叫無法連線的 API 中的方法。當裝置離線或不支援用戶端嘗試呼叫的 API 時，就可能會發生這種情況。
CANCELLED 作業已取消 (通常由呼叫端取消)。
DATA_LOSS 發生無法復原的資料遺失或損毀情形。
DEADLINE_EXCEEDED 已超過期限，但作業尚未完成。針對會變更系統狀態的作業，即使作業順利完成也有可能會傳回這個錯誤。
FAILED_PRECONDITION 作業已遭拒絕，因為系統未處於執行該作業所需的狀態。舉例來說，如果您在已停止的烤箱上呼叫 OvenCavityOperationalStateTrait 的 stop 指令，或是嘗試在非目錄上執行 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 已耗盡某些資源 (可能是每位使用者的配額，也可能是整個檔案系統的空間不足)。舉例來說，如果在寵物餵食器裝置上呼叫 DispenseTrait 的 dispense 指令，但裝置中沒有剩餘的食物，就可能會擲回這個錯誤。
SDK_INITIALIZATION_MISSING_INFO SDK 未提供所有必要資訊就已初始化。舉例來說，如果用戶端嘗試取得特定特徵 ID 的 TraitFactory，但在初始化 SDK 時未納入特徵，系統就會擲回此錯誤。請參閱「在 Android 上初始化住家」。
UNAUTHENTICATED 無法識別呼叫端，或是要求沒有有效的驗證憑證。
UNAVAILABLE 無法使用服務，這很可能是暫時性問題，可透過重試輪詢來解決。請注意，重試非冪等操作不一定安全。
UNIMPLEMENTED 這項服務未實作、支援或啟用要求的作業。
UNKNOWN 發生不明錯誤，發生無法使用任何其他錯誤代碼分類的錯誤狀況時，系統會顯示 UNKNOWN。舉例來說，當從外部 API 收到的狀態值缺乏足夠的根本原因資訊時，就可能傳回此錯誤。