befly 3.74.2 → 3.75.0

package/lib/dbHelper.js

@@ -1,5 +1,6 @@
+import { createError, getRootCause, validationError } from "../utils/error.js";
 import { fieldClear } from "../utils/fieldClear.js";
-import { isNonEmptyString, isNullable, isNumber, isPlainObject, isString } from "../utils/is.js";
+import { isLowerCamelCaseName, isNonEmptyString, isNullable, isNumber, isPlainObject, isString } from "../utils/is.js";
 import { camelCase, canConvertToNumber, keysToSnake, snakeCase } from "../utils/util.js";
 import { DbParse } from "./dbParse.js";
 import { deserializeArrayFields, parseTableRef, serializeArrayFields } from "./dbUtil.js";
@@ -8,18 +9,12 @@ import { SqlBuilder } from "./sqlBuilder.js";
 
 function quoteIdentMySql(identifier) {
     if (!isString(identifier)) {
-        throw new Error(`quoteIdentifier 需要字符串类型标识符 (identifier: ${String(identifier)})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`quoteIdentifier 需要字符串类型标识符 (identifier: ${String(identifier)})`);
     }
 
     const trimmed = identifier.trim();
     if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(trimmed)) {
-        throw new Error(`无效的 SQL 标识符: ${trimmed}`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`无效的 SQL 标识符: ${trimmed}`);
     }
 
     return `\`${trimmed}\``;
@@ -114,28 +109,19 @@ function getExecuteErrorMessage(error) {
 
 function assertGeneratedBatchId(id, table, index) {
     if (typeof id !== "number") {
-        throw new Error(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${table})`, {
-            cause: null,
-            code: "runtime"
-        });
+        throw createError(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${table})`, { code: "runtime" });
     }
 }
 
 function assertTimeIdValue(id) {
     if (!Number.isFinite(id) || id <= 0) {
-        throw new Error(`buildInsertRow(timeId) 失败：id 必须为 > 0 的有限 number (id: ${String(id)})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`buildInsertRow(timeId) 失败：id 必须为 > 0 的有限 number (id: ${String(id)})`);
     }
 }
 
 function assertInsertBatchSize(count, maxBatchSize) {
     if (count > maxBatchSize) {
-        throw new Error(`批量插入数量 ${count} 超过最大限制 ${maxBatchSize}`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`批量插入数量 ${count} 超过最大限制 ${maxBatchSize}`);
     }
 }
 
@@ -144,10 +130,7 @@ function assertWriteDataHasFields(data, message, table) {
         return;
     }
 
-    throw new Error(`${message} (table: ${table})`, {
-        cause: null,
-        code: "validation"
-    });
+    throw validationError(`${message} (table: ${table})`);
 }
 
 function getTableFieldNames(tableInfo) {
@@ -173,8 +156,7 @@ function assertWriteFieldNamesDefined(tableInfo, fieldNames, table, label) {
         return;
     }
 
-    throw new Error(`${label} 包含表 ${table} 未定义字段: ${invalidFields.join(", ")}`, {
-        cause: null,
+    throw createError(`${label} 包含表 ${table} 未定义字段: ${invalidFields.join(", ")}`, {
         code: "validation",
         table: table,
         invalidFields: invalidFields,
@@ -189,74 +171,47 @@ function assertWriteFieldsDefined(tableInfo, data, table, label) {
 function assertNoUndefinedInRecord(row, label) {
     for (const [key, value] of Object.entries(row)) {
         if (value === undefined) {
-            throw new Error(`${label} 存在 undefined 字段值 (field: ${key})`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`${label} 存在 undefined 字段值 (field: ${key})`);
         }
     }
 }
 
 function assertBatchInsertRowsConsistent(rows, options) {
     if (!Array.isArray(rows)) {
-        throw new Error("批量插入 rows 必须是数组", {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError("批量插入 rows 必须是数组");
     }
     if (rows.length === 0) {
-        throw new Error(`插入数据不能为空 (table: ${options.table})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`插入数据不能为空 (table: ${options.table})`);
     }
 
     const first = rows[0];
     if (!first || typeof first !== "object" || Array.isArray(first)) {
-        throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: 0)`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: 0)`);
     }
 
     const fields = Object.keys(first);
     if (fields.length === 0) {
-        throw new Error(`插入数据必须至少有一个字段 (table: ${options.table})`, {
-            cause: null,
-            code: "validation"
-        });
+        throw validationError(`插入数据必须至少有一个字段 (table: ${options.table})`);
     }
 
     const fieldSet = new Set(fields);
     for (let i = 0; i < rows.length; i++) {
         const row = rows[i];
         if (!row || typeof row !== "object" || Array.isArray(row)) {
-            throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: ${i})`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: ${i})`);
         }
 
         const rowKeys = Object.keys(row);
         if (rowKeys.length !== fields.length) {
-            throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i})`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i})`);
         }
 
         for (const key of rowKeys) {
             if (!fieldSet.has(key)) {
-                throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`, {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`);
             }
             if (row[key] === undefined) {
-                throw new Error(`批量插入字段值不能为 undefined (table: ${options.table}, rowIndex: ${i}, field: ${key})`, {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError(`批量插入字段值不能为 undefined (table: ${options.table}, rowIndex: ${i}, field: ${key})`);
             }
         }
     }
@@ -269,10 +224,7 @@ class DbHelper {
         this.redis = options.redis;
 
         if (!isNonEmptyString(options.dbName)) {
-            throw new Error("DbHelper 初始化失败：dbName 必须为非空字符串", {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError("DbHelper 初始化失败：dbName 必须为非空字符串");
         }
         this.dbName = options.dbName;
 
@@ -280,26 +232,22 @@ class DbHelper {
         this.isTransaction = options.isTransaction === true;
         this.beflyMode = options.beflyMode === "manual" ? "manual" : "auto";
         this.tables = isPlainObject(options.tables) ? options.tables : {};
+        // 查询超时（毫秒）：防止 SQL 响应丢失/挂起导致启动或请求静默卡死
+        this.queryTimeout = (options.queryTimeout || 30) * 1000;
     }
 
     getTableDef(table) {
         const tableName = parseTableRef(table).table;
 
-        if (!/^_?[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/.test(tableName)) {
-            throw new Error(`表名必须使用小驼峰写法 (table: ${tableName})`, {
-                cause: null,
-                code: "validation"
-            });
+        if (!isLowerCamelCaseName(tableName)) {
+            throw validationError(`表名必须使用小驼峰写法 (table: ${tableName})`);
         }
 
         const tableInfo = this.tables[tableName];
 
         if (!isPlainObject(tableInfo)) {
             const sourceLabel = tableName.startsWith("befly") ? "packages/core/tables" : "app tables";
-            throw new Error(`表 ${tableName} 缺少本地 tables 定义，请检查 ${sourceLabel}`, {
-                cause: null,
-                code: "runtime"
-            });
+            throw createError(`表 ${tableName} 缺少本地 tables 定义，请检查 ${sourceLabel}`, { code: "runtime" });
         }
 
         return tableInfo;
@@ -321,36 +269,23 @@ class DbHelper {
 
     async execute(sql, params, retryOnConnectionClosed = true) {
         if (!this.sql) {
-            throw new Error("数据库连接未初始化", {
-                cause: null,
-                code: "runtime"
-            });
+            throw createError("数据库连接未初始化", { code: "runtime" });
         }
 
         if (!isString(sql)) {
-            throw new Error(`execute 只接受字符串类型的 SQL，收到类型: ${typeof sql}，值: ${JSON.stringify(sql)}`, {
-                cause: null,
-                code: "validation"
-            });
+            throw validationError(`execute 只接受字符串类型的 SQL，收到类型: ${typeof sql}，值: ${JSON.stringify(sql)}`);
         }
 
         const startTime = Date.now();
-        let safeParams = [];
+        const safeParams = [];
         if (!isNullable(params)) {
             if (!Array.isArray(params)) {
-                throw new Error(`SQL 参数必须是数组，当前类型: ${typeof params}`, {
-                    cause: null,
-                    code: "validation"
-                });
+                throw validationError(`SQL 参数必须是数组，当前类型: ${typeof params}`);
             }
 
-            safeParams = [];
             for (const value of params) {
                 if (value === undefined) {
-                    throw new Error("SQL 参数不能为 undefined", {
-                        cause: null,
-                        code: "validation"
-                    });
+                    throw validationError("SQL 参数不能为 undefined");
                 }
 
                 if (typeof value === "bigint") {
@@ -363,14 +298,16 @@ class DbHelper {
         }
 
         try {
-            let queryResult;
-            const timer = setTimeout(() => {}, 2147483647);
+            // 查询超时兜底：SQL 响应丢失/挂起时显式报错，避免进程静默卡死
             const queryPromise = safeParams.length > 0 ? this.sql.unsafe(sql, safeParams) : this.sql.unsafe(sql);
-            try {
-                queryResult = await queryPromise;
-            } finally {
-                clearTimeout(timer);
-            }
+            let timeoutId;
+            const timeoutPromise = new Promise((_, reject) => {
+                timeoutId = setTimeout(() => {
+                    reject(createError(`SQL 执行超时（${this.queryTimeout}ms）: ${sql.slice(0, 100)}`, { code: "runtime", subsystem: "sql", operation: "execute", sqlInfo: { sql: sql, params: safeParams } }));
+                }, this.queryTimeout);
+            });
+            const queryResult = await Promise.race([queryPromise, timeoutPromise]);
+            clearTimeout(timeoutId);
 
             const duration = Date.now() - startTime;
 
@@ -395,26 +332,25 @@ class DbHelper {
                 params: safeParams,
                 duration: duration
             };
-            const wrappedError = new Error(`SQL执行失败: ${msg}`, {
-                cause: error
+            throw createError(`SQL执行失败: ${msg}`, {
+                cause: error,
+                code: "runtime",
+                subsystem: "sql",
+                operation: "execute",
+                params: safeParams,
+                duration: duration,
+                sqlInfo: sqlInfo
             });
-
-            wrappedError.code = "runtime";
-            wrappedError.subsystem = "sql";
-            wrappedError.operation = "execute";
-            wrappedError.params = safeParams;
-            wrappedError.duration = duration;
-            wrappedError.sqlInfo = sqlInfo;
-
-            throw wrappedError;
         }
     }
 
     isConnectionClosedError(error, msg) {
-        if (error?.code === "ERR_MYSQL_CONNECTION_CLOSED") {
+        // 沿 cause 链取根因判断，保证错误被包装后重试逻辑依然生效
+        const rootCause = getRootCause(error);
+        if (rootCause?.code === "ERR_MYSQL_CONNECTION_CLOSED") {
             return true;
         }
-        if (error?.code === "ERR_POSTGRES_CONNECTION_CLOSED") {
+        if (rootCause?.code === "ERR_POSTGRES_CONNECTION_CLOSED") {
             return true;
         }
         if (typeof msg === "string" && msg.includes("Connection closed")) {
@@ -467,9 +403,6 @@ class DbHelper {
 
         const camelRow = this.normalizeDbFieldNames(row);
         const deserialized = deserializeArrayFields(camelRow);
-        if (!deserialized) {
-            return {};
-        }
 
         const convertedList = normalizeBigIntValues([deserialized]);
         if (convertedList && convertedList.length > 0) {
@@ -534,10 +467,7 @@ class DbHelper {
         const fieldNames = Object.keys(tableInfo);
 
         if (fieldNames.length === 0) {
-            throw new Error(`表 ${table} 的本地 tables 定义为空或没有字段`, {
-                cause: null,
-                code: "runtime"
-            });
+            throw createError(`表 ${table} 的本地 tables 定义为空或没有字段`, { code: "runtime" });
         }
 
         return fieldNames.map((fieldName) => snakeCase(fieldName));
@@ -574,11 +504,11 @@ class DbHelper {
             }
         } catch (error) {
             if (dataList.length === 1) {
-                throw new Error(`生成 ID 失败，Redis 可能不可用 (table: ${table})`, {
+                throw createError(`生成 ID 失败，Redis 可能不可用 (table: ${table})`, {
                     cause: error,
                     code: "runtime",
                     subsystem: "db",
-                    operation: "genTimeId",
+                    operation: "genTimeID",
                     table: table
                 });
             }
@@ -610,10 +540,7 @@ class DbHelper {
 
         if (this.beflyMode === "manual") {
             if (lastInsertRowidNum <= 0) {
-                throw new Error(operation === "insBatch" ? `批量插入失败：beflyMode=manual 时无法获取 lastInsertRowid (table: ${table})` : `插入失败：beflyMode=manual 时无法获取 lastInsertRowid (table: ${table})`, {
-                    cause: null,
-                    code: "runtime"
-                });
+                throw createError(operation === "insBatch" ? `批量插入失败：beflyMode=manual 时无法获取 lastInsertRowid (table: ${table})` : `插入失败：beflyMode=manual 时无法获取 lastInsertRowid (table: ${table})`, { code: "runtime" });
             }
 
             if (count === 1) {
@@ -848,13 +775,7 @@ class DbHelper {
                 sql: executeRes.sql
             };
         } catch (error) {
-            Logger.error("批量插入失败", error, {
-                table: table,
-                snakeTable: snakeTable,
-                count: dataList.length,
-                fields: insertFields
-            });
-            throw new Error("批量插入失败", {
+            throw createError("批量插入失败", {
                 cause: error,
                 code: "runtime",
                 subsystem: "sql",
@@ -1053,17 +974,11 @@ class DbHelper {
 
     async trans(callback) {
         if (this.isTransaction) {
-            throw new Error("不支持嵌套事务", {
-                cause: null,
-                code: "policy"
-            });
+            throw createError("不支持嵌套事务", { code: "policy" });
         }
 
         if (typeof this.sql?.begin !== "function") {
-            throw new Error("不支持事务 begin() 方法", {
-                cause: null,
-                code: "runtime"
-            });
+            throw createError("不支持事务 begin() 方法", { code: "runtime" });
         }
 
         return await this.sql.begin(async (tx) => {