befly 3.24.18 → 3.24.19

package/hooks/rateLimit.js

@@ -0,0 +1,245 @@
+import picomatch from "picomatch";
+
+import { isValidPositiveInt } from "../utils/is.js";
+import { ErrorResponse } from "../utils/response.js";
+
+const RATE_LIMIT_ENABLED_VALUES = new Set([1, true, "1", "true"]);
+
+function isRateLimitEnabled(value) {
+    return RATE_LIMIT_ENABLED_VALUES.has(value);
+}
+
+function toPositiveInt(value, fallbackValue) {
+    const num = Number(value);
+
+    if (!Number.isFinite(num) || num <= 0) {
+        return fallbackValue;
+    }
+
+    return Math.floor(num);
+}
+
+function toSafeString(value, fallbackValue) {
+    if (typeof value !== "string") {
+        return fallbackValue;
+    }
+
+    const trimmed = value.trim();
+
+    if (!trimmed) {
+        return fallbackValue;
+    }
+
+    return trimmed;
+}
+
+function toRuleMethods(rule) {
+    if (Array.isArray(rule?.methods)) {
+        const values = [];
+
+        for (const method of rule.methods) {
+            const text = toSafeString(method, "");
+            if (!text) {
+                continue;
+            }
+
+            values.push(text.toUpperCase());
+        }
+
+        return values;
+    }
+
+    if (typeof rule?.method === "string") {
+        const value = toSafeString(rule.method, "");
+        if (value) {
+            return [value.toUpperCase()];
+        }
+    }
+
+    return [];
+}
+
+function normalizeRule(rawRule, defaultLimit, defaultWindow, defaultKeyType) {
+    const rule = rawRule && typeof rawRule === "object" ? rawRule : {};
+    const pathPattern = toSafeString(rule.path || rule.apiPath || rule.route, "");
+    const methods = toRuleMethods(rule);
+
+    return {
+        pathPattern: pathPattern,
+        methods: methods,
+        limit: toPositiveInt(rule.limit, defaultLimit),
+        window: toPositiveInt(rule.window, defaultWindow),
+        keyType: toSafeString(rule.key, defaultKeyType)
+    };
+}
+
+function createMatcher(pattern) {
+    try {
+        return picomatch(pattern);
+    } catch {
+        return null;
+    }
+}
+
+function normalizeConfig(config) {
+    const defaultLimit = toPositiveInt(config?.defaultLimit, 1000);
+    const defaultWindow = toPositiveInt(config?.defaultWindow, 60);
+    const defaultKeyType = toSafeString(config?.key, "ip");
+
+    const skipMatchers = [];
+    const skipRoutes = Array.isArray(config?.skipRoutes) ? config.skipRoutes : [];
+
+    for (const route of skipRoutes) {
+        const pattern = toSafeString(route, "");
+        if (!pattern) {
+            continue;
+        }
+
+        const matcher = createMatcher(pattern);
+        if (!matcher) {
+            continue;
+        }
+
+        skipMatchers.push(matcher);
+    }
+
+    const rules = [];
+    const rawRules = Array.isArray(config?.rules) ? config.rules : [];
+
+    for (const rawRule of rawRules) {
+        const normalizedRule = normalizeRule(rawRule, defaultLimit, defaultWindow, defaultKeyType);
+
+        if (!normalizedRule.pathPattern) {
+            continue;
+        }
+
+        const matcher = createMatcher(normalizedRule.pathPattern);
+        if (!matcher) {
+            continue;
+        }
+
+        rules.push({
+            matcher: matcher,
+            methods: normalizedRule.methods,
+            limit: normalizedRule.limit,
+            window: normalizedRule.window,
+            keyType: normalizedRule.keyType
+        });
+    }
+
+    return {
+        enabled: isRateLimitEnabled(config?.enable),
+        defaultLimit: defaultLimit,
+        defaultWindow: defaultWindow,
+        defaultKeyType: defaultKeyType,
+        skipMatchers: skipMatchers,
+        rules: rules
+    };
+}
+
+function resolveScopeByKeyType(keyType, ctx) {
+    if (keyType === "userId") {
+        if (isValidPositiveInt(ctx.userId)) {
+            return `user:${ctx.userId}`;
+        }
+
+        return `ip:${ctx.ip || "unknown"}`;
+    }
+
+    if (keyType === "roleCode") {
+        return `role:${ctx.roleCode || "guest"}`;
+    }
+
+    if (keyType === "apiPath") {
+        return `path:${ctx.apiPath || "unknown"}`;
+    }
+
+    if (keyType === "global") {
+        return "global";
+    }
+
+    return `ip:${ctx.ip || "unknown"}`;
+}
+
+function resolveRateRule(normalized, ctx) {
+    for (const rule of normalized.rules) {
+        if (!rule.matcher(ctx.apiPath)) {
+            continue;
+        }
+
+        if (rule.methods.length > 0 && !rule.methods.includes(ctx.method)) {
+            continue;
+        }
+
+        return {
+            limit: rule.limit,
+            window: rule.window,
+            keyType: rule.keyType
+        };
+    }
+
+    return {
+        limit: normalized.defaultLimit,
+        window: normalized.defaultWindow,
+        keyType: normalized.defaultKeyType
+    };
+}
+
+function shouldSkipRateLimit(normalized, ctx) {
+    for (const matcher of normalized.skipMatchers) {
+        if (matcher(ctx.apiPath)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+function buildRateLimitRedisKey(ctx, keyType, scope) {
+    return `rate_limit:${ctx.apiPath}:${ctx.method}:${keyType}:${scope}`;
+}
+
+export default {
+    order: 1.5,
+    handler: async (befly, ctx) => {
+        const normalized = normalizeConfig(befly?.config?.rateLimit);
+
+        if (!normalized.enabled) {
+            return;
+        }
+
+        if (!befly?.redis || typeof befly.redis.incrWithExpire !== "function") {
+            return;
+        }
+
+        if (shouldSkipRateLimit(normalized, ctx)) {
+            return;
+        }
+
+        const rateRule = resolveRateRule(normalized, ctx);
+        const scope = resolveScopeByKeyType(rateRule.keyType, ctx);
+        const redisKey = buildRateLimitRedisKey(ctx, rateRule.keyType, scope);
+        const current = await befly.redis.incrWithExpire(redisKey, rateRule.window);
+
+        if (current <= rateRule.limit) {
+            return;
+        }
+
+        ctx.corsHeaders = ctx.corsHeaders || {};
+        ctx.corsHeaders["Retry-After"] = String(rateRule.window);
+        ctx.response = ErrorResponse(
+            ctx,
+            "请求过于频繁，请稍后再试",
+            1,
+            null,
+            {
+                limit: rateRule.limit,
+                window: rateRule.window,
+                current: current,
+                apiPath: ctx.apiPath,
+                key: rateRule.keyType
+            },
+            "rateLimit"
+        );
+    }
+};

package/lib/cacheHelper.js

@@ -15,6 +15,95 @@ export class CacheHelper {
         this.redis = deps.redis;
     }
 
+    getRoleCacheVersionKey(kind) {
+        return `role:${kind}:activeVersion`;
+    }
+
+    getRoleCacheCodesKey(kind, version) {
+        return `role:${kind}:v:${version}:codes`;
+    }
+
+    getRoleCacheItemKey(kind, roleCode, version) {
+        if (!version) {
+            return `role:${kind}:${roleCode}`;
+        }
+
+        return `role:${kind}:v:${version}:${roleCode}`;
+    }
+
+    async getRoleCacheActiveVersion(kind) {
+        const versionKey = this.getRoleCacheVersionKey(kind);
+        const version = await this.redis.getString(versionKey);
+
+        if (!isNonEmptyString(version)) {
+            return "";
+        }
+
+        return version;
+    }
+
+    async getRoleCacheReadKey(kind, roleCode) {
+        const version = await this.getRoleCacheActiveVersion(kind);
+        return this.getRoleCacheItemKey(kind, roleCode, version);
+    }
+
+    async rebuildRoleCache(kind, roleValuesMap) {
+        const roleCodes = Array.from(roleValuesMap.keys());
+
+        if (roleCodes.length === 0) {
+            Logger.info(`✅ 没有需要缓存的角色 ${kind}`);
+            return;
+        }
+
+        const oldVersion = await this.getRoleCacheActiveVersion(kind);
+        let nextVersion = String(Date.now());
+
+        if (nextVersion === oldVersion) {
+            nextVersion = `${nextVersion}_1`;
+        }
+        const nextCodesKey = this.getRoleCacheCodesKey(kind, nextVersion);
+        const nextItems = [];
+
+        for (const roleCode of roleCodes) {
+            const values = roleValuesMap.get(roleCode) || [];
+            const members = Array.from(new Set(values)).toSorted();
+
+            if (members.length === 0) {
+                continue;
+            }
+
+            nextItems.push({
+                key: this.getRoleCacheItemKey(kind, roleCode, nextVersion),
+                members: members
+            });
+        }
+
+        await this.redis.del(nextCodesKey);
+        await this.redis.sadd(nextCodesKey, roleCodes);
+
+        if (nextItems.length > 0) {
+            await this.redis.saddBatch(nextItems);
+        }
+
+        await this.redis.setString(this.getRoleCacheVersionKey(kind), nextVersion);
+
+        if (!oldVersion || oldVersion === nextVersion) {
+            return;
+        }
+
+        const oldCodesKey = this.getRoleCacheCodesKey(kind, oldVersion);
+        const oldRoleCodes = await this.redis.smembers(oldCodesKey);
+        const cleanupKeys = [oldCodesKey];
+
+        for (const roleCode of oldRoleCodes) {
+            cleanupKeys.push(this.getRoleCacheItemKey(kind, roleCode, oldVersion));
+        }
+
+        if (cleanupKeys.length > 0) {
+            await this.redis.delBatch(cleanupKeys);
+        }
+    }
+
     /**
      * 缓存所有接口到 Redis
      */
@@ -95,33 +184,7 @@ export class CacheHelper {
                 roleApiPathsMap.set(role.code, role.apis);
             }
 
-            const roleCodes = Array.from(roleApiPathsMap.keys());
-            if (roleCodes.length === 0) {
-                Logger.info("✅ 没有需要缓存的角色权限");
-                return;
-            }
-
-            // 清理所有角色的缓存 key（保证幂等）
-            const roleKeys = roleCodes.map((code) => `role:apis:${code}`);
-            await this.redis.delBatch(roleKeys);
-
-            // 批量写入新缓存（只写入非空权限）
-            const items = [];
-
-            for (const roleCode of roleCodes) {
-                const apiPaths = roleApiPathsMap.get(roleCode) || [];
-                const members = Array.from(new Set(apiPaths)).toSorted();
-
-                if (members.length > 0) {
-                    items.push({ key: `role:apis:${roleCode}`, members: members });
-                }
-            }
-
-            if (items.length > 0) {
-                await this.redis.saddBatch(items);
-            }
-
-            // 极简方案不做版本/ready/meta：重建完成即生效
+            await this.rebuildRoleCache("apis", roleApiPathsMap);
         } catch (error) {
             Logger.error("⚠️ 角色权限缓存异常（将阻断启动）", error);
             throw new Error("⚠️ 角色权限缓存异常（将阻断启动）", {
@@ -153,31 +216,7 @@ export class CacheHelper {
                 roleMenuPathsMap.set(role.code, role.menus);
             }
 
-            const roleCodes = Array.from(roleMenuPathsMap.keys());
-            if (roleCodes.length === 0) {
-                Logger.info("✅ 没有需要缓存的角色菜单权限");
-                return;
-            }
-
-            // 清理所有角色的缓存 key（保证幂等）
-            const roleKeys = roleCodes.map((code) => `role:menus:${code}`);
-            await this.redis.delBatch(roleKeys);
-
-            // 批量写入新缓存（只写入非空权限）
-            const items = [];
-
-            for (const roleCode of roleCodes) {
-                const menuPaths = roleMenuPathsMap.get(roleCode) || [];
-                const members = Array.from(new Set(menuPaths)).toSorted();
-
-                if (members.length > 0) {
-                    items.push({ key: `role:menus:${roleCode}`, members: members });
-                }
-            }
-
-            if (items.length > 0) {
-                await this.redis.saddBatch(items);
-            }
+            await this.rebuildRoleCache("menus", roleMenuPathsMap);
         } catch (error) {
             Logger.error("⚠️ 角色菜单权限缓存异常（将阻断启动）", error);
             throw new Error("⚠️ 角色菜单权限缓存异常（将阻断启动）", {
@@ -212,7 +251,7 @@ export class CacheHelper {
             });
         }
 
-        const roleKey = `role:apis:${roleCode}`;
+        const roleKey = await this.getRoleCacheReadKey("apis", roleCode);
 
         // 空数组短路：保证清理残留
         if (apiPaths.length === 0) {
@@ -251,7 +290,7 @@ export class CacheHelper {
             });
         }
 
-        const roleKey = `role:menus:${roleCode}`;
+        const roleKey = await this.getRoleCacheReadKey("menus", roleCode);
 
         // 空数组短路：保证清理残留
         if (menuPaths.length === 0) {
@@ -329,7 +368,8 @@ export class CacheHelper {
      */
     async getRoleApis(roleCode) {
         try {
-            const permissions = await this.redis.smembers(`role:apis:${roleCode}`);
+            const roleKey = await this.getRoleCacheReadKey("apis", roleCode);
+            const permissions = await this.redis.smembers(roleKey);
             return permissions || [];
         } catch (error) {
             Logger.error("获取角色权限缓存失败", error, { roleCode: roleCode });
@@ -350,7 +390,8 @@ export class CacheHelper {
      */
     async getRoleMenus(roleCode) {
         try {
-            const permissions = await this.redis.smembers(`role:menus:${roleCode}`);
+            const roleKey = await this.getRoleCacheReadKey("menus", roleCode);
+            const permissions = await this.redis.smembers(roleKey);
             return permissions || [];
         } catch (error) {
             Logger.error("获取角色菜单权限缓存失败", error, { roleCode: roleCode });
@@ -374,7 +415,8 @@ export class CacheHelper {
         try {
             if (isNullable(apiPath)) return false;
             const value = isString(apiPath) ? apiPath : String(apiPath);
-            return await this.redis.sismember(`role:apis:${roleCode}`, value);
+            const roleKey = await this.getRoleCacheReadKey("apis", roleCode);
+            return await this.redis.sismember(roleKey, value);
         } catch (error) {
             Logger.error("检查角色权限失败", error, { roleCode: roleCode });
             throw new Error("检查角色权限失败", {
@@ -397,7 +439,8 @@ export class CacheHelper {
         try {
             if (isNullable(menuPath)) return false;
             const value = isString(menuPath) ? menuPath : String(menuPath);
-            return await this.redis.sismember(`role:menus:${roleCode}`, value);
+            const roleKey = await this.getRoleCacheReadKey("menus", roleCode);
+            return await this.redis.sismember(roleKey, value);
         } catch (error) {
             Logger.error("检查角色菜单权限失败", error, { roleCode: roleCode });
             throw new Error("检查角色菜单权限失败", {
@@ -417,7 +460,8 @@ export class CacheHelper {
      */
     async deleteRoleApis(roleCode) {
         try {
-            const result = await this.redis.del(`role:apis:${roleCode}`);
+            const roleReadKey = await this.getRoleCacheReadKey("apis", roleCode);
+            const result = await this.redis.delBatch([`role:apis:${roleCode}`, roleReadKey]);
             if (result > 0) {
                 Logger.info(`✅ 已删除角色 ${roleCode} 的权限缓存`);
                 return true;
@@ -442,7 +486,8 @@ export class CacheHelper {
      */
     async deleteRoleMenus(roleCode) {
         try {
-            const result = await this.redis.del(`role:menus:${roleCode}`);
+            const roleReadKey = await this.getRoleCacheReadKey("menus", roleCode);
+            const result = await this.redis.delBatch([`role:menus:${roleCode}`, roleReadKey]);
             if (result > 0) {
                 Logger.info(`✅ 已删除角色 ${roleCode} 的菜单权限缓存`);
                 return true;

package/lib/redisHelper.js

@@ -380,6 +380,74 @@ export class RedisHelper {
         }
     }
 
+    /**
+     * 向有序集合添加成员
+     * @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;
+                }
+
+                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 - 键名