backend / 缓存模块 - WlAdmin 文档

WlAdmin

正在加载文档...

文档内容较大，正在处理中，请稍候

1. 概述

本文档详细说明了后端服务实现的缓存管理模块，涵盖缓存提供器、缓存策略、缓存键规范、模块时间戳等核心概念，以及缓存使用、性能优化、最佳实践等内容，确保系统的高性能和高可用性。

1.1 什么是缓存模块

缓存管理模块是后端服务的核心组件，它提供了统一的缓存服务接口，支持 Redis 和内存两种缓存实现。通过智能的提供器选择和自动降级机制，确保系统的高可用性和高性能。

核心特性

✅ 双提供器支持：Redis 缓存（生产环境）和内存缓存（开发环境/降级方案）
✅ 智能降级：Redis 不可用时自动降级到内存缓存，确保服务可用
✅ 策略化管理：支持不同模块、不同资源类型的缓存策略配置
✅ 统一接口：提供统一的缓存 API，无需关心底层实现
✅ 性能监控：内置缓存命中率、响应时间等监控指标

1.2 为什么需要缓存

在 Web 应用中，数据库查询往往是性能瓶颈。缓存可以：

✅ 提升性能：将频繁访问的数据存储在内存中，减少数据库查询
✅ 降低负载：减少数据库压力，提高系统并发能力
✅ 改善体验：快速响应，提升用户体验
✅ 节省成本：减少数据库资源消耗

1.3 5分钟上手

步骤 1：导入缓存服务

const cacheService = require("../cache");
const { generateCacheKey, getCacheStrategyName } = require("../cache/utils/cacheKeyHelper");

步骤 2：读取缓存

// 生成缓存键
const cacheKey = generateCacheKey("user", "item", `user_123`);
const strategyName = getCacheStrategyName("user", "item");

// 尝试从缓存读取
const cachedData = await cacheService.get(cacheKey, strategyName);
if (cachedData) {
  return cachedData; // 缓存命中，直接返回
}

// 缓存未命中，从数据库查询
const data = await User.findById(123);

// 写入缓存
await cacheService.set(cacheKey, data, strategyName);
return data;

步骤 3：清除缓存

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

// 更新数据后清除相关缓存
await User.updateById(id, updateData);
await clearCacheKeys("user", "update", userId, id);

恭喜！ 你已经掌握了缓存的基本使用。接下来让我们深入了解各个概念。

2. 核心概念

2.1 缓存提供器

缓存模块支持两种提供器：

内存缓存（MemoryCache）

特点：快速、本地、无需外部依赖
适用场景：开发环境、单机部署、Redis 不可用时的降级方案
限制：数据不持久化，服务重启后丢失

Redis 缓存（RedisCache）

特点：分布式、持久化、高性能
适用场景：生产环境、多实例部署、需要数据共享
优势：支持集群、数据持久化、更丰富的功能

智能选择机制

系统会自动选择最优的提供器：

应用启动
    ↓
初始化内存缓存（确保始终可用）
    ↓
尝试连接 Redis
    ↓
连接成功？ → 是 → 使用 Redis（优先）
    ↓ 否
使用内存缓存（降级）

重要：Redis 不可用时，系统会自动降级到内存缓存，确保服务可用。

2.2 缓存策略

缓存策略定义了不同数据的缓存行为，包括：

TTL：过期时间（秒）
useRedis：是否使用 Redis
warmable：是否支持预热
enabled：是否启用缓存

策略配置示例

// config/base/cache.js
strategies: {
  // 默认策略
  defaults: {
    ttl: 3600,        // 1小时
    useRedis: true,
    enabled: true
  },

  // 用户模块策略
  user: {
    item: { ttl: 3600, useRedis: true },  // 用户详情：1小时
    list: { ttl: 1800, useRedis: true },  // 用户列表：30分钟
  }
}

使用策略

// 使用策略名称（推荐）
await cacheService.set(key, value, "user.item");

// 不使用策略（使用默认配置）
await cacheService.set(key, value);

2.3 缓存键规范

缓存键采用统一的命名规范，确保可读性和可维护性。

键结构

{prefix}:{version}:{module}:{resourceType}:{identifier}[:operation]

示例：

pc:v1:user:item:user_123 - 用户详情
pc:v1:user:list:user_1:{"page":1,"limit":10,"fh":"abc123","dp":"def456","epoch":"1234567890"} - 用户列表
pc:v1:permission:codes:user_123 - 用户权限码

键生成工具

const { generateCacheKey } = require("../cache/utils/cacheKeyHelper");

// 生成标准缓存键
const key = generateCacheKey("user", "item", "user_123");
// 结果: "pc:v1:user:item:user_123"

// 生成模式（用于批量删除）
const pattern = getCacheKeyPattern("user", "list");
// 结果: "pc:v1:user:list:*"

重要：始终使用工具函数生成缓存键，避免硬编码字符串。

2.4 模块时间戳（Epoch）

模块时间戳是缓存失效的核心机制。当数据变更时，更新模块时间戳，使所有相关缓存自动失效。

工作原理

用户数据更新
    ↓
更新 user 模块时间戳（epoch）
    ↓
所有包含旧 epoch 的缓存键自动失效
    ↓
下次查询时使用新 epoch，缓存未命中
    ↓
从数据库重新加载数据并缓存

使用示例

const { getModuleEpoch, bumpModuleEpoch } = require("../cache/utils/cacheKeyHelper");

// 获取当前时间戳
const epoch = await getModuleEpoch("user");

// 更新数据后，提升时间戳
await User.updateById(id, data);
await bumpModuleEpoch("user"); // 所有 user 相关缓存失效

3. 基础使用

3.1 读取单条数据

这是最常见的缓存使用场景。

完整示例

const {
  generateCacheKey,
  getModuleEpoch,
  getCacheStrategyName,
} = require("../cache/utils/cacheKeyHelper");
const cacheService = require("../cache");

async function getUser(req, res) {
  const { id } = req.params;

  // 1. 获取模块时间戳
  const epoch = await getModuleEpoch("user_item");

  // 2. 生成缓存键
  const cacheKey = generateCacheKey("user", "item", `user_${id}`, epoch);
  const strategyName = getCacheStrategyName("user", "item");

  // 3. 尝试从缓存读取
  const cachedData = await cacheService.get(cacheKey, strategyName);
  if (cachedData !== null && cachedData !== undefined) {
    // 缓存命中，直接返回
    return success(req, res, "从缓存获取用户信息成功", cachedData);
  }

  // 4. 缓存未命中，从数据库查询
  const userinfo = await User.findById(id);

  if (!userinfo) {
    return notFound(req, res, "用户不存在");
  }

  // 5. 写入缓存
  await cacheService.set(cacheKey, userinfo, strategyName);

  return success(req, res, "获取用户信息成功", userinfo);
}

关键点

使用模块时间戳：确保数据更新后缓存自动失效
检查缓存结果：null 和 undefined 都表示缓存未命中
写入缓存：查询数据库后立即写入缓存

3.2 读取列表数据

列表缓存需要考虑分页、过滤条件、数据权限等因素。

完整示例

const {
  buildListKeys,
  readListResponse,
  writeListResponse,
  getModuleEpoch,
  buildDataPermHash,
  getCacheStrategyName,
} = require("../cache/utils/cacheKeyHelper");
const cacheService = require("../cache");

async function getAllUsers(req, res) {
  const currentUserId = req.user?.id;
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;

  // 1. 构建过滤条件
  const filters = {};
  if (req.query.username) {
    filters.username = req.query.username;
  }

  // 2. 构建数据权限哈希（用于隔离不同数据域）
  const dataPerm = req.dataPermission || null;
  const dpHash = buildDataPermHash(dataPerm);

  // 3. 获取模块时间戳
  const epoch = await getModuleEpoch("user");

  // 4. 构建列表缓存键
  const keys = buildListKeys(
    "user", // 模块名
    "list", // 资源类型
    `user_${currentUserId}`, // 标识符
    page, // 页码
    limit, // 每页数量
    filters, // 过滤条件
    dpHash, // 数据权限哈希
    epoch // 模块时间戳
  );

  const strategyName = getCacheStrategyName("user", "list");

  // 5. 尝试从缓存读取
  const cacheData = await readListResponse(page, limit, keys, strategyName);
  if (cacheData) {
    // 缓存命中，刷新 TTL
    await cacheService.set(keys.responseKey, cacheData, strategyName);
    return success(req, res, "从缓存获取用户列表成功", cacheData);
  }

  // 6. 缓存未命中，从数据库查询
  const [users, total] = await Promise.all([
    User.findList(currentUserId, page, limit, filters, dataPerm),
    User.findCount(currentUserId, filters, dataPerm),
  ]);

  // 7. 写入缓存
  const responseData = await writeListResponse(page, limit, keys, users, total, strategyName);

  return success(req, res, "获取用户列表成功", responseData);
}

关键点

过滤条件哈希：buildListKeys 会自动将过滤条件序列化并计算哈希
数据权限隔离：通过 dpHash 确保不同数据域的缓存隔离
分页信息：缓存键包含分页信息，不同页面的缓存独立

3.3 写入缓存

写入缓存通常在查询数据库后进行。

基本用法

// 使用策略名称（推荐）
await cacheService.set(cacheKey, data, "user.item");

// 使用默认策略
await cacheService.set(cacheKey, data);

自定义 TTL

// 覆盖策略的 TTL（秒）
await cacheService.set(cacheKey, data, "user.item", 300); // 5分钟

3.4 清除缓存

数据更新后需要清除相关缓存，确保数据一致性。

使用 clearCacheKeys（推荐）

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

// 创建用户
await User.create(userData);
await clearCacheKeys("user", "create", userId);

// 更新用户
await User.updateById(id, updateData);
await clearCacheKeys("user", "update", userId, id);

// 删除用户
await User.deleteById(id);
await clearCacheKeys("user", "delete", userId, id);

手动清除

// 删除单个键
await cacheService.del(cacheKey, "user.item");

// 按模式清除
await cacheService.clearByPattern("pc:v1:user:list:*");

4. 进阶使用

4.1 防止缓存穿透

缓存穿透是指查询不存在的数据，导致每次请求都穿透缓存直接查询数据库。

问题场景

// 恶意请求：查询不存在的用户ID
GET / api / users / 999999; // 用户不存在
GET / api / users / 888888; // 用户不存在
// ... 大量请求导致数据库压力

解决方案：空值标记

// 定义空值标记
const NULL_MARKER = { __isNullMarker: true };

async function getUser(req, res) {
  const { id } = req.params;
  const cacheKey = generateCacheKey("user", "item", `user_${id}`, epoch);
  const strategyName = getCacheStrategyName("user", "item");

  // 1. 尝试从缓存读取
  const cachedData = await cacheService.get(cacheKey, strategyName);
  if (cachedData !== null && cachedData !== undefined) {
    // 2. 检查是否是空值标记
    if (cachedData.__isNullMarker === true) {
      return notFound(req, res, "用户不存在"); // 直接返回，不查数据库
    }
    return success(req, res, "从缓存获取用户信息成功", cachedData);
  }

  // 3. 从数据库查询
  const userinfo = await User.findById(id);

  if (!userinfo) {
    // 4. 数据不存在，缓存空值标记（短TTL）
    await cacheService.set(cacheKey, NULL_MARKER, strategyName, 300); // 5分钟
    return notFound(req, res, "用户不存在");
  }

  // 5. 数据存在，缓存实际数据
  await cacheService.set(cacheKey, userinfo, strategyName);
  return success(req, res, "获取用户信息成功", userinfo);
}

关键点

空值标记：使用特殊对象标记"数据不存在"
短 TTL：空值标记设置较短的过期时间（建议 5 分钟）
检查标记：读取缓存时检查是否是空值标记

4.2 缓存联动机制

当数据更新时，需要清除所有相关的缓存，确保数据一致性。

核心函数

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

await clearCacheKeys(module, operationType, userid, id, ids);

参数说明

module: 模块名称（如 'user', 'role', 'permission'）
operationType: 操作类型（'create', 'update', 'delete', 'bindRoles' 等）
userid: 当前操作用户ID
id: 操作对象ID
ids: 关联对象ID数组（可选）

使用示例

// 创建用户
await User.create(userData);
await clearCacheKeys("user", "create", userId);
// 自动清除：用户列表缓存

// 更新用户
await User.updateById(id, updateData);
await clearCacheKeys("user", "update", userId, id, roleIds);
// 自动清除：用户列表缓存、用户详情缓存、相关角色缓存

// 绑定角色
await User.bindRoles(userId, roleIds);
await clearCacheKeys("user", "bindRoles", userId, userId, roleIds);
// 自动清除：用户绑定角色缓存、用户权限缓存、用户菜单缓存

联动规则

系统会根据操作类型自动清除相关缓存：

操作类型	清除的缓存
`create`	模块列表缓存
`update`	模块列表缓存、详情缓存、关联缓存
`delete`	模块列表缓存、详情缓存、绑定关系缓存
`bindRoles`	绑定关系缓存、权限缓存、菜单缓存

4.3 批量操作

批量操作可以提高性能，减少网络往返。

批量获取

const keys = ["user:1", "user:2", "user:3"];
const values = await cacheService.mget(keys, "user.item");
// 返回: [userData1, userData2, userData3]

批量设置

await cacheService.mset([
  { key: "user:1", value: userData1, strategyName: "user.item" },
  { key: "user:2", value: userData2, strategyName: "user.item" },
  { key: "user:3", value: userData3, strategyName: "user.item" },
]);

批量删除

await cacheService.mdel(["user:1", "user:2", "user:3"], "user.item");

4.4 权限验证缓存

权限验证是高频操作，使用缓存可以大幅提升性能。

实际代码示例

// src/middlewares/permissionMiddleware.js
const cacheService = require("../cache");
const { generateCacheKey } = require("../cache/utils/cacheKeyHelper");

async function checkPermission(req, res, next) {
  const currentUserId = req.user.id;

  // 1. 生成权限缓存键
  const cacheKeyCodes = generateCacheKey("permission", "codes", `user_${currentUserId}`);
  const permStrategyName = "permission.codes";

  // 2. 尝试从缓存读取
  let userPermissionCodes = await cacheService.get(cacheKeyCodes, permStrategyName);

  if (!userPermissionCodes) {
    // 3. 缓存未命中，从数据库查询
    const sql = `
            SELECT DISTINCT p.permission_code
            FROM permission p
            INNER JOIN role_permission rp ON p.id = rp.permission_id
            INNER JOIN user_role ur ON rp.role_id = ur.role_id
            WHERE ur.user_id = ? AND p.is_delete = 0 AND p.status = 1
        `;
    const [rows] = await db.execute(sql, [currentUserId]);
    userPermissionCodes = rows.map((row) => row.permission_code);

    // 4. 写入缓存（5分钟）
    await cacheService.set(cacheKeyCodes, userPermissionCodes, permStrategyName, 300);
  }

  // 5. 验证权限
  const hasPermission = userPermissionCodes.includes(requiredPermission);
  if (!hasPermission) {
    return forbidden(req, res, "权限不足");
  }

  next();
}

5. 架构设计

5.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                    应用层 (Controllers)                  │
│  使用统一的 cacheService API，无需关心底层实现            │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│              缓存服务层 (cacheService.js)                 │
│  • 提供器选择  • 策略管理  • 统一接口                     │
└──────────────┬──────────────────────┬───────────────────┘
               │                      │
    ┌──────────▼──────────┐  ┌────────▼──────────┐
    │   MemoryCache       │  │    RedisCache      │
    │   (内存缓存)        │  │   (Redis缓存)      │
    └─────────────────────┘  └────────────────────┘
               │                      │
    ┌──────────▼──────────┐  ┌────────▼──────────┐
    │   Map 数据结构       │  │   Redis 客户端     │
    └─────────────────────┘  └────────────────────┘

5.2 提供器选择机制

初始化流程

// 1. 默认使用内存缓存（确保始终可用）
this.memoryProvider = new MemoryCache();

// 2. 尝试连接 Redis
if (redisModuleAvailable && !explicitlyDisabled) {
  this.redisProvider = new RedisCache();

  // 3. 重试机制（最多3次，每次间隔100ms）
  let retryCount = 0;
  while (retryCount < 3) {
    if (this.redisProvider.isConnected()) {
      this.redisAvailable = true;
      break;
    }
    await sleep(100);
    retryCount++;
  }
}

// 4. 选择默认提供器
this.defaultProvider = this.redisAvailable ? this.redisProvider : this.memoryProvider;

运行时选择

// 根据策略选择提供器
function getCacheProvider(strategyName) {
  const strategy = getCacheStrategy(strategyName);

  // 策略明确禁用 Redis
  if (strategy.useRedis === false) {
    return this.memoryProvider;
  }

  // Redis 可用且策略允许使用
  if (this.redisAvailable && strategy.useRedis !== false) {
    return this.redisProvider;
  }

  // 降级到内存缓存
  return this.memoryProvider;
}

5.3 监控与统计

缓存模块集成了完善的监控功能，支持：

操作统计：总操作数、命中率、响应时间
分类统计：按操作类型（get/set/delete）统计
模块统计：按业务模块统计
提供器统计：Redis 和内存分别统计

获取统计信息

const cacheMonitor = require("../cache/utils/cacheMonitor");
const stats = cacheMonitor.getStats();

console.log(stats);
// {
//   totalOperations: 1000,
//   hits: 850,
//   misses: 150,
//   hitRate: 85.0,
//   avgResponseTime: 2.3,
//   memoryHitRate: 80.0,
//   redisHitRate: 90.0,
//   byModule: {
//     user: { totalOperations: 500, hitRate: 88.0 }
//   }
// }

6. 配置说明

6.1 基础配置

配置文件位置：config/base/cache.js

module.exports = {
    // 缓存类型：memory 或 redis（可通过环境变量覆盖）
    type: process.env.CACHE_TYPE || "memory",

    // 缓存键前缀
    keyPrefix: "pc",

    // 内存缓存配置
    memory: {
        maxItems: 1000,        // 最大缓存项数
        useLRU: true,          // 是否使用LRU淘汰策略
        checkInterval: 60000,  // 清理检查间隔（毫秒）
    },

    // 缓存策略（见下一节）
    strategies: { ... }
};

6.2 策略配置

默认策略

defaults: {
    ttl: 3600,           // 默认过期时间（秒）
    useRedis: true,       // 是否使用Redis
    warmable: false,      // 是否支持预热
    version: "v1",        // 缓存版本
    enabled: true,        // 是否启用缓存
}

模块策略

user: {
    item: { ttl: 3600, useRedis: true, enabled: true },    // 用户详情：1小时
    list: { ttl: 1800, useRedis: true, enabled: true },    // 用户列表：30分钟
    bindroles: { ttl: 1800, useRedis: true },              // 绑定角色：30分钟
},

permission: {
    item: { ttl: 3600, useRedis: true, enabled: true },
    list: { ttl: 7200, useRedis: true, enabled: true },     // 权限列表：2小时
    codes: { ttl: 1800, useRedis: true, enabled: true },     // 权限码：30分钟
},

6.3 环境变量

可通过环境变量覆盖配置：

# 设置缓存类型
CACHE_TYPE=redis

# 其他配置可通过环境配置文件覆盖
# config/env/production.js

7. API 参考

7.1 核心方法

get - 获取缓存

/**
 * 获取缓存
 * @param {string} key - 缓存键
 * @param {string} strategyName - 策略名称（可选）
 * @returns {Promise<any>} 缓存的值，不存在返回 null
 */
const value = await cacheService.get(key, strategyName);

set - 设置缓存

/**
 * 设置缓存
 * @param {string} key - 缓存键
 * @param {any} value - 缓存值
 * @param {string} strategyName - 策略名称（可选）
 * @param {number} customTtl - 自定义TTL（可选，覆盖策略TTL）
 * @returns {Promise<boolean>} 是否设置成功
 */
await cacheService.set(key, value, strategyName, customTtl);

del - 删除缓存

/**
 * 删除缓存
 * @param {string} key - 缓存键
 * @param {string} strategyName - 策略名称（可选）
 * @returns {Promise<boolean>} 是否删除成功
 */
await cacheService.del(key, strategyName);

clearByPattern - 按模式清除

/**
 * 根据模式清除缓存
 * @param {string} pattern - 键模式（支持glob，如 "pc:v1:user:list:*"）
 * @param {Object} options - 选项
 * @param {boolean} options.resetStats - 是否重置统计信息
 * @returns {Promise<boolean>} 是否清除成功
 */
await cacheService.clearByPattern("pc:v1:user:list:*", { resetStats: false });

7.2 工具方法

generateCacheKey - 生成缓存键

const { generateCacheKey } = require("../cache/utils/cacheKeyHelper");

const key = generateCacheKey("user", "item", "user_123");
// 结果: "pc:v1:user:item:user_123"

getCacheKeyPattern - 生成键模式

const { getCacheKeyPattern } = require("../cache/utils/cacheKeyHelper");

const pattern = getCacheKeyPattern("user", "list");
// 结果: "pc:v1:user:list:*"

clearCacheKeys - 统一清除缓存

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

await clearCacheKeys("user", "update", userId, id, roleIds);

getModuleEpoch / bumpModuleEpoch - 模块时间戳

const { getModuleEpoch, bumpModuleEpoch } = require("../cache/utils/cacheKeyHelper");

// 获取时间戳
const epoch = await getModuleEpoch("user");

// 更新时间戳（使所有相关缓存失效）
await bumpModuleEpoch("user");

7.3 管理 API

缓存管理 API 位于 /api/monitor/cache/*，需要认证。

获取缓存列表

GET /api/monitor/cache?search=user&page=1&pageSize=100

删除指定缓存

DELETE /api/monitor/cache/:key

获取统计信息

GET /api/monitor/cache/stats

8. 最佳实践

✅ 推荐做法

使用统一生成的键：始终通过 generateCacheKey 生成缓存键
使用策略名称：通过 strategyName 使用配置的策略
使用 clearCacheKeys：数据更新后自动清除相关缓存
防止缓存穿透：对不存在的数据使用空值标记
监控缓存命中率：定期检查并优化缓存策略
批量操作优先：Redis 环境下优先使用 mget/mset

❌ 避免做法

硬编码缓存键：不要直接写字符串，使用工具函数
忽略缓存清除：数据更新后必须清除相关缓存
TTL 设置过长：避免数据过期后仍使用旧缓存
过度缓存：不要缓存频繁变化的数据
忽略错误处理：缓存操作失败不应影响主业务流程

9. 常见问题

Q1: 缓存不一致怎么办？

原因：

未正确调用 clearCacheKeys
缓存键生成不一致
模块时间戳未更新

解决：

检查数据更新操作是否调用了 clearCacheKeys
确保使用工具函数生成缓存键
检查模块时间戳是否正确更新

Q2: 缓存未命中率很高？

原因：

TTL 设置过短
清理模式过宽
缓存键生成不一致

解决：

检查策略 TTL 设置是否合理
检查清理模式是否过宽
查看日志确认缓存写入和清除操作

Q3: Redis 连接失败？

原因：

Redis 未启用或未连接
配置错误
网络问题

解决：

检查 cacheService.getProviderType() 返回的类型
查看日志中的 Redis 连接错误
检查 Redis 配置和服务状态

Q4: 如何调试缓存问题？

方法：

查看缓存统计信息：GET /api/monitor/cache/stats
查看缓存列表：GET /api/monitor/cache
查看日志中的缓存操作记录
使用 getProviderType() 确认使用的提供器

10. 缓存三大问题

10.1 缓存雪崩

问题：大量缓存同时过期，导致请求全部打到数据库。

解决方案：

✅ 为缓存设置随机过期时间
✅ 实现缓存降级（已实现）
✅ 使用多级缓存

10.2 缓存穿透

问题：查询不存在的数据，每次都穿透缓存查询数据库。

解决方案：

✅ 使用空值标记（已实现 NULL_MARKER）
✅ 布隆过滤器（可选）

10.3 缓存击穿

问题：热点数据过期，大量请求同时查询数据库。

解决方案：

✅ 热点数据永不过期（带更新机制）
✅ 使用互斥锁
✅ 缓存预热

缓存还不是特别完善，后面再重构吧

1. 概述

1.1 什么是缓存模块

核心特性

✅ 双提供器支持：Redis 缓存（生产环境）和内存缓存（开发环境/降级方案）
✅ 智能降级：Redis 不可用时自动降级到内存缓存，确保服务可用
✅ 策略化管理：支持不同模块、不同资源类型的缓存策略配置
✅ 统一接口：提供统一的缓存 API，无需关心底层实现
✅ 性能监控：内置缓存命中率、响应时间等监控指标

1.2 为什么需要缓存

在 Web 应用中，数据库查询往往是性能瓶颈。缓存可以：

✅ 提升性能：将频繁访问的数据存储在内存中，减少数据库查询
✅ 降低负载：减少数据库压力，提高系统并发能力
✅ 改善体验：快速响应，提升用户体验
✅ 节省成本：减少数据库资源消耗

1.3 5分钟上手

步骤 1：导入缓存服务

const cacheService = require("../cache");
const { generateCacheKey, getCacheStrategyName } = require("../cache/utils/cacheKeyHelper");

步骤 2：读取缓存

// 生成缓存键
const cacheKey = generateCacheKey("user", "item", `user_123`);
const strategyName = getCacheStrategyName("user", "item");

// 尝试从缓存读取
const cachedData = await cacheService.get(cacheKey, strategyName);
if (cachedData) {
  return cachedData; // 缓存命中，直接返回
}

// 缓存未命中，从数据库查询
const data = await User.findById(123);

// 写入缓存
await cacheService.set(cacheKey, data, strategyName);
return data;

步骤 3：清除缓存

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

// 更新数据后清除相关缓存
await User.updateById(id, updateData);
await clearCacheKeys("user", "update", userId, id);

恭喜！ 你已经掌握了缓存的基本使用。接下来让我们深入了解各个概念。

2. 核心概念

2.1 缓存提供器

缓存模块支持两种提供器：

内存缓存（MemoryCache）

特点：快速、本地、无需外部依赖
适用场景：开发环境、单机部署、Redis 不可用时的降级方案
限制：数据不持久化，服务重启后丢失

Redis 缓存（RedisCache）

特点：分布式、持久化、高性能
适用场景：生产环境、多实例部署、需要数据共享
优势：支持集群、数据持久化、更丰富的功能

智能选择机制

系统会自动选择最优的提供器：

应用启动
    ↓
初始化内存缓存（确保始终可用）
    ↓
尝试连接 Redis
    ↓
连接成功？ → 是 → 使用 Redis（优先）
    ↓ 否
使用内存缓存（降级）

重要：Redis 不可用时，系统会自动降级到内存缓存，确保服务可用。

2.2 缓存策略

缓存策略定义了不同数据的缓存行为，包括：

TTL：过期时间（秒）
useRedis：是否使用 Redis
warmable：是否支持预热
enabled：是否启用缓存

策略配置示例

// config/base/cache.js
strategies: {
  // 默认策略
  defaults: {
    ttl: 3600,        // 1小时
    useRedis: true,
    enabled: true
  },

  // 用户模块策略
  user: {
    item: { ttl: 3600, useRedis: true },  // 用户详情：1小时
    list: { ttl: 1800, useRedis: true },  // 用户列表：30分钟
  }
}

使用策略

// 使用策略名称（推荐）
await cacheService.set(key, value, "user.item");

// 不使用策略（使用默认配置）
await cacheService.set(key, value);

2.3 缓存键规范

缓存键采用统一的命名规范，确保可读性和可维护性。

键结构

{prefix}:{version}:{module}:{resourceType}:{identifier}[:operation]

示例：

pc:v1:user:item:user_123 - 用户详情
pc:v1:user:list:user_1:{"page":1,"limit":10,"fh":"abc123","dp":"def456","epoch":"1234567890"} - 用户列表
pc:v1:permission:codes:user_123 - 用户权限码

键生成工具

const { generateCacheKey } = require("../cache/utils/cacheKeyHelper");

// 生成标准缓存键
const key = generateCacheKey("user", "item", "user_123");
// 结果: "pc:v1:user:item:user_123"

// 生成模式（用于批量删除）
const pattern = getCacheKeyPattern("user", "list");
// 结果: "pc:v1:user:list:*"

重要：始终使用工具函数生成缓存键，避免硬编码字符串。

2.4 模块时间戳（Epoch）

模块时间戳是缓存失效的核心机制。当数据变更时，更新模块时间戳，使所有相关缓存自动失效。

工作原理

用户数据更新
    ↓
更新 user 模块时间戳（epoch）
    ↓
所有包含旧 epoch 的缓存键自动失效
    ↓
下次查询时使用新 epoch，缓存未命中
    ↓
从数据库重新加载数据并缓存

使用示例

const { getModuleEpoch, bumpModuleEpoch } = require("../cache/utils/cacheKeyHelper");

// 获取当前时间戳
const epoch = await getModuleEpoch("user");

// 更新数据后，提升时间戳
await User.updateById(id, data);
await bumpModuleEpoch("user"); // 所有 user 相关缓存失效

3. 基础使用

3.1 读取单条数据

这是最常见的缓存使用场景。

完整示例

const {
  generateCacheKey,
  getModuleEpoch,
  getCacheStrategyName,
} = require("../cache/utils/cacheKeyHelper");
const cacheService = require("../cache");

async function getUser(req, res) {
  const { id } = req.params;

  // 1. 获取模块时间戳
  const epoch = await getModuleEpoch("user_item");

  // 2. 生成缓存键
  const cacheKey = generateCacheKey("user", "item", `user_${id}`, epoch);
  const strategyName = getCacheStrategyName("user", "item");

  // 3. 尝试从缓存读取
  const cachedData = await cacheService.get(cacheKey, strategyName);
  if (cachedData !== null && cachedData !== undefined) {
    // 缓存命中，直接返回
    return success(req, res, "从缓存获取用户信息成功", cachedData);
  }

  // 4. 缓存未命中，从数据库查询
  const userinfo = await User.findById(id);

  if (!userinfo) {
    return notFound(req, res, "用户不存在");
  }

  // 5. 写入缓存
  await cacheService.set(cacheKey, userinfo, strategyName);

  return success(req, res, "获取用户信息成功", userinfo);
}

关键点

使用模块时间戳：确保数据更新后缓存自动失效
检查缓存结果：null 和 undefined 都表示缓存未命中
写入缓存：查询数据库后立即写入缓存

3.2 读取列表数据

列表缓存需要考虑分页、过滤条件、数据权限等因素。

完整示例

const {
  buildListKeys,
  readListResponse,
  writeListResponse,
  getModuleEpoch,
  buildDataPermHash,
  getCacheStrategyName,
} = require("../cache/utils/cacheKeyHelper");
const cacheService = require("../cache");

async function getAllUsers(req, res) {
  const currentUserId = req.user?.id;
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 10;

  // 1. 构建过滤条件
  const filters = {};
  if (req.query.username) {
    filters.username = req.query.username;
  }

  // 2. 构建数据权限哈希（用于隔离不同数据域）
  const dataPerm = req.dataPermission || null;
  const dpHash = buildDataPermHash(dataPerm);

  // 3. 获取模块时间戳
  const epoch = await getModuleEpoch("user");

  // 4. 构建列表缓存键
  const keys = buildListKeys(
    "user", // 模块名
    "list", // 资源类型
    `user_${currentUserId}`, // 标识符
    page, // 页码
    limit, // 每页数量
    filters, // 过滤条件
    dpHash, // 数据权限哈希
    epoch // 模块时间戳
  );

  const strategyName = getCacheStrategyName("user", "list");

  // 5. 尝试从缓存读取
  const cacheData = await readListResponse(page, limit, keys, strategyName);
  if (cacheData) {
    // 缓存命中，刷新 TTL
    await cacheService.set(keys.responseKey, cacheData, strategyName);
    return success(req, res, "从缓存获取用户列表成功", cacheData);
  }

  // 6. 缓存未命中，从数据库查询
  const [users, total] = await Promise.all([
    User.findList(currentUserId, page, limit, filters, dataPerm),
    User.findCount(currentUserId, filters, dataPerm),
  ]);

  // 7. 写入缓存
  const responseData = await writeListResponse(page, limit, keys, users, total, strategyName);

  return success(req, res, "获取用户列表成功", responseData);
}

关键点

过滤条件哈希：buildListKeys 会自动将过滤条件序列化并计算哈希
数据权限隔离：通过 dpHash 确保不同数据域的缓存隔离
分页信息：缓存键包含分页信息，不同页面的缓存独立

3.3 写入缓存

写入缓存通常在查询数据库后进行。

基本用法

// 使用策略名称（推荐）
await cacheService.set(cacheKey, data, "user.item");

// 使用默认策略
await cacheService.set(cacheKey, data);

自定义 TTL

// 覆盖策略的 TTL（秒）
await cacheService.set(cacheKey, data, "user.item", 300); // 5分钟

3.4 清除缓存

数据更新后需要清除相关缓存，确保数据一致性。

使用 clearCacheKeys（推荐）

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

// 创建用户
await User.create(userData);
await clearCacheKeys("user", "create", userId);

// 更新用户
await User.updateById(id, updateData);
await clearCacheKeys("user", "update", userId, id);

// 删除用户
await User.deleteById(id);
await clearCacheKeys("user", "delete", userId, id);

手动清除

// 删除单个键
await cacheService.del(cacheKey, "user.item");

// 按模式清除
await cacheService.clearByPattern("pc:v1:user:list:*");

4. 进阶使用

4.1 防止缓存穿透

缓存穿透是指查询不存在的数据，导致每次请求都穿透缓存直接查询数据库。

问题场景

// 恶意请求：查询不存在的用户ID
GET / api / users / 999999; // 用户不存在
GET / api / users / 888888; // 用户不存在
// ... 大量请求导致数据库压力

解决方案：空值标记

// 定义空值标记
const NULL_MARKER = { __isNullMarker: true };

async function getUser(req, res) {
  const { id } = req.params;
  const cacheKey = generateCacheKey("user", "item", `user_${id}`, epoch);
  const strategyName = getCacheStrategyName("user", "item");

  // 1. 尝试从缓存读取
  const cachedData = await cacheService.get(cacheKey, strategyName);
  if (cachedData !== null && cachedData !== undefined) {
    // 2. 检查是否是空值标记
    if (cachedData.__isNullMarker === true) {
      return notFound(req, res, "用户不存在"); // 直接返回，不查数据库
    }
    return success(req, res, "从缓存获取用户信息成功", cachedData);
  }

  // 3. 从数据库查询
  const userinfo = await User.findById(id);

  if (!userinfo) {
    // 4. 数据不存在，缓存空值标记（短TTL）
    await cacheService.set(cacheKey, NULL_MARKER, strategyName, 300); // 5分钟
    return notFound(req, res, "用户不存在");
  }

  // 5. 数据存在，缓存实际数据
  await cacheService.set(cacheKey, userinfo, strategyName);
  return success(req, res, "获取用户信息成功", userinfo);
}

关键点

空值标记：使用特殊对象标记"数据不存在"
短 TTL：空值标记设置较短的过期时间（建议 5 分钟）
检查标记：读取缓存时检查是否是空值标记

4.2 缓存联动机制

当数据更新时，需要清除所有相关的缓存，确保数据一致性。

核心函数

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

await clearCacheKeys(module, operationType, userid, id, ids);

参数说明

module: 模块名称（如 'user', 'role', 'permission'）
operationType: 操作类型（'create', 'update', 'delete', 'bindRoles' 等）
userid: 当前操作用户ID
id: 操作对象ID
ids: 关联对象ID数组（可选）

使用示例

// 创建用户
await User.create(userData);
await clearCacheKeys("user", "create", userId);
// 自动清除：用户列表缓存

// 更新用户
await User.updateById(id, updateData);
await clearCacheKeys("user", "update", userId, id, roleIds);
// 自动清除：用户列表缓存、用户详情缓存、相关角色缓存

// 绑定角色
await User.bindRoles(userId, roleIds);
await clearCacheKeys("user", "bindRoles", userId, userId, roleIds);
// 自动清除：用户绑定角色缓存、用户权限缓存、用户菜单缓存

联动规则

系统会根据操作类型自动清除相关缓存：

操作类型	清除的缓存
`create`	模块列表缓存
`update`	模块列表缓存、详情缓存、关联缓存
`delete`	模块列表缓存、详情缓存、绑定关系缓存
`bindRoles`	绑定关系缓存、权限缓存、菜单缓存

4.3 批量操作

批量操作可以提高性能，减少网络往返。

批量获取

const keys = ["user:1", "user:2", "user:3"];
const values = await cacheService.mget(keys, "user.item");
// 返回: [userData1, userData2, userData3]

批量设置

await cacheService.mset([
  { key: "user:1", value: userData1, strategyName: "user.item" },
  { key: "user:2", value: userData2, strategyName: "user.item" },
  { key: "user:3", value: userData3, strategyName: "user.item" },
]);

批量删除

await cacheService.mdel(["user:1", "user:2", "user:3"], "user.item");

4.4 权限验证缓存

权限验证是高频操作，使用缓存可以大幅提升性能。

实际代码示例

// src/middlewares/permissionMiddleware.js
const cacheService = require("../cache");
const { generateCacheKey } = require("../cache/utils/cacheKeyHelper");

async function checkPermission(req, res, next) {
  const currentUserId = req.user.id;

  // 1. 生成权限缓存键
  const cacheKeyCodes = generateCacheKey("permission", "codes", `user_${currentUserId}`);
  const permStrategyName = "permission.codes";

  // 2. 尝试从缓存读取
  let userPermissionCodes = await cacheService.get(cacheKeyCodes, permStrategyName);

  if (!userPermissionCodes) {
    // 3. 缓存未命中，从数据库查询
    const sql = `
            SELECT DISTINCT p.permission_code
            FROM permission p
            INNER JOIN role_permission rp ON p.id = rp.permission_id
            INNER JOIN user_role ur ON rp.role_id = ur.role_id
            WHERE ur.user_id = ? AND p.is_delete = 0 AND p.status = 1
        `;
    const [rows] = await db.execute(sql, [currentUserId]);
    userPermissionCodes = rows.map((row) => row.permission_code);

    // 4. 写入缓存（5分钟）
    await cacheService.set(cacheKeyCodes, userPermissionCodes, permStrategyName, 300);
  }

  // 5. 验证权限
  const hasPermission = userPermissionCodes.includes(requiredPermission);
  if (!hasPermission) {
    return forbidden(req, res, "权限不足");
  }

  next();
}

5. 架构设计

5.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                    应用层 (Controllers)                  │
│  使用统一的 cacheService API，无需关心底层实现            │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│              缓存服务层 (cacheService.js)                 │
│  • 提供器选择  • 策略管理  • 统一接口                     │
└──────────────┬──────────────────────┬───────────────────┘
               │                      │
    ┌──────────▼──────────┐  ┌────────▼──────────┐
    │   MemoryCache       │  │    RedisCache      │
    │   (内存缓存)        │  │   (Redis缓存)      │
    └─────────────────────┘  └────────────────────┘
               │                      │
    ┌──────────▼──────────┐  ┌────────▼──────────┐
    │   Map 数据结构       │  │   Redis 客户端     │
    └─────────────────────┘  └────────────────────┘

5.2 提供器选择机制

初始化流程

// 1. 默认使用内存缓存（确保始终可用）
this.memoryProvider = new MemoryCache();

// 2. 尝试连接 Redis
if (redisModuleAvailable && !explicitlyDisabled) {
  this.redisProvider = new RedisCache();

  // 3. 重试机制（最多3次，每次间隔100ms）
  let retryCount = 0;
  while (retryCount < 3) {
    if (this.redisProvider.isConnected()) {
      this.redisAvailable = true;
      break;
    }
    await sleep(100);
    retryCount++;
  }
}

// 4. 选择默认提供器
this.defaultProvider = this.redisAvailable ? this.redisProvider : this.memoryProvider;

运行时选择

// 根据策略选择提供器
function getCacheProvider(strategyName) {
  const strategy = getCacheStrategy(strategyName);

  // 策略明确禁用 Redis
  if (strategy.useRedis === false) {
    return this.memoryProvider;
  }

  // Redis 可用且策略允许使用
  if (this.redisAvailable && strategy.useRedis !== false) {
    return this.redisProvider;
  }

  // 降级到内存缓存
  return this.memoryProvider;
}

5.3 监控与统计

缓存模块集成了完善的监控功能，支持：

操作统计：总操作数、命中率、响应时间
分类统计：按操作类型（get/set/delete）统计
模块统计：按业务模块统计
提供器统计：Redis 和内存分别统计

获取统计信息

const cacheMonitor = require("../cache/utils/cacheMonitor");
const stats = cacheMonitor.getStats();

console.log(stats);
// {
//   totalOperations: 1000,
//   hits: 850,
//   misses: 150,
//   hitRate: 85.0,
//   avgResponseTime: 2.3,
//   memoryHitRate: 80.0,
//   redisHitRate: 90.0,
//   byModule: {
//     user: { totalOperations: 500, hitRate: 88.0 }
//   }
// }

6. 配置说明

6.1 基础配置

配置文件位置：config/base/cache.js

module.exports = {
    // 缓存类型：memory 或 redis（可通过环境变量覆盖）
    type: process.env.CACHE_TYPE || "memory",

    // 缓存键前缀
    keyPrefix: "pc",

    // 内存缓存配置
    memory: {
        maxItems: 1000,        // 最大缓存项数
        useLRU: true,          // 是否使用LRU淘汰策略
        checkInterval: 60000,  // 清理检查间隔（毫秒）
    },

    // 缓存策略（见下一节）
    strategies: { ... }
};

6.2 策略配置

默认策略

defaults: {
    ttl: 3600,           // 默认过期时间（秒）
    useRedis: true,       // 是否使用Redis
    warmable: false,      // 是否支持预热
    version: "v1",        // 缓存版本
    enabled: true,        // 是否启用缓存
}

模块策略

user: {
    item: { ttl: 3600, useRedis: true, enabled: true },    // 用户详情：1小时
    list: { ttl: 1800, useRedis: true, enabled: true },    // 用户列表：30分钟
    bindroles: { ttl: 1800, useRedis: true },              // 绑定角色：30分钟
},

permission: {
    item: { ttl: 3600, useRedis: true, enabled: true },
    list: { ttl: 7200, useRedis: true, enabled: true },     // 权限列表：2小时
    codes: { ttl: 1800, useRedis: true, enabled: true },     // 权限码：30分钟
},

6.3 环境变量

可通过环境变量覆盖配置：

# 设置缓存类型
CACHE_TYPE=redis

# 其他配置可通过环境配置文件覆盖
# config/env/production.js

7. API 参考

7.1 核心方法

get - 获取缓存

/**
 * 获取缓存
 * @param {string} key - 缓存键
 * @param {string} strategyName - 策略名称（可选）
 * @returns {Promise<any>} 缓存的值，不存在返回 null
 */
const value = await cacheService.get(key, strategyName);

set - 设置缓存

/**
 * 设置缓存
 * @param {string} key - 缓存键
 * @param {any} value - 缓存值
 * @param {string} strategyName - 策略名称（可选）
 * @param {number} customTtl - 自定义TTL（可选，覆盖策略TTL）
 * @returns {Promise<boolean>} 是否设置成功
 */
await cacheService.set(key, value, strategyName, customTtl);

del - 删除缓存

/**
 * 删除缓存
 * @param {string} key - 缓存键
 * @param {string} strategyName - 策略名称（可选）
 * @returns {Promise<boolean>} 是否删除成功
 */
await cacheService.del(key, strategyName);

clearByPattern - 按模式清除

/**
 * 根据模式清除缓存
 * @param {string} pattern - 键模式（支持glob，如 "pc:v1:user:list:*"）
 * @param {Object} options - 选项
 * @param {boolean} options.resetStats - 是否重置统计信息
 * @returns {Promise<boolean>} 是否清除成功
 */
await cacheService.clearByPattern("pc:v1:user:list:*", { resetStats: false });

7.2 工具方法

generateCacheKey - 生成缓存键

const { generateCacheKey } = require("../cache/utils/cacheKeyHelper");

const key = generateCacheKey("user", "item", "user_123");
// 结果: "pc:v1:user:item:user_123"

getCacheKeyPattern - 生成键模式

const { getCacheKeyPattern } = require("../cache/utils/cacheKeyHelper");

const pattern = getCacheKeyPattern("user", "list");
// 结果: "pc:v1:user:list:*"

clearCacheKeys - 统一清除缓存

const { clearCacheKeys } = require("../cache/utils/cacheKeyHelper");

await clearCacheKeys("user", "update", userId, id, roleIds);

getModuleEpoch / bumpModuleEpoch - 模块时间戳

const { getModuleEpoch, bumpModuleEpoch } = require("../cache/utils/cacheKeyHelper");

// 获取时间戳
const epoch = await getModuleEpoch("user");

// 更新时间戳（使所有相关缓存失效）
await bumpModuleEpoch("user");

7.3 管理 API

缓存管理 API 位于 /api/monitor/cache/*，需要认证。

获取缓存列表

GET /api/monitor/cache?search=user&page=1&pageSize=100

删除指定缓存

DELETE /api/monitor/cache/:key

获取统计信息

GET /api/monitor/cache/stats

8. 最佳实践

✅ 推荐做法

使用统一生成的键：始终通过 generateCacheKey 生成缓存键
使用策略名称：通过 strategyName 使用配置的策略
使用 clearCacheKeys：数据更新后自动清除相关缓存
防止缓存穿透：对不存在的数据使用空值标记
监控缓存命中率：定期检查并优化缓存策略
批量操作优先：Redis 环境下优先使用 mget/mset

❌ 避免做法

硬编码缓存键：不要直接写字符串，使用工具函数
忽略缓存清除：数据更新后必须清除相关缓存
TTL 设置过长：避免数据过期后仍使用旧缓存
过度缓存：不要缓存频繁变化的数据
忽略错误处理：缓存操作失败不应影响主业务流程

9. 常见问题

Q1: 缓存不一致怎么办？

原因：

未正确调用 clearCacheKeys
缓存键生成不一致
模块时间戳未更新

解决：

检查数据更新操作是否调用了 clearCacheKeys
确保使用工具函数生成缓存键
检查模块时间戳是否正确更新

Q2: 缓存未命中率很高？

原因：

TTL 设置过短
清理模式过宽
缓存键生成不一致

解决：

检查策略 TTL 设置是否合理
检查清理模式是否过宽
查看日志确认缓存写入和清除操作

Q3: Redis 连接失败？

原因：

Redis 未启用或未连接
配置错误
网络问题

解决：

检查 cacheService.getProviderType() 返回的类型
查看日志中的 Redis 连接错误
检查 Redis 配置和服务状态

Q4: 如何调试缓存问题？

方法：

查看缓存统计信息：GET /api/monitor/cache/stats
查看缓存列表：GET /api/monitor/cache
查看日志中的缓存操作记录
使用 getProviderType() 确认使用的提供器

10. 缓存三大问题

10.1 缓存雪崩

问题：大量缓存同时过期，导致请求全部打到数据库。

解决方案：

✅ 为缓存设置随机过期时间
✅ 实现缓存降级（已实现）
✅ 使用多级缓存

10.2 缓存穿透

问题：查询不存在的数据，每次都穿透缓存查询数据库。

解决方案：

✅ 使用空值标记（已实现 NULL_MARKER）
✅ 布隆过滤器（可选）

10.3 缓存击穿

问题：热点数据过期，大量请求同时查询数据库。

解决方案：

✅ 热点数据永不过期（带更新机制）
✅ 使用互斥锁
✅ 缓存预热

缓存还不是特别完善，后面再重构吧

1. 概述#

1.1 什么是缓存模块#

核心特性#

1.2 为什么需要缓存#

1.3 5分钟上手#

步骤 1：导入缓存服务#

步骤 2：读取缓存#

步骤 3：清除缓存#

2. 核心概念#

2.1 缓存提供器#

内存缓存（MemoryCache）#

Redis 缓存（RedisCache）#

智能选择机制#

2.2 缓存策略#

策略配置示例#

使用策略#

2.3 缓存键规范#

键结构#

键生成工具#

2.4 模块时间戳（Epoch）#

工作原理#

使用示例#

3. 基础使用#

3.1 读取单条数据#

完整示例#

关键点#

3.2 读取列表数据#

完整示例#

关键点#

3.3 写入缓存#

基本用法#

自定义 TTL#

3.4 清除缓存#

使用 clearCacheKeys（推荐）#

手动清除#

4. 进阶使用#

4.1 防止缓存穿透#

问题场景#

解决方案：空值标记#

关键点#

4.2 缓存联动机制#

核心函数#

参数说明#

使用示例#

联动规则#

4.3 批量操作#

批量获取#

批量设置#

批量删除#

4.4 权限验证缓存#

实际代码示例#

5. 架构设计#

5.1 整体架构#

5.2 提供器选择机制#

初始化流程#

运行时选择#

5.3 监控与统计#

获取统计信息#

6. 配置说明#

6.1 基础配置#

6.2 策略配置#

默认策略#

模块策略#

6.3 环境变量#

7. API 参考#

7.1 核心方法#

get - 获取缓存#

set - 设置缓存#

del - 删除缓存#

clearByPattern - 按模式清除#

7.2 工具方法#

generateCacheKey - 生成缓存键#

getCacheKeyPattern - 生成键模式#

clearCacheKeys - 统一清除缓存#

getModuleEpoch / bumpModuleEpoch - 模块时间戳#

7.3 管理 API#

获取缓存列表#

删除指定缓存#

获取统计信息#

8. 最佳实践#

1. 概述

1.1 什么是缓存模块

核心特性

1.2 为什么需要缓存

1.3 5分钟上手

步骤 1：导入缓存服务

步骤 2：读取缓存

步骤 3：清除缓存

2. 核心概念

2.1 缓存提供器

内存缓存（MemoryCache）

Redis 缓存（RedisCache）

智能选择机制

2.2 缓存策略

策略配置示例

使用策略

2.3 缓存键规范

键结构

键生成工具

2.4 模块时间戳（Epoch）

工作原理

使用示例

3. 基础使用

3.1 读取单条数据

完整示例

关键点

3.2 读取列表数据

完整示例

关键点

3.3 写入缓存

基本用法

自定义 TTL

3.4 清除缓存

使用 clearCacheKeys（推荐）

手动清除

4. 进阶使用

4.1 防止缓存穿透

问题场景

解决方案：空值标记

关键点

4.2 缓存联动机制

核心函数

参数说明

使用示例

联动规则

4.3 批量操作

批量获取

批量设置

批量删除

4.4 权限验证缓存

实际代码示例

5. 架构设计

5.1 整体架构

5.2 提供器选择机制

初始化流程

运行时选择

5.3 监控与统计

获取统计信息

6. 配置说明

6.1 基础配置

6.2 策略配置

默认策略

模块策略

6.3 环境变量

7. API 参考

7.1 核心方法

get - 获取缓存

set - 设置缓存

del - 删除缓存

clearByPattern - 按模式清除

7.2 工具方法

generateCacheKey - 生成缓存键

getCacheKeyPattern - 生成键模式

clearCacheKeys - 统一清除缓存

getModuleEpoch / bumpModuleEpoch - 模块时间戳

7.3 管理 API

获取缓存列表

删除指定缓存

获取统计信息

8. 最佳实践