客户端重置
概述
客户端重置错误是客户端 Realm 无法与应用程序后端同步数据的情况。处于该状态的客户端可以继续运行并在本地保存数据，但在执行客户端重置之前无法发送或接收同步更改集。Realm SDK 提供了一些方法，以在大多数情况下自动处理客户端重置。
警告
默认情况下，客户端重置进程会尝试恢复在本地成功保存的未同步更改。当客户端应用程序进行中断性模式更改时，或者如果在服务器上禁用了恢复模式，则客户端重置过程无法恢复可能在设备本地持久保存的未同步数据。
当服务器的历史记录与客户端的历史记录不兼容时，就会发生客户端重置情况。客户端重置的最常见原因是：
Atlas App Services 服务器崩溃：服务器可以通过早期版本的备份进行恢复。该场景的客户端重置将客户端重置为早期版本，并丢失已在客户端上保存但尚未与服务器同步的任何更改。
禁用并重新启用 Sync：如果在 App Services 用户界面中关闭 Sync 并再次打开，将导致所有客户端都需要进行客户端重置。
客户端/后端模式不匹配：如果客户端应用程序尝试与后端同步，同时使用的 Realm 对象模式在后端不存在，该客户端必须执行客户端重置。这仅适用于一个方向：如果后端模式包含客户端中未使用的 Realm 对象类，该客户端不 需要进行客户端重置。
客户端最长离线时间：如果客户端与后端未同步的时间超过客户端最长离线时间天数，该客户端无法再与后端同步未同步的本地更改。客户端必须丢弃自上次同步以来进行的所有本地更改，并从后端下载 Realm 的当前状态。
中断性模式更改：中断性或破坏性更改（例如更改属性类型或主键）需要您终止并重新启用 Sync。这将创建一个新的同步 Realm 文件，其版本与客户端文件无关。在这种情况下，客户端重置过程无法自动完成，您的应用必须提供手动客户端重置处理程序。
从共享集群升级到专用集群：当您从共享集群升级到专用集群时，必须终止旧集群上的同步。升级后，您可以重新启用同步。关闭同步后再打开，会导致所有客户端需要重置客户端。
会话角色更改：在使用 Flexible Sync 时，更改用户的 Flexible Sync 会话角色将导致客户端重置。以下情况都会导致客户端重置：
在服务器端修改会话角色
对“apply when”、读取或写入表达式中任何扩展的值的更改
进行更改以使用户有资格担任不同的会话角色
注意
中断性模式更改需要更新应用模式
发生重大模式更改后：
所有客户端都必须执行手动客户端重置。
您必须更新中断性模式更改影响的客户端模型。
处理客户端重置
SDK 自动检测客户端是否需要重置。在大多数情况下，它们可以自动执行客户端重置，但发生重大模式更改时除外。
在客户端自动重置期间，客户端：
从后端下载 Realm 的全新副本。
执行差异分析，确定将 Realm 的原始（本地）副本更新到与后端最新副本相同状态所需的步骤。
执行该系列步骤，将本地 Realm 转换为可与后端同步的状态。
如果没有模式更改，或只有非重大模式更改，SDK 会尝试恢复尚未同步到后端的所有本地更改。SDK 也会应用后端中尚未同步到客户端的任何插入、更新和删除操作。
如果您在 SDK 中选择丢弃未同步的更改，或者恢复模式无法恢复未同步的更改，则 SDK 可能会丢弃尚未同步到后端的本地更改。然后，它可以应用后端尚未同步到客户端的任何插入、更新和删除操作。要改为丢弃本地更改，请选择所需 SDK 版本的
recoverOrDiscard客户端重置模式。丢弃新副本。应用将继续使用应用了差异的 Realm 的原始副本。
在进行中断性模式更改时，或者如果自动客户端重置失败，则客户端重置将改用您的应用必须定义的手动客户端重置处理程序。当您进行中断性模式更改时，Realm SDK 无法自动执行客户端重置。
与手动恢复相比，自动客户端重置模式具有几个优点：
除了指定模式之外，您的应用程序无需编写任何自定义逻辑即可执行客户端重置。您根本不必手动启动客户端重置或与错误对象交互。
您的应用程序可以执行客户端重置，而无需关闭任何 Realm、与后端应用断开连接或手动重启。这意味着您不必编写任何逻辑来处理这些情况。
当本地 Realm 更新以匹配后端 Realm 的状态时，应用程序用户会收到变更通知。
恢复未同步的更改
在 Device Sync 配置中启用客户端恢复时（默认设置），客户端应用程序可以自动恢复未同步的更改。在大多数情况下，客户端应用程序可以检测到出现的客户端重置错误，并启动自动过程以处理客户端重置。
在进行客户端重置后，应用可以正常打开和运行。
客户端恢复可以恢复客户端重置中的未同步数据，但进行中断性模式更改的情况除外。在确定如何集成设备中的未同步数据时，客户端恢复会应用客户端重置恢复规则。
如果客户端无法恢复未同步的数据，您可以选择回退到“丢弃未同步的更改”。在这种情况下，本地数据将被丢弃，但客户端可以自动执行客户端重置。要改为放弃本地更改，请选择您首选 SDK 版本的recoverOrDiscard客户端重置模式。
客户端重置恢复规则
在不涉及重大模式更改的客户端重置中，Realm SDK 会尝试恢复未同步的更改。SDK 会整合本地创建但在客户端重置之前未同步的对象。这些规则确定当后端和客户端对同一对象进行更改时如何解决冲突：
如果一个对象在服务器上被删除，但在恢复的客户端上被修改，则删除优先，客户端丢弃更新。
如果在恢复的客户端上删除一个对象，但在服务器上没有删除，则客户端应用删除指令。
如果对同一字段的更新发生冲突，则应用客户端更新。
丢弃未同步的更改
警告
永久删除未同步的本地更改
此客户端重置模式将永久删除本地所做的尚未同步到后端的任何更改。如果应用程序需要保留未同步的更改，请勿使用此客户端重置模式。
丢弃未同步更改客户端重置模式会自动处理客户端重置，而不会尝试从客户端设备恢复数据。如果客户端重置恢复规则不适用于您的应用，或者您不需要保存未同步的数据，则可以选择此模式。当此模式使用差异将本地 Realm 达到与后端相同的状态时，未同步的更改将被永久删除。
当发生重大模式更改时，“放弃未同步更改”模式无法执行自动客户端重置。
手动客户端重置
如果进行中断性模式更改，Realm SDK 无法自动处理客户端重置。如果进行中断性模式更改，您必须定义手动客户端重置处理程序。
在这种情况下，手动客户端重置处理程序应该应该做些事情，比如告诉用户更新应用。在自动处理客户端重置的 Realm SDK 版本中，手动客户端重置仅发生在无法进行有意义恢复的错误场景中。
举例
有关执行客户端重置的更多信息，请查看您的 SDK 的客户端重置示例：
启用或禁用恢复模式
默认情况下，每个 Device Sync 配置都会启用恢复模式。您可以禁用恢复模式；如果之前已禁用，您也可以重新启用恢复模式。