befly 3.72.0 → 3.74.0

package/lib/validator.js

@@ -1,368 +1,272 @@
-/**
- * 数据验证器 - Befly 项目专用
- * 纯静态类设计，简洁易用
- */
-
 import { FIELD_RULE_DEFAULT_MAX, FIELD_RULE_DEFAULT_MIN, FIELD_RULE_INPUT_TYPES } from "../configs/constConfig.js";
 import RegexAliases from "../configs/regexpAlias.json";
-import { isFiniteNumber, isIntegerNumber, isJsonObject, isJsonPrimitive, isJsonStructure, isNullable, isNumber, isPlainObject, isRegexInput, isString } from "../utils/is.js";
+import { configSchema } from "../schemas/config.js";
+import { isFiniteNumber, isIntegerNumber, isJsonPrimitive, isNoTrimStringAllowEmpty, isNullable, isPlainObject, isRegexInput, isString, isValidTimeZone } from "../utils/is.js";
 import { getCompiledRegex } from "../utils/regexpUtil.js";
 
 const INPUT_TYPE_SET = new Set(FIELD_RULE_INPUT_TYPES);
-const RULE_ALLOWED_KEYS = new Set(["input", "check", "name", "min", "max", "detail"]);
-
-/**
- * 递归校验 JSON 结构叶子节点是否满足数值规则。
- */
-function checkJsonLeaves(value, rule) {
-    if (isJsonPrimitive(value)) {
-        if (rule === "number") return isFiniteNumber(value);
-        return isIntegerNumber(value);
-    }
+const FIELD_RULE_KEYS = new Set(["input", "check", "name", "min", "max", "detail"]);
+
+function addIssue(issues, path, message) {
+    issues.push({ path: Array.isArray(path) ? path : [path], message: message });
+}
+
+function isJsonScalar(value) {
+    return isJsonPrimitive(value) && (typeof value !== "number" || Number.isFinite(value));
+}
 
+function isScalarArray(value) {
+    return Array.isArray(value) && value.every((item) => isJsonScalar(item));
+}
+
+function isFlatJson(value, kind = "any") {
     if (Array.isArray(value)) {
-        for (const item of value) {
-            if (!checkJsonLeaves(item, rule)) return false;
-        }
-        return true;
+        return value.every((item) => isJsonScalar(item) && (kind === "any" || (kind === "number" ? isFiniteNumber(item) : isIntegerNumber(item))));
     }
 
-    if (isJsonObject(value)) {
-        for (const v of Object.values(value)) {
-            if (v === undefined) continue;
-            if (!checkJsonLeaves(v, rule)) return false;
-        }
-        return true;
+    if (!isPlainObject(value)) {
+        return false;
     }
 
-    return false;
+    return Object.values(value).every((item) => isJsonScalar(item) && (kind === "any" || (kind === "number" ? isFiniteNumber(item) : isIntegerNumber(item))));
 }
 
-function convertStringNumber(value, error, integer = false) {
-    if (!isString(value)) {
-        return { value: null, error: error };
+function toNumber(value, integer = false) {
+    if (isFiniteNumber(value) && (!integer || isIntegerNumber(value))) {
+        return { value: value, error: null };
     }
 
-    const normalized = value.trim();
-    if (normalized.length === 0) {
-        return { value: null, error: error };
+    if (!isString(value) || value.trim().length === 0) {
+        return { value: null, error: integer ? "必须是整数" : "必须是数字" };
     }
 
-    const num = Number(normalized);
-    if (!Number.isFinite(num)) {
-        return { value: null, error: error };
+    const number = Number(value.trim());
+    if (!Number.isFinite(number) || (integer && !Number.isInteger(number))) {
+        return { value: null, error: integer ? "必须是整数" : "必须是数字" };
     }
 
-    if (integer && !Number.isInteger(num)) {
-        return { value: null, error: error };
-    }
-
-    return { value: num, error: null };
+    return { value: number, error: null };
 }
 
-/**
- * 验证器类
- */
-export class Validator {
-    /**
-     * 验证数据对象
-     */
-    static validate(data, rules, required = []) {
-        const fieldErrors = {};
-
-        // 参数检查
-        if (!isPlainObject(data)) {
-            return this.buildResult({ rootError: "数据必须是对象格式" });
-        }
-        if (!isPlainObject(rules)) {
-            return this.buildResult({ rootError: "验证规则必须是对象格式" });
-        }
-
-        // 检查必填字段
-        for (const field of required) {
-            const value = data[field];
-            if (isNullable(value)) {
-                const rawRule = rules[field];
-                const label = isPlainObject(rawRule) && isString(rawRule["name"]) ? rawRule["name"] : field;
-                fieldErrors[field] = `${label}为必填项`;
-            }
-        }
-
-        // 验证有值的字段
-        for (const [field, rawRule] of Object.entries(rules)) {
-            if (fieldErrors[field]) continue;
-            // 字段值为 undefined 时跳过验证（除非是必填字段，但必填字段已在上面检查过）
-            if (isNullable(data[field]) && !required.includes(field)) continue;
-
-            if (!isPlainObject(rawRule)) {
-                fieldErrors[field] = `${field}验证规则必须是对象格式`;
-                continue;
-            }
-
-            const invalidKeys = [];
-            for (const key of Object.keys(rawRule)) {
-                if (!RULE_ALLOWED_KEYS.has(key)) {
-                    invalidKeys.push(key);
-                }
-            }
-            if (invalidKeys.length > 0) {
-                fieldErrors[field] = `${field}存在非法属性: ${invalidKeys.join(",")}`;
-                continue;
-            }
-
-            const ruleName = rawRule["name"];
-            const ruleInput = rawRule["input"];
-            if (!isString(ruleName) || !isString(ruleInput)) {
-                fieldErrors[field] = `${field}验证规则无效`;
-                continue;
-            }
-
-            if (!INPUT_TYPE_SET.has(ruleInput)) {
-                fieldErrors[field] = `${field}input 不支持: ${ruleInput}`;
-                continue;
-            }
-
-            const rule = {
-                name: ruleName,
-                input: ruleInput
-            };
+function getEnumValues(check, numeric = false, integer = false) {
+    if (!isString(check) || check.length === 0) {
+        return null;
+    }
 
-            const check = rawRule["check"];
-            if (isString(check)) rule.check = check;
+    const values = check
+        .split("|")
+        .map((item) => item.trim())
+        .filter(Boolean);
 
-            const detail = rawRule["detail"];
-            if (isString(detail)) rule.detail = detail;
+    if (values.length === 0) {
+        return null;
+    }
 
-            const min = rawRule["min"];
-            if (isNumber(min) || min === null) rule.min = min;
+    if (!numeric) {
+        return values;
+    }
 
-            const max = rawRule["max"];
-            if (isNumber(max) || max === null) rule.max = max;
+    const numbers = values.map(Number);
+    if (numbers.some((value) => !Number.isFinite(value) || (integer && !Number.isInteger(value)))) {
+        return null;
+    }
 
-            const error = this.checkField(data[field], rule, field);
-            if (error) fieldErrors[field] = error;
-        }
+    return numbers;
+}
 
-        return this.buildResult(fieldErrors);
+function checkFieldValue(value, rule) {
+    const min = isFiniteNumber(rule.min) ? rule.min : FIELD_RULE_DEFAULT_MIN;
+    const max = isFiniteNumber(rule.max) ? rule.max : FIELD_RULE_DEFAULT_MAX;
+    const input = rule.input;
+    let converted = value;
+
+    if (input === "number" || input === "integer" || input === "enumNumber" || input === "enumInteger") {
+        const parsed = toNumber(value, input === "integer" || input === "enumInteger");
+        if (parsed.error) return parsed.error;
+        converted = parsed.value;
+    } else if (input === "string" || input === "char" || input === "regexp" || input === "enum") {
+        if (!isString(value)) return "必须是字符串";
+    } else if (input === "array" || input === "arrayNumber" || input === "arrayInteger") {
+        if (!isScalarArray(value)) return "必须是仅包含基础值的一层数组";
+        if (input === "arrayNumber" && !value.every(isFiniteNumber)) return "数组元素必须是数字";
+        if (input === "arrayInteger" && !value.every(isIntegerNumber)) return "数组元素必须是整数";
+    } else if (input === "json" || input === "jsonNumber" || input === "jsonInteger") {
+        const kind = input === "json" ? "any" : input === "jsonNumber" ? "number" : "integer";
+        if (!isFlatJson(value, kind)) return kind === "any" ? "必须是一层JSON对象或数组，成员只能是基础值" : `JSON值必须是${kind === "number" ? "数字" : "整数"}`;
     }
 
-    /**
-     * 验证单个值（带类型转换）
-     */
-    static single(value, fieldDef) {
-        if (!isString(fieldDef.input) || !INPUT_TYPE_SET.has(fieldDef.input)) {
-            const input = isString(fieldDef.input) ? fieldDef.input : "";
-            return { value: null, error: `input 不支持: ${input}` };
-        }
-
-        // 处理空值
-        if (isNullable(value, [""])) {
-            return { value: value, error: null };
-        }
+    if (input === "number" || input === "integer") {
+        if (converted < min) return `不能小于${min}`;
+        if (converted > max) return `不能大于${max}`;
+    }
 
-        // 类型转换
-        const converted = this.convert(value, fieldDef.input);
-        if (converted.error) {
-            return { value: null, error: converted.error };
+    if (input === "string" || input === "char" || input === "regexp" || input === "enum") {
+        if (input === "char" && converted.length !== 1) return "必须是单字符";
+        if (converted.length < min) return `长度不能少于${min}个字符`;
+        if (converted.length > max) return `长度不能超过${max}个字符`;
+
+        if (input === "regexp") {
+            if (!isRegexInput(rule.check)) return "check 规则无效";
+            const pattern = rule.check.startsWith("@") ? RegexAliases[rule.check.slice(1)] || rule.check : rule.check;
+            try {
+                if (!getCompiledRegex(pattern).test(converted)) return "格式不正确";
+            } catch {
+                return "check 规则无效";
+            }
         }
 
-        // 规则验证
-        const error = this.checkRule(converted.value, fieldDef);
-        if (error) {
-            return { value: null, error: error };
+        if (input === "enum") {
+            const values = getEnumValues(rule.check);
+            if (!values) return "check 规则无效";
+            if (!values.includes(converted)) return "值不在枚举范围内";
         }
-
-        return { value: converted.value, error: null };
     }
 
-    // ========== 私有方法 ==========
-
-    /** 构建结果对象 */
-    static buildResult(fieldErrors) {
-        const errors = Object.values(fieldErrors);
-        const errorFields = Object.keys(fieldErrors);
-        const failed = errors.length > 0;
-
-        return {
-            code: failed ? 1 : 0,
-            failed: failed,
-            firstError: failed ? (errors[0] ?? null) : null,
-            errors: errors,
-            errorFields: errorFields,
-            fieldErrors: fieldErrors
-        };
+    if (input === "enumNumber" || input === "enumInteger") {
+        const values = getEnumValues(rule.check, true, input === "enumInteger");
+        if (!values) return "check 规则无效";
+        if (!values.includes(converted)) return "值不在枚举范围内";
     }
 
-    /** 验证单个字段 */
-    static checkField(value, fieldDef, fieldName) {
-        const label = fieldDef.name || fieldName;
-        const converted = this.convert(value, fieldDef.input);
-        if (converted.error) {
-            return `${label}${converted.error}`;
-        }
-
-        const error = this.checkRule(converted.value, fieldDef);
-        return error ? `${label}${error}` : null;
+    if (input === "array" || input === "arrayNumber" || input === "arrayInteger") {
+        if (value.length < min) return `至少需要${min}个元素`;
+        if (value.length > max) return `最多只能有${max}个元素`;
     }
 
-    /** 类型转换 */
-    static convert(value, input) {
-        switch (input) {
-            case "number": {
-                if (isFiniteNumber(value)) return { value: value, error: null };
-                return convertStringNumber(value, "必须是数字");
-            }
-
-            case "integer": {
-                if (isIntegerNumber(value)) return { value: value, error: null };
-                return convertStringNumber(value, "必须是整数", true);
-            }
-
-            case "string": {
-                return isString(value) ? { value: value, error: null } : { value: null, error: "必须是字符串" };
-            }
+    return null;
+}
 
-            case "char":
-                if (!isString(value)) return { value: null, error: "必须是字符串" };
-                return value.length === 1 ? { value: value, error: null } : { value: null, error: "必须是单字符" };
+function buildFieldResult(fieldErrors) {
+    const errors = Object.values(fieldErrors);
+    const errorFields = Object.keys(fieldErrors);
+    const failed = errors.length > 0;
+
+    return {
+        code: failed ? 1 : 0,
+        failed: failed,
+        firstError: failed ? errors[0] : null,
+        errors: errors,
+        errorFields: errorFields,
+        fieldErrors: fieldErrors
+    };
+}
 
-            case "array":
-                return Array.isArray(value) ? { value: value, error: null } : { value: null, error: "必须是数组" };
+export function validateFieldRule(rule) {
+    const issues = [];
+    if (!isPlainObject(rule)) {
+        addIssue(issues, [], "验证规则必须是对象格式");
+        return issues;
+    }
 
-            case "arrayNumber": {
-                if (!Array.isArray(value)) return { value: null, error: "必须是数组" };
-                for (const item of value) {
-                    if (!isFiniteNumber(item)) return { value: null, error: "数组元素必须是数字" };
-                }
-                return { value: value, error: null };
-            }
+    for (const key of Object.keys(rule)) {
+        if (!FIELD_RULE_KEYS.has(key)) addIssue(issues, [key], "不允许出现");
+    }
 
-            case "arrayInteger": {
-                if (!Array.isArray(value)) return { value: null, error: "必须是数组" };
-                for (const item of value) {
-                    if (!isIntegerNumber(item)) return { value: null, error: "数组元素必须是整数" };
-                }
-                return { value: value, error: null };
-            }
+    if (!isString(rule.name) || rule.name.length === 0 || !isNoTrimStringAllowEmpty(rule.name)) addIssue(issues, ["name"], "必须是非空且无首尾空格的字符串");
+    if (!isString(rule.input) || !INPUT_TYPE_SET.has(rule.input)) addIssue(issues, ["input"], "不支持该类型");
+    if (rule.check !== undefined && (!isString(rule.check) || !isNoTrimStringAllowEmpty(rule.check))) addIssue(issues, ["check"], "必须是无首尾空格的字符串");
+    if (rule.detail !== undefined && !isString(rule.detail)) addIssue(issues, ["detail"], "必须是字符串");
+    if (rule.min !== undefined && rule.min !== null && !isFiniteNumber(rule.min)) addIssue(issues, ["min"], "必须是有限数字或 null");
+    if (rule.max !== undefined && rule.max !== null && !isFiniteNumber(rule.max)) addIssue(issues, ["max"], "必须是有限数字或 null");
 
-            case "json":
-                if (!isJsonStructure(value)) return { value: null, error: "必须是JSON对象或数组" };
-                return { value: value, error: null };
+    if (issues.length > 0) return issues;
 
-            case "jsonNumber":
-                if (!isJsonStructure(value)) return { value: null, error: "必须是JSON对象或数组" };
-                return checkJsonLeaves(value, "number") ? { value: value, error: null } : { value: null, error: "JSON值必须是数字" };
+    const min = rule.min === null || rule.min === undefined ? FIELD_RULE_DEFAULT_MIN : rule.min;
+    const max = rule.max === null || rule.max === undefined ? FIELD_RULE_DEFAULT_MAX : rule.max;
+    if (min > max) addIssue(issues, ["min"], "不能大于 max");
 
-            case "jsonInteger":
-                if (!isJsonStructure(value)) return { value: null, error: "必须是JSON对象或数组" };
-                return checkJsonLeaves(value, "integer") ? { value: value, error: null } : { value: null, error: "JSON值必须是整数" };
+    if (["regexp", "enum", "enumNumber", "enumInteger"].includes(rule.input) && !rule.check) {
+        addIssue(issues, ["check"], `${rule.input} 必须提供 check`);
+    }
+    if (rule.input === "regexp" && rule.check && !isRegexInput(rule.check)) addIssue(issues, ["check"], "regexp.check 必须是正则字面量或 @ 别名");
+    if (["enum", "enumNumber", "enumInteger"].includes(rule.input) && rule.check && !getEnumValues(rule.check, rule.input !== "enum", rule.input === "enumInteger")) {
+        addIssue(issues, ["check"], `${rule.input}.check 必须是非空枚举值列表`);
+    }
 
-            case "regexp":
-            case "enum":
-                return isString(value) ? { value: value, error: null } : { value: null, error: "必须是字符串" };
+    return issues;
+}
 
-            case "enumNumber": {
-                if (isFiniteNumber(value)) return { value: value, error: null };
-                return convertStringNumber(value, "必须是数字");
-            }
+export function validateFields(data, fields, required = []) {
+    const fieldErrors = {};
+    if (!isPlainObject(data)) return buildFieldResult({ rootError: "数据必须是对象格式" });
+    if (!isPlainObject(fields)) return buildFieldResult({ rootError: "验证规则必须是对象格式" });
 
-            case "enumInteger": {
-                if (isIntegerNumber(value)) return { value: value, error: null };
-                return convertStringNumber(value, "必须是整数", true);
-            }
-
-            default: {
-                return { value: value, error: null };
-            }
+    for (const field of required) {
+        if (isNullable(data[field])) {
+            fieldErrors[field] = `${isPlainObject(fields[field]) && isString(fields[field].name) ? fields[field].name : field}为必填项`;
         }
     }
 
-    /** 规则验证 */
-    static checkRule(value, fieldDef) {
-        const min = isNumber(fieldDef.min) ? fieldDef.min : FIELD_RULE_DEFAULT_MIN;
-        const max = isNumber(fieldDef.max) ? fieldDef.max : FIELD_RULE_DEFAULT_MAX;
+    for (const [field, rule] of Object.entries(fields)) {
+        if (fieldErrors[field] || (isNullable(data[field]) && !required.includes(field))) continue;
+        const error = checkFieldValue(data[field], rule);
+        if (error) fieldErrors[field] = `${rule.name}${error}`;
+    }
 
-        if (!isString(fieldDef.input)) {
-            return "input 不支持";
-        }
+    return buildFieldResult(fieldErrors);
+}
 
-        if (fieldDef.input === "number" || fieldDef.input === "integer") {
-            if (typeof value !== "number") return fieldDef.input === "integer" ? "必须是整数" : "必须是数字";
-            if (value < min) return `不能小于${min}`;
-            if (value > max) return `不能大于${max}`;
-        } else if (fieldDef.input === "string" || fieldDef.input === "char" || fieldDef.input === "regexp" || fieldDef.input === "enum") {
-            if (!isString(value)) return "必须是字符串";
-            if (fieldDef.input === "char" && value.length !== 1) return "必须是单字符";
-            if (value.length < min) return `长度不能少于${min}个字符`;
-            if (value.length > max) return `长度不能超过${max}个字符`;
-
-            if (fieldDef.input === "regexp") {
-                if (!isString(fieldDef.check) || fieldDef.check.length === 0) return "缺少 check 规则";
-                if (!isRegexInput(fieldDef.check)) return "check 规则无效";
-                const regex = this.resolveRegex(fieldDef.check);
-                if (!this.testRegex(regex, value)) return "格式不正确";
-            }
+function addUnknownKeys(issues, value, allowedKeys, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key)) addIssue(issues, [...path, key], "不允许出现");
+    }
+}
 
-            if (fieldDef.input === "enum") {
-                if (!isString(fieldDef.check) || fieldDef.check.length === 0) return "缺少 check 规则";
-                const enums = fieldDef.check
-                    .split("|")
-                    .map((x) => x.trim())
-                    .filter((x) => x !== "");
-                if (enums.length === 0) return "check 规则无效";
-                if (!enums.includes(value)) return "值不在枚举范围内";
-            }
-        } else if (fieldDef.input === "enumNumber" || fieldDef.input === "enumInteger") {
-            if (typeof value !== "number") return fieldDef.input === "enumInteger" ? "必须是整数" : "必须是数字";
-            if (!isString(fieldDef.check) || fieldDef.check.length === 0) return "缺少 check 规则";
-
-            const enumValues = [];
-            for (const item of fieldDef.check.split("|")) {
-                const normalized = item.trim();
-                if (normalized.length === 0) {
-                    continue;
-                }
-
-                const num = Number(normalized);
-                if (!Number.isFinite(num)) {
-                    return "check 规则无效";
-                }
-
-                if (fieldDef.input === "enumInteger" && !Number.isInteger(num)) {
-                    return "check 规则无效";
-                }
-
-                enumValues.push(num);
-            }
+function isConfigCheckValid(value, check) {
+    if (check === "emailOrEmpty") return value === "" || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+    if (check === "timeZone") return isValidTimeZone(value);
+    if (check === "redisPrefix") return !value.includes(":");
+    return false;
+}
 
-            if (enumValues.length === 0) return "check 规则无效";
-            if (!enumValues.includes(value)) return "值不在枚举范围内";
-        } else if (fieldDef.input === "array" || fieldDef.input === "arrayNumber" || fieldDef.input === "arrayInteger") {
-            if (!Array.isArray(value)) return "必须是数组";
-            if (value.length < min) return `至少需要${min}个元素`;
-            if (value.length > max) return `最多只能有${max}个元素`;
-        } else if (fieldDef.input === "json" || fieldDef.input === "jsonNumber" || fieldDef.input === "jsonInteger") {
-            if (!isJsonStructure(value)) return "必须是JSON对象或数组";
-        }
+function checkConfigLeaf(issues, value, def, path) {
+    if (value === undefined) {
+        if (!def.optional) addIssue(issues, path, "为必填项");
+        return;
+    }
 
-        return null;
+    if (def.type === "string") {
+        if (!isString(value)) addIssue(issues, path, "必须是字符串");
+        else if (def.noTrim && !isNoTrimStringAllowEmpty(value)) addIssue(issues, path, "不允许首尾空格");
+        else if (def.min !== undefined && value.length < def.min) addIssue(issues, path, `长度不能少于${def.min}个字符`);
+    } else if (def.type === "number") {
+        if (!isFiniteNumber(value)) addIssue(issues, path, "必须是有限数字");
+        else if (def.integer && !isIntegerNumber(value)) addIssue(issues, path, "必须是整数");
+        else if (def.min !== undefined && value < def.min) addIssue(issues, path, `不能小于${def.min}`);
+        else if (def.max !== undefined && value > def.max) addIssue(issues, path, `不能大于${def.max}`);
+    } else if (def.type === "boolInt") {
+        if (![0, 1, true, false].includes(value)) addIssue(issues, path, "仅允许 0|1|true|false");
+    } else if (def.type === "values") {
+        if (!def.values.includes(value)) addIssue(issues, path, `仅允许 ${def.values.join("|")}`);
+    } else if (def.type === "stringArray") {
+        if (!Array.isArray(value) || !value.every((item) => isString(item) && (!def.noTrim || isNoTrimStringAllowEmpty(item)))) addIssue(issues, path, "必须是仅包含无首尾空格字符串的一层数组");
     }
 
-    /** 解析正则别名 */
-    static resolveRegex(pattern) {
-        if (pattern.startsWith("@")) {
-            const key = pattern.substring(1);
-            return RegexAliases[key] || pattern;
-        }
-        return pattern;
+    if (def.pattern && isString(value) && !def.pattern.test(value)) addIssue(issues, path, "格式不正确");
+    if (def.check && isString(value) && !isConfigCheckValid(value, def.check)) addIssue(issues, path, "无效值");
+}
+
+export function validateConfig(config) {
+    const issues = [];
+    if (!isPlainObject(config)) {
+        addIssue(issues, [], "配置必须是对象格式");
+        return issues;
     }
 
-    /** 测试正则 */
-    static testRegex(pattern, value) {
-        try {
-            return getCompiledRegex(pattern).test(value);
-        } catch {
-            return false;
+    const { root, groups } = configSchema;
+    addUnknownKeys(issues, config, new Set([...Object.keys(root), ...Object.keys(groups)]), []);
+    for (const [key, def] of Object.entries(root)) checkConfigLeaf(issues, config[key], def, [key]);
+
+    for (const [groupName, fields] of Object.entries(groups)) {
+        const group = config[groupName];
+        if (group === undefined && groupName === "email") continue;
+        if (!isPlainObject(group)) {
+            addIssue(issues, [groupName], "必须是对象格式");
+            continue;
         }
+        addUnknownKeys(issues, group, new Set(Object.keys(fields)), [groupName]);
+        for (const [fieldName, def] of Object.entries(fields)) checkConfigLeaf(issues, group[fieldName], def, [groupName, fieldName]);
     }
+
+    return issues;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.72.0",
+    "version": "3.74.0",
     "gitHead": "49c39d36695036e85fc64083cc43c1652fff96cb",
     "private": false,
     "description": "Befly - 为 Bun 专属打造的 JavaScript API 接口框架核心引擎",
@@ -26,6 +26,7 @@
         "lib",
         "plugins",
         "router",
+        "schemas",
         "scripts",
         "sql",
         "sync",
@@ -56,8 +57,7 @@
     },
     "dependencies": {
         "pathe": "^2.0.3",
-        "picomatch": "^4.0.5",
-        "zod": "^4.4.3"
+        "picomatch": "^4.0.5"
     },
     "engines": {
         "bun": ">=1.3.0"

package/plugins/tool.js

@@ -47,6 +47,21 @@ export function No(msg, data = null, other = {}) {
     return out;
 }
 
+/**
+ * 业务失败并抛出错误
+ *
+ * 仅用于事务内需要回滚的业务失败；抛出后由路由统一转换为 { code: 1 } 响应。
+ * @param msg - 消息
+ * @param data - 数据（可选）
+ * @param other - 其他字段（可选）
+ */
+export function Fail(msg, data = null, other = {}) {
+    const error = new Error(msg);
+    error.isBeflyResponse = true;
+    error.payload = No(msg, data, other);
+    throw error;
+}
+
 /**
  * 统一响应函数
  *
@@ -109,6 +124,7 @@ export default {
         return {
             Yes: Yes,
             No: No,
+            Fail: Fail,
             Raw: Raw
         };
     }

package/router/api.js

@@ -158,6 +158,10 @@ export function apiHandler(apis, hooks, context) {
             // 7. 返回响应（自动处理 response/result/日志）
             return FinalResponse(ctx);
         } catch (err) {
+            if (err && err.isBeflyResponse === true) {
+                ctx.result = err.payload;
+                return FinalResponse(ctx);
+            }
             // 全局错误处理
             Logger.error("请求错误", err, {
                 path: ctx.apiPath,