동기화 오류 처리 - Flutter SDK

클라이언트 재설정 모드

클라이언트 재설정 프로세스 를 관리 하려면 FlexibleSyncConfiguration.clientResetHandler 에서 클라이언트 재설정 모드 를 지정할 수 있습니다. 속성 을 사용하여 영역 을 구성할 수 있습니다. 다음과 같은 클라이언트 재설정 모드를 사용할 수 있습니다.

• 동기화되지 않은 변경 사항 복구 또는 삭제 모드 (기본값): 이 클라이언트 재설정 모드에서 클라이언트 재설정 처리기는 먼저 동기화되지 않은 변경 사항 복구를 시도합니다. 복구가 실패하면 이 핸들러는 동기화되지 않은 로컬 변경 사항을 모두 삭제하는 동기화되지 않은 변경 사항 삭제 모드로 돌아갑니다. 동기화되지 않은 변경 사항 삭제 모드가 실패하면 핸들러는 수동 복구 모드로 돌아갑니다.

• 동기화되지 않은 변경 사항 복구 모드: 이 클라이언트 재설정 모드 에서는 클라이언트 재설정 처리기가 먼저 동기화되지 않은 변경 사항 복구를 시도합니다. 복구가 실패하면 이 핸들러는 수동 복구 모드 로 돌아갑니다.

• 동기화되지 않은 변경 사항 삭제 모드: 이 클라이언트 재설정 모드 는 마지막 동기화 에 성공적인 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제 합니다. 복구가 실패하면 이 핸들러는 수동 복구 모드 로 돌아갑니다.

• 수동 복구 모드: 이 클라이언트 재설정 모드 는 고유한 복구 전략을 구현 수 있는 방법을 제공합니다.

다음 섹션에서는 이러한 클라이언트 재설정 모드를 사용하는 방법에 대해 설명합니다.

자동 및 수동 클라이언트 재설정

Realm SDK는 대부분의 클라이언트 재설정 오류를 자동으로 처리하는 클라이언트 재설정 모드를 제공합니다.

자동 클라이언트 재설정 모드는 영역을 닫거나 알림을 누락하지 않고 로컬 Realm 파일을 동기화 가능한 상태로 복원합니다. The following client reset modes support automatic client resets:

• 동기화되지 않은 변경 사항 복구 모드

• 동기화되지 않은 변경 사항 복구 또는 삭제 모드

• 동기화되지 않은 변경 사항 삭제 모드

이러한 모드의 차이점은 아직 백엔드에 동기화되지 않은 기기의 변경 사항을 처리하는 방법에 따라 달라집니다. 수동 복구 모드만 자동 클라이언트 재설정을 수행하지 않습니다.

동기화되지 않은 변경 사항 복구 모드를 선택하여 대부분의 클라이언트 재설정 시나리오를 자동으로 처리합니다. 이렇게 하면 클라이언트 재설정이 발생할 때 동기화되지 않은 변경 사항을 복구하려고 시도합니다.

앱 에 자동으로 처리할 수 없는 특정 클라이언트 재설정 로직이 필요한 경우 자동 클라이언트 재설정 모드 에 수동 클라이언트 재설정 처리기 를 추가해야 할 수 있습니다.

복구를 통한 클라이언트 재설정

클라이언트 복구는 Realm Mobile Sync를 구성할 때 기본적으로 활성화되는 기능입니다. 클라이언트 복구가 활성화되면 Realm은 대부분의 경우 클라이언트 재설정 프로세스를 managed합니다. 스키마를 변경하면 클라이언트는 스키마 변경이 없는 경우 동기화되지 않은 변경 사항을 복구하거나 깨지지 않는 스키마 변경 사항을 복구할 수 있습니다.

클라이언트 복구를 사용하려면 동기화되지 않은 변경 사항 복구 또는 동기화되지 않은 변경 사항 복구 또는 삭제 클라이언트 재설정 모드로 영역을 구성하세요.

클라이언트 복구가 활성화된 경우 이러한 규칙은 백엔드와 클라이언트가 모두 동일한 객체를 변경할 때 충돌을 해결하는 방법을 포함하여 객체가 통합되는 방식을 결정합니다.

• 로컬에서 생성되었지만 클라이언트 재설정 전에 동기화되지 않은 객체는 동기화됩니다.

• 객체가 서버에서 삭제되었지만 복구 클라이언트에서 수정된 경우 삭제가 우선적으로 적용되고 클라이언트는 업데이트를 삭제합니다.

• 객체가 복구 중인 클라이언트에서는 삭제되고 서버에서는 삭제되지 않는 경우 클라이언트는 서버의 삭제 명령을 적용합니다.

• 동일한 필드에 대한 업데이트가 충돌하는 경우 클라이언트 업데이트가 적용됩니다.

클라이언트 복구 구성에 대한 자세한 내용은 Atlas App Services 문서의 클라이언트 복구 를 참조하세요.

앱이 손상적인 스키마 변경을 수행하는 경우 클라이언트 복구를 수행할 수 없습니다. 단절적 변경은 서버 측 스키마에서 처리할 추가 조치가 필요한 변경 사항입니다. 이 시나리오에서는 클라이언트 재설정을 수동 오류 클라이언트 재설정 폴백으로 대체합니다.

단절적 스키마 변경과 단절적이지 않은 변경에 대한 자세한 내용은 Atlas App Services 문서에서 단절과 단절적이지 않은 변경 비교 빠른 참조 를 참조하세요.

final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: RecoverOrDiscardUnsyncedChangesHandler(
      // All the following callbacks are optional
      onBeforeReset: (beforeResetRealm) {
        // Executed before the client reset begins.
        // Can be used to notify the user that a reset is going
        // to happen.
      },
      onAfterRecovery: (beforeResetRealm, afterResetRealm) {
        // Executed if and only if the automatic recovery has succeeded.
      },
      onAfterDiscard: (beforeResetRealm, afterResetRealm) {
        // Executed if the automatic recovery has failed
        // but the discard unsynced changes fallback has completed
        // successfully.
      },
      onManualResetFallback: (clientResetError) {
        // Automatic reset failed. Handle the reset manually here.
        // Refer to the "Manual Client Reset Fallback" documentation
        // for more information on what you can include here.
      },
    ));

final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: RecoverUnsyncedChangesHandler(
      // All the following callbacks are optional
      onBeforeReset: (beforeResetRealm) {
        // Executed before the client reset begins.
        // Can be used to notify the user that a reset is going
        // to happen.
      },
      onAfterReset: (beforeResetRealm, afterResetRealm) {
        // Executed after the client reset is complete.
        // Can be used to notify the user that the reset is done.
      },
      onManualResetFallback: (clientResetError) {
        // Automatic reset failed. Handle the reset manually here.
        // Refer to the "Manual Client Reset Fallback" documentation
        // for more information on what you can include here.
      },
    ));

동기화되지 않은 변경 사항 삭제 모드

동기화되지 않은 변경 사항 삭제 모드는 마지막 동기화에 성공한 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제합니다. 이 클라이언트 재설정 모드를 사용하기로 선택하면 SDK는 영역을 닫지 않고 알림이 완전히 작동하도록 유지하면서 로컬 영역 파일을 동기화 가능한 상태로 복원합니다. 이 프로세스가 실패하면 수동 복구 모드로 돌아갑니다.

애플리케이션에서 아직 백엔드에 동기화되지 않은 로컬 데이터를 잃을 수 없는 경우 복구 또는 동기화되지 않은 변경 사항 삭제 모드를 사용하지 마세요.

To use discard unsynced changes mode, pass a DiscardUnsyncedChangesHandler callback to the Configure.clientResetHandler. 이 핸들러는 다음과 같은 콜백 메서드를 제공합니다.

• onBeforeReset 클라이언트가 재설정되기 전에 SDK가 호출합니다. 이 콜백을 사용하여 재설정이 시작되기 전에 사용자에게 알릴 수 있습니다.

• onAfterReset 재설정이 성공적으로 완료된 경우에만 SDK가 호출합니다. 재설정이 완료되면 이를 사용하여 사용자에게 알릴 수 있습니다.

• onManualResetFallback, 자동 복구 및 삭제 전략이 실패한 경우에만 SDK가 호출합니다. 수동 복구 섹션에 설명된 대로 재설정 실패를 처리하다 하기 위해 이 콜백 을 구현 합니다.

다음 예제에서는 DiscardUnsyncedChangesHandler 및 각 콜백을 사용하는 방법을 보여 줍니다.

final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: DiscardUnsyncedChangesHandler(
      onBeforeReset: (beforeResetRealm) {
        // Executed before the client reset begins.
        // Can be used to notify the user that a reset is going
        // to happen.
      },
      onAfterReset: (beforeResetRealm, afterResetRealm) {
        // Executed after the client reset is complete.
        // Can be used to notify the user that the reset is done.
      },
      onManualResetFallback: (clientResetError) {
        // Automatic reset failed. Handle the reset manually here.
        // Refer to the "Manual Client Reset Fallback" documentation
        // for more information on what you can include here.
      },
    ));

수동 복구 폴백

복구를 포함한 클라이언트 재설정을 자동으로 완료할 수 없는 경우(예: 손상적인 스키마 변경이 있는 경우) 클라이언트 재설정 프로세스는 수동 오류 처리기에게로 넘어갑니다. 이는 자동 클라이언트 재설정 모드에서 발생할 수 있습니다.

• 동기화되지 않은 변경 사항 복구 모드

• 동기화되지 않은 변경 사항 복구 또는 삭제 모드

• syced되지 않은 변경 사항 삭제 모드

이러한 모드의 경우 클라이언트 재설정 핸들러의 onManualResetFallback 콜백에서 수동 클라이언트 재설정 구현을 제공해야 합니다.

에서 onManualResetFallback 클라이언트 재설정() 콜백 의 ClientResetError 매개변수의 메서드입니다. ClientResetError.resetRealm() 기기에서 영역 을 삭제하고 서버 에서 관련 데이터를 다운로드하여 클라이언트 재설정 을 수행합니다. 이 방법을 사용하기 전에 재설정하려는 영역 의 모든 인스턴스를 닫아야 합니다.

다음 예에서는 동기화되지 않은 모든 변경 사항을 삭제하여 오류 사례를 수동으로 처리하는 방법을 보여줍니다.

// Lazily initialize `realm` so that it can be used in the callback
// before the realm has been opened.
late Realm realm;
final config = Configuration.flexibleSync(currentUser, schema,
    // This example uses the `RecoverOrDiscardUnsyncedChangesHandler`,
    // but the same logic could also be used with the `RecoverUnsyncedChangesHandler`
    // or the `DiscardUnsyncedChangesHandler`.
    clientResetHandler: RecoverOrDiscardUnsyncedChangesHandler(
  onManualResetFallback: (clientResetError) {
    // Prompt user to perform a client reset immediately. If they don't,
    // they won't receive any data from the server until they restart the app
    // and all changes they make will be discarded when the app restarts.
    var didUserConfirmReset = showUserAConfirmationDialog();
    if (didUserConfirmReset) {
      // You must close the Realm before attempting the client reset.
      realm.close();
      // Attempt the client reset.
      try {
        clientResetError.resetRealm();
        // Navigate the user back to the main page or reopen the
        // the Realm and reinitialize the current page.
      } catch (err) {
        // Reset failed.
        // Notify user that they'll need to update the app
      }
    }
  },
));

수동 복구 모드

데이터 복구 프로세스를 사용자 지정해야 하는 드문 경우에는 수동 복구 모드를 사용하세요. 대부분의 경우 클라이언트 재설정에는 다른 전략 중 하나를 사용해야 합니다. 자동 복구 로직이 앱에서 작동하지 않고 동기화되지 않은 로컬 데이터를 삭제할 수 없는 경우 수동 클라이언트 재설정 핸들러를 사용할 수 있습니다.

수동 복구 모드를 사용 하려면 에 Configure.clientResetHandler 콜백합니다.

핸들러 는 다음을 제공합니다. 콜백 을 사용하여 클라이언트 재설정 을 수행할 수 있습니다. 에서 onManualReset ClientResetError.resetRealm() 을 사용하여 클라이언트 재설정 을 시작합니다. 콜백 의 ClientResetError 매개변수의 메서드입니다. ClientResetError.resetRealm() 기기에서 영역 을 삭제하고 서버 에서 관련 데이터를 다운로드하여 클라이언트 재설정 을 수행합니다. 이 방법을 사용하기 전에 재설정하려는 영역 의 모든 인스턴스를 닫아야 합니다.

// Lazily initialize `realm` so that it can be used in the callback
// before the realm has been opened.
late Realm realm;
final config = Configuration.flexibleSync(currentUser, schema,
    clientResetHandler: ManualRecoveryHandler((clientResetError) {
  // You must close the Realm before attempting the client reset.
  realm.close();
  // Handle manual client reset here...
  // Then perform the client reset.
  clientResetError.resetRealm();
}));

클라이언트 재설정 처리 테스트

Device Sync를 종료했다가 다시 활성화하여 애플리케이션의 클라이언트 재설정 처리를 수동으로 테스트할 수 있습니다.

동기화를 종료했다가 다시 허용하면 이전에 동기화로 연결한 클라이언트는 클라이언트 재설정을 수행할 때까지 연결할 수 없습니다. 동기화를 종료하면 클라이언트의 동기화를 허용하는 메타데이터가 서버에서 삭제됩니다. 클라이언트는 서버에서 영역의 새 복사본을 다운로드해야 합니다. 서버는 이러한 클라이언트에 클라이언트 재설정 오류를 보냅니다. 따라서 동기화를 종료하면 trigger 클라이언트 재설정 조건이 됩니다.

클라이언트 재설정 처리를 테스트하려면 다음을 수행합니다.

1. 클라이언트 애플리케이션에서 데이터를 쓰고 동기화될 때까지 기다립니다.

2. Realm Mobile Sync를 종료했다가 다시 활성화합니다.

3. 클라이언트 앱을 다시 실행합니다. 앱이 서버에 연결하려고 할 때 클라이언트 재설정 오류가 발생해야 합니다.