HarmonyOS鸿蒙Next开发者技术支持-通uniapp多端存储方案

HarmonyOS鸿蒙Next开发者技术支持-通uniapp多端存储方案

1.1 问题说明

在uniapp跨平台应用开发中，本地存储作为持久化数据保存的重要手段，广泛应用于用户登录状态、应用配置、缓存数据等场景。然而，不同平台（小程序、H5、App）的存储机制存在差异，如存储容量限制、同步/异步API差异、数据加密要求、存储生命周期管理等问题。直接使用原生存储API（如uni.setStorageSync）会导致代码重复、平台兼容性处理复杂、错误处理不统一、数据安全风险等问题，降低开发效率和代码可维护性。

1.2 原因分析

a. 多端存储API差异显著，兼容代码冗余 小程序、H5、App平台的存储API在同步/异步调用方式、错误处理、存储容量（如小程序10MB限制）、存储生命周期（如小程序清除缓存策略）等方面存在差异，开发者需编写大量平台判断代码。

b. 缺乏统一的数据安全机制 敏感数据（如用户token、个人信息）若直接明文存储，存在泄露风险；不同平台对加密存储的支持程度不同，手动实现加解密逻辑复杂且易出错。

c. 存储操作缺少统一错误处理与监控 存储操作可能因存储空间不足、权限限制、平台差异等原因失败，若未统一处理，可能导致应用状态不一致或崩溃。

d. 数据序列化与反序列化不统一 不同开发者对存储数据格式（如JSON字符串、Base64、直接存储对象）处理方式不一，导致数据读取解析错误或类型转换异常。

缺乏存储生命周期管理 临时缓存与永久存储未明确区分，过期数据未及时清理，可能造成存储空间浪费或脏数据问题。

1.3 解决思路

a. 统一存储接口，封装多端差异 设计统一的存储管理类，对外提供一致的API（如setItem、getItem），内部根据平台调用相应存储接口，屏蔽底层差异。

b. 内置数据安全机制 对敏感数据提供可选的加密存储，默认使用AES加密，并提供安全密钥管理方案；非敏感数据可明文存储以提升性能。

c. 标准化错误处理与日志监控 对所有存储操作进行try-catch封装，统一错误处理逻辑，并支持错误日志上报，便于问题追踪。

d. 统一数据序列化与类型支持 内部统一使用JSON序列化，自动处理对象、数组等复杂类型；支持设置存储过期时间，自动清理过期数据。

e. 分层存储策略与生命周期管理 区分临时缓存（sessionStorage风格）与永久存储（localStorage风格），提供存储空间监控与清理机制。

1.4 解决方案

l 存储管理类设计

// src/utils/storage.js
import CryptoJS from 'crypto-js' // 加密库，需安装

class StorageManager {
  constructor() {
    this.platform = uni.getSystemInfoSync().platform
    this.isEncrypted = true // 默认开启加密
    this.encryptKey = this.getSecureKey() // 安全密钥管理
  }
  // 获取安全密钥（优先从安全存储获取，不存在则生成并保存）
  getSecureKey() {
    let key = uni.getStorageSync('_secure_key')
    if (!key) {
      // 生成随机密钥（实际项目中可根据设备ID等生成）
      key = CryptoJS.lib.WordArray.random(16).toString()
      try {
        uni.setStorageSync('_secure_key', key)
      } catch (e) {
        console.warn('安全密钥存储失败，使用默认密钥', e)
        key = 'default_secure_key_2024' // 降级方案
      }
    }
    return key
  }
  // AES加密
  encrypt(data) {
    if (!this.isEncrypted) return data
    try {
      return CryptoJS.AES.encrypt(JSON.stringify(data), this.encryptKey).toString()
    } catch (e) {
      console.warn('加密失败，返回原始数据', e)
      return data
    }
  }
  // AES解密
  decrypt(cipherText) {
    if (!this.isEncrypted) return cipherText
    try {
      const bytes = CryptoJS.AES.decrypt(cipherText, this.encryptKey)
      const decrypted = bytes.toString(CryptoJS.enc.Utf8)
      return decrypted ? JSON.parse(decrypted) : cipherText
    } catch (e) {
      console.warn('解密失败，返回原始数据', e)
      return cipherText
    }
  }
  // 设置存储（支持过期时间，单位：秒）
  setItem(key, value, expireSeconds = null, encrypt = false) {
    try {
      const data = {
        value,
        _timestamp: Date.now(),
        _expire: expireSeconds ? Date.now() + expireSeconds * 1000 : null,
        _encrypted: encrypt
      }

      // 需要加密的数据单独处理
      let storageValue
      if (encrypt && this.isEncrypted) {
        storageValue = this.encrypt(data)
      } else {
        storageValue = JSON.stringify(data)
      }
      uni.setStorageSync(key, storageValue)
      return true
    } catch (error) {
      console.error(`存储 ${key} 失败:`, error)
      // 存储空间不足时尝试清理过期数据
      if (error.errMsg && error.errMsg.includes('exceed')) {
        this.clearExpired()
        // 重试一次
        try {
          uni.setStorageSync(key, storageValue)
          return true
        } catch (retryError) {
          console.error(`重试存储 ${key} 失败:`, retryError)
        }
      }
      return false
    }
  }

  // 获取存储（自动处理过期和加密）
  getItem(key) {
    try {
      const storageValue = uni.getStorageSync(key)
      if (!storageValue) return null
      // 尝试解析为JSON（非加密数据）
      let data
      try {
        data = JSON.parse(storageValue)
      } catch (e) {
        // 解析失败则尝试解密
        data = this.decrypt(storageValue)
      }
      // 检查数据格式是否有效
      if (!data || typeof data !== 'object') {
        return data // 返回原始值（兼容旧数据）
      }
      // 检查是否过期
      if (data._expire && Date.now() > data._expire) {
        this.removeItem(key)
        return null
      }
      return data.value
    } catch (error) {
      console.error(`读取 ${key} 失败:`, error)
      return null
    }
  }
  // 删除存储
  removeItem(key) {
    try {
      uni.removeStorageSync(key)
      return true
    } catch (error) {
      console.error(`删除 ${key} 失败:`, error)
      return false
    }
  }
  // 清空存储（可选保留白名单）
  clear(whitelist = []) {
    try {
      const { keys } = uni.getStorageInfoSync()
      keys.forEach(key => {
        if (!whitelist.includes(key)) {
          uni.removeStorageSync(key)
        }
      })
      return true
    } catch (error) {
      console.error('清空存储失败:', error)
      return false
    }
  }
  // 清理过期数据
  clearExpired() {
    try {
      const { keys } = uni.getStorageInfoSync()
      keys.forEach(key => {
        // 只检查非系统键（以下划线开头的为系统键）
        if (!key.startsWith('_')) {
          this.getItem(key) // 自动触发过期检查并清理
        }
      })
      return true
    } catch (error) {
      console.error('清理过期数据失败:', error)
      return false
    }
  }
  // 获取存储信息（大小、数量等）
  getStorageInfo() {
    try {
      return uni.getStorageInfoSync()
    } catch (error) {
      console.error('获取存储信息失败:', error)
      return null
    }
  }
}
// 导出单例
export const storage = new StorageManager()

l 在应用中的使用示例

// 在组件或store中使用
import { storage } from '@/utils/storage'
// 存储普通数据
storage.setItem('theme', 'dark')
// 存储敏感数据（自动加密）
storage.setItem('userToken', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', null, true)
// 存储带过期时间的数据（7天）
storage.setItem('cachedData', { list: [1, 2, 3] }, 7 * 24 * 3600)
// 获取数据（自动解密和处理过期）
const token = storage.getItem('userToken')
const theme = storage.getItem('theme')
// 删除数据
storage.removeItem('cachedData')
// 清理所有过期数据
storage.clearExpired()

1.5 总结

a. 问题与痛点： 多端存储API差异大、数据安全风险高、错误处理不统一、缺乏生命周期管理。

b. 技术要点： 统一封装存储接口屏蔽多端差异；内置AES加密保护敏感数据；自动处理数据序列化与过期清理；完善的错误处理与存储监控。

c. 实现效果： 开发者只需调用统一API，无需关心平台差异；敏感数据自动加密存储；过期数据自动清理；存储操作安全可靠。

d. 适用场景： 需要跨平台数据持久化的uniapp项目；对数据安全有要求的应用；需要缓存管理和过期清理的场景；团队协作开发项目。