befly 3.20.5 → 3.20.7

package/apis/dict/all.js

@@ -11,12 +11,7 @@ export default {
     handler: async (befly) => {
         const result = await befly.mysql.getAll({
             table: "beflyDict",
-            joins: [
-                {
-                    table: "beflyDictType",
-                    on: "beflyDict.typeCode = beflyDictType.code"
-                }
-            ],
+            leftJoin: ["beflyDictType ON beflyDict.typeCode = beflyDictType.code"],
             fields: ["beflyDict.id", "beflyDict.typeCode", "beflyDict.key", "beflyDict.label", "beflyDict.sort", "beflyDict.remark", "beflyDict.createdAt", "beflyDict.updatedAt", "beflyDictType.name AS typeName"],
             orderBy: ["beflyDict.sort#ASC", "beflyDict.id#ASC"]
         });

package/apis/dict/detail.js

@@ -10,12 +10,7 @@ export default {
     handler: async (befly, ctx) => {
         const dict = await befly.mysql.getOne({
             table: "beflyDict",
-            joins: [
-                {
-                    table: "beflyDictType",
-                    on: "beflyDict.typeCode = beflyDictType.code"
-                }
-            ],
+            leftJoin: ["beflyDictType ON beflyDict.typeCode = beflyDictType.code"],
             fields: ["beflyDict.id", "beflyDict.typeCode", "beflyDict.key", "beflyDict.label", "beflyDict.sort", "beflyDict.remark", "beflyDict.createdAt", "beflyDict.updatedAt", "beflyDictType.name AS typeName"],
             where: { "beflyDict.id": ctx.body.id }
         });

package/apis/dict/list.js

@@ -15,12 +15,7 @@ export default {
     handler: async (befly, ctx) => {
         const result = await befly.mysql.getList({
             table: "beflyDict",
-            joins: [
-                {
-                    table: "beflyDictType",
-                    on: "beflyDict.typeCode = beflyDictType.code"
-                }
-            ],
+            leftJoin: ["beflyDictType ON beflyDict.typeCode = beflyDictType.code"],
             fields: ["beflyDict.id", "beflyDict.typeCode", "beflyDict.key", "beflyDict.label", "beflyDict.sort", "beflyDict.remark", "beflyDict.createdAt", "beflyDict.updatedAt", "beflyDictType.name AS typeName"],
             where: {
                 "beflyDict.typeCode": ctx.body.typeCode

package/lib/dbHelper/builders.js

@@ -349,6 +349,29 @@ export function processJoinOrderBy(orderBy) {
     });
 }
 
+export function parseLeftJoinItem(joinItem) {
+    if (!isString(joinItem)) {
+        return null;
+    }
+
+    const parts = joinItem.split(/\s+ON\s+/i);
+    if (parts.length !== 2) {
+        return null;
+    }
+
+    const table = parts[0]?.trim();
+    const on = parts[1]?.trim();
+    if (!isNonEmptyString(table) || !isNonEmptyString(on)) {
+        return null;
+    }
+
+    return {
+        type: "left",
+        table: normalizeTableRef(table),
+        on: processJoinOn(on)
+    };
+}
+
 export function processJoinOn(on) {
     if (!isString(on)) {
         return String(on);
@@ -402,7 +425,7 @@ export function processJoinOn(on) {
     return result;
 }
 
-export function addDefaultStateFilter(where = {}, table, hasJoins = false, beflyMode = "auto") {
+export function addDefaultStateFilter(where = {}, table, hasLeftJoin = false, beflyMode = "auto") {
     if (beflyMode === "manual") {
         return where;
     }
@@ -412,7 +435,7 @@ export function addDefaultStateFilter(where = {}, table, hasJoins = false, befly
         return where;
     }
 
-    if (hasJoins && table) {
+    if (hasLeftJoin && table) {
         const result = {};
         for (const [key, value] of Object.entries(where)) {
             result[key] = value;
@@ -575,7 +598,7 @@ export const builderMethods = {
 
     createListBuilder(prepared, whereFiltered, limit, offset) {
         const builder = this.createSqlBuilder().select(prepared.fields).from(prepared.table).where(whereFiltered).limit(limit);
-        this.applyJoins(builder, prepared.joins);
+        this.applyLeftJoins(builder, prepared.leftJoins);
         if (!isNullable(offset)) {
             builder.offset(offset);
         }
@@ -587,7 +610,7 @@ export const builderMethods = {
 
     async fetchCount(prepared, whereFiltered, alias) {
         const builder = this.createSqlBuilder().selectRaw(alias).from(prepared.table).where(whereFiltered);
-        this.applyJoins(builder, prepared.joins);
+        this.applyLeftJoins(builder, prepared.leftJoins);
         const result = builder.toSelectSql();
         const executeRes = await this.execute(result.sql, result.params);
         const countRow = executeRes.data?.[0] || null;
@@ -624,17 +647,24 @@ export const builderMethods = {
         return normalizeBigIntValues(deserializedList);
     },
 
-    normalizeJoinOptions(options, cleanWhere) {
+    normalizeLeftJoinOptions(options, cleanWhere) {
         const processedFields = (options.fields || []).map((field) => processJoinField(field));
         const normalizedTableRef = normalizeTableRef(options.table);
         const mainQualifier = getJoinMainQualifier(options.table);
+        const leftJoins = [];
+        for (const joinItem of options.leftJoin || []) {
+            const parsedJoin = parseLeftJoinItem(joinItem);
+            if (parsedJoin) {
+                leftJoins.push(parsedJoin);
+            }
+        }
 
         return {
             table: normalizedTableRef,
             tableQualifier: mainQualifier,
             fields: processedFields.length > 0 ? processedFields : ["*"],
             where: processJoinWhere(cleanWhere),
-            joins: options.joins,
+            leftJoins: leftJoins,
             orderBy: processJoinOrderBy(options.orderBy || []),
             page: options.page || 1,
             limit: options.limit || 10
@@ -650,7 +680,7 @@ export const builderMethods = {
             tableQualifier: snakeTable,
             fields: processedFields,
             where: whereKeysToSnake(cleanWhere),
-            joins: undefined,
+            leftJoins: undefined,
             orderBy: orderByToSnake(options.orderBy || []),
             page: options.page || 1,
             limit: options.limit || 10
@@ -666,7 +696,7 @@ export const builderMethods = {
 
         if (options.fields !== undefined) output.fields = options.fields;
         if (options.where !== undefined) output.where = options.where;
-        if (options.joins !== undefined) output.joins = options.joins;
+        if (options.leftJoin !== undefined) output.leftJoin = options.leftJoin;
         if (options.orderBy !== undefined) output.orderBy = options.orderBy;
         return output;
     },
@@ -720,35 +750,20 @@ export const builderMethods = {
     async prepareQueryOptions(options, label = "queryOptions") {
         validateQueryOptions(options, label);
         const cleanWhere = clearDeep(options.where || {});
-        const hasJoins = options.joins && options.joins.length > 0;
+        const hasLeftJoin = options.leftJoin && options.leftJoin.length > 0;
 
-        if (hasJoins) {
-            return this.normalizeJoinOptions(options, cleanWhere);
+        if (hasLeftJoin) {
+            return this.normalizeLeftJoinOptions(options, cleanWhere);
         }
 
         return await this.normalizeSingleTableOptions(options, cleanWhere);
     },
 
-    applyJoins(builder, joins) {
-        if (!joins || joins.length === 0) return;
-
-        for (const join of joins) {
-            const processedTable = normalizeTableRef(join.table);
-            const processedOn = processJoinOn(join.on);
-            const type = join.type || "left";
-
-            switch (type) {
-                case "inner":
-                    builder.innerJoin(processedTable, processedOn);
-                    break;
-                case "right":
-                    builder.rightJoin(processedTable, processedOn);
-                    break;
-                case "left":
-                default:
-                    builder.leftJoin(processedTable, processedOn);
-                    break;
-            }
+    applyLeftJoins(builder, leftJoins) {
+        if (!leftJoins || leftJoins.length === 0) return;
+
+        for (const join of leftJoins) {
+            builder.leftJoin(join.table, join.on);
         }
     }
 };

package/lib/dbHelper/dataOps.js

@@ -4,16 +4,16 @@ import { Logger } from "../logger.js";
 import { SqlBuilder } from "../sqlBuilder/index.js";
 import { normalizeSqlMetaNumber, quoteIdentMySql } 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";
+import { assertBatchInsertRowsConsistent, assertNoUndefinedInRecord, validateGeneratedBatchId, validateIncrementOptions, validateInsertBatchSize, validateNoLeftJoinReadOptions, 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 { table, where, leftJoins, tableQualifier } = await this.prepareQueryOptions(options, "getCount.options");
+        const hasLeftJoin = Array.isArray(leftJoins) && leftJoins.length > 0;
 
-        const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasJoins, this.beflyMode);
-        const result = await this.fetchCount({ table: table, joins: joins }, whereFiltered, "COUNT(*) as count");
+        const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasLeftJoin, this.beflyMode);
+        const result = await this.fetchCount({ table: table, leftJoins: leftJoins }, whereFiltered, "COUNT(*) as count");
 
         return {
             data: result.total,
@@ -22,12 +22,12 @@ export const dataOpsMethods = {
     },
 
     async getOne(options) {
-        const { table, fields, where, joins, tableQualifier } = await this.prepareQueryOptions(options, "getOne.options");
-        const hasJoins = Array.isArray(joins) && joins.length > 0;
+        const { table, fields, where, leftJoins, tableQualifier } = await this.prepareQueryOptions(options, "getOne.options");
+        const hasLeftJoin = Array.isArray(leftJoins) && leftJoins.length > 0;
 
-        const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasJoins, this.beflyMode);
+        const whereFiltered = addDefaultStateFilter(where, tableQualifier, hasLeftJoin, this.beflyMode);
         const builder = this.createSqlBuilder().select(fields).from(table).where(whereFiltered);
-        this.applyJoins(builder, joins);
+        this.applyLeftJoins(builder, leftJoins);
 
         const { sql, params } = builder.toSelectSql();
         const executeRes = await this.execute(sql, params);
@@ -48,8 +48,8 @@ export const dataOpsMethods = {
         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, this.beflyMode);
+        const hasLeftJoin = Array.isArray(prepared.leftJoins) && prepared.leftJoins.length > 0;
+        const whereFiltered = addDefaultStateFilter(prepared.where, prepared.tableQualifier, hasLeftJoin, this.beflyMode);
         const countResult = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as total");
         const total = countResult.total;
 
@@ -100,8 +100,8 @@ export const dataOpsMethods = {
         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, this.beflyMode);
+        const hasLeftJoin = Array.isArray(prepared.leftJoins) && prepared.leftJoins.length > 0;
+        const whereFiltered = addDefaultStateFilter(prepared.where, prepared.tableQualifier, hasLeftJoin, this.beflyMode);
         const countResult = await this.fetchCount(prepared, whereFiltered, "COUNT(*) as total");
         const total = countResult.total;
 
@@ -146,7 +146,7 @@ export const dataOpsMethods = {
     },
 
     async exists(options) {
-        validateNoJoinReadOptions(options, "exists", "exists 不支持 joins（请使用显式 query 或拆分查询）");
+        validateNoLeftJoinReadOptions(options, "exists", "exists 不支持 leftJoin（请使用显式 query 或拆分查询）");
         const snakeTable = snakeCase(options.table);
         const snakeWhere = whereKeysToSnake(clearDeep(options.where || {}));
         const whereFiltered = addDefaultStateFilter(snakeWhere, snakeTable, false, this.beflyMode);
@@ -159,7 +159,7 @@ export const dataOpsMethods = {
     },
 
     async getFieldValue(options) {
-        validateNoJoinReadOptions(options, "getFieldValue", "getFieldValue 不支持 joins（请使用 getOne/getList 并自行取字段）");
+        validateNoLeftJoinReadOptions(options, "getFieldValue", "getFieldValue 不支持 leftJoin（请使用 getOne/getList 并自行取字段）");
         const field = options.field;
         validateSafeFieldName(field);
 
@@ -167,7 +167,7 @@ export const dataOpsMethods = {
             table: options.table
         };
         if (options.where !== undefined) oneOptions.where = options.where;
-        if (options.joins !== undefined) oneOptions.joins = options.joins;
+        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;

package/lib/dbHelper/execute.js

@@ -2,6 +2,56 @@ import { toSqlParams } from "../sqlBuilder/util.js";
 import { snakeCase } from "../../utils/util.js";
 import { validateExecuteSql } from "./validate.js";
 
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    } catch {
+        try {
+            return String(value);
+        } catch {
+            return "[Unserializable]";
+        }
+    }
+}
+
+function getExecuteErrorMessage(error) {
+    if (error instanceof Error && typeof error.message === "string" && error.message.trim().length > 0) {
+        return error.message.trim();
+    }
+
+    if (!error || typeof error !== "object") {
+        return String(error);
+    }
+
+    const message = typeof error.message === "string" && error.message.trim().length > 0 ? error.message.trim() : typeof error.sqlMessage === "string" && error.sqlMessage.trim().length > 0 ? error.sqlMessage.trim() : "";
+    const detail = {};
+
+    if (typeof error.code === "string" && error.code.trim().length > 0) {
+        detail.code = error.code;
+    }
+    if (typeof error.errno === "number") {
+        detail.errno = error.errno;
+    }
+    if (typeof error.sqlState === "string" && error.sqlState.trim().length > 0) {
+        detail.sqlState = error.sqlState;
+    }
+    if (typeof error.sqlMessage === "string" && error.sqlMessage.trim().length > 0) {
+        detail.sqlMessage = error.sqlMessage;
+    }
+    if (typeof error.detail === "string" && error.detail.trim().length > 0) {
+        detail.detail = error.detail;
+    }
+
+    const detailText = Object.keys(detail).length > 0 ? safeStringify(detail) : safeStringify(error);
+    if (message && detailText && detailText !== "{}") {
+        return `${message} | ${detailText}`;
+    }
+    if (message) {
+        return message;
+    }
+    return detailText;
+}
+
 export const executeMethods = {
     async execute(sql, params) {
         if (!this.sql) {
@@ -44,21 +94,24 @@ export const executeMethods = {
             };
         } catch (error) {
             const duration = Date.now() - startTime;
-            const msg = error instanceof Error ? error.message : String(error);
-
-            throw new Error(`SQL执行失败: ${msg}`, {
-                cause: error,
-                code: "runtime",
-                subsystem: "sql",
-                operation: "execute",
+            const msg = getExecuteErrorMessage(error);
+            const sqlInfo = {
+                sql: sql,
                 params: safeParams,
-                duration: duration,
-                sqlInfo: {
-                    sql: sql,
-                    params: safeParams,
-                    duration: duration
-                }
+                duration: duration
+            };
+            const wrappedError = new Error(`SQL执行失败: ${msg}`, {
+                cause: error
             });
+
+            wrappedError.code = "runtime";
+            wrappedError.subsystem = "sql";
+            wrappedError.operation = "execute";
+            wrappedError.params = safeParams;
+            wrappedError.duration = duration;
+            wrappedError.sqlInfo = sqlInfo;
+
+            throw wrappedError;
         }
     },
 

package/lib/dbHelper/validate.js

@@ -130,34 +130,58 @@ function validateOrderByItems(orderBy, label) {
     }
 }
 
-function validateJoins(joins, label) {
-    if (!Array.isArray(joins)) {
+function validateLeftJoinItems(leftJoin, label) {
+    if (!Array.isArray(leftJoin)) {
         throw new Error(`${label} 必须是数组`, {
             cause: null,
             code: "validation"
         });
     }
 
-    for (let i = 0; i < joins.length; i++) {
-        const join = joins[i];
-        if (!isPlainObject(join)) {
-            throw new Error(`${label}[${i}] 必须是对象`, {
+    for (let i = 0; i < leftJoin.length; i++) {
+        const joinItem = leftJoin[i];
+        if (!isNonEmptyString(joinItem)) {
+            throw new Error(`${label}[${i}] 必须是非空字符串`, {
                 cause: null,
                 code: "validation"
             });
         }
 
-        assertNonEmptyString(join.table, `${label}[${i}].table`);
-        assertNonEmptyString(join.on, `${label}[${i}].on`);
+        const parts = joinItem.split(/\s+ON\s+/i);
+        if (parts.length !== 2) {
+            throw new Error(`${label}[${i}] 必须是 "table alias ON left.field = right.field" 格式`, {
+                cause: null,
+                code: "validation"
+            });
+        }
 
-        if (!isNullable(join.type)) {
-            const type = isString(join.type) ? join.type.trim().toLowerCase() : "";
-            if (type !== "left" && type !== "right" && type !== "inner") {
-                throw new Error(`${label}[${i}].type 只允许 left/right/inner`, {
-                    cause: null,
-                    code: "validation"
-                });
-            }
+        const tableRef = parts[0]?.trim();
+        const on = parts[1]?.trim();
+        if (!isNonEmptyString(tableRef)) {
+            throw new Error(`${label}[${i}] 缺少 leftJoin 表名`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (!isNonEmptyString(on)) {
+            throw new Error(`${label}[${i}] 缺少 leftJoin 的 ON 条件`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        parseTableRef(tableRef);
+    }
+}
+
+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"
+            });
         }
     }
 }
@@ -187,8 +211,10 @@ export function validateQueryOptions(options, label) {
         validateOrderByItems(options.orderBy, `${label}.orderBy`);
     }
 
-    if (!isNullable(options.joins)) {
-        validateJoins(options.joins, `${label}.joins`);
+    validateLegacyJoinOptions(options, label);
+
+    if (!isNullable(options.leftJoin)) {
+        validateLeftJoinItems(options.leftJoin, `${label}.leftJoin`);
     }
 
     if (!isNullable(options.page) && (!isFiniteNumber(options.page) || Math.floor(options.page) !== options.page)) {
@@ -247,9 +273,10 @@ export function validateTableBatchDataOptions(table, dataList, label) {
     validateBatchDataList(dataList, `${label}.dataList`);
 }
 
-export function validateNoJoinReadOptions(options, label, joinErrorMessage) {
+export function validateNoLeftJoinReadOptions(options, label, joinErrorMessage) {
     validateTableWhereOptions(options, label, false);
-    validateNoJoins(options.joins, joinErrorMessage);
+    validateNoLeftJoin(options.leftJoin, joinErrorMessage);
+    validateLegacyJoinOptions(options, label);
     validateSimpleTableName(options.table, label);
 }
 
@@ -306,8 +333,8 @@ export function validatePageLimitRange(prepared, rawTable) {
     }
 }
 
-export function validateNoJoins(joins, message) {
-    if (Array.isArray(joins) && joins.length > 0) {
+export function validateNoLeftJoin(leftJoin, message) {
+    if (Array.isArray(leftJoin) && leftJoin.length > 0) {
         throw new Error(message, {
             cause: null,
             code: "validation"

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.20.5",
-    "gitHead": "523163fa281ad94542dda8e88551360c4cb8b200",
+    "version": "3.20.7",
+    "gitHead": "a337be6c93cbf8a8e70bf6ac32eeb30c57fba3a3",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",
     "keywords": [
@@ -52,7 +52,7 @@
         "test": "bun test"
     },
     "dependencies": {
-        "fast-xml-parser": "^5.5.5",
+        "fast-xml-parser": "^5.5.8",
         "nodemailer": "^8.0.2",
         "pathe": "^2.0.3",
         "ua-parser-js": "^2.0.9",

package/utils/loggerUtils.js

@@ -41,11 +41,28 @@ function sanitizeErrorValue(err, options) {
         name: err.name || "Error",
         message: truncateString(err.message || "", options.maxStringLen)
     };
+    const state = { nodes: 0 };
+    const visited = new WeakSet();
+
+    visited.add(err);
 
     if (isString(err.stack)) {
         out["stack"] = truncateString(err.stack, options.maxStringLen);
     }
 
+    if (!isNullable(err.cause)) {
+        out["cause"] = sanitizeAny(err.cause, options, state, 0, visited);
+    }
+
+    const ownKeys = Object.keys(err);
+    for (const key of ownKeys) {
+        if (key === "name" || key === "message" || key === "stack" || key === "cause") {
+            continue;
+        }
+
+        out[key] = sanitizeAny(err[key], options, state, 0, visited);
+    }
+
     return out;
 }