befly 3.74.2 → 3.75.0

package/lib/smtpText.js

@@ -1,5 +1,7 @@
 import { Buffer } from "node:buffer";
 
+import { createError } from "../utils/error.js";
+
 function encodeBase64(value) {
     return Buffer.from(String(value || ""), "utf8").toString("base64");
 }
@@ -98,7 +100,7 @@ function createResponseReader() {
 
         const responseLines = [];
         let consumedCount = 0;
-        let code = 0;
+        let code;
         for (const line of completeLines) {
             consumedCount = consumedCount + 1;
             responseLines.push(line);
@@ -143,8 +145,7 @@ function createResponseReader() {
         close: function (error) {
             closedError =
                 error ||
-                new Error("SMTP 连接已关闭", {
-                    cause: null,
+                createError("SMTP 连接已关闭", {
                     code: "runtime",
                     subsystem: "smtp",
                     operation: "readResponse"
@@ -171,8 +172,7 @@ async function readResponseWithTimeout(reader, timeout) {
             new Promise(function (_resolve, reject) {
                 timer = setTimeout(function () {
                     reject(
-                        new Error("SMTP 响应超时", {
-                            cause: null,
+                        createError("SMTP 响应超时", {
                             code: "runtime",
                             subsystem: "smtp",
                             operation: "readResponse"
@@ -189,13 +189,7 @@ async function readResponseWithTimeout(reader, timeout) {
 async function expectResponse(reader, expectedCodes, commandName, timeout) {
     const response = await readResponseWithTimeout(reader, timeout);
     if (!expectedCodes.includes(response.code)) {
-        throw new Error(`SMTP ${commandName} 响应异常: ${response.text}`, {
-            cause: null,
-            code: "runtime",
-            subsystem: "smtp",
-            operation: commandName,
-            response: response.text
-        });
+        throw createError(`SMTP ${commandName} 响应异常: ${response.text}`, { code: "runtime", subsystem: "smtp", operation: commandName, response: response.text });
     }
     return response;
 }
@@ -207,12 +201,7 @@ function writeCommand(socket, command) {
 export async function sendSmtpTextMail(config, options) {
     const mail = createSmtpTextMessage(config, options);
     if (mail.recipients.length === 0) {
-        throw new Error("邮件收件人不能为空", {
-            cause: null,
-            code: "validation",
-            subsystem: "smtp",
-            operation: "sendSmtpTextMail"
-        });
+        throw createError("邮件收件人不能为空", { code: "validation", subsystem: "smtp", operation: "sendSmtpTextMail" });
     }
 
     const reader = createResponseReader();

package/lib/sqlBuilder.js

@@ -1,6 +1,27 @@
 /**
- * SQL 构造器 - JavaScript 版本
  * 提供链式 API 构建 SQL 查询
+ *
+ * ==================== where 节点树协议 ====================
+ *
+ * 本类消费由 lib/dbParse.js 产出的 where 节点树（唯一协议来源），
+ * 新增节点类型/操作符时必须同步修改 dbParse 的产出端与这里的编译端。
+ *
+ * 节点结构（三态）：
+ * 1. 条件组：{ type: "group", join: "AND" | "OR", items: Node[] }
+ *    - items 为空数组时编译为空串（不生成 WHERE 片段）
+ *    - join 为 OR 时，组内每个子条件单独加括号
+ * 2. 操作节点：{ type: "op", field: string, operator: string, value: any }
+ *    - operator 支持（缺省按等值处理）：$not $in $notIn $like $leftLike $rightLike $notLike
+ *      $gt $gte $lt $lte $between $notBetween $null $notNull
+ *    - $between/$notBetween 的 value 为 [min, max]
+ *    - 缺省操作符：value === null 编译为 IS NULL，否则 =
+ *    - field 已由 dbParse 完成合法性校验，这里仅做标识符转义
+ * 3. 原始片段：{ type: "raw", sql: string, params?: any[] }
+ *    - 由 whereRaw() 手动追加，或 dbParse 在特殊场景产出
+ *
+ * 边界约定：
+ * - 空字符串 like/leftLike/rightLike 由 dbParse 过滤，不进入节点树
+ * - 本类不校验节点合法性（信任上层），仅负责编译
  */
 
 import { isNonEmptyString } from "../utils/is.js";
@@ -26,22 +47,6 @@ export class SqlBuilder {
         };
     }
 
-    /**
-     * 重置构建器状态
-     */
-    reset() {
-        this.queryModel = {
-            select: [],
-            from: null,
-            where: { type: "group", join: "AND", items: [] },
-            joins: [],
-            orderBy: [],
-            limit: null,
-            offset: null
-        };
-        return this;
-    }
-
     compileOperatorNode(node) {
         const escapedField = escapeField(node.field, this.quoteIdentifier);
 
@@ -177,14 +182,6 @@ export class SqlBuilder {
         return this;
     }
 
-    /**
-     * FROM 原始表达式（不做转义）
-     */
-    fromRaw(tableExpr) {
-        this.queryModel.from = { type: "raw", value: tableExpr.trim() };
-        return this;
-    }
-
     /**
      * WHERE 条件
      */
@@ -381,32 +378,6 @@ export class SqlBuilder {
         };
     }
 
-    /**
-     * 构建 COUNT 查询
-     */
-    toCountSql() {
-        const params = [];
-        let fromSql = this.queryModel.from.value;
-        if (this.queryModel.from.type !== "raw") {
-            fromSql = escapeTable(this.queryModel.from.value, this.quoteIdentifier);
-        }
-        let sql = `SELECT COUNT(*) as total FROM ${fromSql}`;
-
-        if (this.queryModel.joins.length > 0) {
-            sql += ` ${this.queryModel.joins.map((join) => `${join.type.toUpperCase()} JOIN ${escapeTable(join.table, this.quoteIdentifier)} ON ${join.on}`).join(" ")}`;
-        }
-
-        const whereResult = this.compileWhereNode(this.queryModel.where);
-        if (whereResult.sql) {
-            sql += ` WHERE ${whereResult.sql}`;
-            for (const param of whereResult.params) {
-                params.push(param);
-            }
-        }
-
-        return { sql: sql, params: params };
-    }
-
     static toDeleteInSql(options) {
         if (options.ids.length === 0) {
             return { sql: "", params: [] };

package/lib/xmlParse.js

@@ -1,3 +1,4 @@
+import { createError } from "#befly/utils/error.js";
 import { isString } from "#befly/utils/is.js";
 
 function decodeXmlText(value) {
@@ -44,13 +45,8 @@ function skipIgnoredMarkup(rawXml, startIndex) {
 
         if (rawXml.startsWith("<?", index)) {
             const declarationEnd = rawXml.indexOf("?>", index);
-            if (declarationEnd < 0) {
-                throw new Error("XML 声明未闭合", {
-                    cause: null,
-                    code: "validation",
-                    subsystem: "xml",
-                    operation: "skipIgnoredMarkup"
-                });
+            if (declarationEnd === -1) {
+                throw createError("XML 声明未闭合", { code: "validation", subsystem: "xml", operation: "skipIgnoredMarkup" });
             }
             index = declarationEnd + 2;
             continue;
@@ -58,13 +54,8 @@ function skipIgnoredMarkup(rawXml, startIndex) {
 
         if (rawXml.startsWith("<!--", index)) {
             const commentEnd = rawXml.indexOf("-->", index);
-            if (commentEnd < 0) {
-                throw new Error("XML 注释未闭合", {
-                    cause: null,
-                    code: "validation",
-                    subsystem: "xml",
-                    operation: "skipIgnoredMarkup"
-                });
+            if (commentEnd === -1) {
+                throw createError("XML 注释未闭合", { code: "validation", subsystem: "xml", operation: "skipIgnoredMarkup" });
             }
             index = commentEnd + 3;
             continue;
@@ -78,25 +69,15 @@ function skipIgnoredMarkup(rawXml, startIndex) {
 
 function parseNode(rawXml, startIndex) {
     const openEnd = rawXml.indexOf(">", startIndex);
-    if (openEnd < 0) {
-        throw new Error("XML 开始标签不完整", {
-            cause: null,
-            code: "validation",
-            subsystem: "xml",
-            operation: "parseNode"
-        });
+    if (openEnd === -1) {
+        throw createError("XML 开始标签不完整", { code: "validation", subsystem: "xml", operation: "parseNode" });
     }
 
     const openContent = rawXml.slice(startIndex + 1, openEnd).trim();
     const isSelfClosing = openContent.endsWith("/");
     const tagName = (isSelfClosing ? openContent.slice(0, -1).trim() : openContent).split(/\s+/)[0];
     if (!tagName || tagName.startsWith("/")) {
-        throw new Error("XML 标签格式不正确", {
-            cause: null,
-            code: "validation",
-            subsystem: "xml",
-            operation: "parseNode"
-        });
+        throw createError("XML 标签格式不正确", { code: "validation", subsystem: "xml", operation: "parseNode" });
     }
     if (isSelfClosing) {
         return {
@@ -116,13 +97,8 @@ function parseNode(rawXml, startIndex) {
 
         if (rawXml.startsWith("<![CDATA[", index)) {
             const cdataEnd = rawXml.indexOf("]]>", index);
-            if (cdataEnd < 0) {
-                throw new Error("XML CDATA 未闭合", {
-                    cause: null,
-                    code: "validation",
-                    subsystem: "xml",
-                    operation: "parseNode"
-                });
+            if (cdataEnd === -1) {
+                throw createError("XML CDATA 未闭合", { code: "validation", subsystem: "xml", operation: "parseNode" });
             }
             text += rawXml.slice(index + 9, cdataEnd);
             index = cdataEnd + 3;
@@ -147,45 +123,25 @@ function parseNode(rawXml, startIndex) {
         }
 
         const nextTagIndex = rawXml.indexOf("<", index);
-        if (nextTagIndex < 0) {
-            throw new Error("XML 结束标签缺失", {
-                cause: null,
-                code: "validation",
-                subsystem: "xml",
-                operation: "parseNode"
-            });
+        if (nextTagIndex === -1) {
+            throw createError("XML 结束标签缺失", { code: "validation", subsystem: "xml", operation: "parseNode" });
         }
         text += rawXml.slice(index, nextTagIndex);
         index = nextTagIndex;
     }
 
-    throw new Error("XML 标签未闭合", {
-        cause: null,
-        code: "validation",
-        subsystem: "xml",
-        operation: "parseNode"
-    });
+    throw createError("XML 标签未闭合", { code: "validation", subsystem: "xml", operation: "parseNode" });
 }
 
 export function xmlParse(value) {
     if (!isString(value) || value.length < 1) {
-        throw new Error("xmlParse 输入必须是非空字符串", {
-            cause: null,
-            code: "validation",
-            subsystem: "xml",
-            operation: "xmlParse"
-        });
+        throw createError("xmlParse 输入必须是非空字符串", { code: "validation", subsystem: "xml", operation: "xmlParse" });
     }
 
     const normalized = value.trim();
     const startIndex = skipIgnoredMarkup(normalized, 0);
     if (normalized[startIndex] !== "<") {
-        throw new Error("XML 根节点缺失", {
-            cause: null,
-            code: "validation",
-            subsystem: "xml",
-            operation: "xmlParse"
-        });
+        throw createError("XML 根节点缺失", { code: "validation", subsystem: "xml", operation: "xmlParse" });
     }
 
     const node = parseNode(normalized, startIndex);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.74.2",
+    "version": "3.75.0",
     "gitHead": "49c39d36695036e85fc64083cc43c1652fff96cb",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",

package/plugins/cache.js

@@ -1,15 +1,14 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
 /**
- * 缓存插件 - JavaScript 版本
  * 负责在服务器启动时缓存接口、菜单和角色权限到 Redis
  */
-
 import { CacheHelper } from "../lib/cacheHelper.js";
 
 /**
  * 缓存插件
  */
 export default {
-    order: 6,
+    order: PLUGIN_ORDER.CACHE,
     handler: async function (befly) {
         return new CacheHelper({ mysql: befly.mysql, redis: befly.redis });
     }

package/plugins/config.js

@@ -1,10 +1,12 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
+
 /**
  * 配置插件
  * 提供访问项目配置的能力
  */
 
 export default {
-    order: 1,
+    order: PLUGIN_ORDER.CONFIG,
     handler: (befly) => {
         return befly.config;
     }

package/plugins/cron.js

@@ -1,8 +1,8 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
 /**
  * 定时任务插件
  * 基于 Bun.cron 提供进程内定时任务能力。
  */
-
 import { Logger } from "../lib/logger.js";
 import { isPrimaryProcess } from "../utils/is.js";
 
@@ -84,7 +84,7 @@ export function stopAll() {
 }
 
 export default {
-    order: 8,
+    order: PLUGIN_ORDER.CRON,
     handler: async function (befly) {
         return {
             register: (name, schedule, task) => register(befly, name, schedule, task),

package/plugins/email.js

@@ -2,8 +2,10 @@ import { Logger } from "#befly/lib/logger.js";
 import { sendSmtpTextMail } from "#befly/lib/smtpText.js";
 import { hasEmailConfig } from "#befly/utils/email.js";
 
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
+
 export default {
-    order: 7,
+    order: PLUGIN_ORDER.EMAIL,
     handler: async function (befly) {
         const config = befly?.config?.email || {};
         const enabled = hasEmailConfig(config);

package/plugins/logger.js

@@ -1,15 +1,15 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
 /**
  * 日志插件
  * 提供全局日志功能
  */
-
 import { Logger } from "../lib/logger.js";
 
 /**
  * 日志插件
  */
 export default {
-    order: 2,
+    order: PLUGIN_ORDER.LOGGER,
     handler: async function () {
         // 日志已在 createBefly 中按 runMode 初始化，这里只注入 Logger 实例
         return Logger;

package/plugins/mysql.js

@@ -1,17 +1,17 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
 /**
  * 数据库插件
  * 初始化数据库连接和 SQL 管理器
  */
-
 import { Connect } from "../lib/connect.js";
 import { DbHelper } from "../lib/dbHelper.js";
-import { Logger } from "../lib/logger.js";
+import { createError } from "../utils/error.js";
 
 /**
  * 数据库插件
  */
 export default {
-    order: 5,
+    order: PLUGIN_ORDER.MYSQL,
     handler: async function (befly) {
         try {
             // 创建数据库管理器实例
@@ -20,18 +20,13 @@ export default {
                 dbName: befly.config?.mysql?.database,
                 sql: Connect.getMysql(),
                 beflyMode: befly.config?.mysql?.beflyMode,
+                queryTimeout: befly.config?.mysql?.queryTimeout,
                 tables: befly.tables
             });
 
             return dbManager;
         } catch (error) {
-            Logger.error("数据库初始化失败", error, { runMode: befly.config?.runMode });
-            throw new Error("数据库初始化失败", {
-                cause: error,
-                code: "runtime",
-                subsystem: "db",
-                operation: "init"
-            });
+            throw createError("数据库初始化失败", { cause: error, code: "runtime", subsystem: "db", operation: "init" });
         }
     }
 };

package/plugins/redis.js

@@ -1,19 +1,18 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
 /**
  * Redis 插件
  * 初始化 Redis 连接和助手工具
  */
-
 import { Connect } from "../lib/connect.js";
-import { Logger } from "../lib/logger.js";
 import { RedisHelper } from "../lib/redisHelper.js";
+import { createError } from "../utils/error.js";
 
 /**
  * Redis 插件
  */
 export default {
-    order: 4,
+    order: PLUGIN_ORDER.REDIS,
     handler: async function (befly) {
-        const env = befly.config?.runMode;
         const redisPrefix = befly.config?.redis?.prefix;
         try {
             // 启动期已建立 Redis 连接；这里仅校验连接存在
@@ -22,13 +21,7 @@ export default {
             // 返回 RedisHelper 实例
             return new RedisHelper(redisPrefix);
         } catch (error) {
-            Logger.error("Redis 初始化失败", error, { env: env });
-            throw new Error("Redis 初始化失败", {
-                cause: error,
-                code: "runtime",
-                subsystem: "redis",
-                operation: "init"
-            });
+            throw createError("Redis 初始化失败", { cause: error, code: "runtime", subsystem: "redis", operation: "init" });
         }
     }
 };

package/plugins/tool.js

@@ -1,8 +1,8 @@
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
 /**
  * 工具插件
  * 提供常用的工具函数
  */
-
 import { isNumber, isString } from "../utils/is.js";
 
 /**
@@ -94,7 +94,7 @@ export function Raw(ctx, data, options = {}) {
     } else {
         // JSON 序列化（对象/数组/原始值均可）
         body = JSON.stringify(data);
-        finalContentType = finalContentType || "application/json";
+        finalContentType ||= "application/json";
     }
 
     // 合并响应头
@@ -119,7 +119,7 @@ export function Raw(ctx, data, options = {}) {
 }
 
 export default {
-    order: 3,
+    order: PLUGIN_ORDER.TOOL,
     handler: () => {
         return {
             Yes: Yes,

package/plugins/xmlParse.js

@@ -1,7 +1,9 @@
 import { xmlParse } from "#befly/lib/xmlParse.js";
 
+import { PLUGIN_ORDER } from "../configs/constConfig.js";
+
 export default {
-    order: 4,
+    order: PLUGIN_ORDER.XML_PARSE,
     handler: () => {
         return xmlParse;
     }

package/router/api.js

@@ -8,6 +8,7 @@ import picomatch from "picomatch";
 import { Logger } from "../lib/logger.js";
 // 相对导入
 import { setCorsOptions } from "../utils/cors.js";
+import { createError } from "../utils/error.js";
 import { getClientIp } from "../utils/getClientIp.js";
 import { ErrorResponse, FinalResponse } from "../utils/response.js";
 import { genShortId } from "../utils/util.js";
@@ -17,12 +18,7 @@ function createExcludeApisLogMatchers(excludeApisLog) {
         try {
             return picomatch(pattern);
         } catch (error) {
-            throw new Error(`excludeApisLog glob 无效: ${pattern}`, {
-                cause: error,
-                code: "validation",
-                subsystem: "config",
-                operation: "excludeApisLog"
-            });
+            throw createError(`excludeApisLog glob 无效: ${pattern}`, { cause: error, code: "validation", subsystem: "config", operation: "excludeApisLog" });
         }
     });
 }

package/router/static.js

@@ -76,17 +76,16 @@ export function staticHandler(corsConfig, uploadConfig) {
                 return new Response(file, {
                     headers: headers
                 });
-            } else {
-                return Response.json(
-                    {
-                        code: 1,
-                        msg: "文件未找到"
-                    },
-                    {
-                        headers: corsHeaders
-                    }
-                );
             }
+            return Response.json(
+                {
+                    code: 1,
+                    msg: "文件未找到"
+                },
+                {
+                    headers: corsHeaders
+                }
+            );
         } catch (error) {
             Logger.error("静态文件处理失败", error);
 

package/schemas/config.js

@@ -1,12 +1,9 @@
-import { RUN_MODE_VALUES } from "../configs/constConfig.js";
-
 const noTrimString = { type: "string", noTrim: true };
 const boolInt = { type: "boolInt" };
 const port = { type: "number", integer: true, min: 1, max: 65535 };
 
 export const configSchema = {
     root: {
-        runMode: { type: "values", values: RUN_MODE_VALUES },
         appName: noTrimString,
         appPort: port,
         appHost: noTrimString,
@@ -37,7 +34,8 @@ export const configSchema = {
             beflyMode: { type: "values", values: ["manual", "auto"], optional: true },
             idleTimeout: { type: "number", min: 1, optional: true },
             maxLifetime: { type: "number", min: 0, optional: true },
-            connectionTimeout: { type: "number", min: 1, optional: true }
+            connectionTimeout: { type: "number", min: 1, optional: true },
+            queryTimeout: { type: "number", min: 1, optional: true }
         },
         redis: {
             hostname: noTrimString,
@@ -58,6 +56,8 @@ export const configSchema = {
         },
         rateLimit: {
             enable: boolInt,
+            // 限流服务不可用时是否放行（1 放行 / 0 拒绝），默认 1
+            failOpen: boolInt,
             defaultLimit: { type: "number", integer: true, min: 1 },
             defaultWindow: { type: "number", integer: true, min: 1 },
             key: noTrimString,

package/scripts/syncDb/context.js

@@ -1,9 +1,11 @@
 import { mkdir } from "node:fs/promises";
 import { basename, resolve, join } from "node:path";
 
+import { BEFLY_TABLE_PREFIX } from "#befly/configs/constConfig.js";
 import { Connect } from "#befly/lib/connect.js";
 import { DbHelper } from "#befly/lib/dbHelper.js";
 import { Logger } from "#befly/lib/logger.js";
+import { createError } from "#befly/utils/error.js";
 import { importDefault } from "#befly/utils/importDefault.js";
 import { isNonEmptyString, isPlainObject } from "#befly/utils/is.js";
 import { camelCase } from "#befly/utils/util.js";
@@ -35,12 +37,7 @@ export async function prepareSyncDbBaseContext(mysqlConfig) {
     printSyncDbProcessLog(`表定义目录=${tablesDir}`);
 
     if (!isPlainObject(mysqlConfig)) {
-        throw new Error("syncDb 缺少 mysql 配置", {
-            cause: null,
-            code: "validation",
-            subsystem: "scripts",
-            operation: "syncDb"
-        });
+        throw createError("syncDb 缺少 mysql 配置", { code: "validation", subsystem: "scripts", operation: "syncDb" });
     }
 
     printSyncDbProcessLog(`同步模式=${mysqlConfig.beflyMode === "manual" ? "手动" : "自动"}`);
@@ -61,7 +58,7 @@ export async function prepareSyncDbBaseContext(mysqlConfig) {
     const skippedBeflyTables = new Set();
     for (const row of dbColumns) {
         const tableName = String(row?.tableName || "");
-        if (isNonEmptyString(tableName) && tableName.toLowerCase().startsWith("befly_")) {
+        if (isNonEmptyString(tableName) && tableName.toLowerCase().startsWith(BEFLY_TABLE_PREFIX)) {
             skippedBeflyTables.add(tableName);
         }
     }

package/scripts/syncDb/diff.js

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 
+import { BEFLY_TABLE_PREFIX } from "#befly/configs/constConfig.js";
 import { isNonEmptyString, isPlainObject } from "#befly/utils/is.js";
 import { camelCase, snakeCase } from "#befly/utils/util.js";
 
@@ -67,7 +68,7 @@ export function groupSyncDbColumns(rows) {
         if (!isNonEmptyString(tableName)) {
             continue;
         }
-        if (tableName.toLowerCase().startsWith("befly_")) {
+        if (tableName.toLowerCase().startsWith(BEFLY_TABLE_PREFIX)) {
             continue;
         }
 

package/scripts/syncDb/index.js

@@ -2,6 +2,7 @@ import { join, resolve } from "node:path";
 
 import { Connect } from "#befly/lib/connect.js";
 import { Logger } from "#befly/lib/logger.js";
+import { createError } from "#befly/utils/error.js";
 
 import { prepareSyncDbBaseContext } from "./context.js";
 import { applySyncDbDiff } from "./diff.js";
@@ -34,12 +35,7 @@ export async function syncDb(mysqlConfig) {
             reportPath: writtenReportPath
         };
     } catch (error) {
-        throw new Error("执行表定义同步失败", {
-            cause: error,
-            code: "runtime",
-            subsystem: "scripts",
-            operation: "syncDb"
-        });
+        throw createError("执行表定义同步失败", { cause: error, code: "runtime", subsystem: "scripts", operation: "syncDb" });
     } finally {
         await Connect.disconnect();
         await Logger.flush();