客户端重置

Overview

客户端重置错误是客户端 Realm 无法与应用程序后端同步数据的情况。处于该状态的客户端可以继续运行并在本地保存数据，但在执行客户端重置之前无法发送或接收同步更改集。Realm SDK 提供了一些方法，以在大多数情况下自动处理客户端重置。

当服务器的历史记录与客户端的历史记录不兼容时，就会发生客户端重置情况。客户端重置的最常见原因是：

• Atlas App Services 服务器崩溃：服务器可以通过早期版本的备份进行恢复。该场景的客户端重置将客户端重置为早期版本，并丢失已在客户端上保存但尚未与服务器同步的任何更改。

• 禁用并重新启用 Sync：如果在 App Services 用户界面中关闭 Sync 并再次打开，将导致所有客户端都需要进行客户端重置。

• 客户端/后端模式不匹配：如果客户端应用程序尝试与后端同步，同时使用的 Realm 对象模式在后端不存在，该客户端必须执行客户端重置。这仅适用于一个方向：如果后端模式包含客户端中未使用的 Realm 对象类，该客户端不 需要进行客户端重置。

• 客户端最长离线时间：如果客户端与后端未同步的时间超过客户端最长离线时间天数，该客户端无法再与后端同步未同步的本地更改。客户端必须丢弃自上次同步以来进行的所有本地更改，并从后端下载 Realm 的当前状态。

• 中断性模式更改：中断性或破坏性更改（例如更改属性类型或主键）需要您终止并重新启用 Sync。 这将创建一个新的同步域文件，其版本与客户端的文件无关。 在这种情况下，客户端重置进程无法自动完成，您的应用必须提供手动客户端重置处理程序。

• 从共享集群升级到专用集群：当您从共享集群升级到专用集群时，必须终止旧集群上的同步。升级后，您可以重新启用同步。关闭同步后再打开，会导致所有客户端需要重置客户端。

• 会话角色更改：在使用 Flexible Sync 时，更改用户的 Flexible Sync 会话角色将导致客户端重置。以下情况都会导致客户端重置：

  • 在服务器端修改会话角色

  • 对“apply when”、读取或写入表达式中任何扩展的值的更改

  • 进行更改以使用户有资格担任不同的会话角色

  注意

  中断性模式更改需要更新应用模式

  发生重大模式更改后：

  • 所有客户端必须执行手动客户端重置。

  • 您必须更新中断性模式更改影响的客户端模型。

处理客户端重置

SDK 自动检测客户端是否需要重置。在大多数情况下，它们可以自动执行客户端重置，但发生重大模式更改时除外。

在客户端自动重置期间，客户端：

1. 从后端下载 Realm 的全新副本。

2. 执行差异分析，确定将 Realm 的原始（本地）副本更新到与后端最新副本相同状态所需的步骤。

3. 执行该系列步骤，将本地 Realm 转换为可与后端同步的状态。

   如果没有模式更改，或只有非重大模式更改，SDK 会尝试恢复尚未同步到后端的所有本地更改。SDK 也会应用后端中尚未同步到客户端的任何插入、更新和删除操作。

   如果您在 SDK 中选择丢弃未同步的更改，或者恢复模式无法恢复未同步的更改，则 SDK 可能会丢弃尚未同步到后端的本地更改。然后，它可以应用后端尚未同步到客户端的任何插入、更新和删除操作。要改为丢弃本地更改，请选择所需 SDK 版本的 recoverOrDiscard 客户端重置模式。

4. 丢弃新副本。应用将继续使用应用了差异的 Realm 的原始副本。

如果进行中断性模式更改，或者自动客户端重置失败，客户端重置将改用您的应用必须定义的手动客户端重置处理程序。在您进行中断性模式更改时，Realm SDK 无法自动执行客户端重置。

与手动恢复相比，自动客户端重置模式具有几个优点：

• 除了指定模式之外，您的应用程序无需编写任何自定义逻辑即可执行客户端重置。您根本不必手动启动客户端重置或与错误对象交互。

• 您的应用程序可以执行客户端重置，而无需关闭任何 Realm、与后端应用断开连接或手动重启。这意味着您不必编写任何逻辑来处理这些情况。

• 当本地 Realm 更新以匹配后端 Realm 的状态时，应用程序用户会收到变更通知。

启用或禁用恢复模式

默认情况下，每个 Device Sync 配置都会启用恢复模式。您可以禁用恢复模式；如果之前已禁用，您也可以重新启用恢复模式。