chanjs 2.7.2 → 2.7.3

package/storage/redis.js

@@ -0,0 +1,258 @@
+/**
+ * 纯 Redis 后端（ioredis 封装）
+ *
+ * ============================================================
+ * 使用方法
+ * ============================================================
+ *
+ * 本模块为纯 Redis 后端，仅负责与 Redis 通信，不包含内存降级逻辑。
+ * 适合明确知道自己需要 Redis 的场景独立使用。
+ *
+ * 1. 独立使用
+ *    import RedisBackend from 'chanjs/helper/redis.js';
+ *    const redis = new RedisBackend({ host: '127.0.0.1', port: 6379 });
+ *    await redis.set('key', 'value', 60000);
+ *    const val = await redis.get('key');
+ *
+ * 2. 需要自动适配（Redis + 内存降级）
+ *    请使用 helper/store.js（适配层）。
+ *
+ * 3. 只需要内存缓存（同步 API）
+ *    请使用 helper/cache.js。
+ *
+ * 4. API（全部返回 Promise）
+ *    - get(key)                         读取
+ *    - set(key, value, ttlMs=60000)     写入（毫秒级 TTL）
+ *    - del(key)                         删除
+ *    - incr(key)                        自增（新建 key 自动附加默认 TTL）
+ *    - incrAndExpire(key, ttlMs)        自增 + 首次设置过期
+ *    - exists(key)                      存在性检查
+ *    - expire(key, ttlMs)               刷新过期时间
+ *    - close()                          关闭连接
+ *
+ * 5. 常量
+ *    - DEFAULT_INCR_TTL = 60_000ms      incr 新建 key 的默认 TTL
+ *
+ * ============================================================
+ *
+ * 设计要点：
+ * 1. 仅负责 Redis 通信，不处理降级（降级逻辑在 store.js 适配层）
+ * 2. 客户端懒加载，第一次调用时建立连接
+ * 3. incr/incrAndExpire 用 SET NX PX 保证原子性（兼容 Redis 2.6.12+）
+ * 4. 连接事件监听，便于排查网络问题
+ */
+
+/**
+ * incr 默认 TTL（毫秒）
+ * 用于 incr 新建 key 时自动附加过期，避免永久占用内存
+ */
+const DEFAULT_INCR_TTL = 60 * 1000;
+
+/**
+ * 纯 Redis 后端
+ * @class RedisBackend
+ */
+class RedisBackend {
+  /**
+   * @param {Object} config - Redis 连接配置
+   * @param {string} [config.host='127.0.0.1'] - Redis 主机
+   * @param {number} [config.port=6379] - Redis 端口
+   * @param {string} [config.password] - Redis 密码
+   * @param {number} [config.db=0] - Redis 数据库
+   * @param {number} [config.connectTimeout=5000] - 连接超时（毫秒）
+   * @param {number} [config.commandTimeout=1000] - 命令超时（毫秒）
+   */
+  constructor(config = {}) {
+    this.config = config;
+    this.client = null;
+    this._initPromise = null;
+  }
+
+  /**
+   * 懒加载 Redis 客户端
+   * @private
+   * @returns {Promise<Object>} ioredis 客户端实例
+   * @throws {Error} 连接失败时抛出
+   */
+  async _ensureClient() {
+    if (this.client) return this.client;
+    if (this._initPromise) return this._initPromise;
+
+    this._initPromise = (async () => {
+      const { default: Redis } = await import('ioredis');
+      this.client = new Redis({
+        host: this.config.host || '127.0.0.1',
+        port: this.config.port || 6379,
+        password: this.config.password || undefined,
+        db: this.config.db || 0,
+        connectTimeout: this.config.connectTimeout || 5000,
+        commandTimeout: this.config.commandTimeout || 1000,
+        retryStrategy: this.config.retryStrategy || ((times) => {
+          if (times > 3) return null;
+          return Math.min(times * 200, 1000);
+        }),
+        lazyConnect: true,
+        maxRetriesPerRequest: 1,
+        enableOfflineQueue: false,
+      });
+
+      this.client.on('error', (err) => {
+        console.error('[Redis] 连接错误:', err.message);
+      });
+
+      this.client.on('connect', () => {
+        console.log(`[Redis] 已连接 ${this.config.host}:${this.config.port}`);
+      });
+
+      this.client.on('reconnecting', () => {
+        console.log('[Redis] 正在重连...');
+      });
+
+      await this.client.connect();
+      return this.client;
+    })();
+
+    try {
+      return await this._initPromise;
+    } catch (err) {
+      this.client = null;
+      this._initPromise = null;
+      throw new Error(`Redis 连接失败: ${err.message}`);
+    }
+  }
+
+  /**
+   * 读取
+   * @param {string} key - 键
+   * @returns {Promise<*|null>} 值（自动 JSON 解析），不存在返回 null
+   */
+  async get(key) {
+    const client = await this._ensureClient();
+    const value = await client.get(key);
+    if (value === null) return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+
+  /**
+   * 写入
+   * @param {string} key - 键
+   * @param {*} value - 值（自动 JSON 序列化）
+   * @param {number} [ttlMs=60000] - TTL 毫秒，<=0 表示永久
+   * @returns {Promise<boolean>} 始终返回 true
+   */
+  async set(key, value, ttlMs = 60000) {
+    const client = await this._ensureClient();
+    const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+    if (ttlMs > 0) {
+      // PX 毫秒级过期
+      await client.set(key, serialized, 'PX', ttlMs);
+    } else {
+      await client.set(key, serialized);
+    }
+    return true;
+  }
+
+  /**
+   * 删除
+   * @param {string} key - 键
+   * @returns {Promise<boolean>} 是否删除了至少 1 条
+   */
+  async del(key) {
+    const client = await this._ensureClient();
+    const result = await client.del(key);
+    return result > 0;
+  }
+
+  /**
+   * 自增，新建 key 自动附加默认 TTL
+   *
+   * 实现方式：SET key 1 PX ttl NX + 分支判断
+   * - NX 选项：只有 key 不存在时才设置（原子操作）
+   * - 设置成功返回 "OK" → 新建 key，返回 1
+   * - 设置失败返回 null → key 已存在，走 INCR 递增（不刷新 TTL）
+   *
+   * 兼容性：SET ... NX PX 是 Redis 2.6.12+ 标准用法，覆盖所有生产环境
+   *
+   * @param {string} key - 键
+   * @returns {Promise<number>} 自增后的值
+   */
+  async incr(key) {
+    const client = await this._ensureClient();
+    // 尝试新建 key 并设置默认 TTL（原子操作）
+    const setResult = await client.set(key, 1, 'PX', DEFAULT_INCR_TTL, 'NX');
+    if (setResult === 'OK') {
+      return 1;  // 新建成功
+    }
+    // key 已存在，INCR 递增（不刷新 TTL）
+    return client.incr(key);
+  }
+
+  /**
+   * 自增并首次设置过期时间
+   * 用于 Rate Limit 场景：第一次访问设置 TTL，后续访问只递增不续期
+   *
+   * @param {string} key - 键
+   * @param {number} ttlMs - TTL 毫秒
+   * @returns {Promise<number>} 自增后的值
+   */
+  async incrAndExpire(key, ttlMs) {
+    const client = await this._ensureClient();
+    // 尝试新建 key 并设置指定 TTL（原子操作）
+    const setResult = await client.set(key, 1, 'PX', ttlMs, 'NX');
+    if (setResult === 'OK') {
+      return 1;  // 新建成功，TTL 已设置
+    }
+    // key 已存在，INCR 递增（不刷新 TTL）
+    return client.incr(key);
+  }
+
+  /**
+   * 存在性检查
+   * @param {string} key - 键
+   * @returns {Promise<boolean>}
+   */
+  async exists(key) {
+    const client = await this._ensureClient();
+    const result = await client.exists(key);
+    return result === 1;
+  }
+
+  /**
+   * 刷新过期时间
+   * @param {string} key - 键
+   * @param {number} ttlMs - TTL 毫秒
+   * @returns {Promise<boolean>} 是否设置成功
+   */
+  async expire(key, ttlMs) {
+    const client = await this._ensureClient();
+    return client.pexpire(key, ttlMs);
+  }
+
+  /**
+   * 关闭连接
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (this.client) {
+      await this.client.quit();
+      this.client = null;
+      this._initPromise = null;
+    }
+  }
+
+  /**
+   * 获取客户端状态（诊断用）
+   * @returns {string} 'idle' | 'ready' | 'connecting' | 'closed'
+   */
+  getStatus() {
+    if (!this.client) return 'idle';
+    return this.client.status || 'unknown';
+  }
+}
+
+export { DEFAULT_INCR_TTL };
+export default RedisBackend;

package/storage/store.js

@@ -0,0 +1,266 @@
+/**
+ * 存储适配层
+ * 自动选择后端：内存（cache.js）或 Redis（redis.js），并支持运行时降级
+ *
+ * ============================================================
+ * 使用方法
+ * ============================================================
+ *
+ * 1. 内存模式（默认，零配置开箱即用）
+ *    适用：单机部署、中小流量
+ *    上限：10 万条约 20MB，超出 LRU 淘汰
+ *    底层：基于 helper/cache.js（同步 API 被包装为异步）
+ *
+ * 2. Redis 模式（生产推荐，多机共享）
+ *    启用方式：设置环境变量 REDIS_ENABLED=true
+ *    默认连接：chancms-redis:6379
+ *    可通过环境变量覆盖：
+ *      REDIS_ENABLED=true
+ *      REDIS_HOST=127.0.0.1
+ *      REDIS_PORT=6379
+ *      REDIS_PASSWORD=xxx
+ *      REDIS_DB=0
+ *    底层：基于 helper/redis.js（纯 Redis 后端）
+ *
+ * 3. 自动降级（容灾）
+ *    - 初始化时 Redis 连接失败 → 自动降级到内存模式
+ *    - 运行中 Redis 断连 → 单次操作自动 fallback 到内存执行，不中断业务
+ *    - 后续操作仍会尝试 Redis（自动恢复）
+ *
+ * 4. API（全部返回 Promise）
+ *    - init(config)                      初始化（应用启动时调用一次）
+ *    - get(key)                          读取
+ *    - set(key, value, ttlMs=60000)      写入（毫秒级 TTL）
+ *    - del(key)                          删除
+ *    - incr(key)                         自增（新建 key 自动附加默认 TTL）
+ *    - incrAndExpire(key, ttlMs)         自增 + 首次设置过期
+ *    - exists(key)                       存在性检查
+ *    - expire(key, ttlMs)                刷新过期时间
+ *    - getInfo()                         诊断信息（当前后端/连接状态/内存大小）
+ *    - close()                           关闭连接
+ *
+ * ============================================================
+ *
+ * 架构关系：
+ *
+ *   cache.js  (同步内存)   ◄──── 独立可用，含 incr/incrAndExpire/expire
+ *   redis.js (异步 Redis) ◄──── 独立可用，纯 Redis 后端
+ *   store.js (适配层)     ◄──── 组合 cache + redis，自动选后端 + 降级
+ *
+ * 适用场景：
+ * - 只想要内存缓存（同步）：用 cache.js
+ * - 只想要 Redis：用 redis.js
+ * - 想要自动适配（Redis + 降级）：用 store.js（本模块）
+ */
+
+import { cache, DEFAULT_INCR_TTL } from "./cache.js";
+import RedisBackend from "./redis.js";
+
+export { DEFAULT_INCR_TTL };
+
+/**
+ * 内存后端包装器
+ * 把同步的 cache.js API 包装成异步，对齐 RedisBackend 的接口
+ * 直接复用 cache.js 的 incr/incrAndExpire/expire，保证 TTL 行为与 Redis 一致
+ * @private
+ */
+class MemoryAdapter {
+  /**
+   * @param {Object} [options] - 配置
+   * @param {Object} [options.cache] - 自定义 Cache 实例（默认用全局单例）
+   */
+  constructor(options = {}) {
+    this.cache = options.cache || cache;
+  }
+
+  async get(key) {
+    return this.cache.get(key);
+  }
+
+  async set(key, value, ttlMs = 60000) {
+    this.cache.set(key, value, ttlMs);
+    return true;
+  }
+
+  async del(key) {
+    return this.cache.del(key);
+  }
+
+  async incr(key) {
+    // 直接调用 cache.incr，保证 TTL 不被刷新（与 Redis INCR 行为对齐）
+    return this.cache.incr(key);
+  }
+
+  async incrAndExpire(key, ttlMs) {
+    return this.cache.incrAndExpire(key, ttlMs);
+  }
+
+  async exists(key) {
+    return this.cache.has(key);
+  }
+
+  async expire(key, ttlMs) {
+    return this.cache.expire(key, ttlMs);
+  }
+
+  size() {
+    return this.cache.size();
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+}
+
+/**
+ * 存储适配器
+ * @class Store
+ * 自动选择后端：Redis（启用且可用时）或 内存（默认/降级时）
+ * 运行时 Redis 异常自动 fallback 到内存，不中断业务
+ */
+class Store {
+  constructor() {
+    // 内存后端（始终存在，作为降级兜底）
+    this.memory = new MemoryAdapter();
+    // Redis 后端（按需创建）
+    this.redis = null;
+    // 当前是否使用 Redis
+    this.useRedis = false;
+    // 是否已初始化
+    this._initialized = false;
+    // 降级日志冷却时间，避免高频刷屏
+    this._fallbackCooldown = 0;
+  }
+
+  /**
+   * 初始化适配器
+   * 必须在应用启动时调用
+   * @param {Object} config - 应用配置
+   * @param {boolean} [config.REDIS_ENABLED=false] - 是否启用 Redis
+   * @param {Object} [config.REDIS] - Redis 连接配置
+   */
+  async init(config = {}) {
+    if (this._initialized) return;
+
+    if (config.REDIS_ENABLED) {
+      this.redis = new RedisBackend(config.REDIS || {});
+      // 预热连接，失败则降级到内存模式
+      try {
+        // 触发连接
+        await this.redis._ensureClient();
+        this.useRedis = true;
+        console.log('[Store] 已启用 Redis 后端');
+      } catch (err) {
+        console.warn(`[Store] Redis 不可用，降级到内存模式: ${err.message}`);
+        this.useRedis = false;
+        this.redis = null;
+      }
+    } else {
+      console.log('[Store] 使用内存模式（Map+TTL，上限 10万条/约20MB）');
+    }
+
+    this._initialized = true;
+  }
+
+  /**
+   * 运行时异常兜底：Redis 操作抛错时临时切内存执行
+   * 不中断业务，打印降级日志（带冷却避免刷屏）
+   * @private
+   * @param {string} method - 方法名
+   * @param {Array} args - 参数
+   * @param {*} fallbackValue - 内存 fallback 失败时的兜底返回值
+   * @returns {*} 操作结果
+   */
+  async _safeCall(method, args, fallbackValue) {
+    // 内存模式直接执行
+    if (!this.useRedis) {
+      return this.memory[method](...args);
+    }
+
+    try {
+      return await this.redis[method](...args);
+    } catch (e) {
+      // Redis 异常，降级到内存执行
+      this._logFallback(method, e);
+      try {
+        return await this.memory[method](...args);
+      } catch (memErr) {
+        // 内存也失败（理论上极少发生），返回兜底值
+        console.error(`[Store] 内存 fallback 也失败: ${memErr.message}`);
+        return fallbackValue;
+      }
+    }
+  }
+
+  /**
+   * 打印降级日志（带冷却，1 秒内最多一次）
+   * @private
+   */
+  _logFallback(method, err) {
+    const now = Date.now();
+    if (now - this._fallbackCooldown > 1000) {
+      this._fallbackCooldown = now;
+      console.warn(`[Store] Redis ${method} 失败，临时降级内存执行: ${err.message}`);
+    }
+  }
+
+  async get(key) {
+    return this._safeCall('get', [key], null);
+  }
+
+  async set(key, value, ttlMs = 60000) {
+    return this._safeCall('set', [key, value, ttlMs], false);
+  }
+
+  async del(key) {
+    return this._safeCall('del', [key], false);
+  }
+
+  async incr(key) {
+    return this._safeCall('incr', [key], 0);
+  }
+
+  async incrAndExpire(key, ttlMs) {
+    return this._safeCall('incrAndExpire', [key, ttlMs], 0);
+  }
+
+  async exists(key) {
+    return this._safeCall('exists', [key], false);
+  }
+
+  async expire(key, ttlMs) {
+    return this._safeCall('expire', [key, ttlMs], false);
+  }
+
+  /**
+   * 获取当前后端信息（用于诊断）
+   * @returns {Object} { mode, memorySize, redisConnected }
+   */
+  getInfo() {
+    return {
+      mode: this.useRedis ? 'redis' : 'memory',
+      memorySize: this.memory.size(),
+      redisConnected: this.useRedis && this.redis?.getStatus() === 'ready',
+    };
+  }
+
+  /**
+   * 关闭连接
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (this.redis) {
+      try {
+        await this.redis.close();
+      } catch (e) {
+        console.warn(`[Store] 关闭 Redis 连接失败: ${e.message}`);
+      }
+    }
+    this.memory.clear();
+  }
+}
+
+// 全局单例
+export const store = new Store();
+
+export default Store;