befly 3.17.0 → 3.17.2

package/lib/dbHelper/context.js

@@ -0,0 +1,131 @@
+import { isNonEmptyString, isNullable, isNumber, isPlainObject, isString } from "../../utils/is.js";
+import { canConvertToNumber } from "../../utils/util.js";
+
+export 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}\``;
+}
+
+export function hasBegin(sql) {
+    return typeof sql.begin === "function";
+}
+
+export class DbSqlError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.originalError = options.originalError;
+        this.params = options.params;
+        this.duration = options.duration;
+        this.sqlInfo = options.sqlInfo;
+    }
+}
+
+export class TransAbortError extends Error {
+    constructor(payload) {
+        super("TRANSACTION_ABORT");
+        this.payload = payload;
+    }
+}
+
+export function isBeflyResponse(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+
+    const record = value;
+    return isNumber(record["code"]) && isString(record["msg"]);
+}
+
+export function convertBigIntFields(arr, fields) {
+    if (isNullable(arr)) {
+        return arr;
+    }
+
+    const defaultFields = ["id", "pid", "sort"];
+
+    const buildFields = (userFields) => {
+        if (!userFields || userFields.length === 0) {
+            return defaultFields;
+        }
+
+        const merged = ["id", "pid", "sort"];
+        for (const f of userFields) {
+            if (!isString(f)) {
+                continue;
+            }
+            if (!isNonEmptyString(f)) {
+                continue;
+            }
+            const trimmed = f.trim();
+            if (!merged.includes(trimmed)) {
+                merged.push(trimmed);
+            }
+        }
+        return merged;
+    };
+
+    const effectiveFields = buildFields(fields);
+    const fieldSet = new Set(effectiveFields);
+
+    const convertRecord = (source) => {
+        const converted = {};
+
+        for (const [key, value] of Object.entries(source)) {
+            let nextValue = value;
+
+            if (!isNullable(value)) {
+                const shouldConvert = fieldSet.has(key) || key.endsWith("Id") || key.endsWith("_id") || key.endsWith("At") || key.endsWith("_at");
+
+                if (shouldConvert) {
+                    let bigintValue = null;
+                    if (typeof value === "bigint") {
+                        bigintValue = value;
+                    } else if (isString(value)) {
+                        if (/^-?\d+$/.test(value)) {
+                            try {
+                                bigintValue = BigInt(value);
+                            } catch {
+                                bigintValue = null;
+                            }
+                        }
+                    }
+
+                    if (bigintValue !== null) {
+                        const convertedNumber = canConvertToNumber(bigintValue);
+                        if (convertedNumber !== null) {
+                            nextValue = convertedNumber;
+                        }
+                    }
+                }
+            }
+
+            converted[key] = nextValue;
+        }
+
+        return converted;
+    };
+
+    if (Array.isArray(arr)) {
+        return arr.map((item) => convertRecord(item));
+    }
+
+    if (typeof arr === "object") {
+        return convertRecord(arr);
+    }
+
+    return arr;
+}

package/lib/dbHelper/dataOps.js

@@ -0,0 +1,505 @@
+import { isNullable, isNumber } from "../../utils/is.js";
+import { snakeCase } from "../../utils/util.js";
+import { Logger } from "../logger.js";
+import { SqlBuilder } from "../sqlBuilder/index.js";
+import { quoteIdentMySql } from "./context.js";
+import { toNumberFromSql } from "./util.js";
+import { addDefaultStateFilter, buildInsertRow, buildPartialUpdateData, buildUpdateRow, clearDeep, whereKeysToSnake } from "./builders.js";
+import { assertBatchInsertRowsConsistent, assertNoUndefinedInRecord, validateGeneratedBatchId, validateIncrementOptions, validateInsertBatchSize, validateNoJoinReadOptions, validatePageLimitRange, validateSafeFieldName, validateTableBatchDataOptions, validateTableDataOptions, validateTableName, validateTableWhereOptions } from "./validate.js";
+
+export const dataOpsMethods = {
+    // 读取操作
+    async getCount(options) {
+        const { table, where, joins, tableQualifier } = await this.prepareQueryOptions(options, "getCount.options");
+        const hasJoins = Array.isArray(joins) && joins.length > 0;
+
+        const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasJoins);
+        const result = await this.fetchCount({ table: table, joins: joins }, whereFiltered, "COUNT(*) as count");
+
+        return {
+            data: result.total,
+            sql: result.sql
+        };
+    },
+
+    async getOne(options) {
+        const { table, fields, where, joins, tableQualifier } = await this.prepareQueryOptions(options, "getOne.options");
+        const hasJoins = Array.isArray(joins) && joins.length > 0;
+
+        const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasJoins);
+        const builder = this.createSqlBuilder().select(fields).from(table).where(whereFiltered);
+        this.applyJoins(builder, joins);
+
+        const { sql, params } = builder.toSelectSql();
+        const executeRes = await this.execute(sql, params);
+        const result = executeRes.data;
+
+        const data = this.normalizeRowData(result?.[0] || null, options.bigint);
+        return {
+            data: data,
+            sql: executeRes.sql
+        };
+    },
+
+    async getDetail(options) {
+        return await this.getOne(options);
+    },
+
+    async getList(options) {
+        const prepared = await this.prepareQueryOptions(options, "getList.options");
+        validatePageLimitRange(prepared, options.table);
+
+        const hasJoins = Array.isArray(prepared.joins) && prepared.joins.length > 0;
+        const whereFiltered = addDefaultStateFilter(prepared.where, prepared.tableQualifier, hasJoins);
+        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, options.bigint),
+                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 = 10000;
+        const WARNING_LIMIT = 1000;
+        const prepareOptions = this.buildQueryOptions(options, { page: 1, limit: 10 });
+        const prepared = await this.prepareQueryOptions(prepareOptions, "getAll.options");
+
+        const hasJoins = Array.isArray(prepared.joins) && prepared.joins.length > 0;
+        const whereFiltered = addDefaultStateFilter(prepared.where, prepared.tableQualifier, hasJoins);
+        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, options.bigint);
+
+        return {
+            data: {
+                lists: lists,
+                total: total
+            },
+            sql: {
+                count: countResult.sql,
+                data: listExecuteRes.sql
+            }
+        };
+    },
+
+    async exists(options) {
+        validateNoJoinReadOptions(options, "exists", "exists 不支持 joins（请使用显式 query 或拆分查询）");
+        const snakeTable = snakeCase(options.table);
+        const snakeWhere = whereKeysToSnake(clearDeep(options.where || {}));
+        const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false);
+
+        const builder = this.createSqlBuilder().selectRaw("COUNT(1) as cnt").from(snakeTable).where(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) {
+        validateNoJoinReadOptions(options, "getFieldValue", "getFieldValue 不支持 joins（请使用 getOne/getList 并自行取字段）");
+        const field = options.field;
+        validateSafeFieldName(field);
+
+        const oneOptions = {
+            table: options.table
+        };
+        if (options.where !== undefined) oneOptions.where = options.where;
+        if (options.joins !== undefined) oneOptions.joins = options.joins;
+        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();
+
+        let processed;
+        if (this.idMode === "autoId") {
+            processed = buildInsertRow({ idMode: "autoId", data: data, now: now });
+        } else {
+            let id;
+            try {
+                id = await this.redis.genTimeID();
+            } catch (error) {
+                throw new Error(`生成 ID 失败，Redis 可能不可用 (table: ${table})`, {
+                    cause: error,
+                    code: "runtime",
+                    subsystem: "db",
+                    operation: "genTimeId",
+                    table: table
+                });
+            }
+            processed = buildInsertRow({ idMode: "timeId", data: data, id: id, now: now });
+        }
+
+        assertNoUndefinedInRecord(processed, `insData 插入数据 (table: ${snakeTable})`);
+
+        const builder = this.createSqlBuilder();
+        const { sql, params } = builder.toInsertSql(snakeTable, processed);
+        const executeRes = await this.execute(sql, params);
+
+        const processedId = processed["id"];
+        const processedIdNum = isNumber(processedId) ? processedId : 0;
+        const lastInsertRowidNum = toNumberFromSql(executeRes.data?.lastInsertRowid);
+
+        const insertedId = this.idMode === "autoId" ? lastInsertRowidNum || 0 : processedIdNum || lastInsertRowidNum || 0;
+        if (this.idMode === "autoId" && insertedId <= 0) {
+            throw new Error(`插入失败：autoId 模式下无法获取 lastInsertRowid (table: ${table})`, {
+                cause: null,
+                code: "runtime"
+            });
+        }
+        return {
+            data: insertedId,
+            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();
+        let ids = [];
+
+        let processedList;
+        if (this.idMode === "autoId") {
+            processedList = dataList.map((data) => {
+                return buildInsertRow({ idMode: "autoId", data: data, now: now });
+            });
+        } else {
+            const nextIds = [];
+            for (let i = 0; i < dataList.length; i++) {
+                nextIds.push(await this.redis.genTimeID());
+            }
+            ids = nextIds;
+            processedList = dataList.map((data, index) => {
+                const id = nextIds[index];
+                validateGeneratedBatchId(id, snakeTable, index);
+                return buildInsertRow({ idMode: "timeId", data: data, id: id, now: now });
+            });
+        }
+
+        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);
+
+            if (this.idMode === "autoId") {
+                const firstId = toNumberFromSql(executeRes.data?.lastInsertRowid);
+                if (firstId <= 0) {
+                    throw new Error(`批量插入失败：autoId 模式下无法获取 lastInsertRowid (table: ${table})`, {
+                        cause: null,
+                        code: "runtime"
+                    });
+                }
+
+                const outIds = [];
+                for (let i = 0; i < dataList.length; i++) {
+                    outIds.push(firstId + i);
+                }
+
+                return {
+                    data: outIds,
+                    sql: executeRes.sql
+                };
+            }
+
+            return {
+                data: ids,
+                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");
+        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 = toNumberFromSql(executeRes.data?.changes);
+        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 = 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: "updated_at",
+            updatedAtValue: now,
+            stateField: "state",
+            stateGtZero: true
+        });
+
+        const executeRes = await this.execute(query.sql, query.params);
+        const changes = toNumberFromSql(executeRes.data?.changes);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    },
+
+    async updData(options) {
+        validateTableDataOptions(options, "updData");
+        validateTableWhereOptions(options, "updData", true);
+        const { table, data, where } = options;
+        const snakeTable = snakeCase(table);
+        const snakeWhere = whereKeysToSnake(clearDeep(where));
+
+        const processed = buildUpdateRow({ data: data, now: Date.now(), allowState: true });
+        const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false);
+        const builder = this.createSqlBuilder().where(whereFiltered);
+        const { sql, params } = builder.toUpdateSql(snakeTable, processed);
+
+        const executeRes = await this.execute(sql, params);
+        const changes = toNumberFromSql(executeRes.data?.changes);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    },
+
+    async delData(options) {
+        validateTableWhereOptions(options, "delData", true);
+        const { table, where } = options;
+
+        return await this.updData({
+            table: table,
+            data: { state: 0, deleted_at: Date.now() },
+            where: where
+        });
+    },
+
+    async delForce(options) {
+        validateTableWhereOptions(options, "delForce", true);
+        const { table, where } = options;
+
+        const snakeTable = snakeCase(table);
+        const snakeWhere = whereKeysToSnake(clearDeep(where));
+
+        const builder = this.createSqlBuilder().where(snakeWhere);
+        const { sql, params } = builder.toDeleteSql(snakeTable);
+
+        const executeRes = await this.execute(sql, params);
+        const changes = toNumberFromSql(executeRes.data?.changes);
+        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 snakeTable = snakeCase(table);
+        const snakeField = snakeCase(field);
+
+        const snakeWhere = whereKeysToSnake(clearDeep(where));
+        const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false);
+        const builder = this.createSqlBuilder().where(whereFiltered);
+        const { sql: whereClause, params: whereParams } = builder.getWhereConditions();
+
+        const quotedTable = quoteIdentMySql(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 = toNumberFromSql(executeRes.data?.changes);
+        return {
+            data: changes,
+            sql: executeRes.sql
+        };
+    },
+
+    async decrement(table, field, where, value = 1) {
+        return await this.increment(table, field, where, -value);
+    }
+};

package/lib/dbHelper/execute.js

@@ -0,0 +1,65 @@
+import { toSqlParams } from "../sqlBuilder/util.js";
+import { snakeCase } from "../../utils/util.js";
+import { DbSqlError } from "./context.js";
+import { validateExecuteSql } from "./validate.js";
+
+export const executeMethods = {
+    async execute(sql, params) {
+        if (!this.sql) {
+            throw new Error("数据库连接未初始化", {
+                cause: null,
+                code: "runtime"
+            });
+        }
+
+        validateExecuteSql(sql);
+
+        const startTime = Date.now();
+        const safeParams = toSqlParams(params);
+
+        try {
+            let queryResult;
+            if (safeParams.length > 0) {
+                queryResult = await this.sql.unsafe(sql, safeParams);
+            } else {
+                queryResult = await this.sql.unsafe(sql);
+            }
+
+            const duration = Date.now() - startTime;
+
+            return {
+                data: queryResult,
+                sql: {
+                    sql: sql,
+                    params: safeParams,
+                    duration: duration
+                }
+            };
+        } catch (error) {
+            const duration = Date.now() - startTime;
+            const msg = error instanceof Error ? error.message : String(error);
+
+            throw new DbSqlError(`SQL执行失败: ${msg}`, {
+                originalError: error,
+                params: safeParams,
+                duration: duration,
+                sqlInfo: {
+                    sql: sql,
+                    params: safeParams,
+                    duration: duration
+                }
+            });
+        }
+    },
+
+    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
+        };
+    }
+};