鸿蒙开发——键值型数据库的基本使用与跨设备同步

1、简 述

❓ 什么是键值型数据库

键值型数据库（KV-Store）是一种非关系型数据库，其数据以“键值”对的形式进行组织、索引和存储，其中“键”作为唯一标识符。 键值型数据库适合很少数据关系和业务关系的业务数据存储。 另外，因键值型数据库在分布式场景中降低了解决数据库版本兼容问题的复杂度，和数据同步过程中冲突解决的复杂度而被广泛使用。相比于关系型数据库，更容易做到跨设备跨版本兼容。

当需要存储的数据没有复杂的关系模型，比如存储商品名称及对应价格、员工工号及今日是否已出勤等，由于数据复杂度低，更容易兼容不同数据库版本和设备类型，因此推荐使用键值型数据库持久化此类数据。

📢 使用键值型数据库时，需要注意以下几点：

• 设备协同数据库，针对每条记录，Key的长度≤896 Byte，Value的长度<4 MB。

• 单版本数据库，针对每条记录，Key的长度≤1 KB，Value的长度<4 MB。

• 每个应用程序最多支持同时打开16个键值型分布式数据库。

• 键值型数据库事件回调方法中不允许进行阻塞操作，例如修改UI组件。

• 单个数据库最多支持注册8个订阅数据变化的回调。

• 键值型数据库不支持应用程序自定义冲突解决策略。

2、键值型数据库的基本使用

键值型数据库的能力主要是由 @ohos.data.distributedKVStore 模块提供，实现不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口，应用程序可将数据保存到分布式键值数据库中，并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。

该模块提供以下分布式键值数据库相关的常用功能：

• KVManager：分布式键值数据库管理实例，用于获取数据库的相关信息。

• KVStoreResultSet：提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。

• Query：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。

• SingleKVStore：单版本分布式键值数据库，不对数据所属设备进行区分，提供查询数据和同步数据的方法。

• DeviceKVStore：设备协同数据库，继承自SingleKVStore，以设备维度对数据进行区分，提供查询数据和同步数据的方法。

以下是键值型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下面均以callback形式为例：

// 创建一个KVManager对象实例，用于管理数据库对象。
createKVManager(config: KVManagerConfig): KVManager

// 指定options和storeId，创建并得到指定类型的KVStore数据库。
getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void

// 添加指定类型的键值对到数据库。
put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void

// 获取指定键的值。
get(key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void

// 从数据库中删除指定键值的数据。
delete(key: string, callback: AsyncCallback<void>): void

// 通过storeId的值关闭指定的分布式键值数据库。
closeKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void

// 通过storeId的值删除指定的分布式键值数据库。
deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void

使用示例

👉🏻 step 1：若要使用键值型数据库，首先要获取一个KVManager实例，用于管理数据库对象。示例代码如下所示（代码13 ~ 25行）：

// 导入模块
import { distributedKVStore } from '@kit.ArkData';

import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let kvManager: distributedKVStore.KVManager | undefined = undefined;

export default class EntryAbility extends UIAbility {
  onCreate() {
    let context = this.context;
    const kvManagerConfig: distributedKVStore.KVManagerConfig = {
      context: context,
      bundleName: 'com.example.datamanagertest'
    };
    try {
      // 创建KVManager实例
      kvManager = distributedKVStore.createKVManager(kvManagerConfig);
      console.info('Succeeded in creating KVManager.');
      // 继续创建获取数据库
    } catch (e) {
      let error = e as BusinessError;
      console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
    }
  }
}
if (kvManager !== undefined) {
   kvManager = kvManager as distributedKVStore.KVManager;
  //进行后续操作
  //...
}

👉🏻 step 2：基于step 1创建的kvManager，我们可以创建并获取键值数据库。示例代码如下所示：

let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;
try {
  const options: distributedKVStore.Options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: false,
    // kvStoreType不填时，默认创建多设备协同数据库
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    // 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
    securityLevel: distributedKVStore.SecurityLevel.S1
  };
  kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => {
    if (err) {
      console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in getting KVStore.');
    kvStore = store;
    // 请确保获取到键值数据库实例后，再进行相关数据操作
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}
if (kvStore !== undefined) {
  kvStore = kvStore as distributedKVStore.SingleKVStore;
    //进行后续操作
    //...
}

👉🏻 基于step 2创建的kvStore对象，我们可以调用put()方法向键值数据库中插入数据。示例代码如下所示：

const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value_test_string';
try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}

👉🏻 基于step 2创建的kvStore对象，我们调用get()方法获取指定键的值。示例代码如下所示：

try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
    kvStore = kvStore as distributedKVStore.SingleKVStore;
    kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => {
      if (err != undefined) {
        console.error(`Failed to get data. Code:${err.code},message:${err.message}`);
        return;
      }
      console.info(`Succeeded in getting data. Data:${data}`);
    });
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to get data. Code:${error.code},message:${error.message}`);
}

👉🏻 基于step 2创建的kvStore对象，我们调用delete()方法删除指定键值的数据。示例代码如下所示：

try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
    kvStore = kvStore as distributedKVStore.SingleKVStore;
    kvStore.delete(KEY_TEST_STRING_ELEMENT, (err) => {
      if (err !== undefined) {
        console.error(`Failed to delete data. Code:${err.code},message:${err.message}`);
        return;
      }
      console.info('Succeeded in deleting data.');
    });
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}

👉🏻 基于step 1创建的kvManager对象，我们通过storeId的值关闭指定的分布式键值数据库。示例代码如下所示：

try {
  kvStore = undefined;
  kvManager.closeKVStore('appId', 'storeId', (err: BusinessError)=> {
    if (err) {
      console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info('Succeeded in closing KVStore');
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}

👉🏻 基于step 1创建的kvManager对象，我们通过storeId的值删除指定的分布式键值数据库。示例代码如下所示：

try {
  kvStore = undefined;
  kvManager.deleteKVStore('appId', 'storeId', (err: BusinessError)=> {
    if (err) {
      console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info('Succeeded in closing KVStore');
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}

3、键值型数据库跨设备数据同步

数据管理服务提供了两种同步方式：手动同步和自动同步。键值型数据库可选择其中一种方式实现同应用跨设备数据同步。

手动同步

由应用程序调用sync接口来触发，需要指定同步的设备列表和同步模式。同步模式分为：

• PULL_ONLY（将远端数据拉取到本端）；

• PUSH_ONLY（将本端数据推送到远端）；

• PUSH_PULL（将本端数据推送到远端同时也将远端数据拉取到本端）。

自动同步

在跨设备Call调用实现的多端协同场景中，在应用程序更新数据后，由分布式数据库自动将本端数据推送到远端，同时也将远端数据拉取到本端来完成数据同步，应用不需要主动调用sync接口。

键值型数据库分为两种类型：单版本数据库、多设备协同分布式数据库。两种类型介绍如下：

• 单版本数据库

单版本是指数据在本地是以单个条目为单位的方式保存，当数据在本地被用户修改时，不管它是否已经被同步出去，均直接在这个条目上进行修改。

多个设备全局只保留一份数据，多个设备的相同记录（主码相同）会按时间最新保留一条记录，数据不分设备，设备之间修改相同的key会覆盖。同步也以此为基础，按照它在本地被写入或更改的顺序将当前最新一次修改逐条同步至远端设备，常用于联系人、天气等应用存储场景。

• 多设备协同分布式数据库

多设备协同分布式数据库建立在单版本数据库之上，对应用程序存入的键值型数据中的Key前面拼接了本设备的DeviceID标识符，这样能保证每个设备产生的数据严格隔离。数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。

底层按照设备的维度管理这些数据，多设备协同数据库支持以设备的维度查询分布式数据，但是不支持修改远端设备同步过来的数据。需要分开查询各设备数据的可以使用设备协同版本数据库。常用于图库缩略图存储场景。

以下是单版本键值型分布式数据库跨设备数据同步功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下面均以callback形式为例。

// 创建一个KVManager对象实例，用于管理数据库对象。
createKVManager(config: KVManagerConfig): KVManager

// 指定options和storeId，创建并得到指定类型的KVStore数据库。
getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void

// 插入和更新数据。
put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void

// 订阅数据库中数据的变化。
on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void

// 查询指定Key键的值。
get(key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void

// 在手动模式下，触发数据库同步。
sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void

使用分布式键值数据库需要申明权限：ohos.permission.DISTRIBUTED_DATASYNC，同时需要在应用首次启动时弹窗向用户申请授权

👉🏻 step 1：根据配置构造分布式数据库管理实例

import { distributedKVStore } from '@kit.ArkData';
import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let kvManager: distributedKVStore.KVManager | undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage:window.WindowStage) {
    let context = this.context;
  }
}
 
// .... 
// 获取context之后，构造分布式数据库管理类实例
try {
  const kvManagerConfig: distributedKVStore.KVManagerConfig = {
    bundleName: 'com.harmonyclassroom.datamanagertest',
    context: context
  }
  kvManager = distributedKVStore.createKVManager(kvManagerConfig);
  console.info('Succeeded in creating KVManager.');
  // todo 继续创建获取数据库
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
}

if (kvManager !== undefined) {
  kvManager = kvManager as distributedKVStore.KVManager;
  // 进行后续创建数据库等相关操作
  // ...
}

👉🏻 step 2：获取并得到指定类型的键值型数据库。

1. 声明需要创建的分布式数据库ID描述（例如示例代码中的'storeId'）。

2. 创建分布式数据库，建议关闭自动同步功能（autoSync:false），方便后续对同步功能进行验证，需要同步时主动调用sync接口。

let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;
try {
  let child1 = new distributedKVStore.FieldNode('id');
  child1.type = distributedKVStore.ValueType.INTEGER;
  child1.nullable = false;
  child1.default = '1';
  let child2 = new distributedKVStore.FieldNode('name');
  child2.type = distributedKVStore.ValueType.STRING;
  child2.nullable = false;
  child2.default = 'zhangsan';

  let schema = new distributedKVStore.Schema();
  schema.root.appendChild(child1);
  schema.root.appendChild(child2);
  schema.indexes = ['$.id', '$.name'];
  // 0表示COMPATIBLE模式，1表示STRICT模式。
  schema.mode = 1;
  // 支持在检查Value时，跳过skip指定的字节数，且取值范围为[0,4M-2]。
  schema.skip = 0;

  const options: distributedKVStore.Options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: false,
    // kvStoreType不填时，默认创建多设备协同数据库
    // 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    // schema 可以不填，在需要使用schema功能时可以构造此参数，例如：使用谓词查询等。
    schema: schema,
    securityLevel: distributedKVStore.SecurityLevel.S1
  };
  kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => {
    if (err) {
      console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in getting KVStore.');
    kvStore = store;
    // 请确保获取到键值数据库实例后，再进行相关数据操作
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}
if (kvStore !== undefined) {
  kvStore = kvStore as distributedKVStore.SingleKVStore;
    // 进行后续相关数据操作，包括数据的增、删、改、查、订阅数据变化等操作
    // ...
}

👉🏻 step 3：订阅分布式数据变化

如需关闭订阅分布式数据变化，调用off('dataChange')关闭。

try {
  kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
    console.info(`dataChange callback call data: ${data}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. code:${error.code},message:${error.message}`);
}

👉🏻 step 4：将数据写入分布式数据库。

1. 构造需要写入分布式数据库的Key（键）和Value（值）。

2. 将键值数据写入分布式数据库。

const KEY_TEST_STRING_ELEMENT = 'key_test_string';
// 如果未定义Schema则Value可以传其他符合要求的值。
const VALUE_TEST_STRING_ELEMENT = '{"id":0, "name":"lisi"}';
try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}

👉🏻 step 5：查询分布式数据库数据。

1. 构造需要从单版本分布式数据库中查询的Key（键）。

2. 从单版本分布式数据库中获取数据

try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
    kvStore = kvStore as distributedKVStore.SingleKVStore;
    kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => {
      if (err != undefined) {
        console.error(`Failed to get data. Code:${err.code},message:${err.message}`);
        return;
      }
      console.info(`Succeeded in getting data. Data:${data}`);
    });
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to get data. Code:${error.code},message:${error.message}`);
}

👉🏻 step 6：同步数据到其他设备。

选择同一组网环境下的设备以及同步模式（需用户在应用首次启动的弹窗中确认选择同步模式），进行数据同步。

import { distributedDeviceManager } from '@kit.DistributedServiceKit';
 
let devManager: distributedDeviceManager.DeviceManager;
try {
  // create deviceManager
  devManager = distributedDeviceManager.createDeviceManager(context.applicationInfo.name);
  // deviceIds由deviceManager调用getAvailableDeviceListSync方法得到
  let deviceIds: string[] = [];
  if (devManager != null) {
    let devices = devManager.getAvailableDeviceListSync();
    for (let i = 0; i < devices.length; i++) {
      deviceIds[i] = devices[i].networkId as string;
    }
  }
  try {
    // 1000表示最大延迟时间为1000ms
    kvStore.sync(deviceIds, distributedKVStore.SyncMode.PUSH_ONLY, 1000);
  } catch (e) {
    let error = e as BusinessError;
    console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
  }

} catch (err) {
  let error = err as BusinessError;
  console.error("createDeviceManager errCode:" + error.code + ",errMessage:" + error.message);
}

在手动同步的方式下，其中的deviceIds通过调用devManager.getAvailableDeviceListSync方法得到。