数据的缓存

一、基础概念

• 本地缓存：是指将数据保存在本地存储空间中，能够在关闭应用或页面后继续保留，直到被手动清除或被系统回收。
• uni-app 中提供的本地缓存 API 在小程序、H5、App 等多端表现基本一致。
• 常见用法包括：
  1. 存储用户信息或登录状态。
  2. 存储一些不需要频繁请求后端的数据，如城市列表、字典表等。
  3. 临时保存表单填写进度、草稿等。

二、异步存储 API

2.1 uni.setStorage(OBJECT)

• 功能：将数据存储在本地缓存中指定的 key 中，若该 key 已存在则覆盖旧值。操作是异步的。
• 常见场景：例如在用户登录成功后，将用户信息保存到缓存；在其他页面需要使用时再读取。

用法示例：

uni.setStorage({
  key: 'userInfo',
  data: {
    name: '张三',
    age: 20
  },
  success() {
    console.log('存储成功');
  },
  fail(err) {
    console.error('存储失败:', err);
  },
  complete() {
    console.log('setStorage 调用完成');
  }
});

参数说明：

• key（必填，String）：存储数据对应的键名。
• data（必填，Any）：需要存储的内容，必须是可以被 JSON.stringify 序列化的类型，例如字符串、数字、布尔、对象、数组等。
• success（可选，Function）：接口调用成功的回调函数。
• fail（可选，Function）：接口调用失败的回调函数。
• complete（可选，Function）：接口调用结束的回调函数（无论成功或失败都会执行）。

2.2 uni.getStorage(OBJECT)

• 功能：从本地缓存中异步获取指定 key 对应的内容。
• 常见场景：如在页面加载时读取用户信息，如果缓存存在则直接使用，如果不存在则引导用户登录或请求后端接口。

用法示例：

uni.getStorage({
  key: 'userInfo',
  success: (res) => {
    console.log('读取到的 userInfo:', res.data);
  },
  fail: (err) => {
    console.error('读取失败:', err);
  },
  complete() {
    console.log('getStorage 调用完成');
  }
});

参数说明：

• key（必填，String）：本地缓存中指定的 key。
• success（必填，Function）：成功时的回调，会在回调函数参数 res.data 中返回对应数据。
• fail（可选，Function）：接口调用失败的回调函数。
• complete（可选，Function）：接口调用结束的回调函数（无论成功或失败都会执行）。

在 success 回调的参数对象中，res.data 是获取到的实际数据。如果对应的 key 不存在，可能会走 fail 回调或返回空。

2.3 uni.removeStorage(OBJECT)

• 功能：从本地缓存中异步移除指定 key。
• 常见场景：用户退出登录时，需要移除本地缓存的登录状态或个人信息，保证安全。

用法示例：

uni.removeStorage({
  key: 'userInfo',
  success: () => {
    console.log('已移除 userInfo');
  },
  fail: (err) => {
    console.error('移除失败:', err);
  },
  complete: () => {
    console.log('removeStorage 调用完成');
  }
});

参数说明：

• key（必填，String）：要移除的缓存键。
• success（可选，Function）：接口调用成功的回调函数。
• fail（可选，Function）：接口调用失败的回调函数。
• complete（可选，Function）：接口调用结束的回调函数（无论成功或失败都会执行）。

三、同步存储 API

有时我们需要在页面或组件初始化阶段马上获取数据，或者必须在接下来的逻辑前拿到缓存内容。在这种情况下，异步 API 的回调可能带来不便。为此 uni-app 提供了同步版本的 API，但要注意同步操作可能稍微影响性能，应在必要场景下使用。

3.1 uni.setStorageSync(KEY, DATA)

• 功能：将 data 同步存储到本地缓存中指定的 key。覆盖原有数据。
• 用法示例：

try {
  uni.setStorageSync('userInfo', { name: '李四', age: 25 });
  console.log('同步存储成功');
} catch (e) {
  console.error('同步存储失败', e);
}

参数说明：

• KEY（String）：键名。
• DATA（Any）：可以被序列化的任意类型。

若存储成功则直接执行后续代码，若存储失败会抛出异常，需要在 try-catch 中处理。

3.2 uni.getStorageSync(KEY)

• 功能：同步获取指定 key 的缓存内容。
• 用法示例：

try {
  const userInfo = uni.getStorageSync('userInfo');
  if (userInfo) {
    console.log('获取到的 userInfo:', userInfo);
  } else {
    console.log('暂无 userInfo');
  }
} catch (e) {
  console.error('同步读取失败', e);
}

参数说明：

• KEY（String）：要获取的缓存键名。
• 返回值：若存在该键，则直接返回对应的数据；若获取失败或不存在该键，可能返回空并抛出异常。

3.3 uni.removeStorageSync(KEY)

• 功能：同步移除指定 key。
• 用法示例：

try {
  uni.removeStorageSync('userInfo');
  console.log('同步移除 userInfo 成功');
} catch (e) {
  console.error('移除失败', e);
}

参数说明：

• KEY（String）：要移除的缓存键名。
• 若移除失败会抛出异常，需要 try-catch 捕获处理。

四、注意事项和最佳实践

1. 异步 vs 同步

   • 异步 API (uni.setStorage, uni.getStorage, uni.removeStorage) 更加推荐在日常逻辑中使用。不会阻塞主线程，性能更好。
   • 同步 API (uni.setStorageSync, uni.getStorageSync, uni.removeStorageSync) 适合在必须立即获取结果的场景，如初始化页面必须有缓存数据，或者后续逻辑必须以此作为前提时使用。

2. 存储大小限制

   • 不同平台（App、小程序、H5）对本地存储容量限制不完全相同。通常微信小程序限制在 10MB 左右。若存储空间不足，可能会出现存储失败或者旧数据被系统清理的情况。

3. 存储数据类型

   • 可以存储字符串、数字、布尔值、对象、数组等，只要能够被 JSON.stringify 序列化。
   • 不能存储函数、undefined、循环引用对象等无法被序列化的特殊类型。

4. 异常处理

   • 异步 API 可在 fail 回调里捕获错误；同步 API 建议使用 try-catch，以防止存储或读取失败导致报错。
   • 常见错误可能包括：超出存储限制、设备空间不足、键值冲突等。

5. 有效期和数据更新

   • 若某些数据有时效性，可以自己在存储时加入时间戳或过期时间，取出时判断是否过期，若过期则重新请求数据或删除缓存。

   • 常见实践：

     const now = Date.now();
     const expireTime = now + 1000 * 60 * 60; // 1小时后过期
     uni.setStorageSync('testData', { data: myData, expire: expireTime });
     
     // 读取时判断
     const cache = uni.getStorageSync('testData');
     if (!cache || Date.now() > cache.expire) {
       // 缓存失效，重新请求
     } else {
       // 使用缓存数据
     }
     

6. 集中管理

   • 可以在项目中新建一个 storage.js（或类似名称）的工具文件，封装对缓存的读写逻辑，如 getUserInfo, setUserInfo 等，避免在各页面到处编写重复代码。
   • 有助于后期维护和统一管理缓存的键名、有效期、加解密逻辑等。

7. 平台差异

   • 虽然各个平台（H5、小程序、App）API 名称和参数保持一致，但实际存储位置和最大容量有所区别。
   • 在 H5 中，底层实现可能是 localStorage 或 sessionStorage（由 uni-app 进行封装），需要注意浏览器隐私模式或无痕模式下的限制。