befly 3.74.2 → 3.75.0

package/lib/redisHelper.js

@@ -1,14 +1,14 @@
 /**
- * Redis 助手 - JavaScript 版本
  * 提供 Redis 操作的便捷方法
  */
 
+import { createError } from "../utils/error.js";
 import { Connect } from "./connect.js";
 import { Logger } from "./logger.js";
 
 /**
  * Redis 助手类
- * 约定：除构造函数外，方法默认不抛异常；失败时返回 null/false/0/[] 并记录日志。
+ * 约定：除构造函数与 ping 外，方法默认不抛异常；失败时返回 null/false/0/[] 并记录日志。
  */
 export class RedisHelper {
     /**
@@ -18,15 +18,27 @@ export class RedisHelper {
     constructor(prefix = "") {
         const client = Connect.getRedis();
         if (!client) {
-            throw new Error("Redis 客户端未初始化，请先调用 Connect.connectRedis()", {
-                cause: null,
-                code: "runtime"
-            });
+            throw createError("Redis 客户端未初始化，请先调用 Connect.connectRedis()", { code: "runtime" });
         }
         this.client = client;
         this.prefix = prefix ? `${prefix}:` : "";
     }
 
+    /**
+     * 吞错执行：失败记录日志并返回 fallback（不抛出）
+     * @param label - 操作名（用于日志文案）
+     * @param operation - 实际操作
+     * @param fallback - 失败返回值
+     */
+    async safeCall(label, operation, fallback) {
+        try {
+            return await operation();
+        } catch (error) {
+            Logger.error(`Redis ${label} 错误`, error);
+            return fallback;
+        }
+    }
+
     /**
      * 设置对象到 Redis
      * @param key - 键名
@@ -35,19 +47,15 @@ export class RedisHelper {
      * @returns 操作结果
      */
     async setObject(key, obj, ttl = null) {
-        try {
-            const data = JSON.stringify(obj);
-            const pkey = `${this.prefix}${key}`;
-
-            if (ttl) {
-                return await this.client.setex(pkey, ttl, data);
-            }
-
-            return await this.client.set(pkey, data);
-        } catch (error) {
-            Logger.error("Redis setObject 错误", error);
-            return null;
-        }
+        return this.safeCall(
+            "setObject",
+            async () => {
+                const data = JSON.stringify(obj);
+                const pkey = `${this.prefix}${key}`;
+                return ttl ? this.client.setex(pkey, ttl, data) : this.client.set(pkey, data);
+            },
+            null
+        );
     }
 
     /**
@@ -56,14 +64,15 @@ export class RedisHelper {
      * @returns 对象或 null
      */
     async getObject(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            const data = await this.client.get(pkey);
-            return data ? JSON.parse(data) : null;
-        } catch (error) {
-            Logger.error("Redis getObject 错误", error);
-            return null;
-        }
+        return this.safeCall(
+            "getObject",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                const data = await this.client.get(pkey);
+                return data ? JSON.parse(data) : null;
+            },
+            null
+        );
     }
 
     /**
@@ -71,12 +80,10 @@ export class RedisHelper {
      * @param key - 键名
      */
     async delObject(key) {
-        try {
+        return this.safeCall("delObject", async () => {
             const pkey = `${this.prefix}${key}`;
             await this.client.del(pkey);
-        } catch (error) {
-            Logger.error("Redis delObject 错误", error);
-        }
+        });
     }
 
     // ==================== ID 生成 ====================
@@ -112,17 +119,14 @@ export class RedisHelper {
      * @param ttl - 过期时间（秒）
      */
     async setString(key, value, ttl = null) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            if (ttl) {
-                return await this.client.setex(pkey, ttl, value);
-            }
-
-            return await this.client.set(pkey, value);
-        } catch (error) {
-            Logger.error("Redis setString 错误", error);
-            return null;
-        }
+        return this.safeCall(
+            "setString",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return ttl ? this.client.setex(pkey, ttl, value) : this.client.set(pkey, value);
+            },
+            null
+        );
     }
 
     /**
@@ -130,13 +134,14 @@ export class RedisHelper {
      * @param key - 键名
      */
     async getString(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.get(pkey);
-        } catch (error) {
-            Logger.error("Redis getString 错误", error);
-            return null;
-        }
+        return this.safeCall(
+            "getString",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.get(pkey);
+            },
+            null
+        );
     }
 
     /**
@@ -145,13 +150,14 @@ export class RedisHelper {
      * @returns 是否存在（true/false）
      */
     async exists(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.exists(pkey);
-        } catch (error) {
-            Logger.error("Redis exists 错误", error);
-            return false;
-        }
+        return this.safeCall(
+            "exists",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.exists(pkey);
+            },
+            false
+        );
     }
 
     /**
@@ -160,29 +166,14 @@ export class RedisHelper {
      * @returns 自增后的值
      */
     async incr(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.incr(pkey);
-        } catch (error) {
-            Logger.error("Redis incr 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 原子按指定值自增
-     * @param key - 键名
-     * @param value - 自增值
-     * @returns 自增后的值
-     */
-    async incrBy(key, value) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.incrby(pkey, value);
-        } catch (error) {
-            Logger.error("Redis incrBy 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "incr",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.incr(pkey);
+            },
+            0
+        );
     }
 
     /**
@@ -192,17 +183,18 @@ export class RedisHelper {
      * @returns 自增后的值
      */
     async incrWithExpire(key, seconds) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            const res = await this.client.incr(pkey);
-            if (res === 1) {
-                await this.client.expire(pkey, seconds);
-            }
-            return res;
-        } catch (error) {
-            Logger.error("Redis incrWithExpire 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "incrWithExpire",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                const res = await this.client.incr(pkey);
+                if (res === 1) {
+                    await this.client.expire(pkey, seconds);
+                }
+                return res;
+            },
+            0
+        );
     }
 
     /**
@@ -211,13 +203,14 @@ export class RedisHelper {
      * @param seconds - 秒数
      */
     async expire(key, seconds) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.expire(pkey, seconds);
-        } catch (error) {
-            Logger.error("Redis expire 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "expire",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.expire(pkey, seconds);
+            },
+            0
+        );
     }
 
     /**
@@ -225,32 +218,14 @@ export class RedisHelper {
      * @param key - 键名
      */
     async ttl(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.ttl(pkey);
-        } catch (error) {
-            Logger.error("Redis ttl 错误", error);
-            return -1;
-        }
-    }
-
-    /**
-     * 批量获取剩余过期时间（利用 Bun Redis 自动管道优化）
-     * @param keys - 键名数组
-     * @returns TTL 数组（-2 表示键不存在，-1 表示无过期时间）
-     */
-    async ttlBatch(keys) {
-        if (keys.length === 0) {
-            return [];
-        }
-
-        try {
-            const results = await Promise.all(keys.map((key) => this.ttl(key)));
-            return results;
-        } catch (error) {
-            Logger.error("Redis ttlBatch 错误", error);
-            return keys.map(() => -1);
-        }
+        return this.safeCall(
+            "ttl",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.ttl(pkey);
+            },
+            -1
+        );
     }
 
     /**
@@ -260,19 +235,20 @@ export class RedisHelper {
      * @returns 成功添加的成员数量
      */
     async sadd(key, members) {
-        try {
-            if (members.length === 0) return 0;
-
-            const pkey = `${this.prefix}${key}`;
-            const args = [pkey];
-            for (const member of members) {
-                args.push(member);
-            }
-            return await this.client.sadd.apply(this.client, args);
-        } catch (error) {
-            Logger.error("Redis sadd 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "sadd",
+            async () => {
+                if (members.length === 0) return 0;
+
+                const pkey = `${this.prefix}${key}`;
+                const args = [pkey];
+                for (const member of members) {
+                    args.push(member);
+                }
+                return this.client.sadd.apply(this.client, args);
+            },
+            0
+        );
     }
 
     /**
@@ -282,28 +258,29 @@ export class RedisHelper {
      * @returns 是否存在（true/false）
      */
     async sismember(key, member) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.sismember(pkey, member);
-        } catch (error) {
-            Logger.error("Redis sismember 错误", error);
-            return false;
-        }
+        return this.safeCall(
+            "sismember",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.sismember(pkey, member);
+            },
+            false
+        );
     }
 
     /**
      * 获取 Set 的成员数量
      * @param key - 键名
-     * @returns 成员数量
      */
     async scard(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.scard(pkey);
-        } catch (error) {
-            Logger.error("Redis scard 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "scard",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.scard(pkey);
+            },
+            0
+        );
     }
 
     /**
@@ -312,35 +289,14 @@ export class RedisHelper {
      * @returns 成员数组
      */
     async smembers(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.smembers(pkey);
-        } catch (error) {
-            Logger.error("Redis smembers 错误", error);
-            return [];
-        }
-    }
-
-    /**
-     * 从 Set 中删除一个或多个成员
-     * @param key - 键名
-     * @param members - 成员数组
-     * @returns 删除的成员数量
-     */
-    async srem(key, members) {
-        try {
-            if (members.length === 0) return 0;
-
-            const pkey = `${this.prefix}${key}`;
-            const args = [pkey];
-            for (const member of members) {
-                args.push(member);
-            }
-            return await this.client.srem.apply(this.client, args);
-        } catch (error) {
-            Logger.error("Redis srem 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "smembers",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.smembers(pkey);
+            },
+            []
+        );
     }
 
     /**
@@ -349,128 +305,18 @@ export class RedisHelper {
      * @returns 成功添加的总成员数量
      */
     async saddBatch(items) {
-        if (items.length === 0) {
-            return 0;
-        }
-
-        try {
-            const results = await Promise.all(items.map((item) => this.sadd(item.key, item.members)));
-            return results.reduce((sum, count) => sum + count, 0);
-        } catch (error) {
-            Logger.error("Redis saddBatch 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 批量检查成员是否在 Set 中（利用 Bun Redis 自动管道优化）
-     * @param items - [{ key, member }] 数组
-     * @returns 布尔数组（true 表示存在，false 表示不存在）
-     */
-    async sismemberBatch(items) {
-        if (items.length === 0) {
-            return [];
-        }
-
-        try {
-            return await Promise.all(items.map((item) => this.sismember(item.key, item.member)));
-        } catch (error) {
-            Logger.error("Redis sismemberBatch 错误", error);
-            return items.map(() => false);
-        }
-    }
-
-    /**
-     * 向有序集合添加成员
-     * @param key - 键名
-     * @param items - [{ score, member }] 数组
-     * @returns 成功添加的成员数量
-     */
-    async zadd(key, items) {
-        try {
-            if (items.length === 0) {
-                return 0;
-            }
-
-            const pkey = `${this.prefix}${key}`;
-            const args = [pkey];
-
-            for (const item of items) {
-                const score = Number(item.score);
-                const member = String(item.member);
-
-                if (!Number.isFinite(score) || member.length === 0) {
-                    continue;
+        return this.safeCall(
+            "saddBatch",
+            async () => {
+                if (items.length === 0) {
+                    return 0;
                 }
 
-                args.push(score);
-                args.push(member);
-            }
-
-            if (args.length <= 1) {
-                return 0;
-            }
-
-            return await this.client.zadd.apply(this.client, args);
-        } catch (error) {
-            Logger.error("Redis zadd 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 获取有序集合成员数量
-     * @param key - 键名
-     */
-    async zcard(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.zcard(pkey);
-        } catch (error) {
-            Logger.error("Redis zcard 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 按 score 区间删除有序集合成员
-     * @param key - 键名
-     * @param min - 最小分值
-     * @param max - 最大分值
-     */
-    async zremrangebyscore(key, min, max) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.zremrangebyscore(pkey, min, max);
-        } catch (error) {
-            Logger.error("Redis zremrangebyscore 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 从有序集合删除一个或多个成员
-     * @param key - 键名
-     * @param members - 成员数组
-     */
-    async zrem(key, members) {
-        try {
-            if (members.length === 0) {
-                return 0;
-            }
-
-            const pkey = `${this.prefix}${key}`;
-            const args = [pkey];
-
-            for (const member of members) {
-                args.push(String(member));
-            }
-
-            return await this.client.zrem.apply(this.client, args);
-        } catch (error) {
-            Logger.error("Redis zrem 错误", error);
-            return 0;
-        }
+                const results = await Promise.all(items.map((item) => this.sadd(item.key, item.members)));
+                return results.reduce((sum, count) => sum + count, 0);
+            },
+            0
+        );
     }
 
     /**
@@ -479,13 +325,14 @@ export class RedisHelper {
      * @returns 删除的键数量
      */
     async del(key) {
-        try {
-            const pkey = `${this.prefix}${key}`;
-            return await this.client.del(pkey);
-        } catch (error) {
-            Logger.error("Redis del 错误", error);
-            return 0;
-        }
+        return this.safeCall(
+            "del",
+            async () => {
+                const pkey = `${this.prefix}${key}`;
+                return this.client.del(pkey);
+            },
+            0
+        );
     }
 
     /**
@@ -494,97 +341,23 @@ export class RedisHelper {
      * @returns 成功删除的键数量
      */
     async delBatch(keys) {
-        if (keys.length === 0) {
-            return 0;
-        }
-
-        try {
-            const results = await Promise.all(
-                keys.map((key) => {
-                    const pkey = `${this.prefix}${key}`;
-                    return this.client.del(pkey);
-                })
-            );
-            return results.reduce((sum, count) => sum + count, 0);
-        } catch (error) {
-            Logger.error("Redis delBatch 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 批量设置对象（利用 Bun Redis 自动管道优化）
-     * @param items - 键值对数组 [{ key, value, ttl? }]
-     * @returns 成功设置的数量
-     */
-    async setBatch(items) {
-        if (items.length === 0) {
-            return 0;
-        }
-
-        try {
-            const results = await Promise.all(items.map((item) => this.setObject(item.key, item.value, item.ttl ?? null)));
-            return results.filter((r) => r !== null).length;
-        } catch (error) {
-            Logger.error("Redis setBatch 错误", error);
-            return 0;
-        }
-    }
-
-    /**
-     * 批量获取对象（利用 Bun Redis 自动管道优化）
-     * @param keys - 键名数组
-     * @returns 对象数组（不存在的键返回 null）
-     */
-    async getBatch(keys) {
-        if (keys.length === 0) {
-            return [];
-        }
-
-        try {
-            const results = await Promise.all(keys.map((key) => this.getObject(key)));
-            return results;
-        } catch (error) {
-            Logger.error("Redis getBatch 错误", error);
-            return keys.map(() => null);
-        }
-    }
-
-    /**
-     * 批量检查键是否存在（利用 Bun Redis 自动管道优化）
-     * @param keys - 键名数组
-     * @returns 布尔数组（true 表示存在，false 表示不存在）
-     */
-    async existsBatch(keys) {
-        if (keys.length === 0) {
-            return [];
-        }
-
-        try {
-            return await Promise.all(keys.map((key) => this.exists(key)));
-        } catch (error) {
-            Logger.error("Redis existsBatch 错误", error);
-            return keys.map(() => false);
-        }
-    }
-
-    /**
-     * 批量设置过期时间（利用 Bun Redis 自动管道优化）
-     * @param items - 键名和过期时间数组 [{ key, seconds }]
-     * @returns 成功设置的数量
-     */
-    async expireBatch(items) {
-        if (items.length === 0) {
-            return 0;
-        }
+        return this.safeCall(
+            "delBatch",
+            async () => {
+                if (keys.length === 0) {
+                    return 0;
+                }
 
-        try {
-            const results = await Promise.all(items.map((item) => this.expire(item.key, item.seconds)));
-            return results.filter((r) => r > 0).length;
-        } catch (error) {
-            Logger.error("Redis expireBatch 错误", error);
-            return 0;
-        }
+                const results = await Promise.all(
+                    keys.map((key) => {
+                        const pkey = `${this.prefix}${key}`;
+                        return this.client.del(pkey);
+                    })
+                );
+                return results.reduce((sum, count) => sum + count, 0);
+            },
+            0
+        );
     }
 
     /**
@@ -592,29 +365,27 @@ export class RedisHelper {
      * @param section - 可选 section（如 "server"）
      */
     async info(section) {
-        try {
-            const client = this.client;
+        return this.safeCall(
+            "info",
+            async () => {
+                const client = this.client;
 
-            if (typeof client.info === "function") {
-                return await client.info(section);
-            }
+                if (typeof client.info === "function") {
+                    return client.info(section);
+                }
 
-            if (typeof client.send === "function") {
-                return await client.send("INFO", section ? [String(section)] : []);
-            }
+                if (typeof client.send === "function") {
+                    return client.send("INFO", section ? [String(section)] : []);
+                }
 
-            throw new Error("Redis info 不支持", {
-                cause: null,
-                code: "runtime"
-            });
-        } catch (error) {
-            Logger.error("Redis info 错误", error);
-            return "";
-        }
+                throw createError("Redis info 不支持", { code: "runtime" });
+            },
+            ""
+        );
     }
 
     /**
-     * 测试 Redis 连接
+     * 测试 Redis 连接（异常时抛出，供调用方感知连接状态）
      * @returns ping 响应结果
      */
     async ping() {
@@ -622,12 +393,7 @@ export class RedisHelper {
             return await this.client.ping();
         } catch (error) {
             Logger.error("Redis ping 错误", error);
-            throw new Error("Redis ping 错误", {
-                cause: error,
-                code: "runtime",
-                subsystem: "redis",
-                operation: "ping"
-            });
+            throw createError("Redis ping 错误", { cause: error, code: "runtime", subsystem: "redis", operation: "ping" });
         }
     }
 }