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 代码
代码 含义
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 某些资源已用尽，可能是因为达到了每用户配额或整个文件系统空间不足。例如，如果在宠物喂食器设备上调用 DispenseTrait 的 dispense 命令，但设备中没有剩余食物，则可能会抛出此错误。

这也可能是因为超出了 Home API 项目配额。如需了解详情，请参阅配额管理。
SDK_INITIALIZATION_MISSING_INFO 初始化 SDK 时未提供所有必需信息。 例如，如果客户端尝试获取给定特征 ID 的 TraitFactory，但在初始化 SDK 时未包含该特征，则会抛出此错误。请参阅在 Android 上初始化住宅。
UNAUTHENTICATED 无法识别调用方，或者请求没有有效的身份验证凭证。
UNAVAILABLE 服务不可用，这很可能是暂时性情况，可以通过使用退避算法重试来更正。请注意，重试执行非幂等操作并非总是安全的。
UNIMPLEMENTED 请求的操作在此服务中未实现、不受支持或未启用。
UNKNOWN 未知错误。当出现无法使用任何其他错误代码进行分类的错误情况时，系统会显示 UNKNOWN。 例如，如果从外部 API 收到的状态值缺少有关根本原因的足够信息，则可能会返回此错误。
WRITE_FAILED 写入操作未能执行。如需了解详情，请查看子错误代码。