befly 2.0.7 → 2.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "2.0.7",
+    "version": "2.0.10",
     "description": "Buma - 为 Bun 专属打造的 API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -51,5 +51,5 @@
         "README.md",
         "vitest.config.js"
     ],
-    "gitHead": "f6e4038c4b81010d5898b4f61c132d9ac05882f2"
+    "gitHead": "e87ddebec60d7dcde96510b2177ec23719972f54"
 }

package/plugins/db.js

@@ -101,75 +101,36 @@ export default {
                         }
                     }
 
-                    // 执行原始 SQL - 核心方法
-                    async execute(sql, params = []) {
+                    // 私有方法：执行 SQL（支持传入连接对象）
+                    async #executeWithConn(sql, params = [], conn = null) {
                         if (!sql || typeof sql !== 'string') {
                             throw new Error('SQL 语句是必需的');
                         }
 
-                        let conn;
+                        let providedConn = conn;
+                        let shouldRelease = false;
+
                         try {
-                            conn = await this.#pool.getConnection();
+                            // 如果没有提供连接，从池中获取
+                            if (!providedConn) {
+                                providedConn = await this.#pool.getConnection();
+                                shouldRelease = true;
+                            }
 
                             if (Env.MYSQL_DEBUG === 1) {
                                 Logger.debug('执行SQL:', { sql, params });
                             }
 
-                            const result = await conn.query(sql, params);
+                            const result = await providedConn.query(sql, params);
                             return result;
                         } catch (error) {
                             Logger.error('SQL 执行失败:', { sql, params, error: error.message });
                             throw error;
                         } finally {
-                            if (conn) {
-                                try {
-                                    conn.release();
-                                } catch (releaseError) {
-                                    Logger.warn('连接释放警告:', releaseError.message);
-                                }
-                            }
-                        }
-                    }
-
-                    // 事务处理
-                    async transaction(callback) {
-                        if (typeof callback !== 'function') {
-                            throw new Error('事务回调函数是必需的');
-                        }
-
-                        let conn;
-                        try {
-                            conn = await this.#pool.getConnection();
-                            await conn.beginTransaction();
-
-                            // 为回调函数提供连接对象
-                            const txMethods = {
-                                query: async (sql, params = []) => {
-                                    return await conn.query(sql, params);
-                                },
-                                execute: async (sql, params = []) => {
-                                    return await conn.query(sql, params);
-                                }
-                            };
-
-                            const result = await callback(txMethods);
-
-                            await conn.commit();
-                            return result;
-                        } catch (error) {
-                            if (conn) {
-                                try {
-                                    await conn.rollback();
-                                    Logger.info('事务已回滚');
-                                } catch (rollbackError) {
-                                    Logger.error('事务回滚失败:', rollbackError);
-                                }
-                            }
-                            throw error;
-                        } finally {
-                            if (conn) {
+                            // 只有当连接是我们获取的时候才释放
+                            if (shouldRelease && providedConn) {
                                 try {
-                                    conn.release();
+                                    providedConn.release();
                                 } catch (releaseError) {
                                     Logger.warn('连接释放警告:', releaseError.message);
                                 }
@@ -177,18 +138,13 @@ export default {
                         }
                     }
 
-                    // 获取单条记录详情
-                    async getDetail(table, options = {}) {
+                    // 私有方法：获取单条记录详情（支持传入连接对象）
+                    async #getDetailWithConn(table, options = {}, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
 
-                        const {
-                            //
-                            where = {},
-                            fields = '*',
-                            leftJoins = []
-                        } = typeof options === 'object' && !Array.isArray(options) ? options : { where: options };
+                        const { where = {}, fields = '*', leftJoins = [] } = typeof options === 'object' && !Array.isArray(options) ? options : { where: options };
 
                         try {
                             const builder = createQueryBuilder().select(fields).from(table).where(where).limit(1);
@@ -206,7 +162,7 @@ export default {
                             });
 
                             const { sql, params } = builder.toSelectSql();
-                            const result = await this.execute(sql, params);
+                            const result = await this.#executeWithConn(sql, params, conn);
                             return result[0] || null;
                         } catch (error) {
                             Logger.error('getDetail 执行失败:', error);
@@ -214,8 +170,8 @@ export default {
                         }
                     }
 
-                    // 获取列表（支持分页）
-                    async getList(table, options = {}) {
+                    // 私有方法：获取列表（支持传入连接对象）
+                    async #getListWithConn(table, options = {}, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -260,7 +216,7 @@ export default {
                             }
 
                             const { sql, params } = builder.toSelectSql();
-                            const list = await this.execute(sql, params);
+                            const rows = await this.#executeWithConn(sql, params, conn);
 
                             // 获取总数（如果需要分页）
                             let total = 0;
@@ -280,12 +236,12 @@ export default {
                                 });
 
                                 const { sql: countSql, params: countParams } = countBuilder.toCountSql();
-                                const countResult = await this.execute(countSql, countParams);
+                                const countResult = await this.#executeWithConn(countSql, countParams, conn);
                                 total = countResult[0]?.total || 0;
                             }
 
                             return {
-                                list: Array.isArray(list) ? list : [],
+                                rows: Array.isArray(rows) ? rows : [],
                                 total,
                                 page: numPage,
                                 pageSize: numPageSize
@@ -296,8 +252,8 @@ export default {
                         }
                     }
 
-                    // 获取所有记录
-                    async getAll(table, options = {}) {
+                    // 私有方法：获取所有记录（支持传入连接对象）
+                    async #getAllWithConn(table, options = {}, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -324,7 +280,7 @@ export default {
                             }
 
                             const { sql, params } = builder.toSelectSql();
-                            const result = await this.execute(sql, params);
+                            const result = await this.#executeWithConn(sql, params, conn);
                             return Array.isArray(result) ? result : [];
                         } catch (error) {
                             Logger.error('getAll 执行失败:', error);
@@ -332,8 +288,8 @@ export default {
                         }
                     }
 
-                    // 插入数据 - 增强版，自动添加 ID 和时间戳
-                    async insData(table, data) {
+                    // 私有方法：插入数据（支持传入连接对象）
+                    async #insDataWithConn(table, data, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -346,15 +302,15 @@ export default {
                             const processedData = await this.#processDataForInsert(data);
                             const builder = createQueryBuilder();
                             const { sql, params } = builder.toInsertSql(table, processedData);
-                            return await this.execute(sql, params);
+                            return await this.#executeWithConn(sql, params, conn);
                         } catch (error) {
                             Logger.error('insData 执行失败:', error);
                             throw error;
                         }
                     }
 
-                    // 更新数据 - 增强版，自动添加 updated_at，过滤敏感字段
-                    async upData(table, data, where) {
+                    // 私有方法：更新数据（支持传入连接对象）
+                    async #upDataWithConn(table, data, where, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -379,15 +335,15 @@ export default {
 
                             const builder = createQueryBuilder().where(where);
                             const { sql, params } = builder.toUpdateSql(table, updateData);
-                            return await this.execute(sql, params);
+                            return await this.#executeWithConn(sql, params, conn);
                         } catch (error) {
                             Logger.error('upData 执行失败:', error);
                             throw error;
                         }
                     }
 
-                    // 删除数据
-                    async delData(table, where) {
+                    // 私有方法：删除数据（支持传入连接对象）
+                    async #delDataWithConn(table, where, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -399,15 +355,15 @@ export default {
                         try {
                             const builder = createQueryBuilder().where(where);
                             const { sql, params } = builder.toDeleteSql(table);
-                            return await this.execute(sql, params);
+                            return await this.#executeWithConn(sql, params, conn);
                         } catch (error) {
                             Logger.error('delData 执行失败:', error);
                             throw error;
                         }
                     }
 
-                    // 批量插入 - 增强版，自动添加 ID 和时间戳
-                    async insBatch(table, dataArray) {
+                    // 私有方法：批量插入（支持传入连接对象）
+                    async #insBatchWithConn(table, dataArray, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -420,15 +376,15 @@ export default {
                             const processedDataArray = await this.#processDataForInsert(dataArray);
                             const builder = createQueryBuilder();
                             const { sql, params } = builder.toInsertSql(table, processedDataArray);
-                            return await this.execute(sql, params);
+                            return await this.#executeWithConn(sql, params, conn);
                         } catch (error) {
                             Logger.error('insBatch 执行失败:', error);
                             throw error;
                         }
                     }
 
-                    // 获取记录总数
-                    async getCount(table, options = {}) {
+                    // 私有方法：获取记录总数（支持传入连接对象）
+                    async #getCountWithConn(table, options = {}, conn = null) {
                         if (!table || typeof table !== 'string') {
                             throw new Error('表名是必需的');
                         }
@@ -451,7 +407,7 @@ export default {
                             });
 
                             const { sql, params } = builder.toCountSql();
-                            const result = await this.execute(sql, params);
+                            const result = await this.#executeWithConn(sql, params, conn);
                             return result[0]?.total || 0;
                         } catch (error) {
                             Logger.error('getCount 执行失败:', error);
@@ -459,6 +415,131 @@ export default {
                         }
                     }
 
+                    // 执行原始 SQL - 核心方法
+                    async execute(sql, params = []) {
+                        return await this.#executeWithConn(sql, params);
+                    }
+
+                    // 获取单条记录详情
+                    async getDetail(table, options = {}) {
+                        return await this.#getDetailWithConn(table, options);
+                    }
+
+                    // 获取列表（支持分页）
+                    async getList(table, options = {}) {
+                        return await this.#getListWithConn(table, options);
+                    }
+
+                    // 获取所有记录
+                    async getAll(table, options = {}) {
+                        return await this.#getAllWithConn(table, options);
+                    }
+
+                    // 插入数据 - 增强版，自动添加 ID 和时间戳
+                    async insData(table, data) {
+                        return await this.#insDataWithConn(table, data);
+                    }
+
+                    // 更新数据 - 增强版，自动添加 updated_at，过滤敏感字段
+                    async upData(table, data, where) {
+                        return await this.#upDataWithConn(table, data, where);
+                    }
+
+                    // 删除数据
+                    async delData(table, where) {
+                        return await this.#delDataWithConn(table, where);
+                    }
+
+                    // 批量插入 - 增强版，自动添加 ID 和时间戳
+                    async insBatch(table, dataArray) {
+                        return await this.#insBatchWithConn(table, dataArray);
+                    }
+
+                    // 获取记录总数
+                    async getCount(table, options = {}) {
+                        return await this.#getCountWithConn(table, options);
+                    }
+
+                    // 事务处理
+                    async trans(callback) {
+                        if (typeof callback !== 'function') {
+                            throw new Error('事务回调函数是必需的');
+                        }
+
+                        let conn;
+                        try {
+                            conn = await this.#pool.getConnection();
+                            await conn.beginTransaction();
+
+                            // 为回调函数提供连接对象和高级方法
+                            const txMethods = {
+                                // 原始SQL执行方法
+                                query: async (sql, params = []) => {
+                                    return await conn.query(sql, params);
+                                },
+                                execute: async (sql, params = []) => {
+                                    return await conn.query(sql, params);
+                                },
+
+                                // 高级数据操作方法 - 直接调用私有方法，传入事务连接
+                                getDetail: async (table, options = {}) => {
+                                    return await this.#getDetailWithConn(table, options, conn);
+                                },
+
+                                getList: async (table, options = {}) => {
+                                    return await this.#getListWithConn(table, options, conn);
+                                },
+
+                                getAll: async (table, options = {}) => {
+                                    return await this.#getAllWithConn(table, options, conn);
+                                },
+
+                                insData: async (table, data) => {
+                                    return await this.#insDataWithConn(table, data, conn);
+                                },
+
+                                upData: async (table, data, where) => {
+                                    return await this.#upDataWithConn(table, data, where, conn);
+                                },
+
+                                delData: async (table, where) => {
+                                    return await this.#delDataWithConn(table, where, conn);
+                                },
+
+                                getCount: async (table, options = {}) => {
+                                    return await this.#getCountWithConn(table, options, conn);
+                                },
+
+                                insBatch: async (table, dataArray) => {
+                                    return await this.#insBatchWithConn(table, dataArray, conn);
+                                }
+                            };
+
+                            const result = await callback(txMethods);
+
+                            await conn.commit();
+                            return result;
+                        } catch (error) {
+                            if (conn) {
+                                try {
+                                    await conn.rollback();
+                                    Logger.info('事务已回滚');
+                                } catch (rollbackError) {
+                                    Logger.error('事务回滚失败:', rollbackError);
+                                }
+                            }
+                            throw error;
+                        } finally {
+                            if (conn) {
+                                try {
+                                    conn.release();
+                                } catch (releaseError) {
+                                    Logger.warn('连接释放警告:', releaseError.message);
+                                }
+                            }
+                        }
+                    }
+
                     // 获取连接池状态
                     getPoolStatus() {
                         return {

package/utils/curd.js

@@ -58,6 +58,7 @@ export class SqlBuilder {
             if (value === undefined) {
                 return;
             }
+
             if (key === '$and') {
                 if (Array.isArray(value)) {
                     value.forEach((condition) => this._processWhereConditions(condition));
@@ -81,83 +82,85 @@ export class SqlBuilder {
                         this._params.push(...tempParams);
                     }
                 }
-            } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                // 字段级操作符
-                Object.entries(value).forEach(([operator, operatorValue]) => {
-                    this._validateParam(operatorValue);
-
-                    switch (operator) {
-                        case '$ne':
-                        case '$not':
-                            this._where.push(`${key} != ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$in':
-                            if (Array.isArray(operatorValue) && operatorValue.length > 0) {
-                                const placeholders = operatorValue.map(() => '?').join(',');
-                                this._where.push(`${key} IN (${placeholders})`);
-                                this._params.push(...operatorValue);
-                            }
-                            break;
-                        case '$nin':
-                        case '$notIn':
-                            if (Array.isArray(operatorValue) && operatorValue.length > 0) {
-                                const placeholders = operatorValue.map(() => '?').join(',');
-                                this._where.push(`${key} NOT IN (${placeholders})`);
-                                this._params.push(...operatorValue);
-                            }
-                            break;
-                        case '$like':
-                            this._where.push(`${key} LIKE ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$notLike':
-                            this._where.push(`${key} NOT LIKE ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$gt':
-                            this._where.push(`${key} > ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$gte':
-                            this._where.push(`${key} >= ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$lt':
-                            this._where.push(`${key} < ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$lte':
-                            this._where.push(`${key} <= ?`);
-                            this._params.push(operatorValue);
-                            break;
-                        case '$between':
-                            if (Array.isArray(operatorValue) && operatorValue.length === 2) {
-                                this._where.push(`${key} BETWEEN ? AND ?`);
-                                this._params.push(operatorValue[0], operatorValue[1]);
-                            }
-                            break;
-                        case '$notBetween':
-                            if (Array.isArray(operatorValue) && operatorValue.length === 2) {
-                                this._where.push(`${key} NOT BETWEEN ? AND ?`);
-                                this._params.push(operatorValue[0], operatorValue[1]);
-                            }
-                            break;
-                        case '$null':
-                            if (operatorValue === true) {
-                                this._where.push(`${key} IS NULL`);
-                            }
-                            break;
-                        case '$notNull':
-                            if (operatorValue === true) {
-                                this._where.push(`${key} IS NOT NULL`);
-                            }
-                            break;
-                        default:
-                            this._where.push(`${key} = ?`);
-                            this._params.push(operatorValue);
-                    }
-                });
+            } else if (key.includes('$')) {
+                // 一级属性格式：age$gt, role$in 等
+                const lastDollarIndex = key.lastIndexOf('$');
+                const fieldName = key.substring(0, lastDollarIndex);
+                const operator = '$' + key.substring(lastDollarIndex + 1);
+
+                this._validateParam(value);
+
+                switch (operator) {
+                    case '$ne':
+                    case '$not':
+                        this._where.push(`${fieldName} != ?`);
+                        this._params.push(value);
+                        break;
+                    case '$in':
+                        if (Array.isArray(value) && value.length > 0) {
+                            const placeholders = value.map(() => '?').join(',');
+                            this._where.push(`${fieldName} IN (${placeholders})`);
+                            this._params.push(...value);
+                        }
+                        break;
+                    case '$nin':
+                    case '$notIn':
+                        if (Array.isArray(value) && value.length > 0) {
+                            const placeholders = value.map(() => '?').join(',');
+                            this._where.push(`${fieldName} NOT IN (${placeholders})`);
+                            this._params.push(...value);
+                        }
+                        break;
+                    case '$like':
+                        this._where.push(`${fieldName} LIKE ?`);
+                        this._params.push(value);
+                        break;
+                    case '$notLike':
+                        this._where.push(`${fieldName} NOT LIKE ?`);
+                        this._params.push(value);
+                        break;
+                    case '$gt':
+                        this._where.push(`${fieldName} > ?`);
+                        this._params.push(value);
+                        break;
+                    case '$gte':
+                        this._where.push(`${fieldName} >= ?`);
+                        this._params.push(value);
+                        break;
+                    case '$lt':
+                        this._where.push(`${fieldName} < ?`);
+                        this._params.push(value);
+                        break;
+                    case '$lte':
+                        this._where.push(`${fieldName} <= ?`);
+                        this._params.push(value);
+                        break;
+                    case '$between':
+                        if (Array.isArray(value) && value.length === 2) {
+                            this._where.push(`${fieldName} BETWEEN ? AND ?`);
+                            this._params.push(value[0], value[1]);
+                        }
+                        break;
+                    case '$notBetween':
+                        if (Array.isArray(value) && value.length === 2) {
+                            this._where.push(`${fieldName} NOT BETWEEN ? AND ?`);
+                            this._params.push(value[0], value[1]);
+                        }
+                        break;
+                    case '$null':
+                        if (value === true) {
+                            this._where.push(`${fieldName} IS NULL`);
+                        }
+                        break;
+                    case '$notNull':
+                        if (value === true) {
+                            this._where.push(`${fieldName} IS NOT NULL`);
+                        }
+                        break;
+                    default:
+                        this._where.push(`${fieldName} = ?`);
+                        this._params.push(value);
+                }
             } else {
                 // 简单的等于条件
                 this._validateParam(value);
@@ -189,43 +192,31 @@ export class SqlBuilder {
         return this;
     }
 
-    orderBy(field, direction = 'ASC') {
-        if (Array.isArray(field)) {
-            field.forEach((item) => {
-                if (typeof item === 'string' && item.includes('#')) {
-                    const [fieldName, dir] = item.split('#');
-                    const cleanDir = (dir || 'ASC').trim().toUpperCase();
-                    if (!['ASC', 'DESC'].includes(cleanDir)) {
-                        throw new Error('ORDER BY direction must be ASC or DESC');
-                    }
-                    this._orderBy.push(`${fieldName.trim()} ${cleanDir}`);
-                } else if (Array.isArray(item) && item.length >= 1) {
-                    const [fieldName, dir] = item;
-                    const cleanDir = (dir || 'ASC').toUpperCase();
-                    if (!['ASC', 'DESC'].includes(cleanDir)) {
-                        throw new Error('ORDER BY direction must be ASC or DESC');
-                    }
-                    this._orderBy.push(`${fieldName} ${cleanDir}`);
-                } else if (typeof item === 'string') {
-                    this._orderBy.push(`${item} ASC`);
-                }
-            });
-        } else if (typeof field === 'string') {
-            if (field.includes('#')) {
-                const [fieldName, dir] = field.split('#');
-                const cleanDir = (dir || 'ASC').trim().toUpperCase();
-                if (!['ASC', 'DESC'].includes(cleanDir)) {
-                    throw new Error('ORDER BY direction must be ASC or DESC');
-                }
-                this._orderBy.push(`${fieldName.trim()} ${cleanDir}`);
-            } else {
-                const cleanDir = direction.toUpperCase();
-                if (!['ASC', 'DESC'].includes(cleanDir)) {
-                    throw new Error('ORDER BY direction must be ASC or DESC');
-                }
-                this._orderBy.push(`${field} ${cleanDir}`);
-            }
+    orderBy(fields) {
+        if (!Array.isArray(fields)) {
+            throw new Error('orderBy must be an array of strings in "field#direction" format');
         }
+
+        fields.forEach((item) => {
+            if (typeof item !== 'string' || !item.includes('#')) {
+                throw new Error('orderBy field must be a string in "field#direction" format (e.g., "name#ASC", "id#DESC")');
+            }
+
+            const [fieldName, direction] = item.split('#');
+            const cleanField = fieldName.trim();
+            const cleanDir = direction.trim().toUpperCase();
+
+            if (!cleanField) {
+                throw new Error('Field name cannot be empty in orderBy');
+            }
+
+            if (!['ASC', 'DESC'].includes(cleanDir)) {
+                throw new Error('ORDER BY direction must be ASC or DESC');
+            }
+
+            this._orderBy.push(`${cleanField} ${cleanDir}`);
+        });
+
         return this;
     }