一、前言

心晴驿站已正式上架华为应用市场，作为纯端侧离线鸿蒙应用，项目全程无云端服务、无网络数据上报，所有用户有效数据均依赖本地存储维护。在上一篇中，我们完成了核心隐私功能——情绪树洞的开发，实现了零留存、零清空、零隐私残留的极致私密效果。

但在产品实际业务中，并非所有数据都需要即时销毁。心理测评记录、情绪状态数据、用户个性化配置等内容，需要安全、稳定、私密的本地留存，同时必须保证用户可自主查看、自主清空、无隐性留存、无隐私泄露风险。

本篇作为系列第八篇，聚焦鸿蒙原生轻量化数据存储体系，针对心晴驿站业务场景，基于官方 Preferences 组件，封装一套高可用、合规、安全、易扩展的全局存储工具。同时实现数据分类隔离、隐私数据防护、一键清空、异常兜底能力，完全适配华为应用市场隐私审核规范，为项目测评记录、个人配置、情绪数据留存提供底层存储支撑。

二、业务存储场景与行业痛点分析

2.1 心晴驿站存储业务划分

结合产品隐私设计规范，我们将项目数据严格分为两大类，采用差异化存储策略，从业务层规避隐私风险：

• 极致隐私数据（无存储）：情绪树洞宣泄内容，全程仅内存临时存储，页面退出立即销毁，不做任何本地持久化；

• 可控留存数据（本地安全存储）：PHQ-9、GAD-7 测评记录、用户情绪偏好、应用基础配置、功能使用记录，仅留存于应用私有目录，用户可自主删除。

2.2 原生存储开发常见痛点

鸿蒙原生开发中，直接使用原生 Preferences 零散调用，极易出现各类问题，也是新手项目上架被驳回的高频原因：

• 代码冗余散乱：页面多处重复初始化存储实例，代码重复、难以统一管控；

• 数据Key混乱：硬编码Key遍布页面，修改维护成本高，极易出现读写不匹配问题；

• 无数据隔离：所有数据混杂存储，敏感数据与普通配置无分层，隐私风险高；

• 无异常兜底：存储初始化失败、数据读取异常、类型不匹配时直接报错，影响应用稳定性；

• 无批量清空能力：无法一键清除用户隐私数据，不符合应用市场隐私合规审核要求。

三、项目存储方案选型与架构设计

3.1 主流存储方案对比选型

结合心晴驿站轻量化、低功耗、小数据量、高隐私的业务特性，对鸿蒙三大主流端侧存储方案做精准选型：

• SQLite 数据库：适合海量结构化数据，本项目仅存储测评记录、基础配置，体量过重，冗余性高，舍弃；

• 文件存储：读写繁琐、安全性低、数据解析复杂，不适合轻量键值对数据，舍弃；

• Preferences 键值存储：鸿蒙官方轻量化存储组件，读写速度快、API简洁、适配小数据场景、私有目录隔离性强，完全匹配项目需求，最终采用。

3.2 分层存储架构设计

为解决原生存储的散乱问题，项目搭建三层标准化存储架构，实现统一管控、分层隔离、合规可控：

1. 常量配置层：统一管理所有存储 Key，杜绝硬编码，全局唯一可控；

2. 工具封装层：封装统一增删改查、批量清空、异常兜底、类型校验方法；

3. 业务调用层：业务页面直接调用工具方法，无需感知底层存储逻辑，实现解耦。

3.3 隐私合规设计准则

所有本地存储逻辑严格遵循三条合规准则，保障顺利过审：

• 数据不出设备：所有存储数据仅留存应用私有目录，无任何云端上传、无数据共享；

• 用户完全可控：支持用户一键清空所有测评、情绪数据，无隐性留存；

• 最小必要存储：仅存储业务必需数据，不采集、不缓存任何冗余用户隐私信息。

四、完整 ArkTS 存储工具落地（上架成品版）

4.1 统一存储 Key 常量管理

新建 constant/store_key.ets，全局统一管理所有存储字段，彻底消灭硬编码，方便后期迭代维护。

/**
 * 全局存储Key常量
 * 统一管理Preferences所有读写字段，杜绝硬编码
 * 适配测评数据、用户配置、情绪记录存储
 */
export default class StoreKey {
  // 测评相关数据
  static readonly PHQ9_SCORE: string = 'phq9_score'
  static readonly GAD7_SCORE: string = 'gad7_score'
  static readonly TEST_LEVEL: string = 'test_level'
  static readonly TEST_DESC: string = 'test_desc'

  // 应用基础配置
  static readonly FIRST_ENTER: string = 'first_enter'
  static readonly SOUND_SWITCH: string = 'sound_switch'
}

4.2 全局 Preferences 工具类封装

新建 utils/store_utils.ets，封装初始化、存值、取值、删除单条、清空全部五大核心能力，内置 try-catch 全局异常兜底，保障存储稳定性。

/**
 * 全局Preferences轻量化存储工具
 * 心晴驿站上架正式版本
 * 统一封装、异常兜底、隐私可控、支持批量清空
 */
import preferences from '@ohos.data.preferences'
import common from '@ohos.app.ability.common'

// 存储实例名称
const STORE_NAME: string = 'xinqing_store'
let dataPreferences: preferences.Preferences | null = null

/**
 * 初始化存储实例
 */
export async function initPreferences(context: common.UIAbilityContext) {
  try {
    dataPreferences = await preferences.getPreferences(context, STORE_NAME)
  } catch (err) {
    console.error('存储初始化失败：', JSON.stringify(err))
  }
}

/**
 * 存储数据
 * @param key 存储键名
 * @param value 存储值
 */
export async function setStoreData(key: string, value: preferences.ValueType) {
  if (!dataPreferences) return
  try {
    await dataPreferences.put(key, value)
    await dataPreferences.flush()
  } catch (err) {
    console.error('数据存储失败：', JSON.stringify(err))
  }
}

/**
 * 获取存储数据
 * @param key 存储键名
 * @param defaultValue 默认值
 * @returns 对应存储值
 */
export async function getStoreData<T>(key: string, defaultValue: T): Promise<T> {
  if (!dataPreferences) return defaultValue
  try {
    return await dataPreferences.get(key, defaultValue) as T
  } catch (err) {
    console.error('数据读取失败：', JSON.stringify(err))
    return defaultValue
  }
}

/**
 * 删除单条存储数据
 * @param key 存储键名
 */
export async function deleteStoreData(key: string) {
  if (!dataPreferences) return
  try {
    await dataPreferences.delete(key)
    await dataPreferences.flush()
  } catch (err) {
    console.error('数据删除失败：', JSON.stringify(err))
  }
}

/**
 * 一键清空所有存储数据（隐私合规核心能力）
 */
export async function clearAllStoreData() {
  if (!dataPreferences) return
  try {
    await dataPreferences.clear()
    await dataPreferences.flush()
  } catch (err) {
    console.error('清空存储失败：', JSON.stringify(err))
  }
}
    

4.3 应用全局初始化存储

在项目入口 Ability 中完成存储全局初始化，保证全应用生命周期可正常读写数据，无需重复创建实例。

/**
 * EntryAbility 全局初始化存储
 */
import UIAbility from '@ohos.app.ability.UIAbility'
import hilog from '@ohos.hilog'
import type AbilityConstant from '@ohos.app.ability.AbilityConstant'
import type Want from '@ohos.app.ability.Want'
import { initPreferences } from '../utils/store_utils'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    // 全局初始化本地存储
    initPreferences(this.context)
    hilog.info(0x0000, 'STORE_INIT', '心晴驿站本地存储初始化完成')
  }
}
    

五、业务场景实战调用

结合项目测评核心业务，演示数据存储、读取、清空的完整实战用法，贴合上架版本真实业务逻辑。

5.1 测评结果数据存储

用户完成 PHQ-9/GAD-7 测评后，自动保存分数、测评等级、情绪描述数据。

import { setStoreData } from '../utils/store_utils'
import StoreKey from '../constant/store_key'

// 保存测评结果
async function saveTestResult(score: number, level: string, desc: string) {
  await setStoreData(StoreKey.PHQ9_SCORE, score)
  await setStoreData(StoreKey.TEST_LEVEL, level)
  await setStoreData(StoreKey.TEST_DESC, desc)
}
    

5.2 读取历史测评数据

个人中心页面读取本地历史测评记录，渲染用户情绪轨迹数据。

import { getStoreData } from '../utils/store_utils'
import StoreKey from '../constant/store_key'

// 获取历史测评数据
async function getTestRecord() {
  const score = await getStoreData<number>(StoreKey.PHQ9_SCORE, 0)
  const level = await getStoreData<string>(StoreKey.TEST_LEVEL, '暂无测评记录')
  const desc = await getStoreData<string>(StoreKey.TEST_DESC, '暂无描述')
  return { score, level, desc }
}

5.3 一键清空隐私数据（合规核心）

用户在设置页面可主动清空所有本地测评、配置数据，完全掌控个人隐私数据。

import { clearAllStoreData } from '../utils/store_utils'

// 一键清空所有本地数据
async function clearAllUserPrivateData() {
  await clearAllStoreData()
}
    

六、存储架构核心优势与上架合规亮点

6.1 架构规范、低耦合易维护

通过常量+工具类双层封装，彻底解耦业务与存储逻辑，页面无需关注存储底层实现，新增存储字段仅需新增 Key 常量即可，迭代效率极高。

6.2 全局异常兜底，稳定性拉满

所有存储方法内置 try-catch 异常捕获，杜绝存储初始化失败、读写异常导致的页面闪退、功能失效问题，完全满足上架稳定性要求。

6.3 隐私合规完全达标

支持用户主动一键清空所有隐私数据，无隐性留存、无自动上传、无后台缓存，完全匹配华为应用市场《隐私数据最小化留存》规范，是项目顺利过审的关键能力。

6.4 轻量化低功耗

基于官方轻量化 Preferences 组件，无冗余依赖、无过度性能消耗，读写速度快、内存占用低，贴合项目轻量化产品定位。

七、开发踩坑复盘（上架避坑）

7.1 存储未全局初始化导致读写失效

问题：初期在页面内局部初始化 Preferences，多次页面跳转后实例失效，数据读写失败。

解决：迁移至 EntryAbility 全局初始化，应用生命周期内唯一实例，全程稳定可用。

7.2 未执行 flush 导致数据不落地

问题：调用 put 存值后未执行 flush，应用重启后数据丢失。

解决：封装方法内置强制 flush，保证数据实时持久化落地。

7.3 无默认值导致读取报错

问题：首次启动应用无缓存数据，读取 null 导致页面渲染异常。

解决：统一封装默认值兜底，空数据场景正常适配，无报错闪退。

7.4 无批量清空能力导致合规不通过

问题：初期仅支持单条删除，无一键清空功能，不符合隐私合规要求，存在上架驳回风险。

解决：新增全局清空方法，用户可自主清除所有隐私数据，完全合规。

八、本篇总结与下篇预告

本篇我们完整落地了鸿蒙端侧轻量化、合规化本地存储体系，基于 ArkTS 封装全局 Preferences 工具类，实现了数据统一读写、异常兜底、批量清空、隐私隔离的完整能力。同时区分了项目极致隐私数据与可控留存数据的存储策略，完美契合心晴驿站「高隐私、纯离线、轻量化」的产品定位，彻底解决本地存储散乱、数据不安全、合规不达标等核心问题。

至此，项目的架构、路由、UI组件、核心隐私功能、本地存储五大底层能力全部搭建完成，项目基础底座完全成熟。

下篇预告（第九篇）：心理测评模块全流程实战，从零实现 PHQ-9/GAD-7 双量表答题、实时计分、情绪评级、结果本地化留存完整业务功能，落地项目核心测评业务闭环。