befly 3.20.8 → 3.20.9

package/lib/sqlBuilder/parser.js

@@ -1,4 +1,3 @@
-import { SqlErrors } from "./errors.js";
 import { validateParam } from "./util.js";
 import { isNonEmptyString, isString } from "../../utils/is.js";
 
@@ -19,7 +18,7 @@ export function appendSelectItems(list, fields) {
         return;
     }
 
-    throw new Error(SqlErrors.SELECT_FIELDS_INVALID, {
+    throw new Error("SELECT 字段必须是字符串或数组", {
         cause: null,
         code: "validation"
     });
@@ -27,7 +26,7 @@ export function appendSelectItems(list, fields) {
 
 export function appendSelectRaw(list, expr) {
     if (!isNonEmptyString(expr)) {
-        throw new Error(SqlErrors.SELECT_RAW_NEED_NON_EMPTY(expr), {
+        throw new Error(`selectRaw 需要非空字符串 (expr: ${String(expr)})`, {
             cause: null,
             code: "validation"
         });
@@ -37,7 +36,7 @@ export function appendSelectRaw(list, expr) {
 
 export function setFromValue(state, table, isRaw) {
     if (!isNonEmptyString(table)) {
-        const err = isRaw ? SqlErrors.FROM_RAW_NEED_NON_EMPTY(table) : SqlErrors.FROM_NEED_NON_EMPTY(table);
+        const err = isRaw ? `fromRaw 需要非空字符串 (tableExpr: ${String(table)})` : `FROM 表名必须是非空字符串 (table: ${String(table)})`;
         throw new Error(err, {
             cause: null,
             code: "validation"
@@ -49,7 +48,7 @@ export function setFromValue(state, table, isRaw) {
 
 export function appendJoinItem(list, joinType, table, on) {
     if (!isString(table) || !isString(on)) {
-        throw new Error(SqlErrors.JOIN_NEED_STRING(table, on), {
+        throw new Error(`JOIN 表名和条件必须是字符串 (table: ${String(table)}, on: ${String(on)})`, {
             cause: null,
             code: "validation"
         });
@@ -60,7 +59,7 @@ export function appendJoinItem(list, joinType, table, on) {
 
 export function appendOrderByItems(list, fields) {
     if (!Array.isArray(fields)) {
-        throw new Error(SqlErrors.ORDER_BY_NEED_ARRAY, {
+        throw new Error('orderBy 必须是字符串数组，格式为 "字段#方向"', {
             cause: null,
             code: "validation"
         });
@@ -68,7 +67,7 @@ export function appendOrderByItems(list, fields) {
 
     for (const item of fields) {
         if (!isString(item) || !item.includes("#")) {
-            throw new Error(SqlErrors.ORDER_BY_ITEM_NEED_HASH(item), {
+            throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${String(item)})`, {
                 cause: null,
                 code: "validation"
             });
@@ -76,7 +75,7 @@ export function appendOrderByItems(list, fields) {
 
         const parts = item.split("#");
         if (parts.length !== 2) {
-            throw new Error(SqlErrors.ORDER_BY_ITEM_NEED_HASH(item), {
+            throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${String(item)})`, {
                 cause: null,
                 code: "validation"
             });
@@ -88,14 +87,14 @@ export function appendOrderByItems(list, fields) {
         const cleanDir = direction.trim().toUpperCase();
 
         if (!cleanField) {
-            throw new Error(SqlErrors.ORDER_BY_FIELD_EMPTY(item), {
+            throw new Error(`orderBy 中字段名不能为空 (item: ${item})`, {
                 cause: null,
                 code: "validation"
             });
         }
 
         if (!["ASC", "DESC"].includes(cleanDir)) {
-            throw new Error(SqlErrors.ORDER_BY_DIR_INVALID(cleanDir), {
+            throw new Error(`ORDER BY 方向必须是 ASC 或 DESC (direction: ${cleanDir})`, {
                 cause: null,
                 code: "validation"
             });
@@ -107,30 +106,24 @@ export function appendOrderByItems(list, fields) {
 
 export function appendWhereInput(root, conditionOrField, value) {
     if (conditionOrField && typeof conditionOrField === "object" && !Array.isArray(conditionOrField)) {
-        const node = parseWhereObject(conditionOrField);
-        if (node && node.items.length > 0) {
-            root.items.push(node);
-        }
+        appendWhereObject(root, conditionOrField);
         return;
     }
 
     if (isString(conditionOrField)) {
         if (value === undefined) {
-            throw new Error(SqlErrors.WHERE_VALUE_REQUIRED, {
+            throw new Error("where(field, value) 不允许省略 value。若需传入原始 WHERE，请使用 whereRaw", {
                 cause: null,
                 code: "validation"
             });
         }
-        const node = buildOperatorNode(conditionOrField, "=", value);
-        if (node) {
-            root.items.push(node);
-        }
+        appendWhereNode(root, buildOperatorNode(conditionOrField, "=", value));
     }
 }
 
 export function appendWhereRaw(root, sql, params) {
     if (!isNonEmptyString(sql)) {
-        throw new Error(SqlErrors.WHERE_RAW_NEED_NON_EMPTY(sql), {
+        throw new Error(`whereRaw 需要非空字符串 (sql: ${String(sql)})`, {
             cause: null,
             code: "validation"
         });
@@ -144,6 +137,19 @@ export function appendWhereRaw(root, sql, params) {
     root.items.push({ type: "raw", sql: sql, params: paramList });
 }
 
+function appendWhereNode(root, node) {
+    if (node) {
+        root.items.push(node);
+    }
+}
+
+function appendWhereObject(root, whereObj) {
+    const node = parseWhereObject(whereObj);
+    if (node.items.length > 0) {
+        root.items.push(node);
+    }
+}
+
 function parseWhereObject(whereObj) {
     if (!whereObj || typeof whereObj !== "object") {
         return { type: "group", join: "AND", items: [] };
@@ -157,117 +163,130 @@ function parseWhereObject(whereObj) {
         }
 
         if (key === "$and") {
-            if (Array.isArray(value)) {
-                for (const condition of value) {
-                    if (condition && typeof condition === "object" && !Array.isArray(condition)) {
-                        const sub = parseWhereObject(condition);
-                        if (sub.items.length > 0) {
-                            if (sub.join === "AND") {
-                                for (const item of sub.items) {
-                                    group.items.push(item);
-                                }
-                            } else {
-                                group.items.push(sub);
-                            }
-                        }
-                    }
-                }
-            }
+            appendAndConditions(group, value);
             continue;
         }
 
         if (key === "$or") {
-            if (Array.isArray(value)) {
-                const orGroup = { type: "group", join: "OR", items: [] };
-                for (const condition of value) {
-                    if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
-                        continue;
-                    }
-                    const sub = parseWhereObject(condition);
-                    if (sub.items.length > 0) {
-                        orGroup.items.push(sub);
-                    }
-                }
-                if (orGroup.items.length > 0) {
-                    group.items.push(orGroup);
-                }
-            }
+            appendOrConditions(group, value);
             continue;
         }
 
-        if (key.includes("$")) {
-            const lastDollarIndex = key.lastIndexOf("$");
-            const fieldName = key.substring(0, lastDollarIndex);
-            const operator = "$" + key.substring(lastDollarIndex + 1);
-            const node = buildOperatorNode(fieldName, operator, value);
-            if (node) {
-                group.items.push(node);
-            }
+        appendFieldCondition(group, key, value);
+    }
+
+    return group;
+}
+
+function appendAndConditions(group, value) {
+    if (!Array.isArray(value)) {
+        return;
+    }
+
+    for (const condition of value) {
+        if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
             continue;
         }
 
-        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-            for (const [op, val] of Object.entries(value)) {
-                const node = buildOperatorNode(key, op, val);
-                if (node) {
-                    group.items.push(node);
-                }
+        const sub = parseWhereObject(condition);
+        if (sub.items.length === 0) {
+            continue;
+        }
+
+        if (sub.join === "AND") {
+            for (const item of sub.items) {
+                group.items.push(item);
             }
             continue;
         }
 
-        const node = buildOperatorNode(key, "=", value);
-        if (node) {
-            group.items.push(node);
+        group.items.push(sub);
+    }
+}
+
+function appendOrConditions(group, value) {
+    if (!Array.isArray(value)) {
+        return;
+    }
+
+    const orGroup = { type: "group", join: "OR", items: [] };
+    for (const condition of value) {
+        if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+            continue;
+        }
+
+        const sub = parseWhereObject(condition);
+        if (sub.items.length > 0) {
+            orGroup.items.push(sub);
         }
     }
 
-    return group;
+    if (orGroup.items.length > 0) {
+        group.items.push(orGroup);
+    }
+}
+
+function appendFieldCondition(group, key, value) {
+    if (key.includes("$")) {
+        const lastDollarIndex = key.lastIndexOf("$");
+        appendWhereNode(group, buildOperatorNode(key.substring(0, lastDollarIndex), `$${key.substring(lastDollarIndex + 1)}`, value));
+        return;
+    }
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        for (const [operator, operatorValue] of Object.entries(value)) {
+            appendWhereNode(group, buildOperatorNode(key, operator, operatorValue));
+        }
+        return;
+    }
+
+    appendWhereNode(group, buildOperatorNode(key, "=", value));
+}
+
+function buildArrayOperatorNode(fieldName, operator, value, errorFactory, emptyMessage) {
+    if (!Array.isArray(value)) {
+        throw new Error(errorFactory(operator), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (value.length === 0) {
+        throw new Error(emptyMessage, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return { type: "op", field: fieldName, operator: operator, value: value };
+}
+
+function buildRangeOrNullOperatorNode(fieldName, operator, value) {
+    if (operator === "$between" || operator === "$notBetween") {
+        if (Array.isArray(value) && value.length === 2) {
+            return { type: "op", field: fieldName, operator: operator, value: value };
+        }
+        return null;
+    }
+
+    if (value === true) {
+        return { type: "op", field: fieldName, operator: operator, value: value };
+    }
+
+    return null;
 }
 
 function buildOperatorNode(fieldName, operator, value) {
     switch (operator) {
         case "$in":
-            if (!Array.isArray(value)) {
-                throw new Error(SqlErrors.IN_NEED_ARRAY(operator), {
-                    cause: null,
-                    code: "validation"
-                });
-            }
-            if (value.length === 0) {
-                throw new Error(SqlErrors.IN_NEED_NON_EMPTY, {
-                    cause: null,
-                    code: "validation"
-                });
-            }
-            return { type: "op", field: fieldName, operator: operator, value: value };
+            return buildArrayOperatorNode(fieldName, operator, value, (currentOperator) => `$in 操作符的值必须是数组 (operator: ${currentOperator})`, "$in 操作符的数组不能为空。提示：空数组会导致查询永远不匹配任何记录，这通常不是预期行为。请检查查询条件或移除该字段。");
         case "$nin":
         case "$notIn":
-            if (!Array.isArray(value)) {
-                throw new Error(SqlErrors.NIN_NEED_ARRAY(operator), {
-                    cause: null,
-                    code: "validation"
-                });
-            }
-            if (value.length === 0) {
-                throw new Error(SqlErrors.NIN_NEED_NON_EMPTY, {
-                    cause: null,
-                    code: "validation"
-                });
-            }
-            return { type: "op", field: fieldName, operator: operator, value: value };
+            return buildArrayOperatorNode(fieldName, operator, value, (currentOperator) => `$nin/$notIn 操作符的值必须是数组 (operator: ${currentOperator})`, "$nin/$notIn 操作符的数组不能为空。提示：空数组会导致查询匹配所有记录，这通常不是预期行为。请检查查询条件或移除该字段。");
         case "$between":
         case "$notBetween":
-            if (Array.isArray(value) && value.length === 2) {
-                return { type: "op", field: fieldName, operator: operator, value: value };
-            }
-            return null;
         case "$null":
         case "$notNull":
-            if (value === true) {
-                return { type: "op", field: fieldName, operator: operator, value: value };
-            }
-            return null;
+            return buildRangeOrNullOperatorNode(fieldName, operator, value);
         case "$like":
         case "like":
         case "$leftLike":

package/lib/sqlBuilder/util.js

@@ -1,6 +1,46 @@
 import { isNullable, isString } from "../../utils/is.js";
 import { SqlCheck } from "./check.js";
-import { SqlErrors } from "./errors.js";
+
+function isQuotedIdentPaired(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 2) {
+        return false;
+    }
+
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    return (first === "`" && last === "`") || (first === '"' && last === '"');
+}
+
+function startsWithIdentifierQuote(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith("`") || trimmed.startsWith('"');
+}
+
+function assertPairedQuotedIdent(value, label) {
+    if (startsWithIdentifierQuote(value) && !isQuotedIdentPaired(value)) {
+        throw new Error(`${label} 引用不完整，请使用成对的 \`...\` 或 "..." (value: ${value})`, {
+            cause: null,
+            code: "validation"
+        });
+    }
+}
+
+function escapeIdentifierPart(part, kind, quoteIdent, unpairedErrorFactory) {
+    if (isQuotedIdent(part)) {
+        return part;
+    }
+
+    if (startsWithQuote(part)) {
+        throw new Error(unpairedErrorFactory(part), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    SqlCheck.assertSafeIdentifierPart(part, kind);
+    return quoteIdent(part);
+}
 
 export function resolveQuoteIdent(options) {
     if (options && options.quoteIdent) {
@@ -9,7 +49,7 @@ export function resolveQuoteIdent(options) {
 
     return (identifier) => {
         if (!isString(identifier)) {
-            throw new Error(SqlErrors.QUOTE_IDENT_NEED_STRING(identifier), {
+            throw new Error(`quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`, {
                 cause: null,
                 code: "validation"
             });
@@ -17,7 +57,7 @@ export function resolveQuoteIdent(options) {
 
         const trimmed = identifier.trim();
         if (!trimmed) {
-            throw new Error(SqlErrors.IDENT_EMPTY, {
+            throw new Error("SQL 标识符不能为空", {
                 cause: null,
                 code: "validation"
             });
@@ -29,11 +69,11 @@ export function resolveQuoteIdent(options) {
 }
 
 export function isQuotedIdent(value) {
-    return SqlCheck.isQuotedIdentPaired(value);
+    return isQuotedIdentPaired(value);
 }
 
 export function startsWithQuote(value) {
-    return SqlCheck.startsWithQuote(value);
+    return startsWithIdentifierQuote(value);
 }
 
 export function escapeField(field, quoteIdent) {
@@ -43,7 +83,7 @@ export function escapeField(field, quoteIdent) {
 
     const trimmed = field.trim();
 
-    SqlCheck.assertPairedQuotedIdentIfStartsWithQuote(trimmed, "字段标识符");
+    assertPairedQuotedIdent(trimmed, "字段标识符");
 
     if (trimmed === "*" || isQuotedIdent(trimmed)) {
         return trimmed;
@@ -52,7 +92,7 @@ export function escapeField(field, quoteIdent) {
     try {
         SqlCheck.assertNoExprField(trimmed);
     } catch {
-        throw new Error(SqlErrors.FIELD_EXPR_NOT_ALLOWED(trimmed), {
+        throw new Error(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`, {
             cause: null,
             code: "validation"
         });
@@ -61,7 +101,7 @@ export function escapeField(field, quoteIdent) {
     if (trimmed.toUpperCase().includes(" AS ")) {
         const parts = trimmed.split(/\s+AS\s+/i);
         if (parts.length !== 2) {
-            throw new Error(SqlErrors.FIELD_INVALID(trimmed), {
+            throw new Error(`字段格式非法，请使用简单字段名或安全引用，复杂表达式请使用 selectRaw/whereRaw (field: ${trimmed})`, {
                 cause: null,
                 code: "validation"
             });
@@ -71,7 +111,14 @@ export function escapeField(field, quoteIdent) {
         const aliasPart = parts[1];
         const cleanFieldPart = fieldPart.trim();
         const cleanAliasPart = aliasPart.trim();
-        SqlCheck.assertSafeAlias(cleanAliasPart);
+        if (!isQuotedIdent(cleanAliasPart)) {
+            if (!SqlCheck.SAFE_IDENTIFIER_RE.test(cleanAliasPart)) {
+                throw new Error(`无效的字段别名: ${cleanAliasPart}`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+        }
         return `${escapeField(cleanFieldPart, quoteIdent)} AS ${cleanAliasPart}`;
     }
 
@@ -83,7 +130,7 @@ export function escapeField(field, quoteIdent) {
                 if (cleanPart === "*" || isQuotedIdent(cleanPart)) {
                     return cleanPart;
                 }
-                SqlCheck.assertPairedQuotedIdentIfStartsWithQuote(cleanPart, "字段标识符");
+                assertPairedQuotedIdent(cleanPart, "字段标识符");
                 return quoteIdent(cleanPart);
             })
             .join(".");
@@ -105,14 +152,14 @@ export function escapeTable(table, quoteIdent) {
 
     const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
     if (parts.length === 0) {
-        throw new Error(SqlErrors.FROM_EMPTY, {
+        throw new Error("FROM 表名不能为空", {
             cause: null,
             code: "validation"
         });
     }
 
     if (parts.length > 2) {
-        throw new Error(SqlErrors.TABLE_REF_TOO_MANY_PARTS(trimmed), {
+        throw new Error(`不支持的表引用格式（包含过多片段）。请使用 fromRaw 显式传入复杂表达式 (table: ${trimmed})`, {
             cause: null,
             code: "validation"
         });
@@ -124,7 +171,7 @@ export function escapeTable(table, quoteIdent) {
 
     const nameSegments = namePart.split(".");
     if (nameSegments.length > 2) {
-        throw new Error(SqlErrors.TABLE_REF_SCHEMA_TOO_DEEP(trimmed), {
+        throw new Error(`不支持的表引用格式（schema 层级过深）。请使用 fromRaw (table: ${trimmed})`, {
             cause: null,
             code: "validation"
         });
@@ -137,49 +184,15 @@ export function escapeTable(table, quoteIdent) {
         const schema = schemaRaw.trim();
         const tableName = tableNameRaw.trim();
 
-        const escapedSchema = isQuotedIdent(schema)
-            ? schema
-            : (() => {
-                  if (startsWithQuote(schema) && !isQuotedIdent(schema)) {
-                      throw new Error(SqlErrors.SCHEMA_QUOTE_NOT_PAIRED(schema), {
-                          cause: null,
-                          code: "validation"
-                      });
-                  }
-                  SqlCheck.assertSafeIdentifierPart(schema, "schema");
-                  return quoteIdent(schema);
-              })();
-
-        const escapedTableName = isQuotedIdent(tableName)
-            ? tableName
-            : (() => {
-                  if (startsWithQuote(tableName) && !isQuotedIdent(tableName)) {
-                      throw new Error(SqlErrors.TABLE_QUOTE_NOT_PAIRED(tableName), {
-                          cause: null,
-                          code: "validation"
-                      });
-                  }
-                  SqlCheck.assertSafeIdentifierPart(tableName, "table");
-                  return quoteIdent(tableName);
-              })();
+        const escapedSchema = escapeIdentifierPart(schema, "schema", quoteIdent, (part) => `schema 标识符引用不完整，请使用成对的 \`...\` 或 "..." (schema: ${part})`);
+        const escapedTableName = escapeIdentifierPart(tableName, "table", quoteIdent, (part) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${part})`);
 
         escapedName = `${escapedSchema}.${escapedTableName}`;
     } else {
         const tableNameRaw = nameSegments[0];
         const tableName = tableNameRaw.trim();
 
-        if (isQuotedIdent(tableName)) {
-            escapedName = tableName;
-        } else {
-            if (startsWithQuote(tableName) && !isQuotedIdent(tableName)) {
-                throw new Error(SqlErrors.TABLE_QUOTE_NOT_PAIRED(tableName), {
-                    cause: null,
-                    code: "validation"
-                });
-            }
-            SqlCheck.assertSafeIdentifierPart(tableName, "table");
-            escapedName = quoteIdent(tableName);
-        }
+        escapedName = escapeIdentifierPart(tableName, "table", quoteIdent, (part) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${part})`);
     }
 
     if (aliasPart) {
@@ -196,7 +209,7 @@ export function validateParam(value) {
 
 export function normalizeLimitValue(count, offset) {
     if (typeof count !== "number" || count < 0) {
-        throw new Error(SqlErrors.LIMIT_MUST_NON_NEGATIVE(count), {
+        throw new Error(`LIMIT 数量必须是非负数 (count: ${String(count)})`, {
             cause: null,
             code: "validation"
         });
@@ -206,7 +219,7 @@ export function normalizeLimitValue(count, offset) {
     let offsetValue = null;
     if (!isNullable(offset)) {
         if (typeof offset !== "number" || offset < 0) {
-            throw new Error(SqlErrors.OFFSET_MUST_NON_NEGATIVE(offset), {
+            throw new Error(`OFFSET 必须是非负数 (offset: ${String(offset)})`, {
                 cause: null,
                 code: "validation"
             });
@@ -219,7 +232,7 @@ export function normalizeLimitValue(count, offset) {
 
 export function normalizeOffsetValue(count) {
     if (typeof count !== "number" || count < 0) {
-        throw new Error(SqlErrors.OFFSET_COUNT_MUST_NON_NEGATIVE(count), {
+        throw new Error(`OFFSET 必须是非负数 (count: ${String(count)})`, {
             cause: null,
             code: "validation"
         });

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "befly",
-    "version": "3.20.8",
-    "gitHead": "c5906450b26c4f674094344de80a750c5f753736",
+    "version": "3.20.9",
+    "gitHead": "c6107d7e5006ffeba25cedef95ae0c7a5d294673",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",
     "keywords": [

package/lib/cacheKeys.js

@@ -1,42 +0,0 @@
-/**
- * Cache Key 统一管理
- * 所有缓存键在此统一定义，避免硬编码分散
- */
-
-/**
- * Cache Key 生成函数集合
- */
-export class CacheKeys {
-    /** 所有接口缓存2 */
-    static apisAll() {
-        return "apis:all";
-    }
-
-    /** 所有菜单缓存 */
-    static menusAll() {
-        return "menus:all";
-    }
-
-    /** 角色信息缓存（完整角色对象） */
-    static roleInfo(roleCode) {
-        return `role:info:${roleCode}`;
-    }
-
-    /**
-     * 角色菜单权限缓存（Set 集合）
-     * - key: role:menus:${roleCode}
-     * - member: menu.path（例如 /permission/role）
-     */
-    static roleMenus(roleCode) {
-        return `role:menus:${roleCode}`;
-    }
-
-    /**
-     * 角色接口权限缓存（Set 集合）
-     * - key: role:apis:${roleCode}
-     * - member: url.pathname（例如 /api/user/login；与 method 无关）
-     */
-    static roleApis(roleCode) {
-        return `role:apis:${roleCode}`;
-    }
-}