befly 3.76.6 → 3.77.0

package/hooks/rateLimit.js

@@ -13,6 +13,27 @@ function getSkipMatchers(config) {
     return matchers;
 }
 
+function getRuleMatchers(config) {
+    if (!Array.isArray(config.rules) || config.rules.length === 0) {
+        return [];
+    }
+    let matchers = matcherCache.get(config.rules);
+    if (!matchers) {
+        // rules: [{ path: "/api/guest/login/*", limit: 10, window: 60 }]，首个匹配生效，未命中用默认值
+        matchers = config.rules.map((rule) => ({ matcher: new Bun.Glob(rule.path), limit: rule.limit, window: rule.window }));
+        matcherCache.set(config.rules, matchers);
+    }
+    return matchers;
+}
+
+function resolveRateRule(config, apiPath) {
+    const hit = getRuleMatchers(config).find((rule) => rule.matcher.match(apiPath));
+    if (hit) {
+        return { limit: hit.limit, window: hit.window };
+    }
+    return { limit: config.defaultLimit, window: config.defaultWindow };
+}
+
 function resolveScope(keyType, ctx) {
     if (keyType === "userId") return isValidPositiveInt(ctx.userId) ? `user:${ctx.userId}` : `ip:${ctx.ip}`;
     if (keyType === "roleCode") return `role:${ctx.roleCode || "guest"}`;
@@ -37,19 +58,29 @@ export default {
         }
 
         const scope = resolveScope(config.key, ctx);
+        const rule = resolveRateRule(config, ctx.apiPath);
         const key = `rate_limit:${ctx.apiPath}:${ctx.method}:${config.key}:${scope}`;
-        const current = await befly.redis.incrWithExpire(key, config.defaultWindow);
-        if (current <= config.defaultLimit) return;
+        let current;
+        try {
+            current = await befly.redis.incrWithExpire(key, rule.window);
+        } catch {
+            // 计数器故障时按 failOpen 配置决定放行或拒绝，不静默失效
+            if (config.failOpen) return;
+            ctx.corsHeaders["Retry-After"] = String(rule.window);
+            ctx.response = ErrorResponse(ctx, "服务繁忙，请稍后再试", 1, null, { reason: "rate_limit_unavailable" }, "rateLimit");
+            return;
+        }
+        if (current <= rule.limit) return;
 
-        ctx.corsHeaders["Retry-After"] = String(config.defaultWindow);
+        ctx.corsHeaders["Retry-After"] = String(rule.window);
         ctx.response = ErrorResponse(
             ctx,
             "请求过于频繁，请稍后再试",
             1,
             null,
             {
-                limit: config.defaultLimit,
-                window: config.defaultWindow,
+                limit: rule.limit,
+                window: rule.window,
                 current: current,
                 apiPath: ctx.apiPath,
                 key: config.key

package/hooks/validator.js

@@ -1,6 +1,6 @@
 import { compile } from "#befly/libs/validator/index.js";
 
-import { getFieldSchema } from "../checks/field.js";
+import { buildApiSchema, getFieldErrors } from "../checks/field.js";
 import { HOOK_ORDER } from "../configs/constConfig.js";
 import { isPlainObject } from "../utils/is.js";
 import { ErrorResponse } from "../utils/response.js";
@@ -17,20 +17,9 @@ function getValidator(fields, required, constraints) {
     const cacheKey = JSON.stringify([required, constraints]);
     let validate = validators.get(cacheKey);
     if (validate) return validate;
-    const requiredSet = new Set(required);
-    validate = compile({
-        paramType: "object",
-        fields: Object.fromEntries(
-            Object.entries(fields).map(([field, definition]) => [
-                field,
-                {
-                    ...getFieldSchema(definition),
-                    optional: !requiredSet.has(field)
-                }
-            ])
-        ),
-        constraints: constraints
-    });
+    // 前提：fields 与 required/constraints 均来自启动期扫描的静态 apiData，
+    // 每个 fields 对象在内层 Map 只会有一个缓存条目，无需淘汰策略
+    validate = compile(buildApiSchema(fields, required, constraints));
     validators.set(cacheKey, validate);
     return validate;
 }
@@ -54,7 +43,7 @@ export default {
             return;
         }
 
-        const fieldErrors = Object.fromEntries(result.issues.map((issue) => [issue.path[0], `${ctx.apiFields[issue.path[0]]?.name || issue.path[0]}${issue.message}`]));
+        const fieldErrors = getFieldErrors(result.issues, ctx.apiFields);
         ctx.response = ErrorResponse(ctx, Object.values(fieldErrors)[0] || "参数验证失败", 1, null, fieldErrors, "validator");
     }
 };

package/index.js

@@ -33,49 +33,55 @@ function prefixMenuPaths(menus, prefix) {
 }
 
 export async function createBefly(config = {}, menus = []) {
-    const mergeStartTime = Bun.nanoseconds();
-    const mergedConfig = deepMerge(beflyConfig, config);
-    const mergedMenus = deepMerge(prefixMenuPaths(beflyMenus, "core"), menus);
+    try {
+        const mergeStartTime = Bun.nanoseconds();
+        const mergedConfig = deepMerge(beflyConfig, config);
+        const mergedMenus = deepMerge(prefixMenuPaths(beflyMenus, "core"), menus);
 
-    Logger.configure({ runtimeEnv: getRunMode(), ...mergedConfig.logger });
-    Logger.info(`启动 合并配置 耗时 ${calcPerfTime(mergeStartTime)}`);
+        Logger.configure({ runtimeEnv: getRunMode(), ...mergedConfig.logger });
+        Logger.info(`启动 合并配置 耗时 ${calcPerfTime(mergeStartTime)}`);
 
-    let stageStartTime = Bun.nanoseconds();
-    const configErrors = await checkConfig(mergedConfig);
-    Logger.info(`启动 检查配置 耗时 ${calcPerfTime(stageStartTime)}`);
+        let stageStartTime = Bun.nanoseconds();
+        const configErrors = await checkConfig(mergedConfig);
+        Logger.info(`启动 检查配置 耗时 ${calcPerfTime(stageStartTime)}`);
 
-    stageStartTime = Bun.nanoseconds();
-    const { apis, tables, plugins, hooks, corns } = await scanSources({ beflyMode: mergedConfig.mysql.beflyMode });
-    Logger.info(`启动 扫描源码 耗时 ${calcPerfTime(stageStartTime)}`);
+        stageStartTime = Bun.nanoseconds();
+        const { apis, tables, plugins, hooks, corns } = await scanSources({ beflyMode: mergedConfig.mysql.beflyMode });
+        Logger.info(`启动 扫描源码 耗时 ${calcPerfTime(stageStartTime)}`);
 
-    const checks = [
-        ["配置", configErrors],
-        ["接口", await checkApi(apis)],
-        ["表结构", await checkTable(tables)],
-        ["插件", await checkPlugin(plugins)],
-        ["钩子", await checkHook(hooks)],
-        ["定时器", checkCorn(corns)],
-        ["菜单", await checkMenu(mergedMenus)]
-    ];
-    const failedChecks = checks.filter(([, errors]) => errors.length > 0).map(([check, errors]) => ({ check: check, errors: errors }));
+        const checks = [
+            ["配置", configErrors],
+            ["接口", await checkApi(apis)],
+            ["表结构", await checkTable(tables)],
+            ["插件", await checkPlugin(plugins)],
+            ["钩子", await checkHook(hooks)],
+            ["定时器", checkCorn(corns)],
+            ["菜单", await checkMenu(mergedMenus)]
+        ];
+        const failedChecks = checks.filter(([, errors]) => errors.length > 0).map(([check, errors]) => ({ check: check, errors: errors }));
 
-    if (failedChecks.length > 0) {
-        throw createError("检查失败：存在配置/结构问题", {
-            code: "policy",
-            subsystem: "checks",
-            operation: "checkAll",
-            errors: failedChecks
+        if (failedChecks.length > 0) {
+            throw createError("检查失败：存在配置/结构问题", {
+                code: "policy",
+                subsystem: "checks",
+                operation: "checkAll",
+                errors: failedChecks
+            });
+        }
+
+        mergedConfig.runMode = getRunMode();
+        return new Befly({
+            config: mergedConfig,
+            tables: tables,
+            menus: mergedMenus,
+            apis: apis,
+            hooks: hooks,
+            plugins: plugins,
+            corns: corns
         });
+    } catch (error) {
+        Logger.error("启动失败", error);
+        await Logger.shutdown();
+        throw error;
     }
-
-    mergedConfig.runMode = getRunMode();
-    return new Befly({
-        config: mergedConfig,
-        tables: tables,
-        menus: mergedMenus,
-        apis: apis,
-        hooks: hooks,
-        plugins: plugins,
-        corns: corns
-    });
 }

package/libs/cacheHelper.js

@@ -7,6 +7,10 @@ import { Logger } from "#befly/libs/logger/index.js";
 import { BEFLY_API_TABLE, BEFLY_MENU_TABLE, BEFLY_ROLE_TABLE } from "../configs/constConfig.js";
 import { createError } from "../utils/error.js";
 import { isNonEmptyString, isNullable, isString } from "../utils/is.js";
+import { memRemember, memSet } from "./memCache.js";
+
+// 角色权限版本号变化频率极低（仅启动全量重建时切换），进程内短缓存可省掉每请求一次 getString 往返
+const ROLE_VERSION_CACHE_TTL_MS = 3000;
 
 /**
  * 缓存助手类
@@ -35,13 +39,10 @@ export class CacheHelper {
 
     async getRoleCacheActiveVersion(kind) {
         const versionKey = this.getRoleCacheVersionKey(kind);
-        const version = await this.redis.getString(versionKey);
-
-        if (!isNonEmptyString(version)) {
-            return "";
-        }
-
-        return version;
+        return await memRemember(`befly:cache:${versionKey}`, ROLE_VERSION_CACHE_TTL_MS, async () => {
+            const version = await this.redis.getString(versionKey);
+            return isNonEmptyString(version) ? version : "";
+        });
     }
 
     async getRoleCacheReadKey(kind, roleCode) {
@@ -82,6 +83,7 @@ export class CacheHelper {
         }
 
         await this.redis.setString(this.getRoleCacheVersionKey(kind), nextVersion);
+        memSet(`befly:cache:${this.getRoleCacheVersionKey(kind)}`, nextVersion, ROLE_VERSION_CACHE_TTL_MS);
 
         if (!oldVersion || oldVersion === nextVersion) {
             return;
@@ -107,18 +109,11 @@ export class CacheHelper {
      */
     async cacheAllItems(kind, table) {
         try {
+            // setObject 失败会直接抛错阻断启动（写操作 fail-fast），无需返回值判断
             const items = await this.mysql.getAll({
                 table: table
             });
-
-            const result = await this.redis.setObject(`${kind}:all`, items.data.lists);
-
-            if (result === null) {
-                Logger.warn(`⚠️ ${kind} 缓存失败`, {
-                    subsystem: "cache",
-                    operation: "cacheAllItems"
-                });
-            }
+            await this.redis.setObject(`${kind}:all`, items.data.lists);
         } catch (error) {
             throw createError(`${kind} 缓存异常`, { cause: error, code: "runtime", subsystem: "cache", operation: "cacheAllItems" });
         }
@@ -178,9 +173,9 @@ export class CacheHelper {
     }
 
     /**
-     * 增量刷新单个角色的某类权限缓存
+     * 增量刷新单个角色的某类权限缓存（写入当前活跃版本 key）
      * - paths 为空数组：仅清理缓存（防止残留）
-     * - paths 非空：使用最小查询，DEL 后 SADD
+     * - paths 非空：DEL 后 SADD
      * @param kind - 权限类别（apis/menus）
      */
     async refreshRoleItems(kind, roleCode, paths) {

package/libs/logger/logger.js

@@ -103,14 +103,20 @@ class FileSink {
     write(line) {
         if (this.disabled) return;
         const bytes = textEncoder.encode(line).byteLength;
-        this.pending = this.pending.then(async () => {
-            await this.prepare(bytes);
-            if (!this.stream || this.disabled) return;
-            this.size += bytes;
-            await new Promise((resolveWrite) => {
-                this.stream.write(line, resolveWrite);
+        // 链尾 catch 隔离单次写失败：保持 pending 永远 resolved，
+        // 避免未处理 rejection 与后续日志全部静默丢失
+        this.pending = this.pending
+            .then(async () => {
+                await this.prepare(bytes);
+                if (!this.stream || this.disabled) return;
+                this.size += bytes;
+                await new Promise((resolveWrite) => {
+                    this.stream.write(line, resolveWrite);
+                });
+            })
+            .catch((error) => {
+                writeStderr(`写入失败 (${this.prefix}): ${error?.message || error}`);
             });
-        });
     }
 
     async flush() {
@@ -154,16 +160,25 @@ function prepareDirectory(clearDevelopmentLog) {
 }
 
 function getSink(level) {
-    prepareDirectory(false);
+    // 目录只在新建 sink 时确保一次，避免每条日志一次 mkdirSync 系统调用
     if (config.runtimeEnv === "development") {
-        if (!appSink) appSink = new FileSink("dev", config);
+        if (!appSink) {
+            prepareDirectory(false);
+            appSink = new FileSink("dev", config);
+        }
         return appSink;
     }
     if (level === "error") {
-        if (!errorSink) errorSink = new FileSink("error", config);
+        if (!errorSink) {
+            prepareDirectory(false);
+            errorSink = new FileSink("error", config);
+        }
         return errorSink;
     }
-    if (!appSink) appSink = new FileSink("app", config);
+    if (!appSink) {
+        prepareDirectory(false);
+        appSink = new FileSink("app", config);
+    }
     return appSink;
 }
 
@@ -241,6 +256,9 @@ export const Logger = {
         const sinks = [appSink, errorSink].filter(Boolean);
         appSink = null;
         errorSink = null;
-        await Promise.all(sinks.map((sink) => sink.shutdown()));
+        const results = await Promise.allSettled(sinks.map((sink) => sink.shutdown()));
+        for (const result of results) {
+            if (result.status === "rejected") writeStderr(`关闭失败: ${result.reason?.message || result.reason}`);
+        }
     }
 };

package/libs/memCache.js

@@ -0,0 +1,53 @@
+/**
+ * 进程级 TTL 缓存：存放跨请求复用的短时效数据（角色权限版本号、系统资源快照、统计项目校验等）。
+ *
+ * 边界约定：
+ * - 仅单进程内有效，多实例部署时各进程独立缓存
+ * - 适合可容忍秒级陈旧、读取代价高的数据；不适合需要强一致的数据
+ * - 无常驻定时器，过期条目在读写时惰性清理，写入超过上限时全量清淤，无内存泄漏
+ */
+const MAX_ENTRIES = 1000;
+
+const store = new Map();
+
+function pruneExpired(now) {
+    for (const [key, entry] of store) {
+        if (entry.expireAt <= now) {
+            store.delete(key);
+        }
+    }
+}
+
+export function memGet(key) {
+    const entry = store.get(key);
+    if (!entry) return;
+    if (entry.expireAt <= Date.now()) {
+        store.delete(key);
+        return;
+    }
+    return entry.value;
+}
+
+export function memSet(key, value, ttlMs) {
+    if (store.size >= MAX_ENTRIES) {
+        pruneExpired(Date.now());
+    }
+    store.set(key, {
+        value: value,
+        expireAt: Date.now() + ttlMs
+    });
+}
+
+export function memDelete(key) {
+    store.delete(key);
+}
+
+export async function memRemember(key, ttlMs, loader) {
+    const cached = memGet(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const value = await loader();
+    memSet(key, value, ttlMs);
+    return value;
+}

package/libs/mysql/dbHelper.js

@@ -78,39 +78,27 @@ function getExecuteErrorMessage(error) {
         return String(error);
     }
 
-    const message = typeof error.message === "string" && error.message.trim().length > 0 ? error.message.trim() : typeof error.sqlMessage === "string" && error.sqlMessage.trim().length > 0 ? error.sqlMessage.trim() : "";
-    const detail = {};
+    const message = [error.message, error.sqlMessage].find((text) => typeof text === "string" && text.trim().length > 0)?.trim() || "";
+    const detail = {
+        code: error.code,
+        errno: error.errno,
+        sqlState: error.sqlState,
+        sqlMessage: error.sqlMessage,
+        detail: error.detail
+    };
 
-    if (typeof error.code === "string" && error.code.trim().length > 0) {
-        detail.code = error.code;
-    }
-    if (typeof error.errno === "number") {
-        detail.errno = error.errno;
-    }
-    if (typeof error.sqlState === "string" && error.sqlState.trim().length > 0) {
-        detail.sqlState = error.sqlState;
-    }
-    if (typeof error.sqlMessage === "string" && error.sqlMessage.trim().length > 0) {
-        detail.sqlMessage = error.sqlMessage;
-    }
-    if (typeof error.detail === "string" && error.detail.trim().length > 0) {
-        detail.detail = error.detail;
+    for (const key of Object.keys(detail)) {
+        const value = detail[key];
+        if (value === undefined || (typeof value === "string" && value.trim().length === 0)) {
+            delete detail[key];
+        }
     }
 
     const detailText = Object.keys(detail).length > 0 ? safeStringify(detail) : safeStringify(error);
-    if (message && detailText && detailText !== "{}") {
+    if (message && detailText !== "{}") {
         return `${message} | ${detailText}`;
     }
-    if (message) {
-        return message;
-    }
-    return detailText;
-}
-
-function assertGeneratedBatchId(id, table, index) {
-    if (typeof id !== "number") {
-        throw createError(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${table})`, { code: "runtime" });
-    }
+    return message || detailText;
 }
 
 function assertTimeIdValue(id) {
@@ -168,14 +156,6 @@ function assertWriteFieldsDefined(tableInfo, data, table, label) {
     assertWriteFieldNamesDefined(tableInfo, Object.keys(data), table, label);
 }
 
-function assertNoUndefinedInRecord(row, label) {
-    for (const [key, value] of Object.entries(row)) {
-        if (value === undefined) {
-            throw validationError(`${label} 存在 undefined 字段值 (field: ${key})`);
-        }
-    }
-}
-
 function assertBatchInsertRowsConsistent(rows, options) {
     if (!Array.isArray(rows)) {
         throw validationError("批量插入 rows 必须是数组");
@@ -338,7 +318,8 @@ class DbHelper {
             const duration = Date.now() - startTime;
             const msg = getExecuteErrorMessage(executeError);
 
-            if (retryOnConnectionClosed && this.isConnectionClosedError(executeError, msg)) {
+            // 事务内连接已中断时重发单条语句可能造成半提交，直接抛出由事务回滚
+            if (retryOnConnectionClosed && !this.isTransaction && this.isConnectionClosedError(executeError, msg)) {
                 return this.execute(sql, params, false);
             }
 
@@ -395,7 +376,8 @@ class DbHelper {
     }
 
     async fetchCount(prepared, alias) {
-        const builder = this.createSqlBuilder().selectRaw(alias).from(prepared.table).where(prepared.where);
+        const countExpr = this.resolveCountExpr(prepared, alias);
+        const builder = this.createSqlBuilder().selectRaw(countExpr).from(prepared.table).where(prepared.where);
         this.applyLeftJoins(builder, prepared.leftJoins);
         const result = builder.toSelectSql();
         const executeRes = await this.execute(result.sql, result.params);
@@ -408,6 +390,17 @@ class DbHelper {
         };
     }
 
+    resolveCountExpr(prepared, alias) {
+        if (!prepared.leftJoins || prepared.leftJoins.length === 0) {
+            return alias;
+        }
+        // leftJoin 一对多时 COUNT(*) 统计的是 join 后行数，按主表主键去重保证 total 与主表条数一致
+        const parts = prepared.table.trim().split(/\s+/);
+        const qualifier = parts.length > 1 ? parts.at(-1) : parts[0].split(".").pop();
+        const primary = snakeCase(this.getTableModel(prepared.codeTable).primary || "id");
+        return `COUNT(DISTINCT ${quoteIdentMySql(qualifier)}.${quoteIdentMySql(primary)}) as total`;
+    }
+
     normalizeRowData(row, tableInfo = {}) {
         if (!row) {
             return {};
@@ -512,38 +505,16 @@ class DbHelper {
             };
         }
 
-        const ids = [];
-        try {
-            for (let i = 0; i < dataList.length; i++) {
-                ids.push(genId());
-            }
-        } catch (error) {
-            if (dataList.length === 1) {
-                throw createError(`生成 ID 失败 (table: ${table})`, {
-                    cause: error,
-                    code: "runtime",
-                    subsystem: "db",
-                    operation: "genId",
-                    table: table
-                });
-            }
-            throw error;
-        }
-
-        const processedList = dataList.map((data, index) => {
-            const id = ids[index];
-            if (dataList.length > 1) {
-                assertGeneratedBatchId(id, snakeTable, index);
-            }
-
-            return this.buildInsertRow({
+        const ids = dataList.map(() => genId());
+        const processedList = dataList.map((data, index) =>
+            this.buildInsertRow({
                 data: data,
-                id: id,
+                id: ids[index],
                 now: now,
                 beflyMode: tableMode,
                 tableInfo: tableInfo
-            });
-        });
+            })
+        );
 
         return {
             ids: ids,
@@ -715,7 +686,9 @@ class DbHelper {
         return {
             data: {
                 lists: lists,
-                total: total
+                total: total,
+                // 达到硬上限被截断时显式告知调用方，避免拿到不完整数据无感知
+                truncated: result.length >= MAX_LIMIT
             },
             sql: {
                 count: countResult.sql,
@@ -743,12 +716,8 @@ class DbHelper {
         const now = Date.now();
         const insertRows = await this.createInsertRows(table, snakeTable, [data], now);
         const processed = insertRows.processedList[0];
-
-        assertWriteDataHasFields(processed, "插入数据必须至少有一个字段", snakeTable);
         assertWriteFieldsDefined(tableInfo, processed, table, "insData.data");
 
-        assertNoUndefinedInRecord(processed, `insData 插入数据 (table: ${snakeTable})`);
-
         const builder = this.createSqlBuilder();
         const { sql, params } = builder.toInsertSql(snakeTable, processed);
         const executeRes = await this.execute(sql, params);
@@ -909,7 +878,6 @@ class DbHelper {
             beflyMode: this.getTableMode(parsed.table),
             tableInfo: tableInfo
         });
-        assertWriteDataHasFields(processed, "更新数据必须至少有一个字段", parsed.snakeTable);
         assertWriteFieldsDefined(tableInfo, processed, parsed.table, "updData.data");
         const builder = this.createSqlBuilder().where(parsed.where);
         const { sql, params } = builder.toUpdateSql(parsed.snakeTable, processed);

package/libs/mysql/dbParse.js

@@ -516,7 +516,11 @@ function applyDefaultStateFilter(where = {}, table, hasLeftJoin = false, beflyMo
         return where;
     }
 
-    const hasStateCondition = Object.keys(where).some((key) => key.startsWith("state") || key.includes(".state"));
+    // 剥离 $op / $or 后缀后精确匹配，避免 stateCode 等业务字段误判为已有 state 条件
+    const hasStateCondition = Object.keys(where).some((key) => {
+        const field = key.split("$")[0];
+        return field === "state" || field.endsWith(".state");
+    });
     if (hasStateCondition) {
         return where;
     }

package/libs/mysql/sql/sqlBuilder.js

@@ -26,6 +26,12 @@
 
 import { escapeField, escapeTable, resolveQuoteIdent } from "./identifier.js";
 
+function assertSafeLimit(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`LIMIT/OFFSET 必须是非负整数 (value: ${String(value)})`);
+    }
+}
+
 /**
  * SQL 构建器类
  */
@@ -290,8 +296,11 @@ export class SqlBuilder {
         }
 
         if (this.queryModel.limit !== null) {
+            // LIMIT/OFFSET 直接内插，必须在此断言整型，不信任调用方已校验
+            assertSafeLimit(this.queryModel.limit);
             sql += ` LIMIT ${this.queryModel.limit}`;
             if (this.queryModel.offset !== null && this.queryModel.offset !== undefined) {
+                assertSafeLimit(this.queryModel.offset);
                 sql += ` OFFSET ${this.queryModel.offset}`;
             }
         }