chanjs 2.7.3 → 2.7.5

package/storage/redis.js

@@ -1,258 +1,200 @@
-/**
- * 纯 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. 连接事件监听，便于排查网络问题
- */
+import logger from "../utils/logger.js";
 
-/**
- * incr 默认 TTL（毫秒）
- * 用于 incr 新建 key 时自动附加过期，避免永久占用内存
- */
-const DEFAULT_INCR_TTL = 60 * 1000;
+// Redis固定常量统一管理，冻结防止修改
+const REDIS_CONST = Object.freeze({
+  DEFAULT_INCR_TTL: 60 * 1000,       // incr新建key默认过期时间 60s
+  DEFAULT_CONNECT_TIMEOUT: 5000,     // 连接超时5秒
+  DEFAULT_CMD_TIMEOUT: 1000,         // 单条命令执行超时1秒
+  MAX_RETRY_TIMES: 3,                // 重连最大尝试次数
+});
+export const DEFAULT_INCR_TTL = REDIS_CONST.DEFAULT_INCR_TTL;
 
 /**
- * 纯 Redis 后端
- * @class RedisBackend
+ * Redis纯存储后端封装（基于ioredis）
+ * 1. 懒加载连接：首次调用才创建客户端，启动不阻塞进程
+ * 2. incr：先INCR，返回1（新建/过期重建）则补PEXPIRE，递增不刷新TTL，无竞态
+ * 3. 自动序列化/反序列化JSON，普通字符串直接透传
+ * 4. 关闭离线队列、单次请求仅重试1次，故障快速抛出供上层降级
  */
 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] - 命令超时（毫秒）
+   * @param {Object} cfg Redis连接配置 host/port/password/db/超时/重连策略
    */
-  constructor(config = {}) {
-    this.config = config;
-    this.client = null;
-    this._initPromise = null;
+  constructor(cfg = {}) {
+    this.cfg = cfg;          // 连接配置缓存
+    this.client = null;      // ioredis实例
+    this.initTask = null;    // 连接初始化Promise，防止并发重复建连
   }
 
   /**
-   * 懒加载 Redis 客户端
-   * @private
-   * @returns {Promise<Object>} ioredis 客户端实例
-   * @throws {Error} 连接失败时抛出
+   * 内部工具：懒加载获取Redis客户端，连接失败抛出异常
+   * 外部store适配层可调用，去掉#私有标识解决跨文件访问报错
    */
-  async _ensureClient() {
+  async _getClient() {
+    // 已有客户端直接返回
     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;
+    // 正在初始化，等待初始化Promise
+    if (this.initTask) return this.initTask;
+
+    // 开始异步初始化连接
+    this.initTask = (async () => {
+      // 动态导入ioredis，避免未安装Redis依赖时报启动错误
+      const { default: Redis } = await import("ioredis");
+      const client = new Redis({
+        host: this.cfg.host ?? "127.0.0.1",
+        port: this.cfg.port ?? 6379,
+        password: this.cfg.password || undefined,
+        db: this.cfg.db ?? 0,
+        connectTimeout: this.cfg.connectTimeout ?? REDIS_CONST.DEFAULT_CONNECT_TIMEOUT,
+        commandTimeout: this.cfg.commandTimeout ?? REDIS_CONST.DEFAULT_CMD_TIMEOUT,
+        lazyConnect: true,                  // 实例化不立即连接，手动connect
+        maxRetriesPerRequest: 1,            // 单条命令失败仅重试1次
+        enableOfflineQueue: false,           // 断连后不堆积请求，直接报错
+        retryStrategy: this.cfg.retryStrategy ?? ((times) => {
+          // 超过最大重试次数返回null，停止重连
+          if (times > REDIS_CONST.MAX_RETRY_TIMES) return null;
+          // 重试间隔阶梯增长，最大1秒
           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] 正在重连...');
-      });
+      // 连接事件监听，打印日志
+      client
+        .on("error", err => logger.error("[Redis] 连接异常", err.message))
+        .on("connect", () => logger.info(`[Redis] 已连接 ${this.cfg.host}:${this.cfg.port}`))
+        .on("reconnecting", () => logger.info("[Redis] 正在重连"));
 
-      await this.client.connect();
-      return this.client;
+      // 手动发起连接
+      await client.connect();
+      this.client = client;
+      return client;
     })();
 
     try {
-      return await this._initPromise;
+      return await this.initTask;
     } catch (err) {
+      // 连接失败清空缓存，下次调用重新初始化
       this.client = null;
-      this._initPromise = null;
-      throw new Error(`Redis 连接失败: ${err.message}`);
+      this.initTask = null;
+      throw new Error(`Redis连接失败: ${err.message}`);
     }
   }
 
   /**
-   * 读取
-   * @param {string} key - 键
-   * @returns {Promise<*|null>} 值（自动 JSON 解析），不存在返回 null
+   * 读取缓存
+   * @param {string} key 缓存键名
+   * @returns {any|null} 解析后数据，不存在返回null
    */
   async get(key) {
-    const client = await this._ensureClient();
-    const value = await client.get(key);
-    if (value === null) return null;
+    const cli = await this._getClient();
+    const raw = await cli.get(key);
+    if (raw === null) return null;
     try {
-      return JSON.parse(value);
+      // JSON字符串自动解析
+      return JSON.parse(raw);
     } catch {
-      return value;
+      // 普通字符串直接返回
+      return raw;
     }
   }
 
   /**
-   * 写入
-   * @param {string} key - 键
-   * @param {*} value - 值（自动 JSON 序列化）
-   * @param {number} [ttlMs=60000] - TTL 毫秒，<=0 表示永久
-   * @returns {Promise<boolean>} 始终返回 true
+   * 写入缓存
+   * @param {string} key 键名
+   * @param {any} val 存储值
+   * @param {number} ttlMs 过期毫秒，<=0永久存储
+   * @returns {boolean} 固定返回true
    */
-  async set(key, value, ttlMs = 60000) {
-    const client = await this._ensureClient();
-    const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+  async set(key, val, ttlMs = 60000) {
+    const cli = await this._getClient();
+    const data = typeof val === "string" ? val : JSON.stringify(val);
     if (ttlMs > 0) {
-      // PX 毫秒级过期
-      await client.set(key, serialized, 'PX', ttlMs);
+      await cli.set(key, data, "PX", ttlMs);
     } else {
-      await client.set(key, serialized);
+      await cli.set(key, data);
     }
     return true;
   }
 
   /**
-   * 删除
-   * @param {string} key - 键
-   * @returns {Promise<boolean>} 是否删除了至少 1 条
+   * 删除key
+   * @param {string} key 键名
+   * @returns {boolean} 是否删除成功
    */
   async del(key) {
-    const client = await this._ensureClient();
-    const result = await client.del(key);
-    return result > 0;
+    const cli = await this._getClient();
+    const cnt = await cli.del(key);
+    return cnt > 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>} 自增后的值
+   * 自增计数，新建key使用全局默认TTL
+   * 纯ioredis方案：先INCR，返回1（key新建/过期重建）则补PEXPIRE，递增不刷新TTL
+   * 解决原 SET NX + INCR 之间 key 过期导致的无 TTL 内存泄漏竞态
+   * @param {string} key 计数key
+   * @returns {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);
+    const cli = await this._getClient();
+    const count = await cli.incr(key);
+    // count===1 说明 key 是新建的（首次或过期重建），补设 TTL；递增(count>1)不刷新 TTL
+    if (count === 1) await cli.pexpire(key, REDIS_CONST.DEFAULT_INCR_TTL);
+    return count;
   }
 
   /**
-   * 自增并首次设置过期时间
-   * 用于 Rate Limit 场景：第一次访问设置 TTL，后续访问只递增不续期
-   *
-   * @param {string} key - 键
-   * @param {number} ttlMs - TTL 毫秒
-   * @returns {Promise<number>} 自增后的值
+   * 限流专用自增，自定义新建key过期时间
+   * @param {string} key 计数key
+   * @param {number} ttlMs 窗口过期时间
+   * @returns {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);
+    const cli = await this._getClient();
+    const count = await cli.incr(key);
+    if (count === 1) await cli.pexpire(key, ttlMs);
+    return count;
   }
 
   /**
-   * 存在性检查
-   * @param {string} key - 键
-   * @returns {Promise<boolean>}
+   * 判断key是否存在
+   * @param {string} key 键名
+   * @returns {boolean} true存在 / false不存在
    */
   async exists(key) {
-    const client = await this._ensureClient();
-    const result = await client.exists(key);
-    return result === 1;
+    const cli = await this._getClient();
+    const res = await cli.exists(key);
+    return res === 1;
   }
 
   /**
-   * 刷新过期时间
-   * @param {string} key - 键
-   * @param {number} ttlMs - TTL 毫秒
-   * @returns {Promise<boolean>} 是否设置成功
+   * 主动刷新key过期时间
+   * @param {string} key 键名
+   * @param {number} ttlMs 新过期毫秒
+   * @returns {number} redis原生返回值
    */
   async expire(key, ttlMs) {
-    const client = await this._ensureClient();
-    return client.pexpire(key, ttlMs);
+    const cli = await this._getClient();
+    return cli.pexpire(key, ttlMs);
   }
 
   /**
-   * 关闭连接
-   * @returns {Promise<void>}
+   * 关闭Redis连接，清空实例缓存
    */
   async close() {
-    if (this.client) {
-      await this.client.quit();
-      this.client = null;
-      this._initPromise = null;
-    }
+    if (!this.client) return;
+    await this.client.quit();
+    this.client = null;
+    this.initTask = null;
   }
 
   /**
-   * 获取客户端状态（诊断用）
-   * @returns {string} 'idle' | 'ready' | 'connecting' | 'closed'
+   * 获取客户端连接状态，用于上层诊断监控
+   * @returns {'idle'|'ready'|'connecting'|'closed'}
    */
   getStatus() {
-    if (!this.client) return 'idle';
-    return this.client.status || 'unknown';
+    if (!this.client) return "idle";
+    return this.client.status ?? "unknown";
   }
 }
 
-export { DEFAULT_INCR_TTL };
-export default RedisBackend;
+export default RedisBackend;