befly 3.20.11 → 3.21.0

package/lib/dbHelper.js

@@ -0,0 +1,1626 @@
+import { fieldClear } from "../utils/fieldClear.js";
+import { isNonEmptyString, isNullable, isNumber, isPlainObject, isString } from "../utils/is.js";
+import { arrayKeysToCamel, canConvertToNumber, keysToCamel, keysToSnake, snakeCase } from "../utils/util.js";
+import { Logger } from "./logger.js";
+import { SqlBuilder } from "./sqlBuilder.js";
+import { addDefaultStateFilter, assertBatchInsertRowsConsistent, assertNoUndefinedInRecord, clearDeep, deserializeArrayFields, fieldsToSnake, orderByToSnake, parseLeftJoinItem, parseTableRef, processJoinField, processJoinOrderBy, processJoinWhere, serializeArrayFields, validateExplicitLeftJoinFields, validateExplicitReadFields, whereKeysToSnake } from "./dbUtil.js";
+
+function quoteIdentMySql(identifier) {
+    if (!isString(identifier)) {
+        throw new Error(`quoteIdentifier 需要字符串类型标识符 (identifier: ${String(identifier)})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const trimmed = identifier.trim();
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(trimmed)) {
+        throw new Error(`无效的 SQL 标识符: ${trimmed}`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return `\`${trimmed}\``;
+}
+
+function normalizeTableRef(tableRef) {
+    const parsed = parseTableRef(tableRef);
+    const schemaPart = parsed.schema ? snakeCase(parsed.schema) : null;
+    const tablePart = snakeCase(parsed.table);
+    const aliasPart = parsed.alias ? snakeCase(parsed.alias) : null;
+    let result = schemaPart ? `${schemaPart}.${tablePart}` : tablePart;
+    if (aliasPart) {
+        result = `${result} ${aliasPart}`;
+    }
+    return result;
+}
+
+function getJoinMainQualifier(tableRef) {
+    const parsed = parseTableRef(tableRef);
+    if (parsed.alias) {
+        return snakeCase(parsed.alias);
+    }
+    return snakeCase(parsed.table);
+}
+
+function normalizeSqlMetaNumber(value) {
+    if (isNullable(value)) {
+        return 0;
+    }
+
+    if (typeof value !== "number") {
+        return 0;
+    }
+
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+
+    return value;
+}
+
+function normalizeBigIntValues(value) {
+    if (isNullable(value)) {
+        return value;
+    }
+
+    const convertRecord = (source) => {
+        const converted = {};
+
+        for (const [key, item] of Object.entries(source)) {
+            let nextValue = item;
+
+            if (typeof item === "bigint") {
+                const convertedNumber = canConvertToNumber(item);
+                if (convertedNumber !== null) {
+                    nextValue = convertedNumber;
+                } else {
+                    nextValue = String(item);
+                }
+            }
+
+            converted[key] = nextValue;
+        }
+
+        return converted;
+    };
+
+    if (Array.isArray(value)) {
+        return value.map((item) => convertRecord(item));
+    }
+
+    if (typeof value === "object") {
+        return convertRecord(value);
+    }
+
+    return value;
+}
+
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    } catch {
+        try {
+            return String(value);
+        } catch {
+            return "[Unserializable]";
+        }
+    }
+}
+
+function getExecuteErrorMessage(error) {
+    if (error instanceof Error && typeof error.message === "string" && error.message.trim().length > 0) {
+        return error.message.trim();
+    }
+
+    if (!error || typeof error !== "object") {
+        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 = {};
+
+    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;
+    }
+
+    const detailText = Object.keys(detail).length > 0 ? safeStringify(detail) : safeStringify(error);
+    if (message && detailText && detailText !== "{}") {
+        return `${message} | ${detailText}`;
+    }
+    if (message) {
+        return message;
+    }
+    return detailText;
+}
+
+function assertNonEmptyString(value, label) {
+    if (!isNonEmptyString(value)) {
+        throw new Error(`${label} 必须是非空字符串`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function assertPlainObjectValue(value, label) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateExcludeRules(excludeRules, label) {
+    if (isNullable(excludeRules)) {
+        return;
+    }
+
+    if (!isPlainObject(excludeRules)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const [key, value] of Object.entries(excludeRules)) {
+        assertNonEmptyString(key, `${label} 的字段名`);
+        if (!Array.isArray(value)) {
+            throw new Error(`${label}.${key} 必须是数组`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function validateWhereMeta(where, label) {
+    if (!isPlainObject(where)) {
+        return;
+    }
+
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "$exclude") {
+            validateExcludeRules(value, `${label}.$exclude`);
+            continue;
+        }
+
+        if ((key === "$or" || key === "$and") && Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                if (isPlainObject(value[i])) {
+                    validateWhereMeta(value[i], `${label}.${key}[${i}]`);
+                }
+            }
+            continue;
+        }
+
+        if (isPlainObject(value)) {
+            validateWhereMeta(value, `${label}.${key}`);
+        }
+    }
+}
+
+function validateWhereObject(where, label, required = false) {
+    if (isNullable(where)) {
+        if (required) {
+            throw new Error(`${label} 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        return;
+    }
+
+    if (!isPlainObject(where)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    validateWhereMeta(where, label);
+}
+
+function validateOrderByItems(orderBy, label) {
+    if (!Array.isArray(orderBy)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const item of orderBy) {
+        if (!isString(item) || !item.includes("#")) {
+            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const parts = item.split("#");
+        if (parts.length !== 2) {
+            throw new Error(`${label} 字段必须是 "字段#方向" 格式的字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const field = isString(parts[0]) ? parts[0].trim() : "";
+        const direction = isString(parts[1]) ? parts[1].trim().toUpperCase() : "";
+        if (!field) {
+            throw new Error(`${label} 中字段名不能为空`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (direction !== "ASC" && direction !== "DESC") {
+            throw new Error(`${label} 方向必须是 ASC 或 DESC`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function validateJoinFieldRef(value, label) {
+    if (!isNonEmptyString(value)) {
+        throw new Error(`${label} 不能为空`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const parts = value.split(".").map((item) => item.trim());
+    if (parts.length !== 2 || !isNonEmptyString(parts[0]) || !isNonEmptyString(parts[1])) {
+        throw new Error(`${label} 必须是 alias.field 格式`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function parseLeftJoinEquality(joinItem) {
+    if (!isNonEmptyString(joinItem)) {
+        return null;
+    }
+
+    const match = joinItem.match(/^([a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*) ([a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*)$/);
+    if (!match) {
+        return null;
+    }
+
+    return {
+        left: match[1],
+        right: match[2]
+    };
+}
+
+function validateLeftJoinItems(leftJoin, label) {
+    if (!Array.isArray(leftJoin)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (let i = 0; i < leftJoin.length; i++) {
+        const joinItem = leftJoin[i];
+        if (!isNonEmptyString(joinItem)) {
+            throw new Error(`${label}[${i}] 必须是非空字符串`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const parsed = parseLeftJoinEquality(joinItem);
+        if (!parsed) {
+            throw new Error(`${label}[${i}] 必须是 "left.field right.field" 格式（空格表示等于）`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        validateJoinFieldRef(parsed.left, `${label}[${i}] 左侧字段`);
+        validateJoinFieldRef(parsed.right, `${label}[${i}] 右侧字段`);
+    }
+}
+
+function validateLegacyJoinOptions(options, label) {
+    const legacyJoinKeys = ["joins", "innerJoin", "rightJoin"];
+    for (const key of legacyJoinKeys) {
+        if (!isNullable(options[key])) {
+            throw new Error(`${label} 仅支持 leftJoin，${label}.${key} 已废弃`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function validateQueryTableOption(table, leftJoin, label) {
+    if (Array.isArray(table)) {
+        if (table.length === 0) {
+            throw new Error(`${label}.table 不能为空数组`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        for (let i = 0; i < table.length; i++) {
+            assertNonEmptyString(table[i], `${label}.table[${i}]`);
+            parseTableRef(table[i]);
+        }
+
+        if (Array.isArray(leftJoin) && leftJoin.length > 0) {
+            if (table.length !== leftJoin.length + 1) {
+                throw new Error(`${label}.table 与 ${label}.leftJoin 数量不匹配，要求 table.length = leftJoin.length + 1`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            return;
+        }
+
+        if (table.length > 1) {
+            throw new Error(`${label}.table 为数组时必须配合 leftJoin 使用`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        return;
+    }
+
+    assertNonEmptyString(table, `${label}.table`);
+    parseTableRef(table);
+
+    if (Array.isArray(leftJoin) && leftJoin.length > 0) {
+        throw new Error(`${label}.leftJoin 启用时，${label}.table 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateQueryOptions(options, label) {
+    if (!isPlainObject(options)) {
+        throw new Error(`${label} 必须是对象`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    validateQueryTableOption(options.table, options.leftJoin, label);
+
+    if (!isNullable(options.where)) {
+        validateWhereObject(options.where, `${label}.where`);
+    }
+
+    if (!isNullable(options.fields) && !Array.isArray(options.fields)) {
+        throw new Error(`${label}.fields 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.orderBy)) {
+        validateOrderByItems(options.orderBy, `${label}.orderBy`);
+    }
+
+    validateLegacyJoinOptions(options, label);
+
+    if (!isNullable(options.leftJoin)) {
+        validateLeftJoinItems(options.leftJoin, `${label}.leftJoin`);
+    }
+
+    if (!isNullable(options.page) && (!Number.isFinite(options.page) || Math.floor(options.page) !== options.page)) {
+        throw new Error(`${label}.page 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!isNullable(options.limit) && (!Number.isFinite(options.limit) || Math.floor(options.limit) !== options.limit)) {
+        throw new Error(`${label}.limit 必须是整数`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateTableName(table, label) {
+    assertNonEmptyString(table, label);
+}
+
+function validateBatchDataList(dataList, label) {
+    if (!Array.isArray(dataList)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (let i = 0; i < dataList.length; i++) {
+        if (!isPlainObject(dataList[i])) {
+            throw new Error(`${label}[${i}] 必须是对象`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+}
+
+function validateTableWhereOptions(options, label, required = false) {
+    validateTableName(options.table, `${label}.table`);
+    validateWhereObject(options.where, `${label}.where`, required);
+}
+
+function validateTableDataOptions(options, label) {
+    validateTableName(options.table, `${label}.table`);
+    assertPlainObjectValue(options.data, `${label}.data`);
+}
+
+function validateTableBatchDataOptions(table, dataList, label) {
+    validateTableName(table, `${label}.table`);
+    validateBatchDataList(dataList, `${label}.dataList`);
+}
+
+function validateSimpleTableName(rawTable, label) {
+    if (Array.isArray(rawTable)) {
+        throw new Error(`${label}.table 不支持数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const table = isString(rawTable) ? rawTable.trim() : "";
+    if (!table) {
+        throw new Error(`${label}.table 不能为空`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (table.includes(" ")) {
+        throw new Error(`${label} 不支持别名表写法（table: ${table}）`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (table.includes(".")) {
+        throw new Error(`${label} 不支持 schema.table 写法（table: ${table}）`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateNoLeftJoin(leftJoin, message) {
+    if (Array.isArray(leftJoin) && leftJoin.length > 0) {
+        throw new Error(message, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateNoLeftJoinReadOptions(options, label, joinErrorMessage) {
+    validateTableName(options.table, `${label}.table`);
+    validateWhereObject(options.where, `${label}.where`, false);
+    validateNoLeftJoin(options.leftJoin, joinErrorMessage);
+    validateLegacyJoinOptions(options, label);
+    validateSimpleTableName(options.table, label);
+}
+
+function validateSafeFieldName(field) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
+        throw new Error(`无效的字段名: ${field}，只允许字母、数字和下划线`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validatePageLimitRange(prepared, rawTable) {
+    if (prepared.page < 1 || prepared.page > 10000) {
+        throw new Error(`页码必须在 1 到 10000 之间 (table: ${rawTable}, page: ${prepared.page}, limit: ${prepared.limit})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (prepared.limit < 1 || prepared.limit > 100000) {
+        throw new Error(`每页数量必须在 1 到 100000 之间 (table: ${rawTable}, page: ${prepared.page}, limit: ${prepared.limit})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateGeneratedBatchId(id, table, index) {
+    if (typeof id !== "number") {
+        throw new Error(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${table})`, {
+            cause: null,
+            code: "runtime"
+        });
+    }
+}
+
+function validateTimeIdValue(id) {
+    if (!Number.isFinite(id) || id <= 0) {
+        throw new Error(`buildInsertRow(timeId) 失败：id 必须为 > 0 的有限 number (id: ${String(id)})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateInsertBatchSize(count, maxBatchSize) {
+    if (count > maxBatchSize) {
+        throw new Error(`批量插入数量 ${count} 超过最大限制 ${maxBatchSize}`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateIncrementValue(table, field, value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`自增值必须是有效的数字 (table: ${table}, field: ${field}, value: ${value})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateIncrementOptions(table, field, where, value, label) {
+    validateTableName(table, `${label}.table`);
+    validateWhereObject(where, `${label}.where`, true);
+    validateSafeFieldName(snakeCase(table));
+    validateSafeFieldName(snakeCase(field));
+    validateIncrementValue(table, field, value);
+}
+
+function validateIdList(ids, label) {
+    if (!Array.isArray(ids)) {
+        throw new Error(`${label} 必须是数组`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateEffectiveWhere(snakeWhere, label) {
+    if (!snakeWhere || Object.keys(snakeWhere).length === 0) {
+        throw new Error(`${label} 需要有效的 WHERE 条件`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function validateDataReadOptions(options, label) {
+    validateQueryOptions(options, label);
+
+    const hasLeftJoin = Array.isArray(options.leftJoin) && options.leftJoin.length > 0;
+    const classifiedFields = hasLeftJoin ? validateExplicitLeftJoinFields(options.fields) : validateExplicitReadFields(options.fields);
+
+    return {
+        hasLeftJoin: hasLeftJoin,
+        classifiedFields: classifiedFields
+    };
+}
+
+function validateCountReadOptions(options, label) {
+    validateQueryOptions(options, label);
+
+    return {
+        hasLeftJoin: Array.isArray(options.leftJoin) && options.leftJoin.length > 0
+    };
+}
+
+function validateGetCountOptions(options) {
+    return validateCountReadOptions(options, "getCount.options");
+}
+
+function validateGetOneOptions(options) {
+    return validateDataReadOptions(options, "getOne.options");
+}
+
+function validateGetListOptions(options) {
+    return validateDataReadOptions(options, "getList.options");
+}
+
+function validateGetAllOptions(options) {
+    return validateDataReadOptions(options, "getAll.options");
+}
+
+class DbHelper {
+    constructor(options = {}) {
+        this.redis = options.redis;
+
+        if (!isNonEmptyString(options.dbName)) {
+            throw new Error("DbHelper 初始化失败：dbName 必须为非空字符串", {
+                cause: null,
+                code: "validation"
+            });
+        }
+        this.dbName = options.dbName;
+
+        this.sql = options.sql || null;
+        this.isTransaction = options.isTransaction === true;
+        this.beflyMode = options.beflyMode === "manual" ? "manual" : "auto";
+    }
+
+    async execute(sql, params) {
+        if (!this.sql) {
+            throw new Error("数据库连接未初始化", {
+                cause: null,
+                code: "runtime"
+            });
+        }
+
+        if (!isString(sql)) {
+            throw new Error(`execute 只接受字符串类型的 SQL，收到类型: ${typeof sql}，值: ${JSON.stringify(sql)}`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const startTime = Date.now();
+        let safeParams = [];
+        if (!isNullable(params)) {
+            if (!Array.isArray(params)) {
+                throw new Error(`SQL 参数必须是数组，当前类型: ${typeof params}`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            safeParams = [];
+            for (const value of params) {
+                if (value === undefined) {
+                    throw new Error("SQL 参数不能为 undefined", {
+                        cause: null,
+                        code: "validation"
+                    });
+                }
+
+                if (typeof value === "bigint") {
+                    safeParams.push(value.toString());
+                    continue;
+                }
+
+                safeParams.push(value);
+            }
+        }
+
+        try {
+            let queryResult;
+            const timer = setTimeout(() => {}, 2147483647);
+            const queryPromise = safeParams.length > 0 ? this.sql.unsafe(sql, safeParams) : this.sql.unsafe(sql);
+            try {
+                queryResult = await queryPromise;
+            } finally {
+                clearTimeout(timer);
+            }
+
+            const duration = Date.now() - startTime;
+
+            return {
+                data: queryResult,
+                sql: {
+                    sql: sql,
+                    params: safeParams,
+                    duration: duration
+                }
+            };
+        } catch (error) {
+            const duration = Date.now() - startTime;
+            const msg = getExecuteErrorMessage(error);
+            const sqlInfo = {
+                sql: sql,
+                params: safeParams,
+                duration: duration
+            };
+            const wrappedError = new Error(`SQL执行失败: ${msg}`, {
+                cause: error
+            });
+
+            wrappedError.code = "runtime";
+            wrappedError.subsystem = "sql";
+            wrappedError.operation = "execute";
+            wrappedError.params = safeParams;
+            wrappedError.duration = duration;
+            wrappedError.sqlInfo = sqlInfo;
+
+            throw wrappedError;
+        }
+    }
+
+    async tableExists(tableName) {
+        const snakeTableName = snakeCase(tableName);
+        const executeRes = await this.execute("SELECT COUNT(*) as count FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ?", [snakeTableName]);
+        const exists = (executeRes.data?.[0]?.count || 0) > 0;
+
+        return {
+            data: exists,
+            sql: executeRes.sql
+        };
+    }
+
+    createSqlBuilder() {
+        return new SqlBuilder({ quoteIdent: quoteIdentMySql });
+    }
+
+    createListBuilder(prepared, whereFiltered, limit, offset) {
+        const builder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(limit);
+        this.applyLeftJoins(builder, prepared.leftJoins);
+        if (!isNullable(offset)) {
+            builder.offset(offset);
+        }
+        if (prepared.orderBy && prepared.orderBy.length > 0) {
+            builder.orderBy(prepared.orderBy);
+        }
+        return builder;
+    }
+
+    async fetchCount(prepared, whereFiltered, alias) {
+        const builder = this.createSqlBuilder().selectRaw(alias).from(prepared.table).where(whereFiltered);
+        this.applyLeftJoins(builder, prepared.leftJoins);
+        const result = builder.toSelectSql();
+        const executeRes = await this.execute(result.sql, result.params);
+        const countRow = executeRes.data?.[0] || null;
+        const normalizedCountRow = countRow ? normalizeBigIntValues(countRow) : null;
+        const total = normalizedCountRow?.total ?? normalizedCountRow?.count ?? 0;
+        return {
+            total: total,
+            sql: executeRes.sql
+        };
+    }
+
+    normalizeRowData(row) {
+        if (!row) {
+            return {};
+        }
+
+        const camelRow = keysToCamel(row);
+        const deserialized = deserializeArrayFields(camelRow);
+        if (!deserialized) {
+            return {};
+        }
+
+        const convertedList = normalizeBigIntValues([deserialized]);
+        if (convertedList && convertedList.length > 0) {
+            return convertedList[0];
+        }
+
+        return deserialized;
+    }
+
+    normalizeListData(list) {
+        const camelList = arrayKeysToCamel(list);
+        const deserializedList = camelList.map((item) => deserializeArrayFields(item)).filter((item) => item !== null);
+        return normalizeBigIntValues(deserializedList);
+    }
+
+    _joinFieldsToSnake(classifiedFields) {
+        if (classifiedFields.type === "include") {
+            return classifiedFields.fields.map((field) => processJoinField(field));
+        }
+
+        return [];
+    }
+
+    _cleanAndSnakeAndSerializeWriteData(data, excludeValues = [null, undefined]) {
+        const cleanData = fieldClear(data, { excludeValues: excludeValues });
+        return serializeArrayFields(keysToSnake(cleanData));
+    }
+
+    _stripSystemFieldsForWrite(data, allowState) {
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (key === "id") continue;
+            if (key === "created_at") continue;
+            if (key === "updated_at") continue;
+            if (key === "deleted_at") continue;
+            if (!allowState && key === "state") continue;
+            result[key] = value;
+        }
+        return result;
+    }
+
+    _prepareWriteUserData(data, allowState) {
+        return this._stripSystemFieldsForWrite(this._cleanAndSnakeAndSerializeWriteData(data), allowState);
+    }
+
+    _buildInsertRow(options) {
+        const result = { ...this._prepareWriteUserData(options.data, false) };
+
+        if (options.beflyMode === "auto") {
+            validateTimeIdValue(options.id);
+            result.id = options.id;
+        }
+
+        if (options.beflyMode !== "manual") {
+            result.created_at = options.now;
+            result.updated_at = options.now;
+            result.state = 1;
+        }
+
+        return result;
+    }
+
+    _buildUpdateRow(options) {
+        const result = { ...this._prepareWriteUserData(options.data, options.allowState) };
+        if (options.beflyMode !== "manual") {
+            result.updated_at = options.now;
+        }
+        return result;
+    }
+
+    _buildPartialUpdateData(options) {
+        return this._prepareWriteUserData(options.data, options.allowState);
+    }
+
+    normalizeLeftJoinOptions(options, cleanWhere, classifiedFields) {
+        const processedFields = this._joinFieldsToSnake(classifiedFields);
+        const mainTableRef = options.table[0];
+        const joinTableRefs = options.table.slice(1);
+        const normalizedTableRef = normalizeTableRef(mainTableRef);
+        const mainQualifier = getJoinMainQualifier(mainTableRef);
+        const leftJoins = options.leftJoin.map((joinItem, index) => parseLeftJoinItem(joinTableRefs[index], joinItem));
+
+        return {
+            table: normalizedTableRef,
+            tableQualifier: mainQualifier,
+            fields: processedFields,
+            where: processJoinWhere(cleanWhere),
+            leftJoins: leftJoins,
+            orderBy: processJoinOrderBy(options.orderBy || []),
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    normalizeLeftJoinCountOptions(options, cleanWhere) {
+        const mainTableRef = options.table[0];
+        const joinTableRefs = options.table.slice(1);
+        const normalizedTableRef = normalizeTableRef(mainTableRef);
+        const mainQualifier = getJoinMainQualifier(mainTableRef);
+        const leftJoins = options.leftJoin.map((joinItem, index) => parseLeftJoinItem(joinTableRefs[index], joinItem));
+
+        return {
+            table: normalizedTableRef,
+            tableQualifier: mainQualifier,
+            fields: [],
+            where: processJoinWhere(cleanWhere),
+            leftJoins: leftJoins,
+            orderBy: [],
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    async normalizeSingleTableOptions(options, cleanWhere, classifiedFields) {
+        const tableRef = Array.isArray(options.table) ? options.table[0] : options.table;
+        const snakeTable = snakeCase(tableRef);
+        const processedFields = await fieldsToSnake(snakeTable, classifiedFields, this.getTableColumns.bind(this));
+
+        return {
+            table: snakeTable,
+            tableQualifier: snakeTable,
+            fields: processedFields,
+            where: whereKeysToSnake(cleanWhere),
+            leftJoins: [],
+            orderBy: orderByToSnake(options.orderBy || []),
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    buildQueryOptions(options, defaults) {
+        const output = {
+            table: options.table,
+            page: defaults.page,
+            limit: defaults.limit
+        };
+
+        if (options.fields !== undefined) output.fields = options.fields;
+        if (options.where !== undefined) output.where = options.where;
+        if (options.leftJoin !== undefined) output.leftJoin = options.leftJoin;
+        if (options.orderBy !== undefined) output.orderBy = options.orderBy;
+        return output;
+    }
+
+    resolveFieldValue(record, field) {
+        if (!isPlainObject(record)) {
+            return null;
+        }
+
+        if (Object.hasOwn(record, field)) {
+            return record[field];
+        }
+
+        const camelField = field.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+        if (camelField !== field && Object.hasOwn(record, camelField)) {
+            return record[camelField];
+        }
+
+        const snakeField = field.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+        if (snakeField !== field && Object.hasOwn(record, snakeField)) {
+            return record[snakeField];
+        }
+
+        return null;
+    }
+
+    async getTableColumns(table) {
+        const parsed = parseTableRef(table);
+        const schemaPart = parsed.schema ? `${quoteIdentMySql(snakeCase(parsed.schema))}.` : "";
+        const quotedTable = quoteIdentMySql(snakeCase(parsed.table));
+        const executeRes = await this.execute(`SHOW COLUMNS FROM ${schemaPart}${quotedTable}`, []);
+        const result = executeRes.data;
+
+        if (!result || result.length === 0) {
+            throw new Error(`表 ${table} 不存在或没有字段`, {
+                cause: null,
+                code: "runtime"
+            });
+        }
+
+        const columnNames = [];
+        for (const row of result) {
+            const record = row;
+            const name = record.Field;
+            if (isNonEmptyString(name)) {
+                columnNames.push(name);
+            }
+        }
+
+        return columnNames;
+    }
+
+    applyLeftJoins(builder, leftJoins) {
+        if (!leftJoins || leftJoins.length === 0) {
+            return;
+        }
+
+        for (const join of leftJoins) {
+            builder.leftJoin(join.table, join.on);
+        }
+    }
+
+    async prepareBaseReadContext(options, validation, buildPrepared) {
+        const cleanWhere = clearDeep(options.where || {});
+        const prepared = await buildPrepared.call(this, options, cleanWhere, validation);
+
+        return {
+            prepared: prepared,
+            whereFiltered: addDefaultStateFilter(prepared.where, prepared.tableQualifier, prepared.leftJoins.length > 0, this.beflyMode)
+        };
+    }
+
+    async buildPreparedReadOptions(options, cleanWhere, validation) {
+        if (validation.hasLeftJoin) {
+            return this.normalizeLeftJoinOptions(options, cleanWhere, validation.classifiedFields);
+        }
+
+        return await this.normalizeSingleTableOptions(options, cleanWhere, validation.classifiedFields);
+    }
+
+    buildPreparedCountOptions(options, cleanWhere, validation) {
+        if (validation.hasLeftJoin) {
+            return this.normalizeLeftJoinCountOptions(options, cleanWhere);
+        }
+
+        const snakeTable = snakeCase(Array.isArray(options.table) ? options.table[0] : options.table);
+        return {
+            table: snakeTable,
+            tableQualifier: snakeTable,
+            fields: [],
+            where: whereKeysToSnake(cleanWhere),
+            leftJoins: [],
+            orderBy: [],
+            page: options.page || 1,
+            limit: options.limit || 10
+        };
+    }
+
+    async prepareReadContext(options, validation) {
+        return await this.prepareBaseReadContext(options, validation, this.buildPreparedReadOptions);
+    }
+
+    async prepareCountContext(options, validation) {
+        return await this.prepareBaseReadContext(options, validation, this.buildPreparedCountOptions);
+    }
+
+    prepareSingleTableWhere(table, where, useDefaultStateFilter = true) {
+        const snakeTable = snakeCase(table);
+        const snakeWhere = whereKeysToSnake(clearDeep(where || {}));
+
+        return {
+            snakeTable: snakeTable,
+            whereFiltered: useDefaultStateFilter ? addDefaultStateFilter(snakeWhere, snakeTable, false, this.beflyMode) : snakeWhere
+        };
+    }
+
+    prepareRequiredSingleTableWhere(table, where, useDefaultStateFilter, label) {
+        const snakeTable = snakeCase(table);
+        const snakeWhere = whereKeysToSnake(clearDeep(where || {}));
+        validateEffectiveWhere(snakeWhere, label);
+
+        return {
+            snakeTable: snakeTable,
+            whereFiltered: useDefaultStateFilter ? addDefaultStateFilter(snakeWhere, snakeTable, false, this.beflyMode) : snakeWhere
+        };
+    }
+
+    async createInsertRows(table, snakeTable, dataList, now) {
+        if (this.beflyMode === "manual") {
+            return {
+                ids: [],
+                processedList: dataList.map((data) =>
+                    this._buildInsertRow({
+                        data: data,
+                        now: now,
+                        beflyMode: this.beflyMode
+                    })
+                )
+            };
+        }
+
+        const ids = [];
+        try {
+            for (let i = 0; i < dataList.length; i++) {
+                ids.push(await this.redis.genTimeID());
+            }
+        } catch (error) {
+            if (dataList.length === 1) {
+                throw new Error(`生成 ID 失败，Redis 可能不可用 (table: ${table})`, {
+                    cause: error,
+                    code: "runtime",
+                    subsystem: "db",
+                    operation: "genTimeId",
+                    table: table
+                });
+            }
+            throw error;
+        }
+
+        const processedList = dataList.map((data, index) => {
+            const id = ids[index];
+            if (dataList.length > 1) {
+                validateGeneratedBatchId(id, snakeTable, index);
+            }
+
+            return this._buildInsertRow({
+                data: data,
+                id: id,
+                now: now,
+                beflyMode: this.beflyMode
+            });
+        });
+
+        return {
+            ids: ids,
+            processedList: processedList
+        };
+    }
+
+    resolveInsertedData(table, count, executeRes, generatedIds, operation) {
+        const lastInsertRowidNum = normalizeSqlMetaNumber(executeRes.data?.lastInsertRowid);
+
+        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"
+                });
+            }
+
+            if (count === 1) {
+                return lastInsertRowidNum;
+            }
+
+            const outIds = [];
+            for (let i = 0; i < count; i++) {
+                outIds.push(lastInsertRowidNum + i);
+            }
+            return outIds;
+        }
+
+        if (count === 1) {
+            const generatedId = generatedIds[0];
+            return (isNumber(generatedId) ? generatedId : 0) || lastInsertRowidNum || 0;
+        }
+
+        return generatedIds;
+    }
+
+    async getCount(options) {
+        const validation = validateGetCountOptions(options);
+        const { prepared, whereFiltered } = await this.prepareCountContext(options, validation);
+        const result = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as count");
+
+        return {
+            data: result.total,
+            sql: result.sql
+        };
+    }
+
+    async getOne(options) {
+        const validation = validateGetOneOptions(options);
+        const { prepared, whereFiltered } = await this.prepareReadContext(options, validation);
+        const builder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered);
+        this.applyLeftJoins(builder, prepared.leftJoins);
+
+        const { sql, params } = builder.toSelectSql();
+        const executeRes = await this.execute(sql, params);
+        const result = executeRes.data;
+
+        const data = this.normalizeRowData(result?.[0] || null);
+        return {
+            data: data,
+            sql: executeRes.sql
+        };
+    }
+
+    async getList(options) {
+        const validation = validateGetListOptions(options);
+        const { prepared, whereFiltered } = await this.prepareReadContext(options, validation);
+        validatePageLimitRange(prepared, options.table);
+        const countResult = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as total");
+        const total = countResult.total;
+
+        const offset = (prepared.page - 1) * prepared.limit;
+        const dataBuilder = this.createListBuilder(prepared, whereFiltered, prepared.limit, offset);
+        const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
+
+        if (total === 0) {
+            return {
+                data: {
+                    lists: [],
+                    total: 0,
+                    page: prepared.page,
+                    limit: prepared.limit,
+                    pages: 0
+                },
+                sql: {
+                    count: countResult.sql,
+                    data: {
+                        sql: dataSql,
+                        params: dataParams,
+                        duration: 0
+                    }
+                }
+            };
+        }
+        const listExecuteRes = await this.execute(dataSql, dataParams);
+        const list = listExecuteRes.data || [];
+
+        return {
+            data: {
+                lists: this.normalizeListData(list),
+                total: total,
+                page: prepared.page,
+                limit: prepared.limit,
+                pages: Math.ceil(total / prepared.limit)
+            },
+            sql: {
+                count: countResult.sql,
+                data: listExecuteRes.sql
+            }
+        };
+    }
+
+    async getAll(options) {
+        const MAX_LIMIT = 100000;
+        const WARNING_LIMIT = 10000;
+        const prepareOptions = this.buildQueryOptions(options, { page: 1, limit: 10 });
+        const validation = validateGetAllOptions(prepareOptions);
+        const { prepared, whereFiltered } = await this.prepareReadContext(prepareOptions, validation);
+        const countResult = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as total");
+        const total = countResult.total;
+
+        if (total === 0) {
+            return {
+                data: {
+                    lists: [],
+                    total: 0
+                },
+                sql: {
+                    count: countResult.sql
+                }
+            };
+        }
+
+        const dataBuilder = this.createListBuilder(prepared, whereFiltered, MAX_LIMIT, null);
+
+        const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
+        const listExecuteRes = await this.execute(dataSql, dataParams);
+        const result = listExecuteRes.data || [];
+
+        if (result.length >= WARNING_LIMIT) {
+            Logger.warn("getAll 返回数据过多，建议使用 getList 分页查询", { table: options.table, count: result.length, total: total });
+        }
+
+        if (result.length >= MAX_LIMIT) {
+            Logger.warn(`getAll 达到最大限制 ${MAX_LIMIT}，实际总数 ${total}，只返回前 ${MAX_LIMIT} 条`, { table: options.table, limit: MAX_LIMIT, total: total });
+        }
+
+        const lists = this.normalizeListData(result);
+
+        return {
+            data: {
+                lists: lists,
+                total: total
+            },
+            sql: {
+                count: countResult.sql,
+                data: listExecuteRes.sql
+            }
+        };
+    }
+
+    async exists(options) {
+        validateNoLeftJoinReadOptions(options, "exists", "exists 不支持 leftJoin（请使用显式 query 或拆分查询）");
+        const prepared = this.prepareSingleTableWhere(options.table, options.where, true);
+
+        const builder = this.createSqlBuilder().selectRaw("COUNT(1) as cnt").from(prepared.snakeTable).where(prepared.whereFiltered).limit(1);
+        const { sql, params } = builder.toSelectSql();
+        const executeRes = await this.execute(sql, params);
+        const exists = (executeRes.data?.[0]?.cnt || 0) > 0;
+        return { data: exists, sql: executeRes.sql };
+    }
+
+    async getFieldValue(options) {
+        validateNoLeftJoinReadOptions(options, "getFieldValue", "getFieldValue 不支持 leftJoin（请使用 getOne/getList 并自行取字段）");
+        const field = options.field;
+        validateSafeFieldName(field);
+
+        const oneOptions = {
+            table: options.table
+        };
+        if (options.where !== undefined) oneOptions.where = options.where;
+        if (options.leftJoin !== undefined) oneOptions.leftJoin = options.leftJoin;
+        if (options.orderBy !== undefined) oneOptions.orderBy = options.orderBy;
+        if (options.page !== undefined) oneOptions.page = options.page;
+        if (options.limit !== undefined) oneOptions.limit = options.limit;
+        oneOptions.fields = [field];
+
+        const oneRes = await this.getOne(oneOptions);
+
+        const result = oneRes.data;
+        const value = this.resolveFieldValue(result, field);
+        return {
+            data: value,
+            sql: oneRes.sql
+        };
+    }
+
+    async insData(options) {
+        validateTableDataOptions(options, "insData");
+        const { table, data } = options;
+        const snakeTable = snakeCase(table);
+        const now = Date.now();
+        const insertRows = await this.createInsertRows(table, snakeTable, [data], now);
+        const processed = insertRows.processedList[0];
+
+        assertNoUndefinedInRecord(processed, `insData 插入数据 (table: ${snakeTable})`);
+
+        const builder = this.createSqlBuilder();
+        const { sql, params } = builder.toInsertSql(snakeTable, processed);
+        const executeRes = await this.execute(sql, params);
+
+        return {
+            data: this.resolveInsertedData(table, 1, executeRes, insertRows.ids, "insData"),
+            sql: executeRes.sql
+        };
+    }
+
+    async insBatch(table, dataList) {
+        validateTableBatchDataOptions(table, dataList, "insBatch");
+        if (dataList.length === 0) {
+            return {
+                data: [],
+                sql: { sql: "", params: [], duration: 0 }
+            };
+        }
+
+        const MAX_BATCH_SIZE = 1000;
+        validateInsertBatchSize(dataList.length, MAX_BATCH_SIZE);
+
+        const snakeTable = snakeCase(table);
+        const now = Date.now();
+        const insertRows = await this.createInsertRows(table, snakeTable, dataList, now);
+        const processedList = insertRows.processedList;
+
+        const insertFields = assertBatchInsertRowsConsistent(processedList, { table: snakeTable });
+        const builder = this.createSqlBuilder();
+        const { sql, params } = builder.toInsertSql(snakeTable, processedList);
+
+        try {
+            const executeRes = await this.execute(sql, params);
+            return {
+                data: this.resolveInsertedData(table, dataList.length, executeRes, insertRows.ids, "insBatch"),
+                sql: executeRes.sql
+            };
+        } catch (error) {
+            Logger.error("批量插入失败", error, {
+                table: table,
+                snakeTable: snakeTable,
+                count: dataList.length,
+                fields: insertFields
+            });
+            throw new Error("批量插入失败", {
+                cause: error,
+                code: "runtime",
+                subsystem: "sql",
+                operation: "insBatch",
+                table: table,
+                snakeTable: snakeTable,
+                count: dataList.length,
+                fields: insertFields
+            });
+        }
+    }
+
+    async delForceBatch(table, ids) {
+        validateTableName(table, "delForceBatch.table");
+        validateIdList(ids, "delForceBatch.ids");
+        if (ids.length === 0) {
+            return {
+                data: 0,
+                sql: { sql: "", params: [], duration: 0 }
+            };
+        }
+
+        const snakeTable = snakeCase(table);
+        const query = SqlBuilder.toDeleteInSql({
+            table: snakeTable,
+            idField: "id",
+            ids: ids,
+            quoteIdent: quoteIdentMySql
+        });
+        const executeRes = await this.execute(query.sql, query.params);
+        const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    }
+
+    async updBatch(table, dataList) {
+        validateTableBatchDataOptions(table, dataList, "updBatch");
+        if (dataList.length === 0) {
+            return {
+                data: 0,
+                sql: { sql: "", params: [], duration: 0 }
+            };
+        }
+
+        const snakeTable = snakeCase(table);
+        const now = Date.now();
+
+        const processedList = [];
+        const fieldSet = new Set();
+
+        for (const item of dataList) {
+            const userData = this._buildPartialUpdateData({ data: item.data, allowState: true });
+
+            for (const key of Object.keys(userData)) {
+                fieldSet.add(key);
+            }
+
+            processedList.push({ id: item.id, data: userData });
+        }
+
+        const fields = Array.from(fieldSet).sort();
+        if (fields.length === 0) {
+            return {
+                data: 0,
+                sql: { sql: "", params: [], duration: 0 }
+            };
+        }
+
+        const query = SqlBuilder.toUpdateCaseByIdSql({
+            table: snakeTable,
+            idField: "id",
+            rows: processedList,
+            fields: fields,
+            quoteIdent: quoteIdentMySql,
+            updatedAtField: this.beflyMode === "auto" ? "updated_at" : "",
+            updatedAtValue: this.beflyMode === "auto" ? now : null,
+            stateField: "state",
+            stateGtZero: this.beflyMode === "auto"
+        });
+
+        const executeRes = await this.execute(query.sql, query.params);
+        const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    }
+
+    async updData(options) {
+        validateTableDataOptions(options, "updData");
+        validateTableWhereOptions(options, "updData", true);
+        const { table, data, where } = options;
+        const prepared = this.prepareRequiredSingleTableWhere(table, where, true, "updData");
+
+        const processed = this._buildUpdateRow({ data: data, now: Date.now(), allowState: true, beflyMode: this.beflyMode });
+        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
+        const { sql, params } = builder.toUpdateSql(prepared.snakeTable, processed);
+
+        const executeRes = await this.execute(sql, params);
+        const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    }
+
+    async delData(options) {
+        validateTableWhereOptions(options, "delData", true);
+        const { table, where } = options;
+        const prepared = this.prepareRequiredSingleTableWhere(table, where, true, "delData");
+        const now = Date.now();
+        const processed = {
+            state: 0,
+            deleted_at: now
+        };
+
+        if (this.beflyMode === "auto") {
+            processed.updated_at = now;
+        }
+
+        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
+        const { sql, params } = builder.toUpdateSql(prepared.snakeTable, processed);
+        const executeRes = await this.execute(sql, params);
+        const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
+
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    }
+
+    async delForce(options) {
+        validateTableWhereOptions(options, "delForce", true);
+        const { table, where } = options;
+        const prepared = this.prepareRequiredSingleTableWhere(table, where, false, "delForce");
+
+        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
+        const { sql, params } = builder.toDeleteSql(prepared.snakeTable);
+
+        const executeRes = await this.execute(sql, params);
+        const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    }
+
+    async disableData(options) {
+        validateTableWhereOptions(options, "disableData", true);
+        const { table, where } = options;
+
+        return await this.updData({
+            table: table,
+            data: {
+                state: 2
+            },
+            where: where
+        });
+    }
+
+    async enableData(options) {
+        validateTableWhereOptions(options, "enableData", true);
+        const { table, where } = options;
+
+        return await this.updData({
+            table: table,
+            data: {
+                state: 1
+            },
+            where: where
+        });
+    }
+
+    async increment(table, field, where, value = 1) {
+        validateIncrementOptions(table, field, where, value, "increment");
+        const prepared = this.prepareRequiredSingleTableWhere(table, where, true, "increment");
+        const snakeField = snakeCase(field);
+
+        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
+        const { sql: whereClause, params: whereParams } = builder.getWhereConditions();
+
+        const quotedTable = quoteIdentMySql(prepared.snakeTable);
+        const quotedField = quoteIdentMySql(snakeField);
+        const sql = whereClause ? `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ? WHERE ${whereClause}` : `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ?`;
+
+        const params = [value];
+        for (const param of whereParams) {
+            params.push(param);
+        }
+
+        const executeRes = await this.execute(sql, params);
+        const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    }
+
+    async decrement(table, field, where, value = 1) {
+        return await this.increment(table, field, where, -value);
+    }
+
+    async trans(callback) {
+        const abortMark = "__beflyTransAbort";
+
+        if (this.isTransaction) {
+            const result = await callback(this);
+            if (result?.code !== undefined && result.code !== 0) {
+                const abortError = new Error("TRANSACTION_ABORT", {
+                    cause: null,
+                    code: "runtime"
+                });
+                abortError[abortMark] = true;
+                abortError.payload = result;
+                throw abortError;
+            }
+            return result;
+        }
+
+        if (typeof this.sql?.begin !== "function") {
+            throw new Error("不支持事务 begin() 方法", {
+                cause: null,
+                code: "runtime"
+            });
+        }
+
+        try {
+            return await this.sql.begin(async (tx) => {
+                const trans = new this.constructor({
+                    redis: this.redis,
+                    dbName: this.dbName,
+                    sql: tx,
+                    isTransaction: true,
+                    beflyMode: this.beflyMode
+                });
+                const result = await callback(trans);
+                if (result?.code !== undefined && result.code !== 0) {
+                    const abortError = new Error("TRANSACTION_ABORT", {
+                        cause: null,
+                        code: "runtime"
+                    });
+                    abortError[abortMark] = true;
+                    abortError.payload = result;
+                    throw abortError;
+                }
+                return result;
+            });
+        } catch (error) {
+            if (error && error[abortMark] === true) {
+                return error.payload;
+            }
+            throw error;
+        }
+    }
+}
+
+export { DbHelper };