应用数据持久化，是指应用将内存中的数据通过文件或数据库的形式保存到设备上。内存中的数据形态通常是任意的数据结构或数据对象，存储介质上的数据形态可能是文本、数据库、二进制文件等。

HarmonyOS标准系统支持典型的存储数据形态，包括用户首选项、键值型数据库、关系型数据库。

开发者可以根据如下功能介绍，选择合适的数据形态以满足自己应用数据的持久化需要。

• 用户首选项（Preferences）：通常用于保存应用的配置信息。数据通过文本的形式保存在设备中，应用使用过程中会将文本中的数据全量加载到内存中，所以访问速度快、效率高，但不适合需要存储大量数据的场景。

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

• 关系型数据库（RelationalStore）：一种关系型数据库，以行和列的形式存储数据，广泛用于应用中的关系型数据的处理，包括一系列的增、删、改、查等接口，开发者也可以运行自己定义的SQL语句来满足复杂业务场景的需要。

通过用户首选项实现数据持久化

约束限制

• 首选项无法保证进程并发安全，会有文件损坏和数据丢失的风险，不支持在多进程场景下使用。

• Key键为string类型，要求非空且长度不超过1024个字节。

• 如果Value值为string类型，请使用UTF-8编码格式，可以为空，不为空时长度不超过16 * 1024 * 1024个字节。

• 内存会随着存储数据量的增大而增大，所以存储的数据量应该是轻量级的，建议存储的数据不超过一万条，否则会在内存方面产生较大的开销。

• 接口说明

• 以下是用户首选项持久化功能的相关接口，更多接口及使用方式请见用户首选项。

• 接口名称	描述
  getPreferencesSync(context: Context, options: Options): Preferences	获取Preferences实例。该接口存在异步接口。
  putSync(key: string, value: ValueType): void	将数据写入Preferences实例，可通过flush将Preferences实例持久化。该接口存在异步接口。
  hasSync(key: string): boolean	检查Preferences实例是否包含名为给定Key的存储键值对。给定的Key值不能为空。该接口存在异步接口。
  getSync(key: string, defValue: ValueType): ValueType	获取键对应的值，如果值为null或者非默认值类型，返回默认数据defValue。该接口存在异步接口。
  deleteSync(key: string): void	从Preferences实例中删除名为给定Key的存储键值对。该接口存在异步接口。
  flush(callback: AsyncCallback<void>): void	将当前Preferences实例的数据异步存储到用户首选项持久化文件中。
  on(type: 'change', callback: Callback<string>): void	订阅数据变更，订阅的数据发生变更后，在执行flush方法后，触发callback回调。
  off(type: 'change', callback?: Callback<string>): void	取消订阅数据变更。
  deletePreferences(context: Context, options: Options, callback: AsyncCallback<void>): void	从内存中移除指定的Preferences实例。若Preferences实例有对应的持久化文件，则同时删除其持久化文件。

• 封装的代码如下：

• import preferences from '@ohos.data.preferences'
  import { JSON } from '@kit.ArkTS'
  import { BusinessError } from '@kit.BasicServicesKit'
  
  const TAG: string = 'PreferencesUtil'
  
  /**
   * 用户持久化工具类封装
   *
   * @author weipeng
   * @since 2025-01-04
   */
  class PreferencesUtil {
    prefMap: Map<string, preferences.Preferences> = new Map
  
    async loadPreference(context: Context, name: string) {
      try {
        // 加载preferences
        let pref = await preferences.getPreferences(context, name)
        this.prefMap.set(name, pref)
        console.log(TAG, `加载Preferences[${name}]成功`)
      } catch (exception) {
        console.log(TAG, `加载Preferences[${name}]失败`, JSON.stringify(exception))
      }
    }
  
    async putPreferencesValue(name: string, key: string, value: preferences.ValueType) {
      let pref = this.prefMap.get(name)
      if (!pref) {
        console.log(TAG, `Preferences[${name}]尚未初始化!`)
        return
      }
      try {
        // 写入数据
        await pref.put(key, value)
        // 刷盘
        await pref.flush()
        console.log(TAG, `保存Preferences[${name}.${key} = ${value}]成功`)
      } catch (exception) {
        console.log(TAG, `保存Preferences[${name}.${key} = ${value}]失败`, JSON.stringify(exception))
      }
    }
  
    async getPreferencesValue(name: string, key: string, defaultValue: preferences.ValueType) {
      let pref = this.prefMap.get(name)
      if (!pref) {
        console.log(TAG, `Preferences[${name}]尚未初始化!`)
        return
      }
      try {
        // 读数据
        let value = await pref.get(key, defaultValue)
        console.log(TAG, `获取Preferences[${name}.${key} = ${value}]成功`)
      } catch (exception) {
        console.log(TAG, `获取Preferences[${name}.${key} ]失败`, JSON.stringify(exception))
      }
    }
  
    deletePreferencesKeyValue(name: string, key: string) {
      let pref = this.prefMap.get(name)
      if (!pref) {
        console.log(TAG, `Preferences[${name}]尚未初始化!`)
        return
      }
      try {
        // 删除指定键值对
        let value = pref.deleteSync(key)
        console.log(TAG, `删除Preferences[${name}.${key} = ${value}]成功`)
      } catch (exception) {
        console.log(TAG, `删除Preferences[${name}.${key} ]失败`, JSON.stringify(exception))
      }
    }
  
    deletePreferences(context: Context, name: string) {
      preferences.deletePreferences(context, name, (err: BusinessError) => {
        if (err) {
          console.error(TAG, `Failed to delete preferences. Code:${err.code}, message:${err.message}`)
          return
        }
        console.info(TAG, 'Succeeded in deleting preferences.')
        this.prefMap.delete(name)
      })
    }
  }
  
  const preferencesUtil: PreferencesUtil = new PreferencesUtil()
  
  export default preferencesUtil as PreferencesUtil

通过关系型数据库实现数据持久化

场景介绍

关系型数据库基于SQLite组件，适用于存储包含复杂关系数据的场景，比如一个班级的学生信息，需要包括姓名、学号、各科成绩等，又或者公司的雇员信息，需要包括姓名、工号、职位等，由于数据之间有较强的对应关系，复杂程度比键值型数据更高，此时需要使用关系型数据库来持久化保存数据。

大数据量场景下查询数据可能会导致耗时长甚至应用卡死，如有相关操作可参考文档批量数据写数据库场景，且有建议如下：

运作机制

关系型数据库对应用提供通用的操作接口，底层使用SQLite作为持久化存储引擎，支持SQLite具有的数据库特性，包括但不限于事务、索引、视图、触发器、外键、参数化查询和预编译SQL语句。

图1 关系型数据库运作机制

• 单次查询数据量不超过5000条。
• 在TaskPool中查询。
• 拼接SQL语句尽量简洁。
• 合理地分批次查询。

• 基本概念

• 谓词：数据库中用来代表数据实体的性质、特征或者数据实体之间关系的词项，主要用来定义数据库的操作条件。

• 结果集：指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便地拿到用户想要的数据。

约束限制

系统默认日志方式是WAL（Write Ahead Log）模式，系统默认落盘方式是FULL模式。

数据库中有4个读连接和1个写连接，线程获取到空闲读连接时，即可进行读取操作。当没有空闲读连接且有空闲写连接时，会将写连接当做读连接来使用。

为保证数据的准确性，数据库同一时间只能支持一个写操作。

当应用被卸载完成后，设备上的相关数据库文件及临时文件会被自动清除。

接口说明

以下是关系型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见关系型数据库。

接口名称	描述
getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<RdbStore>): void	获得一个RdbStore，操作关系型数据库，用户可以根据自己的需求配置RdbStore的参数，然后通过RdbStore调用相关接口可以执行相关的数据操作。
executeSql(sql: string, bindArgs: Array<ValueType>, callback: AsyncCallback<void>):void	执行包含指定参数但不返回值的SQL语句。
insert(table: string, values: ValuesBucket, callback: AsyncCallback<number>):void	向目标表中插入一行数据。
update(values: ValuesBucket, predicates: RdbPredicates, callback: AsyncCallback<number>):void	根据predicates的指定实例对象更新数据库中的数据。
delete(predicates: RdbPredicates, callback: AsyncCallback<number>):void	根据predicates的指定实例对象从数据库中删除数据。
query(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void	根据指定条件查询数据库中的数据。
deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void	删除数据库。

• • ArkTS侧支持的基本数据类型：number、string、二进制类型数据、boolean。

  • 为保证插入并读取数据成功，建议一条数据不要超过2M。超出该大小，插入成功，读取失败。

  • 封装的代码如下：

  • bean：

  • @Observed
    export default  class TaskInfo {
      id: number
      name: string
      finished: boolean
    
      constructor(id: number, name: string) {
        this.id = id
        this.name = name
        this.finished = false
      }
    }

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

const TAG: string = 'DbUtil'

/**
 * 关系型DB工具类封装
 *
 * @author weipeng
 * @since 2025-01-04
 */
class DbUtil {
  private rgbStore: relationalStore.RdbStore | undefined
  private tableName:string = 'TASK'

  initDb(context: Context) {
    // 1、rdb配置
    // customDir: 'customDir/subCustomDir', // 可选参数，数据库自定义路径。数据库将在如下的目录结构中被创建
    // context.databaseDir + '/rdb/' + customDir，其中context.databaseDir是应用沙箱对应的路径，
    // '/rdb/'表示创建的是关系型数据库，customDir表示自定义的路径。当此参数不填时，默认在本应用沙箱目录下创建RdbStore实例。
    const config: relationalStore.StoreConfig = {
      name: 'wp.db', // 数据库文件名
      securityLevel: relationalStore.SecurityLevel.S1, // 数据库安全级别
      encrypt: false, // 可选参数，指定数据库是否加密，默认不加密
      isReadOnly: false // 可选参数，指定数据库是否以只读方式打开。该参数默认为false，表示数据库可读可写
    }

    // 2、建表Sql语句, IDENTITY为bigint类型，sql中指定类型为UNLIMITED INT
    const sql = `CREATE TABLE IF NOT EXISTS TASK (ID INTEGER PRIMARY KEY AUTOINCREMENT
       NAME TEXT NOT NULL, FINISHED bit)`;

    // 3、获取rgb
    relationalStore.getRdbStore(context, config, (err, rgbStore) => {
      if (err) {
        console.log(TAG, '获取rgbStore失败')
        return
      }
      // 执行sql
      rgbStore.executeSql(sql)
      console.log(TAG, '创建task表成功！')
      // 保存rgbStore
      this.rgbStore = rgbStore
    })
  }

  /**
   * 查询
   */
  async getTaskList() {
    // 1、构建查询条件
    let predicates = new relationalStore.RdbPredicates(this.tableName)
    // 2、查询
    let result = await this.rgbStore?.query(predicates, ['ID', 'NAME', 'FINISHED'])
    // 3、解析查询结果
    // 3.1 定义一个数组，组装最终的查询结果
    let tasks: TaskInfo[] = []
    // 3.2 遍历封装
    while(!result?.isAtLastRow) {
      // 3.3 指针移动到下一行
      result?.goToNextRow()
      let id = result?.getLong(result.getColumnIndex('ID')) as number
      let name = result?.getString(result.getColumnIndex('NAME'))
      let finished = result?.getLong(result.getColumnIndex('FINISHED'))
      // 3.4 封装到数组
      tasks.push(new TaskInfo(id, ''))
    }
    return tasks
  }
}