更新记录

1.0.0（2026-07-20）

新增

• 首次发布，基于 mh-request 的智能请求缓存插件
• 支持内存（memory）和本地持久化（storage）双存储引擎
• 支持缓存有效期（cacheTime）和陈旧数据刷新策略（staleTime），过期数据先返回再后台更新
• 内置 LRU 淘汰策略，缓存超限时自动清理最久未使用条目
• 支持自定义缓存键生成函数，适应复杂业务场景
• 提供完整的缓存管理接口：clear()、stats()、get()、set()
• 默认仅缓存 GET 请求，支持 enableMethods 灵活配置
• 异步刷新并发控制，相同缓存键同时只刷新一次，避免重复请求

平台兼容性

uni-app(3.8.0)

uni-app x(3.8.0)

mh-request-cache

基于 mh-request 的智能请求缓存插件，通过拦截重复请求并缓存响应数据，显著降低网络请求次数、提升页面加载速度与用户体验。

本插件是 mh-request 的配套插件，需配合使用。

特性

• 💾 双存储引擎：支持内存缓存（极速）和本地持久化（跨会话保留）两种模式
• ⏳ 智能过期策略：通过 cacheTime 控制有效期，过期后自动失效
• 🔄 陈旧数据刷新策略：配置 staleTime 后，过期数据先返回旧内容，后台异步静默更新，用户无需等待
• 🗑️ LRU 自动淘汰：缓存数量超限时自动清理最久未使用的条目，内存可控
• 🎯 精准缓存控制：默认仅缓存 GET 请求，支持自定义缓存方法列表
• 🔑 灵活键生成：内置基于 URL + 参数排序的键生成器，支持完全自定义
• 🛠️ 管理接口：提供 clear()、stats() 等便捷方法，随时查看和清理缓存
• 🔌 即插即用：作为 mh-request 插件，一行代码集成，无需改动业务逻辑

快速开始

引入插件

import { Request } from '@/uni_modules/mh-request'
import { cachePlugin } from '@/uni_modules/mh-request-cache'

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: cachePlugin,
      config: {
        cacheTime: 5 * 60 * 1000,   // 缓存有效期 5 分钟
        staleTime: 60 * 1000,       // 过期后 1 分钟内仍返回旧数据，后台异步刷新
        cacheCapacity: 50,
        storageType: 'memory'
      }
    }
  ]
})

// 正常使用，缓存自动生效
const data = await request.get('/user/info')

配置项

工作原理

缓存生命周期

缓存数据从存入到删除，经历三个阶段：

只有当 staleTime > 0 时才会进入陈旧期，否则过期后直接进入完全失效。

LRU 淘汰机制

当缓存条目数超过 cacheCapacity 时，自动淘汰 最久未访问 的条目，确保内存占用可控。

使用示例

基础用法（内存缓存）

import { Request } from '@/uni_modules/mh-request'
import { cachePlugin } from '@/uni_modules/mh-request-cache'

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: cachePlugin,
      config: {
        cacheTime: 60 * 1000,  // 1 分钟有效期
        cacheCapacity: 30
      }
    }
  ]
})

// 首次请求：发起网络请求
const data1 = await request.get('/user/info')

// 1 分钟内再次请求：直接返回缓存，不发网络请求
const data2 = await request.get('/user/info')

本地持久化缓存

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: cachePlugin,
      config: {
        cacheTime: 10 * 60 * 1000,  // 10 分钟
        storageType: 'storage',     // 持久化存储，应用重启后缓存仍在
        cacheCapacity: 100
      }
    }
  ]
})

陈旧数据刷新策略

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: cachePlugin,
      config: {
        cacheTime: 60 * 1000,   // 1 分钟新鲜期
        staleTime: 30 * 1000    // 过期后 30 秒内返回旧数据并异步刷新
      }
    }
  ]
})

// 第 0 秒：请求数据，存入缓存
// 第 30 秒：命中缓存，直接返回（新鲜期）
// 第 70 秒：缓存已过期但仍在 staleTime 内，立即返回旧数据 + 后台刷新
// 第 100 秒：完全失效，发起真实请求

缓存 POST 请求

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: cachePlugin,
      config: {
        enableMethods: ['GET', 'POST'],  // 同时缓存 GET 和 POST
        cacheTime: 30 * 1000
      }
    }
  ]
})

// POST 请求也会被缓存
const res = await request.post('/search', { keyword: '手机' })

自定义缓存键

默认键生成规则：method + url + 排序后的 data。如需自定义：

const request = new Request({
  baseURL: 'https://api.example.com',
  plugins: [
    {
      plugin: cachePlugin,
      config: {
        keyGenerator: (options) => {
          // 仅根据 URL 和方法生成键（忽略参数）
          return `${options.method}:${options.url}`
        }
      }
    }
  ]
})

缓存管理

插件在 request 实例上挂载 cache 对象，提供管理能力：

// 清空所有缓存（内存 + 持久化同步清除）
request.cache.clear()

// 查看缓存统计
const stats = request.cache.stats()
console.log('缓存条数:', stats.size)
console.log('缓存键列表:', stats.keys)

// 手动获取/设置缓存（一般不需要，仅用于调试）
const cached = request.cache.get('GET:/user/info')
request.cache.set('GET:/user/info', { id: 1, name: 'John' })

不同实例独立缓存

每个 Request 实例拥有独立的缓存空间，互不干扰：

const userRequest = new Request({
  baseURL: 'https://api.user.com',
  plugins: [{ plugin: cachePlugin, config: { cacheCapacity: 20 } }]
})

const productRequest = new Request({
  baseURL: 'https://api.product.com',
  plugins: [{ plugin: cachePlugin, config: { cacheCapacity: 50 } }]
})

// 两个实例的缓存完全隔离

注意事项

• 缓存内容：缓存的是 mh-request 返回的业务数据（即 ApiResponse.data），而非完整响应结构
• 存储限制：uni.setStorageSync 通常有 5MB 大小限制，请合理设置 cacheCapacity 和单条数据大小
• 刷新失败：异步刷新失败不会影响已返回的缓存数据，仅在控制台输出警告
• 方法限制：upload 和 download 不会被缓存，仅影响 request / get / post