chanjs 2.7.4 → 2.7.6

package/storage/store.js

@@ -1,266 +1,241 @@
-/**
- * 存储适配层
- * 自动选择后端：内存（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";
+import logger from "../utils/logger.js";
 
 export { DEFAULT_INCR_TTL };
 
+// Redis 故障日志防抖间隔：避免高频失败时刷屏
+const FALLBACK_LOG_COOLDOWN = 1000;
+// 熔断触发阈值：Redis 连续失败次数达到此值进入熔断
+const CIRCUIT_THRESHOLD = 5;
+// 熔断冷却时长：熔断开启后此段时间内所有请求直接走内存
+const CIRCUIT_COOLDOWN = 30000;
+
 /**
- * 内存后端包装器
- * 把同步的 cache.js API 包装成异步，对齐 RedisBackend 的接口
- * 直接复用 cache.js 的 incr/incrAndExpire/expire，保证 TTL 行为与 Redis 一致
- * @private
+ * 内存缓存适配器
+ * 内部 LRU Cache 是同步方法，对外统一包装为 Promise/async 风格，
+ * 保持与 RedisAdapter 接口形状一致，让 Store 内部用同一套 _safeExec 调度。
  */
 class MemoryAdapter {
-  /**
-   * @param {Object} [options] - 配置
-   * @param {Object} [options.cache] - 自定义 Cache 实例（默认用全局单例）
-   */
-  constructor(options = {}) {
-    this.cache = options.cache || cache;
-  }
+  constructor(instance = cache) { this._cache = instance; }
 
-  async get(key) {
-    return this.cache.get(key);
-  }
+  /** 读取缓存值，无值返回 null */
+  get(key) { return this._cache.get(key); }
 
-  async set(key, value, ttlMs = 60000) {
-    this.cache.set(key, value, ttlMs);
-    return true;
-  }
+  /**
+   * 写入缓存
+   * @param {string} key 键
+   * @param {*} val 值
+   * @param {number} [ttlMs=60000] 过期时间（毫秒）
+   * @returns {boolean} 写入成功
+   */
+  set(key, val, ttlMs = 60000) { this._cache.set(key, val, ttlMs); return true; }
 
-  async del(key) {
-    return this.cache.del(key);
-  }
+  /** 删除指定 key */
+  del(key) { return this._cache.del(key); }
 
-  async incr(key) {
-    // 直接调用 cache.incr，保证 TTL 不被刷新（与 Redis INCR 行为对齐）
-    return this.cache.incr(key);
-  }
+  /** 原子自增；新 key 起始值 1 */
+  incr(key) { return this._cache.incr(key); }
 
-  async incrAndExpire(key, ttlMs) {
-    return this.cache.incrAndExpire(key, ttlMs);
-  }
+  /**
+   * 原子自增并自动设置 TTL（限流场景专用）
+   * @param {string} key 键
+   * @param {number} ttlMs 过期时间（毫秒）
+   */
+  incrAndExpire(key, ttlMs) { return this._cache.incrAndExpire(key, ttlMs); }
 
-  async exists(key) {
-    return this.cache.has(key);
-  }
+  /** 判断 key 是否存在 */
+  exists(key) { return this._cache.has(key); }
 
-  async expire(key, ttlMs) {
-    return this.cache.expire(key, ttlMs);
-  }
+  /**
+   * 给已存在的 key 设置过期时间
+   * @returns {boolean} key 不存在时返回 false
+   */
+  expire(key, ttlMs) { return this._cache.expire(key, ttlMs); }
 
-  size() {
-    return this.cache.size();
-  }
+  /** 获取当前缓存条目数 */
+  size() { return this._cache.size(); }
 
-  clear() {
-    this.cache.clear();
-  }
+  /** 清空所有缓存 */
+  clear() { this._cache.clear(); }
 }
 
 /**
- * 存储适配器
- * @class Store
- * 自动选择后端：Redis（启用且可用时）或 内存（默认/降级时）
- * 运行时 Redis 异常自动 fallback 到内存，不中断业务
+ * 存储统一适配层（项目全局唯一入口）
+ *
+ * 设计目标：
+ *   1. 业务侧无需关心底层是 Redis 还是内存，统一调用 store.xxx()
+ *   2. Redis 故障时自动降级到内存，熔断保护避免雪崩
+ *   3. 接口形状与 Redis 客户端保持一致，零业务侵入
+ *
+ * 降级策略：
+ *   - Redis 不可用 → 启动时直接走内存（useRedis=false）
+ *   - Redis 运行时挂掉 → 连续失败 5 次触发熔断，30s 冷却期内全部走内存
+ *   - 冷却期过后自动尝试 Redis，成功则关闭熔断，失败则续期
+ *
+ * 兜底语义：所有方法失败时返回安全默认值（null/false/0），不抛异常上抛
  */
 class Store {
   constructor() {
-    // 内存后端（始终存在，作为降级兜底）
     this.memory = new MemoryAdapter();
-    // Redis 后端（按需创建）
     this.redis = null;
-    // 当前是否使用 Redis
     this.useRedis = false;
-    // 是否已初始化
     this._initialized = false;
-    // 降级日志冷却时间，避免高频刷屏
-    this._fallbackCooldown = 0;
+    this._lastFallbackLog = 0;
+    // 熔断状态机：broken=是否熔断中 / failures=连续失败计数 / lastFailAt=最近失败时间戳
+    this._circuit = { broken: false, failures: 0, lastFailAt: 0 };
   }
 
   /**
-   * 初始化适配器
-   * 必须在应用启动时调用
-   * @param {Object} config - 应用配置
-   * @param {boolean} [config.REDIS_ENABLED=false] - 是否启用 Redis
-   * @param {Object} [config.REDIS] - Redis 连接配置
+   * 初始化存储后端
+   * @param {object} [cfg={}] 配置
+   * @param {boolean} [cfg.REDIS_ENABLED] 是否启用 Redis
+   * @param {object} [cfg.REDIS] Redis 连接配置（host/port/password/db 等）
    */
-  async init(config = {}) {
+  async init(cfg = {}) {
     if (this._initialized) return;
+    this._initialized = true;
 
-    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）');
+    if (!cfg.REDIS_ENABLED) {
+      logger.info("[Store] 运行内存存储模式（10w容量TTL-LRU）");
+      return;
     }
 
-    this._initialized = true;
+    this.redis = new RedisBackend(cfg.REDIS ?? {});
+    try {
+      await this.redis._getClient();
+      this.useRedis = true;
+      logger.info("[Store] 已启用Redis分布式存储后端");
+    } catch (err) {
+      logger.warn(`[Store] Redis连接失败，自动降级内存：${err.message}`);
+      this.useRedis = false;
+      this.redis = null;
+    }
   }
 
   /**
-   * 运行时异常兜底：Redis 操作抛错时临时切内存执行
-   * 不中断业务，打印降级日志（带冷却避免刷屏）
-   * @private
-   * @param {string} method - 方法名
-   * @param {Array} args - 参数
-   * @param {*} fallbackValue - 内存 fallback 失败时的兜底返回值
-   * @returns {*} 操作结果
+   * 内部统一调度：优先 Redis，异常自动切换内存
+   * @param {string} method 适配器方法名
+   * @param {Array} args 参数数组
+   * @param {*} fallbackVal Redis + 内存全部失败时的兜底返回值
+   * @returns {Promise<*>}
    */
-  async _safeCall(method, args, fallbackValue) {
-    // 内存模式直接执行
-    if (!this.useRedis) {
+  async _safeExec(method, args, fallbackVal) {
+    // 1. 未启用 Redis → 直接走内存
+    if (!this.useRedis) return this.memory[method](...args);
+
+    // 2. 熔断中且冷却期未过 → 直接走内存，避免对死掉的 Redis 持续重试
+    if (this._circuit.broken && Date.now() - this._circuit.lastFailAt < CIRCUIT_COOLDOWN) {
       return this.memory[method](...args);
     }
 
+    // 3. 正常路径：尝试 Redis
     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;
+      const result = await this.redis[method](...args);
+      // 成功后重置熔断状态
+      this._circuit.failures = 0;
+      if (this._circuit.broken) {
+        this._circuit.broken = false;
+        logger.info("[Store] Redis 已恢复，熔断关闭");
+      }
+      return result;
+    } catch (err) {
+      // 4. Redis 调用失败：累计失败次数，必要时触发熔断
+      this._printFallbackLog(method, err);
+      this._circuit.failures++;
+      this._circuit.lastFailAt = Date.now();
+      if (this._circuit.failures >= CIRCUIT_THRESHOLD && !this._circuit.broken) {
+        this._circuit.broken = true;
+        logger.warn(`[Store] Redis 连续失败${this._circuit.failures}次，触发熔断：${CIRCUIT_COOLDOWN}ms 后自动重试`);
+      }
+      // 5. 内存兜底：再失败则返回安全默认值，不抛异常
+      try { return await this.memory[method](...args); }
+      catch (memErr) {
+        logger.error(`[Store] 内存兜底调用${method}失败：${memErr.message}`);
+        return fallbackVal;
       }
     }
   }
 
   /**
-   * 打印降级日志（带冷却，1 秒内最多一次）
-   * @private
+   * 打印降级日志（防抖）
+   * 高频失败场景下避免日志被刷爆，1s 内只打一次
    */
-  _logFallback(method, err) {
+  _printFallbackLog(method, err) {
     const now = Date.now();
-    if (now - this._fallbackCooldown > 1000) {
-      this._fallbackCooldown = now;
-      console.warn(`[Store] Redis ${method} 失败，临时降级内存执行: ${err.message}`);
-    }
+    if (now - this._lastFallbackLog < FALLBACK_LOG_COOLDOWN) return;
+    this._lastFallbackLog = now;
+    logger.warn(`[Store] Redis ${method} 请求异常，临时切换内存：${err.message}`);
   }
 
-  async get(key) {
-    return this._safeCall('get', [key], null);
-  }
+  // ===================== 统一对外 API =====================
+  // 业务侧统一通过 store.xxx() 调用，底层后端透明
 
-  async set(key, value, ttlMs = 60000) {
-    return this._safeCall('set', [key, value, ttlMs], false);
-  }
+  /** 读取缓存；无值或异常返回 null */
+  get(key) { return this._safeExec("get", [key], null); }
 
-  async del(key) {
-    return this._safeCall('del', [key], false);
-  }
+  /**
+   * 写入缓存
+   * @param {string} key
+   * @param {*} val
+   * @param {number} [ttlMs=60000] 过期毫秒数
+   * @returns {Promise<boolean>}
+   */
+  set(key, val, ttlMs = 60000) { return this._safeExec("set", [key, val, ttlMs], false); }
 
-  async incr(key) {
-    return this._safeCall('incr', [key], 0);
-  }
+  /** 删除指定 key；不存在或异常返回 false */
+  del(key) { return this._safeExec("del", [key], false); }
 
-  async incrAndExpire(key, ttlMs) {
-    return this._safeCall('incrAndExpire', [key, ttlMs], 0);
-  }
+  /** 原子自增；首次返回 1，异常返回 0 */
+  incr(key) { return this._safeExec("incr", [key], 0); }
 
-  async exists(key) {
-    return this._safeCall('exists', [key], false);
-  }
+  /**
+   * 原子自增并设置 TTL（限流/计数场景专用）
+   * @param {string} key
+   * @param {number} ttlMs
+   * @returns {Promise<number>}
+   */
+  incrAndExpire(key, ttlMs) { return this._safeExec("incrAndExpire", [key, ttlMs], 0); }
 
-  async expire(key, ttlMs) {
-    return this._safeCall('expire', [key, ttlMs], false);
-  }
+  /** 判断 key 是否存在；异常返回 false */
+  exists(key) { return this._safeExec("exists", [key], false); }
 
   /**
-   * 获取当前后端信息（用于诊断）
-   * @returns {Object} { mode, memorySize, redisConnected }
+   * 给已存在 key 设置过期时间
+   * @param {string} key
+   * @param {number} ttlMs
+   * @returns {Promise<boolean>}
+   */
+  expire(key, ttlMs) { return this._safeExec("expire", [key, ttlMs], false); }
+
+  /**
+   * 获取诊断信息（健康检查/监控上报用）
+   * @returns {{mode: string, memorySize: number, redisConnected: boolean, circuitOpen: boolean}}
    */
   getInfo() {
+    let mode = "memory";
+    if (this.useRedis) mode = this._circuit.broken ? "memory(fallback:redis熔断)" : "redis";
     return {
-      mode: this.useRedis ? 'redis' : 'memory',
+      mode,
       memorySize: this.memory.size(),
-      redisConnected: this.useRedis && this.redis?.getStatus() === 'ready',
+      redisConnected: this.useRedis && this.redis?.getStatus() === "ready",
+      circuitOpen: this._circuit.broken,
     };
   }
 
   /**
-   * 关闭连接
-   * @returns {Promise<void>}
+   * 关闭并释放资源（优雅停机时调用）
+   * Redis 异常不阻断，内存缓存直接清空
    */
   async close() {
     if (this.redis) {
-      try {
-        await this.redis.close();
-      } catch (e) {
-        console.warn(`[Store] 关闭 Redis 连接失败: ${e.message}`);
-      }
+      try { await this.redis.close(); }
+      catch (e) { logger.warn(`[Store] Redis关闭异常：${e.message}`); }
     }
     this.memory.clear();
   }
 }
 
-// 全局单例
+// 全局单例：业务侧统一通过 `import { store } from "chanjs"` 访问
 export const store = new Store();
-
 export default Store;

package/utils/data-parse.js

@@ -1,186 +1,42 @@
-/**
- * 解析 JSON 字符串或返回原始值
- * @param {string} str - 要解析的字符串
- * @returns {Object|string} 解析后的对象或原始字符串
- * @description
- * 尝试将字符串解析为 JSON 对象
- * 如果解析失败或结果不是对象，则返回原始字符串
- * @example
- * const obj = dataParse('{"name":"张三","age":25}');
- * console.log(obj); // { name: '张三', age: 25 }
- * 
- * const str = dataParse('hello');
- * console.log(str); // 'hello'
- */
-export function dataParse(str) {
-  try {
-    const data = JSON.parse(str);
-    if (typeof data === 'object' && data !== null) {
-      return data;
-    }
-  } catch (e) {
-    return str;
-  }
-  return str;
-}
-
-/**
- * 将数组转换为对象
- * @param {Array<Object>} arr - 要转换的数组
- * @param {string} [keyField="config_key"] - 作为对象键的字段名
- * @param {string} [valueField="config_value"] - 作为对象值的字段名
- * @returns {Object} 转换后的对象
- * @description
- * 将数组中的每个元素转换为一个键值对
- * 键由 keyField 指定，值由 valueField 指定
- * @example
- * const arr = [
- *   { config_key: 'app.name', config_value: 'MyApp' },
- *   { config_key: 'app.port', config_value: '3000' }
- * ];
- * const obj = arrToObj(arr);
- * console.log(obj);
- * // { 'app.name': 'MyApp', 'app.port': '3000' }
- */
-export const arrToObj = (
-  arr,
-  keyField = "config_key",
-  valueField = "config_value"
-) => {
-  if (!Array.isArray(arr)) {
-    console.error("[arrToObj] 输入必须是数组");
-    return {};
-  }
-
-  return arr.reduce((result, item) => {
-    if (item && typeof item === "object") {
-      const key = item[keyField];
-      const value = item[valueField];
-      if (key !== undefined && value !== undefined) {
-        result[key] = value;
-      }
-    }
-    return result;
-  }, {});
-};
-
-/**
- * 解析对象中的 JSON 字符串字段
- * @param {Object} obj - 要处理的对象
- * @returns {Object} 处理后的对象
- * @description
- * 遍历对象的所有属性，将 JSON 字符串格式的值解析为对象
- * 只解析以 '{' 或 '[' 开头的字符串值
- * @example
- * const obj = {
- *   name: '张三',
- *   settings: '{"theme":"dark","lang":"zh"}',
- *   tags: '["a","b","c"]'
- * };
- * const result = parseJsonFields(obj);
- * console.log(result);
- * // { name: '张三', settings: { theme: 'dark', lang: 'zh' }, tags: ['a', 'b', 'c'] }
- */
-export function parseJsonFields(obj) {
-  const result = {};
-  for (const key in obj) {
-    if (!obj.hasOwnProperty(key)) continue;
-    const value = obj[key];
-    if (
-      typeof value === "string" &&
-      (value.startsWith("{") || value.startsWith("["))
-    ) {
-      try {
-        result[key] = JSON.parse(value);
-      } catch (e) {
-        console.error(`JSON parse failed for field: ${key}`, e);
-        result[key] = value;
-      }
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result;
-}
-
-/**
- * 构建树形结构
- * @param {Array<Object>} arr - 扁平化的数据数组
- * @param {number|string} [pid=0] - 根节点的父 ID
- * @param {string} [idKey="id"] - ID 字段名
- * @param {string} [pidKey="pid"] - 父 ID 字段名
- * @param {string} [childrenKey="children"] - 子节点字段名
- * @returns {Array<Object>} 树形结构数组
- * @description
- * 将扁平化的数组转换为树形结构
- * 支持自定义 ID 和父 ID 字段名
- * 自动检测并跳过循环引用
- * 自动清理空的 children 数组
- * @example
- * const arr = [
- *   { id: 1, pid: 0, name: '根节点' },
- *   { id: 2, pid: 1, name: '子节点1' },
- *   { id: 3, pid: 1, name: '子节点2' },
- *   { id: 4, pid: 2, name: '孙节点' }
- * ];
- * const tree = buildTree(arr);
- * console.log(tree);
- * // [
- * //   { id: 1, pid: 0, name: '根节点', children: [
- * //     { id: 2, pid: 1, name: '子节点1', children: [
- * //       { id: 4, pid: 2, name: '孙节点' }
- * //     ]},
- * //     { id: 3, pid: 1, name: '子节点2' }
- * //   ]}
- * // ]
- */
-export function buildTree(
-  arr,
-  pid = 0,
-  idKey = "id",
-  pidKey = "pid",
-  childrenKey = "children"
-) {
-  if (!Array.isArray(arr) || arr.length === 0) return [];
-
-  const nodeMap = new Map();
-  const tree = [];
-  const visited = new Set();
-
-  for (const item of arr) {
-    if (item && typeof item === 'object') {
-      nodeMap.set(item[idKey], { ...item, [childrenKey]: [] });
-    }
-  }
-
-  for (const node of nodeMap.values()) {
-    const parentId = node[pidKey];
-    if (parentId === pid || parentId == null) {
-      tree.push(node);
-    } else {
-      const parent = nodeMap.get(parentId);
-      if (parent) {
-        if (visited.has(node[idKey])) {
-          console.error(`[buildTree] 检测到循环引用: ${node[idKey]}`);
-          continue;
-        }
-        visited.add(node[idKey]);
-        parent[childrenKey].push(node);
-      }
-    }
-  }
-
-  const cleanEmptyChildren = (nodes) => {
-    for (const node of nodes) {
-      if (node[childrenKey].length === 0) {
-        delete node[childrenKey];
-      } else {
-        cleanEmptyChildren(node[childrenKey]);
-      }
-    }
-  };
-  cleanEmptyChildren(tree);
-
-  return tree;
-}
+import logger from "./logger.js";
+
+/**
+ * 通用数据解析工具集
+ */
+
+/**
+ * 将对象数组转换成键值映射对象
+ * 适用于数据库配置列表、字典列表快速转map读取
+ * @param {Array<Object>} arr - 原始对象数组
+ * @param {string} [keyField="config_key"] - 映射key取自item的哪个字段
+ * @param {string} [valueField="config_value"] - 映射value取自item的哪个字段
+ * @returns {Record<string, any>} 键值映射对象
+ */
+export const arrToObj = (arr, keyField = "config_key", valueField = "config_value") => {
+  if (!Array.isArray(arr)) {
+    logger.error("[arrToObj] 参数类型错误：输入必须为数组", arr);
+    return {};
+  }
+  return arr.reduce((result, item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return result;
+    const mapKey = item[keyField];
+    const mapVal = item[valueField];
+    if (mapKey !== undefined && mapVal !== undefined) result[mapKey] = mapVal;
+    return result;
+  }, {});
+};
+
+/**
+ * 根据拼音/ID匹配分类，返回分类完整数据与分类ID
+ * @param {string | number} py - 检索条件：拼音字符串 / 数字ID
+ * @param {Array<Object>} source - 分类数据源数组
+ * @returns {{ cate: Object, id: string|number }}
+ */
+export function getChildrenId(py, source) {
+  if (!Array.isArray(source)) {
+    logger.warn("[getChildrenId] 数据源source不是数组", source);
+    return { cate: {}, id: "" };
+  }
+  const cate = source.find(item => item && typeof item === "object" && (item.pinyin === py || item.id === py)) || {};
+  return { cate, id: cate.id ?? "" };
+}