befly 3.21.1 → 3.22.0

package/lib/dbHelper.js

@@ -2,8 +2,9 @@ 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 { DbParse } from "./dbParse.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";
+import { deserializeArrayFields, parseTableRef, serializeArrayFields } from "./dbUtil.js";
 
 function quoteIdentMySql(identifier) {
     if (!isString(identifier)) {
@@ -24,26 +25,6 @@ function quoteIdentMySql(identifier) {
     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;
@@ -147,503 +128,129 @@ function getExecuteErrorMessage(error) {
     return detailText;
 }
 
-function assertNonEmptyString(value, label) {
-    if (!isNonEmptyString(value)) {
-        throw new Error(`${label} 必须是非空字符串`, {
+function assertGeneratedBatchId(id, table, index) {
+    if (typeof id !== "number") {
+        throw new Error(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${table})`, {
             cause: null,
-            code: "validation"
+            code: "runtime"
         });
     }
 }
 
-function assertPlainObjectValue(value, label) {
-    if (!isPlainObject(value)) {
-        throw new Error(`${label} 必须是对象`, {
+function assertTimeIdValue(id) {
+    if (!Number.isFinite(id) || id <= 0) {
+        throw new Error(`buildInsertRow(timeId) 失败：id 必须为 > 0 的有限 number (id: ${String(id)})`, {
             cause: null,
             code: "validation"
         });
     }
 }
 
-function validateExcludeRules(excludeRules, label) {
-    if (isNullable(excludeRules)) {
-        return;
-    }
-
-    if (!isPlainObject(excludeRules)) {
-        throw new Error(`${label} 必须是对象`, {
+function assertInsertBatchSize(count, maxBatchSize) {
+    if (count > maxBatchSize) {
+        throw new Error(`批量插入数量 ${count} 超过最大限制 ${maxBatchSize}`, {
             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)) {
+function assertWriteDataHasFields(data, message, table) {
+    if (Object.keys(data).length > 0) {
         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}`);
-        }
-    }
+    throw new Error(`${message} (table: ${table})`, {
+        cause: null,
+        code: "validation"
+    });
 }
 
-function validateWhereObject(where, label, required = false) {
-    if (isNullable(where)) {
-        if (required) {
-            throw new Error(`${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"
             });
         }
-        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} 必须是数组`, {
+function assertBatchInsertRowsConsistent(rows, options) {
+    if (!Array.isArray(rows)) {
+        throw new Error("批量插入 rows 必须是数组", {
             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} 不能为空`, {
+    if (rows.length === 0) {
+        throw new Error(`插入数据不能为空 (table: ${options.table})`, {
             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 格式`, {
+    const first = rows[0];
+    if (!first || typeof first !== "object" || Array.isArray(first)) {
+        throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: 0)`, {
             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} 必须是数组`, {
+    const fields = Object.keys(first);
+    if (fields.length === 0) {
+        throw new Error(`插入数据必须至少有一个字段 (table: ${options.table})`, {
             cause: null,
             code: "validation"
         });
     }
 
-    for (let i = 0; i < leftJoin.length; i++) {
-        const joinItem = leftJoin[i];
-        if (!isNonEmptyString(joinItem)) {
-            throw new Error(`${label}[${i}] 必须是非空字符串`, {
+    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"
             });
         }
 
-        const parsed = parseLeftJoinEquality(joinItem);
-        if (!parsed) {
-            throw new Error(`${label}[${i}] 必须是 "left.field right.field" 格式（空格表示等于）`, {
+        const rowKeys = Object.keys(row);
+        if (rowKeys.length !== fields.length) {
+            throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i})`, {
                 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`, {
+        for (const key of rowKeys) {
+            if (!fieldSet.has(key)) {
+                throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`, {
                     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"
-            });
+        for (const field of fields) {
+            if (!(field in row)) {
+                throw new Error(`批量插入缺少字段 (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+            if (row[field] === undefined) {
+                throw new Error(`批量插入字段值不能为 undefined (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+                    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");
+    return fields;
 }
 
 class DbHelper {
@@ -661,6 +268,30 @@ class DbHelper {
         this.sql = options.sql || null;
         this.isTransaction = options.isTransaction === true;
         this.beflyMode = options.beflyMode === "manual" ? "manual" : "auto";
+        this.tables = isPlainObject(options.tables) ? options.tables : {};
+    }
+
+    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"
+            });
+        }
+
+        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"
+            });
+        }
+
+        return tableInfo;
     }
 
     async execute(sql, params) {
@@ -764,20 +395,16 @@ class DbHelper {
         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;
+    createDbParse() {
+        return new DbParse({
+            tables: this.tables,
+            beflyMode: this.beflyMode,
+            getTableColumns: this.getTableColumns.bind(this)
+        });
     }
 
-    async fetchCount(prepared, whereFiltered, alias) {
-        const builder = this.createSqlBuilder().selectRaw(alias).from(prepared.table).where(whereFiltered);
+    async fetchCount(prepared, alias) {
+        const builder = this.createSqlBuilder().selectRaw(alias).from(prepared.table).where(prepared.where);
         this.applyLeftJoins(builder, prepared.leftJoins);
         const result = builder.toSelectSql();
         const executeRes = await this.execute(result.sql, result.params);
@@ -815,22 +442,11 @@ class DbHelper {
         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) {
+    _prepareWriteUserData(data, allowState) {
+        const cleanData = fieldClear(data, { excludeValues: [null, undefined] });
         const result = {};
-        for (const [key, value] of Object.entries(data)) {
+
+        for (const [key, value] of Object.entries(serializeArrayFields(keysToSnake(cleanData)))) {
             if (key === "id") continue;
             if (key === "created_at") continue;
             if (key === "updated_at") continue;
@@ -838,18 +454,15 @@ class DbHelper {
             if (!allowState && key === "state") continue;
             result[key] = value;
         }
-        return result;
-    }
 
-    _prepareWriteUserData(data, allowState) {
-        return this._stripSystemFieldsForWrite(this._cleanAndSnakeAndSerializeWriteData(data), allowState);
+        return result;
     }
 
     _buildInsertRow(options) {
         const result = { ...this._prepareWriteUserData(options.data, false) };
 
         if (options.beflyMode === "auto") {
-            validateTimeIdValue(options.id);
+            assertTimeIdValue(options.id);
             result.id = options.id;
         }
 
@@ -870,126 +483,18 @@ class DbHelper {
         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;
+        const tableInfo = this.getTableDef(table);
+        const fieldNames = Object.keys(tableInfo);
 
-        if (!result || result.length === 0) {
-            throw new Error(`表 ${table} 不存在或没有字段`, {
+        if (fieldNames.length === 0) {
+            throw new Error(`表 ${table} 的本地 tables 定义为空或没有字段`, {
                 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;
+        return fieldNames.map((fieldName) => snakeCase(fieldName));
     }
 
     applyLeftJoins(builder, leftJoins) {
@@ -1002,71 +507,6 @@ class DbHelper {
         }
     }
 
-    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 {
@@ -1102,7 +542,7 @@ class DbHelper {
         const processedList = dataList.map((data, index) => {
             const id = ids[index];
             if (dataList.length > 1) {
-                validateGeneratedBatchId(id, snakeTable, index);
+                assertGeneratedBatchId(id, snakeTable, index);
             }
 
             return this._buildInsertRow({
@@ -1150,9 +590,8 @@ class DbHelper {
     }
 
     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");
+        const prepared = this.createDbParse().parseCount(options);
+        const result = await this.fetchCount(prepared, "COUNT(*) as count");
 
         return {
             data: result.total,
@@ -1161,9 +600,8 @@ class DbHelper {
     }
 
     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);
+        const prepared = await this.createDbParse().parseRead(options, "one");
+        const builder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(prepared.where);
         this.applyLeftJoins(builder, prepared.leftJoins);
 
         const { sql, params } = builder.toSelectSql();
@@ -1178,14 +616,16 @@ class DbHelper {
     }
 
     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 prepared = await this.createDbParse().parseRead(options, "list");
+        const countResult = await this.fetchCount(prepared, "COUNT(*) as total");
         const total = countResult.total;
 
         const offset = (prepared.page - 1) * prepared.limit;
-        const dataBuilder = this.createListBuilder(prepared, whereFiltered, prepared.limit, offset);
+        const dataBuilder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(prepared.where).limit(prepared.limit).offset(offset);
+        this.applyLeftJoins(dataBuilder, prepared.leftJoins);
+        if (prepared.orderBy && prepared.orderBy.length > 0) {
+            dataBuilder.orderBy(prepared.orderBy);
+        }
         const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
 
         if (total === 0) {
@@ -1228,10 +668,19 @@ class DbHelper {
     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 prepareOptions = {
+            table: options.table,
+            page: 1,
+            limit: 10
+        };
+
+        if (options.fields !== undefined) prepareOptions.fields = options.fields;
+        if (options.where !== undefined) prepareOptions.where = options.where;
+        if (options.leftJoin !== undefined) prepareOptions.leftJoin = options.leftJoin;
+        if (options.orderBy !== undefined) prepareOptions.orderBy = options.orderBy;
+
+        const prepared = await this.createDbParse().parseRead(prepareOptions, "all");
+        const countResult = await this.fetchCount(prepared, "COUNT(*) as total");
         const total = countResult.total;
 
         if (total === 0) {
@@ -1246,7 +695,11 @@ class DbHelper {
             };
         }
 
-        const dataBuilder = this.createListBuilder(prepared, whereFiltered, MAX_LIMIT, null);
+        const dataBuilder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(prepared.where).limit(MAX_LIMIT);
+        this.applyLeftJoins(dataBuilder, prepared.leftJoins);
+        if (prepared.orderBy && prepared.orderBy.length > 0) {
+            dataBuilder.orderBy(prepared.orderBy);
+        }
 
         const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
         const listExecuteRes = await this.execute(dataSql, dataParams);
@@ -1275,10 +728,9 @@ class DbHelper {
     }
 
     async exists(options) {
-        validateNoLeftJoinReadOptions(options, "exists", "exists 不支持 leftJoin（请使用显式 query 或拆分查询）");
-        const prepared = this.prepareSingleTableWhere(options.table, options.where, true);
+        const prepared = this.createDbParse().parseExists(options);
 
-        const builder = this.createSqlBuilder().selectRaw("COUNT(1) as cnt").from(prepared.snakeTable).where(prepared.whereFiltered).limit(1);
+        const builder = this.createSqlBuilder().selectRaw("COUNT(1) as cnt").from(prepared.snakeTable).where(prepared.where).limit(1);
         const { sql, params } = builder.toSelectSql();
         const executeRes = await this.execute(sql, params);
         const exists = (executeRes.data?.[0]?.cnt || 0) > 0;
@@ -1286,38 +738,55 @@ class DbHelper {
     }
 
     async getFieldValue(options) {
-        validateNoLeftJoinReadOptions(options, "getFieldValue", "getFieldValue 不支持 leftJoin（请使用 getOne/getList 并自行取字段）");
-        const field = options.field;
-        validateSafeFieldName(field);
+        const parsed = await this.createDbParse().parseFieldValue(options);
+        const builder = this.createSqlBuilder().select(parsed.prepared.fields).from(parsed.prepared.table).where(parsed.prepared.where);
+        this.applyLeftJoins(builder, parsed.prepared.leftJoins);
+        if (parsed.prepared.orderBy && parsed.prepared.orderBy.length > 0) {
+            builder.orderBy(parsed.prepared.orderBy);
+        }
+        const { sql, params } = builder.toSelectSql();
+        const executeRes = await this.execute(sql, params);
+        const result = this.normalizeRowData(executeRes.data?.[0] || null);
+        let value = null;
+        let hasValue = false;
+
+        if (isPlainObject(result)) {
+            if (Object.hasOwn(result, parsed.field)) {
+                value = result[parsed.field];
+                hasValue = true;
+            }
 
-        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];
+            if (!hasValue) {
+                const camelField = parsed.field.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+                if (camelField !== parsed.field && Object.hasOwn(result, camelField)) {
+                    value = result[camelField];
+                    hasValue = true;
+                }
+            }
 
-        const oneRes = await this.getOne(oneOptions);
+            if (!hasValue) {
+                const snakeField = parsed.field.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+                if (snakeField !== parsed.field && Object.hasOwn(result, snakeField)) {
+                    value = result[snakeField];
+                }
+            }
+        }
 
-        const result = oneRes.data;
-        const value = this.resolveFieldValue(result, field);
         return {
             data: value,
-            sql: oneRes.sql
+            sql: executeRes.sql
         };
     }
 
     async insData(options) {
-        validateTableDataOptions(options, "insData");
-        const { table, data } = options;
-        const snakeTable = snakeCase(table);
+        const parsed = this.createDbParse().parseInsert(options);
+        const { table, snakeTable, data } = parsed;
         const now = Date.now();
         const insertRows = await this.createInsertRows(table, snakeTable, [data], now);
         const processed = insertRows.processedList[0];
 
+        assertWriteDataHasFields(processed, "插入数据必须至少有一个字段", snakeTable);
+
         assertNoUndefinedInRecord(processed, `insData 插入数据 (table: ${snakeTable})`);
 
         const builder = this.createSqlBuilder();
@@ -1331,7 +800,9 @@ class DbHelper {
     }
 
     async insBatch(table, dataList) {
-        validateTableBatchDataOptions(table, dataList, "insBatch");
+        const parsed = this.createDbParse().parseInsertBatch(table, dataList);
+        table = parsed.table;
+        dataList = parsed.dataList;
         if (dataList.length === 0) {
             return {
                 data: [],
@@ -1340,9 +811,9 @@ class DbHelper {
         }
 
         const MAX_BATCH_SIZE = 1000;
-        validateInsertBatchSize(dataList.length, MAX_BATCH_SIZE);
+        assertInsertBatchSize(dataList.length, MAX_BATCH_SIZE);
 
-        const snakeTable = snakeCase(table);
+        const snakeTable = parsed.snakeTable;
         const now = Date.now();
         const insertRows = await this.createInsertRows(table, snakeTable, dataList, now);
         const processedList = insertRows.processedList;
@@ -1378,8 +849,9 @@ class DbHelper {
     }
 
     async delForceBatch(table, ids) {
-        validateTableName(table, "delForceBatch.table");
-        validateIdList(ids, "delForceBatch.ids");
+        const parsed = this.createDbParse().parseDelForceBatch(table, ids);
+        table = parsed.table;
+        ids = parsed.ids;
         if (ids.length === 0) {
             return {
                 data: 0,
@@ -1387,7 +859,7 @@ class DbHelper {
             };
         }
 
-        const snakeTable = snakeCase(table);
+        const snakeTable = parsed.snakeTable;
         const query = SqlBuilder.toDeleteInSql({
             table: snakeTable,
             idField: "id",
@@ -1403,7 +875,9 @@ class DbHelper {
     }
 
     async updBatch(table, dataList) {
-        validateTableBatchDataOptions(table, dataList, "updBatch");
+        const parsed = this.createDbParse().parseUpdateBatch(table, dataList);
+        table = parsed.table;
+        dataList = parsed.dataList;
         if (dataList.length === 0) {
             return {
                 data: 0,
@@ -1411,14 +885,14 @@ class DbHelper {
             };
         }
 
-        const snakeTable = snakeCase(table);
+        const snakeTable = parsed.snakeTable;
         const now = Date.now();
 
         const processedList = [];
         const fieldSet = new Set();
 
         for (const item of dataList) {
-            const userData = this._buildPartialUpdateData({ data: item.data, allowState: true });
+            const userData = this._prepareWriteUserData(item.data, true);
 
             for (const key of Object.keys(userData)) {
                 fieldSet.add(key);
@@ -1456,14 +930,12 @@ class DbHelper {
     }
 
     async updData(options) {
-        validateTableDataOptions(options, "updData");
-        validateTableWhereOptions(options, "updData", true);
-        const { table, data, where } = options;
-        const prepared = this.prepareRequiredSingleTableWhere(table, where, true, "updData");
+        const parsed = this.createDbParse().parseUpdate(options);
 
-        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 processed = this._buildUpdateRow({ data: parsed.data, now: Date.now(), allowState: true, beflyMode: this.beflyMode });
+        assertWriteDataHasFields(processed, "更新数据必须至少有一个字段", parsed.snakeTable);
+        const builder = this.createSqlBuilder().where(parsed.where);
+        const { sql, params } = builder.toUpdateSql(parsed.snakeTable, processed);
 
         const executeRes = await this.execute(sql, params);
         const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
@@ -1474,9 +946,7 @@ class DbHelper {
     }
 
     async delData(options) {
-        validateTableWhereOptions(options, "delData", true);
-        const { table, where } = options;
-        const prepared = this.prepareRequiredSingleTableWhere(table, where, true, "delData");
+        const parsed = this.createDbParse().parseDelete(options, false);
         const now = Date.now();
         const processed = {
             state: 0,
@@ -1487,8 +957,8 @@ class DbHelper {
             processed.updated_at = now;
         }
 
-        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
-        const { sql, params } = builder.toUpdateSql(prepared.snakeTable, processed);
+        const builder = this.createSqlBuilder().where(parsed.where);
+        const { sql, params } = builder.toUpdateSql(parsed.snakeTable, processed);
         const executeRes = await this.execute(sql, params);
         const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
 
@@ -1499,12 +969,10 @@ class DbHelper {
     }
 
     async delForce(options) {
-        validateTableWhereOptions(options, "delForce", true);
-        const { table, where } = options;
-        const prepared = this.prepareRequiredSingleTableWhere(table, where, false, "delForce");
+        const parsed = this.createDbParse().parseDelete(options, true);
 
-        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
-        const { sql, params } = builder.toDeleteSql(prepared.snakeTable);
+        const builder = this.createSqlBuilder().where(parsed.where);
+        const { sql, params } = builder.toDeleteSql(parsed.snakeTable);
 
         const executeRes = await this.execute(sql, params);
         const changes = normalizeSqlMetaNumber(executeRes.data?.affectedRows);
@@ -1515,7 +983,6 @@ class DbHelper {
     }
 
     async disableData(options) {
-        validateTableWhereOptions(options, "disableData", true);
         const { table, where } = options;
 
         return await this.updData({
@@ -1528,7 +995,6 @@ class DbHelper {
     }
 
     async enableData(options) {
-        validateTableWhereOptions(options, "enableData", true);
         const { table, where } = options;
 
         return await this.updData({
@@ -1541,18 +1007,16 @@ class DbHelper {
     }
 
     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 parsed = this.createDbParse().parseIncrement(table, field, where, value, "increment");
 
-        const builder = this.createSqlBuilder().where(prepared.whereFiltered);
+        const builder = this.createSqlBuilder().where(parsed.where);
         const { sql: whereClause, params: whereParams } = builder.getWhereConditions();
 
-        const quotedTable = quoteIdentMySql(prepared.snakeTable);
-        const quotedField = quoteIdentMySql(snakeField);
+        const quotedTable = quoteIdentMySql(parsed.snakeTable);
+        const quotedField = quoteIdentMySql(parsed.snakeField);
         const sql = whereClause ? `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ? WHERE ${whereClause}` : `UPDATE ${quotedTable} SET ${quotedField} = ${quotedField} + ?`;
 
-        const params = [value];
+        const params = [parsed.value];
         for (const param of whereParams) {
             params.push(param);
         }
@@ -1600,7 +1064,8 @@ class DbHelper {
                     dbName: this.dbName,
                     sql: tx,
                     isTransaction: true,
-                    beflyMode: this.beflyMode
+                    beflyMode: this.beflyMode,
+                    tables: this.tables
                 });
                 const result = await callback(trans);
                 if (result?.code !== undefined && result.code !== 0) {