处理同步错误 — React Native SDK

添加通用同步错误处理程序

通用同步错误处理程序是跟踪同步错误的好方法。使用FlexibleSyncConfiguration ，您可以定义错误处理行为。

要添加通用同步错误处理程序，请执行以下操作：

1. 编写错误处理函数。

2. 为您的RealmProvider创建一个 FlexibleSyncConfiguration对象。

3. 将错误处理程序传递给FlexibleSyncConfiguration对象的onError属性。

const syncConfigWithErrorHandling = {
  flexible: true,
  onError: (_session, error) => {
    console.log(error);
  },
};
function RealmWithErrorHandling() {
  return (
    <RealmProvider sync={syncConfigWithErrorHandling}>
      <RestOfApp />
    </RealmProvider>
  );
}

处理补偿写入错误

您可能希望同步错误处理程序以对您的应用有意义的方式专门解决补偿写入错误。 CompensatingWriteError类可以帮助您识别自定义错误处理程序中的补偿写入错误并做出反应。

要处理补偿写入错误，请执行以下操作：

1. 编写一个错误处理程序函数，使用CompensatingWriteError来识别补偿写入错误。

2. 为您的RealmProvider创建一个FlexibleSyncConfiguration对象。

3. 将错误处理程序传递给FlexibleSyncConfiguration对象的onError属性。

export const CompensatingWriteErrorHandling = () => {
  const [error, setError] = useState<CompensatingWriteError | undefined>(
    undefined,
  );
  // Create a callback for sync error handling using CompensatingWriteError
  const errorCallback: ErrorCallback = (_session, error) => {
    if (error instanceof CompensatingWriteError) {
      // Handle the compensating write error as needed
      console.debug({
        code: error.code,
        name: error.name,
        category: error.category,
        message: error.message,
        url: error.logUrl,
        writes: error.writes,
      });
      setError(error);
    }
  };
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          schema={[Person, Turtle]}
          sync={{
            flexible: true,
            onError: errorCallback,
          }}>
          <CompensatingWriteErrorHandler error={error} />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
};

客户端重置模式

您可以指定应用程序应使用哪种客户端重置模式将域恢复到可同步状态：

• 恢复未同步更改模式：当您选择此模式时，客户端会尝试恢复未同步更改。如果您不想丢弃未同步的更改，请选择此模式。

• 恢复或丢弃未同步的更改模式：客户端首先尝试恢复尚未同步的更改。如果客户端无法恢复未同步的数据，则会放弃未同步的更改，但会继续自动执行客户端重置。当您想要启用客户端自动恢复以丢弃未同步的更改时，请选择此模式。

• 放弃未同步的更改模式：通过放弃自上次同步以来所做的更改，将 Realm 恢复到可同步状态。

• 手动恢复模式：下载 Realm 的新副本，并将不同步的 Realm 移动到备份。将未同步的数据从 Realm 的备份副本迁移到新的可同步副本。

自动与手动客户端重置

Realm SDK 提供了客户端重置模式，可自动处理大多数客户端重置错误。

客户端自动重置模式将本地 Realm 文件恢复到可同步状态，而无需关闭 Realm 或丢失通知。 以下客户端重置模式支持客户端自动重置：

• 恢复未同步变更模式

• 恢复或丢弃未同步的变更模式

• 丢弃未同步更改模式

这些模式之间的差异取决于它们如何处理设备上尚未同步到后端的更改。 仅手动恢复模式不执行自动客户端重置。

选择恢复未同步更改模式以自动处理大多数客户端重置情况。 这会尝试在客户端重置时恢复未同步的更改。

如果您的应用需要无法自动处理的特定客户端重置逻辑，您可能希望或需要将手动客户端重置处理程序添加到自动客户端重置模式。

客户端重置与恢复

客户端恢复是配置 Device Sync 时默认启用的功能。 启用客户端恢复后，Realm 在大多数情况下会自动托管客户端重置过程。当没有模式更改或非中断性模式更改时，客户端可以恢复未同步的更改。

要使用客户端恢复，请使用以下客户端重置模式之一配置您的域：

• 恢复未同步变更模式

• 恢复或丢弃未同步的更改

启用客户端恢复后，这些规则将决定如何集成对象，包括当后端和客户端都对同一对象进行更改时如何解决冲突：

• 同步在客户端重置之前未同步的本地创建的对象。

• 如果一个对象在服务器上被删除，但在恢复的客户端上被修改，则删除优先，客户端丢弃更新。

• 如果在正在恢复的客户端上删除了对象，而不是在服务器上删除了对象，则客户端将应用服务器的删除指令。

• 如果对同一字段的更新发生冲突，则应用客户端更新。

有关配置客户端恢复的详细信息，请参阅 App Services 文档中的客户端恢复。

当您的应用程序进行中断性模式更改时，客户端恢复无法成功。重大更改是您可以在服务器端模式中进行的需要执行额外操作来处理的更改。在这种情况下，客户端重置回退到手动错误客户端重置回退。

有关中断性与非中断性模式更改的信息，请参阅 App Services 文档中的中断性与非中断性更改快速参考。

丢弃未同步更改模式

放弃未同步的更改模式会永久删除自上次成功同步以来所做的所有本地未同步更改。当您的应用需要与自动 客户端恢复不一致的客户端恢复逻辑，或者您不想恢复未同步的数据时，可以使用此模式。

如果您的应用程序不能丢失尚未同步到后端的本地数据，请勿使用丢弃未同步的更改模式。

要使用丢弃未同步更改模式处理客户端重置，请将ClientResetConfiguration传递给FlexibleSyncConfiguration的clientReset字段。在ClientResetConfiguration中包含这些属性：

• mode：设置为"discardUnsyncedChanges" 。

• onBefore：可选。 当 SDK 从后端收到客户端重置错误时，在 SDK 执行此模式之前调用的回调函数。 提供 Realm 的副本。

• onAfter：可选。 SDK 成功执行此模式后调用的回调函数。 提供客户端重置前后 Realm 的实例。

以下示例实现了丢弃未同步更改模式：

手动模式

在手动模式下，您可以定义自己的客户端重置处理程序。 如果自动恢复逻辑不适用于您的应用，并且您无法丢弃未同步的本地数据，您可能需要使用手动客户端重置处理程序。

要使用手动模式处理客户端重置，请将ClientResetConfiguration传递给FlexibleSyncConfiguration的clientReset字段。在ClientResetConfiguration中包含这些属性：

• mode：设置为"manual" 。

• onManual：可选。 客户端重置时调用的回调函数。 提供有关同步会话和当前 Realm 路径的信息。 如果您不设置onManual错误处理程序，则客户端重置错误将回退到常规同步错误处理程序。

测试客户端重置处理

您可以通过终止并重新启用 Device Sync 来手动测试应用程序的客户端重置处理。

当您终止并重新启用 Sync 时，之前使用 Sync 连接的客户端在执行客户端重置之前无法进行连接。 终止同步会从服务器中删除允许客户端同步的元数据。 客户端必须从服务器下载 Realm 的新副本。 服务器向这些客户端发送客户端重置错误。 因此，当您终止同步时，就会trigger客户端重置条件。

要测试客户端重置处理，请执行以下操作：

1. 从客户端应用程序写入数据并等待其同步。

2. 终止并重新启用 Device Sync。

3. 再次运行客户端应用程序。 当应用尝试连接到服务器时，应该会出现客户端重置错误。