befly 3.17.0 → 3.17.2

package/lib/sqlBuilder/batch.js

@@ -0,0 +1,113 @@
+import { SqlErrors } from "./errors.js";
+import { isNonEmptyString } from "../../utils/is.js";
+import { SqlCheck } from "./check.js";
+
+export function toDeleteInSql(options) {
+    if (!isNonEmptyString(options.table)) {
+        throw new Error(SqlErrors.TO_DELETE_IN_NEED_TABLE(options.table), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (!isNonEmptyString(options.idField)) {
+        throw new Error(SqlErrors.TO_DELETE_IN_NEED_ID_FIELD(options.idField), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (!Array.isArray(options.ids)) {
+        throw new Error(SqlErrors.TO_DELETE_IN_NEED_IDS, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (options.ids.length === 0) {
+        return { sql: "", params: [] };
+    }
+
+    const placeholders = options.ids.map(() => "?").join(",");
+    const sql = `DELETE FROM ${options.quoteIdent(options.table)} WHERE ${options.quoteIdent(options.idField)} IN (${placeholders})`;
+    const params = [];
+    for (const id of options.ids) {
+        params.push(id);
+    }
+    return { sql: sql, params: params };
+}
+
+export function toUpdateCaseByIdSql(options) {
+    if (!isNonEmptyString(options.table)) {
+        throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_TABLE(options.table), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (!isNonEmptyString(options.idField)) {
+        throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_ID_FIELD(options.idField), {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (!Array.isArray(options.rows)) {
+        throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_ROWS, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (options.rows.length === 0) {
+        return { sql: "", params: [] };
+    }
+    if (!Array.isArray(options.fields)) {
+        throw new Error(SqlErrors.TO_UPDATE_CASE_NEED_FIELDS, {
+            cause: null,
+            code: "validation"
+        });
+    }
+    if (options.fields.length === 0) {
+        return { sql: "", params: [] };
+    }
+
+    const ids = options.rows.map((row) => row.id);
+    const placeholders = ids.map(() => "?").join(",");
+
+    const setSqlList = [];
+    const args = [];
+
+    const quotedId = options.quoteIdent(options.idField);
+
+    for (const field of options.fields) {
+        const whenList = [];
+
+        for (const row of options.rows) {
+            if (!(field in row.data)) {
+                continue;
+            }
+
+            whenList.push("WHEN ? THEN ?");
+            args.push(row.id);
+            const value = row.data[field];
+            SqlCheck.assertNoUndefinedParam(value, "SQL 参数值");
+            args.push(value);
+        }
+
+        if (whenList.length === 0) {
+            continue;
+        }
+
+        const quotedField = options.quoteIdent(field);
+        setSqlList.push(`${quotedField} = CASE ${quotedId} ${whenList.join(" ")} ELSE ${quotedField} END`);
+    }
+
+    setSqlList.push(`${options.quoteIdent(options.updatedAtField)} = ?`);
+    args.push(options.updatedAtValue);
+
+    for (const id of ids) {
+        args.push(id);
+    }
+
+    let sql = `UPDATE ${options.quoteIdent(options.table)} SET ${setSqlList.join(", ")} WHERE ${quotedId} IN (${placeholders})`;
+    if (options.stateGtZero && options.stateField) {
+        sql += ` AND ${options.quoteIdent(options.stateField)} > 0`;
+    }
+
+    return { sql: sql, params: args };
+}

package/lib/sqlBuilder/check.js

@@ -0,0 +1,150 @@
+import { isMinLengthString, isNonEmptyString } from "../../utils/is.js";
+
+export class SqlCheck {
+    static assertNoUndefinedParam(value, label) {
+        if (value === undefined) {
+            throw new Error(`${label} 不能为 undefined`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+
+    static startsWithQuote(value) {
+        const trimmed = value.trim();
+        return trimmed.startsWith("`") || trimmed.startsWith('"');
+    }
+
+    static isQuotedIdentPaired(value) {
+        const trimmed = value.trim();
+        if (!isMinLengthString(trimmed, 2)) {
+            return false;
+        }
+        const first = trimmed[0];
+        const last = trimmed[trimmed.length - 1];
+        if (first === "`" && last === "`") {
+            return true;
+        }
+        if (first === '"' && last === '"') {
+            return true;
+        }
+        return false;
+    }
+
+    static assertPairedQuotedIdentIfStartsWithQuote(value, label) {
+        if (SqlCheck.startsWithQuote(value) && !SqlCheck.isQuotedIdentPaired(value)) {
+            throw new Error(`${label} 引用不完整，请使用成对的 \`...\` 或 "..." (value: ${value})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+
+    static assertSafeIdentifierPart(part, kind) {
+        if (!SqlCheck.SAFE_IDENTIFIER_RE.test(part)) {
+            throw new Error(`无效的 ${kind} 标识符: ${part}`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+
+    static assertSafeAlias(aliasPart) {
+        if (SqlCheck.isQuotedIdentPaired(aliasPart)) {
+            return;
+        }
+        if (!SqlCheck.SAFE_IDENTIFIER_RE.test(aliasPart)) {
+            throw new Error(`无效的字段别名: ${aliasPart}`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+
+    static assertNoExprField(field) {
+        if (!isNonEmptyString(field)) {
+            return;
+        }
+        const trimmed = field.trim();
+        if (trimmed.includes("(") || trimmed.includes(")")) {
+            throw new Error(`字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${trimmed})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+    }
+
+    static assertBatchInsertRowsConsistent(rows, options) {
+        if (!Array.isArray(rows)) {
+            throw new Error("批量插入 rows 必须是数组", {
+                cause: null,
+                code: "validation"
+            });
+        }
+        if (rows.length === 0) {
+            throw new Error(`插入数据不能为空 (table: ${options.table})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const first = rows[0];
+        if (!first || typeof first !== "object" || Array.isArray(first)) {
+            throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: 0)`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const fields = Object.keys(first);
+        if (fields.length === 0) {
+            throw new Error(`插入数据必须至少有一个字段 (table: ${options.table})`, {
+                cause: null,
+                code: "validation"
+            });
+        }
+
+        const fieldSet = new Set(fields);
+
+        for (let i = 0; i < rows.length; i++) {
+            const row = rows[i];
+            if (!row || typeof row !== "object" || Array.isArray(row)) {
+                throw new Error(`批量插入的每一行必须是对象 (table: ${options.table}, rowIndex: ${i})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            const rowKeys = Object.keys(row);
+            if (rowKeys.length !== fields.length) {
+                throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i})`, {
+                    cause: null,
+                    code: "validation"
+                });
+            }
+
+            for (const key of rowKeys) {
+                if (!fieldSet.has(key)) {
+                    throw new Error(`批量插入每行字段必须一致 (table: ${options.table}, rowIndex: ${i}, extraField: ${key})`, {
+                        cause: null,
+                        code: "validation"
+                    });
+                }
+            }
+
+            for (const field of fields) {
+                if (!(field in row)) {
+                    throw new Error(`批量插入缺少字段 (table: ${options.table}, rowIndex: ${i}, field: ${field})`, {
+                        cause: null,
+                        code: "validation"
+                    });
+                }
+                SqlCheck.assertNoUndefinedParam(row[field], `批量插入字段值 (table: ${options.table}, rowIndex: ${i}, field: ${field})`);
+            }
+        }
+
+        return fields;
+    }
+}
+
+SqlCheck.SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;

package/lib/sqlBuilder/compiler.js

@@ -0,0 +1,347 @@
+import { SqlCheck } from "./check.js";
+import { SqlErrors } from "./errors.js";
+import { escapeField, escapeTable, validateParam } from "./util.js";
+import { isString } from "../../utils/is.js";
+
+export function compileSelect(model, quoteIdent) {
+    let sql = "SELECT ";
+    const params = [];
+
+    if (model.select.length > 0) {
+        const fields = model.select.map((item) => {
+            if (item.type === "raw") {
+                return item.value;
+            }
+            return escapeField(item.value, quoteIdent);
+        });
+        sql += fields.join(", ");
+    } else {
+        sql += "*";
+    }
+
+    if (!model.from) {
+        throw new Error(SqlErrors.FROM_REQUIRED, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const fromSql = model.from.type === "raw" ? model.from.value : escapeTable(model.from.value, quoteIdent);
+    sql += ` FROM ${fromSql}`;
+
+    if (model.joins.length > 0) {
+        const joinSql = model.joins
+            .map((join) => {
+                const joinTable = escapeTable(join.table, quoteIdent);
+                const joinType = join.type.toUpperCase();
+                return `${joinType} JOIN ${joinTable} ON ${join.on}`;
+            })
+            .join(" ");
+        sql += ` ${joinSql}`;
+    }
+
+    const whereResult = compileWhere(model.where, quoteIdent);
+    if (whereResult.sql) {
+        sql += ` WHERE ${whereResult.sql}`;
+        for (const param of whereResult.params) {
+            params.push(param);
+        }
+    }
+
+    if (model.groupBy.length > 0) {
+        const groupSql = model.groupBy.map((field) => escapeField(field, quoteIdent)).join(", ");
+        sql += ` GROUP BY ${groupSql}`;
+    }
+
+    if (model.having.length > 0) {
+        sql += ` HAVING ${model.having.join(" AND ")}`;
+    }
+
+    if (model.orderBy.length > 0) {
+        const orderSql = model.orderBy
+            .map((item) => {
+                const escapedField = escapeField(item.field, quoteIdent);
+                return `${escapedField} ${item.dir}`;
+            })
+            .join(", ");
+        sql += ` ORDER BY ${orderSql}`;
+    }
+
+    if (model.limit !== null) {
+        sql += ` LIMIT ${model.limit}`;
+        if (model.offset !== null) {
+            sql += ` OFFSET ${model.offset}`;
+        }
+    }
+
+    return { sql: sql, params: params };
+}
+
+export function compileCount(model, quoteIdent) {
+    let sql = "SELECT COUNT(*) as total";
+    const params = [];
+
+    if (!model.from) {
+        throw new Error(SqlErrors.COUNT_NEED_FROM, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const fromSql = model.from.type === "raw" ? model.from.value : escapeTable(model.from.value, quoteIdent);
+    sql += ` FROM ${fromSql}`;
+
+    if (model.joins.length > 0) {
+        const joinSql = model.joins
+            .map((join) => {
+                const joinTable = escapeTable(join.table, quoteIdent);
+                const joinType = join.type.toUpperCase();
+                return `${joinType} JOIN ${joinTable} ON ${join.on}`;
+            })
+            .join(" ");
+        sql += ` ${joinSql}`;
+    }
+
+    const whereResult = compileWhere(model.where, quoteIdent);
+    if (whereResult.sql) {
+        sql += ` WHERE ${whereResult.sql}`;
+        for (const param of whereResult.params) {
+            params.push(param);
+        }
+    }
+
+    return { sql: sql, params: params };
+}
+
+export function compileInsert(table, data, quoteIdent) {
+    if (!table || !isString(table)) {
+        throw new Error(SqlErrors.INSERT_NEED_TABLE(table), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!data || typeof data !== "object") {
+        throw new Error(SqlErrors.INSERT_NEED_DATA(table, data), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const escapedTable = escapeTable(table, quoteIdent);
+
+    if (Array.isArray(data)) {
+        const fields = SqlCheck.assertBatchInsertRowsConsistent(data, { table: table });
+
+        const escapedFields = fields.map((field) => escapeField(field, quoteIdent));
+        const placeholders = fields.map(() => "?").join(", ");
+        const values = data.map(() => `(${placeholders})`).join(", ");
+
+        const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES ${values}`;
+        const params = [];
+        for (let i = 0; i < data.length; i++) {
+            const row = data[i];
+            for (const field of fields) {
+                const value = row[field];
+                validateParam(value);
+                params.push(value);
+            }
+        }
+
+        return { sql: sql, params: params };
+    }
+
+    const fields = Object.keys(data);
+    if (fields.length === 0) {
+        throw new Error(SqlErrors.INSERT_NEED_AT_LEAST_ONE_FIELD(table), {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    for (const field of fields) {
+        validateParam(data[field]);
+    }
+
+    const escapedFields = fields.map((field) => escapeField(field, quoteIdent));
+    const placeholders = fields.map(() => "?").join(", ");
+    const sql = `INSERT INTO ${escapedTable} (${escapedFields.join(", ")}) VALUES (${placeholders})`;
+    const params = [];
+    for (const field of fields) {
+        params.push(data[field]);
+    }
+
+    return { sql: sql, params: params };
+}
+
+export function compileUpdate(model, table, data, quoteIdent) {
+    if (!table || !isString(table)) {
+        throw new Error(SqlErrors.UPDATE_NEED_TABLE, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new Error(SqlErrors.UPDATE_NEED_OBJECT, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const fields = Object.keys(data);
+    if (fields.length === 0) {
+        throw new Error(SqlErrors.UPDATE_NEED_AT_LEAST_ONE_FIELD, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const escapedTable = escapeTable(table, quoteIdent);
+    const setFields = fields.map((field) => `${escapeField(field, quoteIdent)} = ?`);
+    const params = [];
+    for (const value of Object.values(data)) {
+        params.push(value);
+    }
+
+    let sql = `UPDATE ${escapedTable} SET ${setFields.join(", ")}`;
+
+    const whereResult = compileWhere(model.where, quoteIdent);
+    if (whereResult.sql) {
+        sql += ` WHERE ${whereResult.sql}`;
+        for (const param of whereResult.params) {
+            params.push(param);
+        }
+    } else {
+        throw new Error(SqlErrors.UPDATE_NEED_WHERE, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return { sql: sql, params: params };
+}
+
+export function compileDelete(model, table, quoteIdent) {
+    if (!table || !isString(table)) {
+        throw new Error(SqlErrors.DELETE_NEED_TABLE, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    const escapedTable = escapeTable(table, quoteIdent);
+    let sql = `DELETE FROM ${escapedTable}`;
+
+    const whereResult = compileWhere(model.where, quoteIdent);
+    if (whereResult.sql) {
+        sql += ` WHERE ${whereResult.sql}`;
+    } else {
+        throw new Error(SqlErrors.DELETE_NEED_WHERE, {
+            cause: null,
+            code: "validation"
+        });
+    }
+
+    return { sql: sql, params: whereResult.params };
+}
+
+export function compileWhere(node, quoteIdent) {
+    if (!node) {
+        return { sql: "", params: [] };
+    }
+
+    if (node.type === "raw") {
+        const params = Array.isArray(node.params) ? node.params.slice() : [];
+        return { sql: node.sql, params: params };
+    }
+
+    if (node.type === "op") {
+        return compileOperatorNode(node, quoteIdent);
+    }
+
+    if (node.type === "group") {
+        if (!node.items || node.items.length === 0) {
+            return { sql: "", params: [] };
+        }
+        const parts = [];
+        const params = [];
+        for (const item of node.items) {
+            const built = compileWhere(item, quoteIdent);
+            if (!built.sql) {
+                continue;
+            }
+            let clause = built.sql;
+            if (node.join === "OR") {
+                clause = `(${clause})`;
+            } else if (item.type === "group" && item.join === "OR") {
+                clause = `(${clause})`;
+            }
+            parts.push(clause);
+            for (const param of built.params) {
+                params.push(param);
+            }
+        }
+        return { sql: parts.join(` ${node.join} `), params: params };
+    }
+
+    return { sql: "", params: [] };
+}
+
+function compileOperatorNode(node, quoteIdent) {
+    const escapedField = escapeField(node.field, quoteIdent);
+    const operator = node.operator;
+
+    switch (operator) {
+        case "$ne":
+        case "$not":
+            validateParam(node.value);
+            return { sql: `${escapedField} != ?`, params: [node.value] };
+        case "$in": {
+            const placeholders = node.value.map(() => "?").join(",");
+            const params = [];
+            for (const item of node.value) {
+                params.push(item);
+            }
+            return { sql: `${escapedField} IN (${placeholders})`, params: params };
+        }
+        case "$nin":
+        case "$notIn": {
+            const placeholders = node.value.map(() => "?").join(",");
+            const params = [];
+            for (const item of node.value) {
+                params.push(item);
+            }
+            return { sql: `${escapedField} NOT IN (${placeholders})`, params: params };
+        }
+        case "$like":
+            validateParam(node.value);
+            return { sql: `${escapedField} LIKE ?`, params: [node.value] };
+        case "$notLike":
+            validateParam(node.value);
+            return { sql: `${escapedField} NOT LIKE ?`, params: [node.value] };
+        case "$gt":
+            validateParam(node.value);
+            return { sql: `${escapedField} > ?`, params: [node.value] };
+        case "$gte":
+            validateParam(node.value);
+            return { sql: `${escapedField} >= ?`, params: [node.value] };
+        case "$lt":
+            validateParam(node.value);
+            return { sql: `${escapedField} < ?`, params: [node.value] };
+        case "$lte":
+            validateParam(node.value);
+            return { sql: `${escapedField} <= ?`, params: [node.value] };
+        case "$between":
+            return { sql: `${escapedField} BETWEEN ? AND ?`, params: [node.value[0], node.value[1]] };
+        case "$notBetween":
+            return { sql: `${escapedField} NOT BETWEEN ? AND ?`, params: [node.value[0], node.value[1]] };
+        case "$null":
+            return { sql: `${escapedField} IS NULL`, params: [] };
+        case "$notNull":
+            return { sql: `${escapedField} IS NOT NULL`, params: [] };
+        default:
+            validateParam(node.value);
+            return { sql: `${escapedField} = ?`, params: [node.value] };
+    }
+}

package/lib/sqlBuilder/errors.js

@@ -0,0 +1,60 @@
+export const SqlErrors = {
+    QUOTE_IDENT_NEED_STRING: (identifier) => `quoteIdent 需要字符串类型标识符 (identifier: ${String(identifier)})`,
+    IDENT_EMPTY: "SQL 标识符不能为空",
+
+    FIELD_EXPR_NOT_ALLOWED: (field) => `字段包含函数/表达式，请使用 selectRaw/whereRaw (field: ${field})`,
+    FIELD_INVALID: (field) => `字段格式非法，请使用简单字段名或安全引用，复杂表达式请使用 selectRaw/whereRaw (field: ${field})`,
+
+    FROM_EMPTY: "FROM 表名不能为空",
+    FROM_NEED_NON_EMPTY: (table) => `FROM 表名必须是非空字符串 (table: ${String(table)})`,
+    FROM_REQUIRED: "FROM 表名是必需的",
+    COUNT_NEED_FROM: "COUNT 需要 FROM 表名",
+
+    TABLE_REF_TOO_MANY_PARTS: (table) => `不支持的表引用格式（包含过多片段）。请使用 fromRaw 显式传入复杂表达式 (table: ${table})`,
+    TABLE_REF_SCHEMA_TOO_DEEP: (table) => `不支持的表引用格式（schema 层级过深）。请使用 fromRaw (table: ${table})`,
+    SCHEMA_QUOTE_NOT_PAIRED: (schema) => `schema 标识符引用不完整，请使用成对的 \`...\` 或 "..." (schema: ${schema})`,
+    TABLE_QUOTE_NOT_PAIRED: (tableName) => `table 标识符引用不完整，请使用成对的 \`...\` 或 "..." (table: ${tableName})`,
+
+    SELECT_FIELDS_INVALID: "SELECT 字段必须是字符串或数组",
+    SELECT_RAW_NEED_NON_EMPTY: (expr) => `selectRaw 需要非空字符串 (expr: ${String(expr)})`,
+    FROM_RAW_NEED_NON_EMPTY: (tableExpr) => `fromRaw 需要非空字符串 (tableExpr: ${String(tableExpr)})`,
+    WHERE_RAW_NEED_NON_EMPTY: (sql) => `whereRaw 需要非空字符串 (sql: ${String(sql)})`,
+    WHERE_VALUE_REQUIRED: "where(field, value) 不允许省略 value。若需传入原始 WHERE，请使用 whereRaw",
+
+    JOIN_NEED_STRING: (table, on) => `JOIN 表名和条件必须是字符串 (table: ${String(table)}, on: ${String(on)})`,
+
+    ORDER_BY_NEED_ARRAY: 'orderBy 必须是字符串数组，格式为 "字段#方向"',
+    ORDER_BY_ITEM_NEED_HASH: (item) => `orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${String(item)})`,
+    ORDER_BY_FIELD_EMPTY: (item) => `orderBy 中字段名不能为空 (item: ${item})`,
+    ORDER_BY_DIR_INVALID: (direction) => `ORDER BY 方向必须是 ASC 或 DESC (direction: ${direction})`,
+
+    LIMIT_MUST_NON_NEGATIVE: (count) => `LIMIT 数量必须是非负数 (count: ${String(count)})`,
+    OFFSET_MUST_NON_NEGATIVE: (offset) => `OFFSET 必须是非负数 (offset: ${String(offset)})`,
+    OFFSET_COUNT_MUST_NON_NEGATIVE: (count) => `OFFSET 必须是非负数 (count: ${String(count)})`,
+
+    INSERT_NEED_TABLE: (table) => `INSERT 需要表名 (table: ${String(table)})`,
+    INSERT_NEED_DATA: (table, data) => `INSERT 需要数据 (table: ${String(table)}, data: ${JSON.stringify(data)})`,
+    INSERT_NEED_AT_LEAST_ONE_FIELD: (table) => `插入数据必须至少有一个字段 (table: ${table})`,
+
+    UPDATE_NEED_TABLE: "UPDATE 需要表名",
+    UPDATE_NEED_OBJECT: "UPDATE 需要数据对象",
+    UPDATE_NEED_AT_LEAST_ONE_FIELD: "更新数据必须至少有一个字段",
+    UPDATE_NEED_WHERE: "为安全起见，UPDATE 需要 WHERE 条件",
+
+    DELETE_NEED_TABLE: "DELETE 需要表名",
+    DELETE_NEED_WHERE: "为安全起见，DELETE 需要 WHERE 条件",
+
+    TO_DELETE_IN_NEED_TABLE: (table) => `toDeleteInSql 需要非空表名 (table: ${String(table)})`,
+    TO_DELETE_IN_NEED_ID_FIELD: (idField) => `toDeleteInSql 需要非空 idField (idField: ${String(idField)})`,
+    TO_DELETE_IN_NEED_IDS: "toDeleteInSql 需要 ids 数组",
+
+    TO_UPDATE_CASE_NEED_TABLE: (table) => `toUpdateCaseByIdSql 需要非空表名 (table: ${String(table)})`,
+    TO_UPDATE_CASE_NEED_ID_FIELD: (idField) => `toUpdateCaseByIdSql 需要非空 idField (idField: ${String(idField)})`,
+    TO_UPDATE_CASE_NEED_ROWS: "toUpdateCaseByIdSql 需要 rows 数组",
+    TO_UPDATE_CASE_NEED_FIELDS: "toUpdateCaseByIdSql 需要 fields 数组",
+
+    IN_NEED_ARRAY: (operator) => `$in 操作符的值必须是数组 (operator: ${operator})`,
+    IN_NEED_NON_EMPTY: "$in 操作符的数组不能为空。提示：空数组会导致查询永远不匹配任何记录，这通常不是预期行为。请检查查询条件或移除该字段。",
+    NIN_NEED_ARRAY: (operator) => `$nin/$notIn 操作符的值必须是数组 (operator: ${operator})`,
+    NIN_NEED_NON_EMPTY: "$nin/$notIn 操作符的数组不能为空。提示：空数组会导致查询匹配所有记录，这通常不是预期行为。请检查查询条件或移除该字段。"
+};