schema-dsl 1.1.0 → 1.1.2

package/index.js

@@ -22,6 +22,10 @@ const ErrorCodes = require('./lib/core/ErrorCodes');
 const MessageTemplate = require('./lib/core/MessageTemplate');
 const Locale = require('./lib/core/Locale');
 
+// ========== 错误类 ==========
+const ValidationError = require('./lib/errors/ValidationError');
+const I18nError = require('./lib/errors/I18nError');
+
 // ========== String 扩展 ==========
 const { installStringExtensions, uninstallStringExtensions } = require('./lib/core/StringExtensions');
 
@@ -48,6 +52,36 @@ dsl.if = function(...args) {
   return ConditionalBuilder.start(args[0]);
 };
 
+// ✅ dsl.error：统一的多语言错误抛出（v1.1.1+）
+dsl.error = {
+  /**
+   * 创建多语言错误（不抛出）
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @returns {I18nError} 错误实例
+   */
+  create: (code, params, statusCode) => I18nError.create(code, params, statusCode),
+
+  /**
+   * 抛出多语言错误
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 直接抛出错误
+   */
+  throw: (code, params, statusCode) => I18nError.throw(code, params, statusCode),
+
+  /**
+   * 断言方法 - 条件不满足时抛错
+   * @param {boolean} condition - 条件表达式
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   */
+  assert: (condition, code, params, statusCode) => I18nError.assert(condition, code, params, statusCode)
+};
+
 /**
  * 全局配置
  * @param {Object} options - 配置选项
@@ -182,8 +216,6 @@ installStringExtensions(dsl);
 
 // ========== 导出 ==========
 
-// 导入 ValidationError
-const ValidationError = require('./lib/errors/ValidationError');
 
 // 导入 validateAsync
 const { validateAsync } = require('./lib/adapters/DslAdapter');
@@ -214,6 +246,7 @@ module.exports = {
 
   // 错误类 (v2.1.0 新增)
   ValidationError,
+  I18nError,                   // v1.1.1 新增：多语言错误类
 
   // 错误消息系统
   ErrorCodes,

package/lib/adapters/DslAdapter.js

@@ -268,12 +268,59 @@ class DslAdapter {
    * @param {string} baseType - 基础类型
    * @param {string} constraint - 约束字符串
    * @returns {Object} 约束对象
+   *
+   * @example
+   * // 比较运算符 (v1.2.0+)
+   * _parseConstraint('number', '>0')     // { exclusiveMinimum: 0 }
+   * _parseConstraint('number', '>=18')   // { minimum: 18 }
+   * _parseConstraint('number', '<100')   // { exclusiveMaximum: 100 }
+   * _parseConstraint('number', '<=100')  // { maximum: 100 }
+   * _parseConstraint('number', '=100')   // { enum: [100] }
+   * _parseConstraint('number', '>0.5')   // { exclusiveMinimum: 0.5 } 支持小数
    */
   static _parseConstraint(baseType, constraint) {
     if (!constraint) return {};
 
     const result = {};
 
+    // ========== 比较运算符（v1.1.2新增，最高优先级）==========
+    if (baseType === 'number' || baseType === 'integer') {
+      // 1. 大于等于: >=18, >=-10 (支持负数)
+      const gteMatch = constraint.match(/^>=(-?\d+(?:\.\d+)?)$/);
+      if (gteMatch) {
+        result.minimum = parseFloat(gteMatch[1]);
+        return result;
+      }
+
+      // 2. 小于等于: <=100, <=-10 (支持负数)
+      const lteMatch = constraint.match(/^<=(-?\d+(?:\.\d+)?)$/);
+      if (lteMatch) {
+        result.maximum = parseFloat(lteMatch[1]);
+        return result;
+      }
+
+      // 3. 大于: >0, >-10 (不包括边界值，支持负数)
+      const gtMatch = constraint.match(/^>(-?\d+(?:\.\d+)?)$/);
+      if (gtMatch) {
+        result.exclusiveMinimum = parseFloat(gtMatch[1]);
+        return result;
+      }
+
+      // 4. 小于: <100, <-10 (不包括边界值，支持负数)
+      const ltMatch = constraint.match(/^<(-?\d+(?:\.\d+)?)$/);
+      if (ltMatch) {
+        result.exclusiveMaximum = parseFloat(ltMatch[1]);
+        return result;
+      }
+
+      // 5. 等于: =100, =-10 (支持负数)
+      const eqMatch = constraint.match(/^=(-?\d+(?:\.\d+)?)$/);
+      if (eqMatch) {
+        result.enum = [parseFloat(eqMatch[1])];
+        return result;
+      }
+    }
+
     // 枚举: value1|value2|value3 （优先检查，避免被数字范围误判）
     if (constraint.includes('|') && !/^\d+-\d+$/.test(constraint)) {
       result.enum = constraint.split('|').map(v => v.trim());
@@ -281,7 +328,8 @@ class DslAdapter {
     }
 
     // 范围约束: min-max 或 min- 或 -max
-    const rangeMatch = constraint.match(/^(\d*)-(\d*)$/);
+    // 支持小数: 0.5-99.9
+    const rangeMatch = constraint.match(/^(\d*\.?\d*)-(\d*\.?\d*)$/);
     if (rangeMatch) {
       const [, min, max] = rangeMatch;
       if (baseType === 'string') {
@@ -291,20 +339,21 @@ class DslAdapter {
         if (min) result.minItems = parseInt(min, 10);
         if (max) result.maxItems = parseInt(max, 10);
       } else {
-        if (min) result.minimum = parseInt(min, 10);
-        if (max) result.maximum = parseInt(max, 10);
+        if (min) result.minimum = parseFloat(min);
+        if (max) result.maximum = parseFloat(max);
       }
       return result;
     }
 
     // 单个约束: min, max
-    const singleMatch = constraint.match(/^(\d+)$/);
+    // 支持小数: 99.99
+    const singleMatch = constraint.match(/^(\d+(?:\.\d+)?)$/);
     if (singleMatch) {
-      const value = parseInt(singleMatch[1], 10);
+      const value = parseFloat(singleMatch[1]);
       if (baseType === 'string') {
-        result.maxLength = value;
+        result.maxLength = Math.floor(value);
       } else if (baseType === 'array') {
-        result.maxItems = value;
+        result.maxItems = Math.floor(value);
       } else {
         result.maximum = value;
       }

package/lib/core/ConditionalBuilder.js

@@ -59,7 +59,7 @@ class ConditionalBuilder {
     this._conditions.push({
       type: 'if',
       condition: conditionFn,
-      combinedConditions: [{ op: 'root', fn: conditionFn }]
+      combinedConditions: [{ op: 'root', fn: conditionFn, message: null }]
     });
 
     return this;
@@ -73,6 +73,7 @@ class ConditionalBuilder {
    * @example
    * dsl.if((data) => data.age >= 18)
    *   .and((data) => data.userType === 'admin')
+   *   .message('必须是管理员')
    *   .then('email!')
    */
   and(conditionFn) {
@@ -85,7 +86,7 @@ class ConditionalBuilder {
       throw new Error('.and() must follow .if() or .elseIf()');
     }
 
-    last.combinedConditions.push({ op: 'and', fn: conditionFn });
+    last.combinedConditions.push({ op: 'and', fn: conditionFn, message: null });
     return this;
   }
 
@@ -109,7 +110,7 @@ class ConditionalBuilder {
       throw new Error('.or() must follow .if() or .elseIf()');
     }
 
-    last.combinedConditions.push({ op: 'or', fn: conditionFn });
+    last.combinedConditions.push({ op: 'or', fn: conditionFn, message: null });
     return this;
   }
 
@@ -136,7 +137,7 @@ class ConditionalBuilder {
     this._conditions.push({
       type: 'elseIf',
       condition: conditionFn,
-      combinedConditions: [{ op: 'root', fn: conditionFn }]
+      combinedConditions: [{ op: 'root', fn: conditionFn, message: null }]
     });
 
     return this;
@@ -144,7 +145,7 @@ class ConditionalBuilder {
 
   /**
    * 设置错误消息（支持多语言 key）
-t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
+   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
    *
    * @param {string} msg - 错误消息或多语言 key
    * @returns {ConditionalBuilder} 当前实例（支持链式调用）
@@ -153,6 +154,13 @@ t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
    * // 如果是未成年人，抛出错误
    * dsl.if((data) => data.age < 18)
    *   .message('未成年用户不能注册')
+   *
+   * @example
+   * // 为 and 条件设置独立消息
+   * dsl.if((data) => !data)
+   *   .message('账户不存在')
+   *   .and((data) => data.balance < 100)
+   *   .message('余额不足')
    */
   message(msg) {
     if (typeof msg !== 'string') {
@@ -164,6 +172,14 @@ t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
       throw new Error('.message() must follow .if() or .elseIf()');
     }
 
+    // 找到最后一个添加的条件（可能是 root、and 或 or）
+    const lastCombined = last.combinedConditions[last.combinedConditions.length - 1];
+    if (lastCombined) {
+      // 为最后一个组合条件设置消息
+      lastCombined.message = msg;
+    }
+
+    // 同时设置整体消息（作为后备）
     last.message = msg;
     last.action = 'throw';  // 有 message 就自动 throw
     return this;
@@ -216,31 +232,117 @@ t   * 条件为 true 时自动抛出此错误，条件为 false 时通过验证
    * @private
    * @param {Object} conditionObj - 条件对象
    * @param {*} data - 待验证数据对象
-   * @returns {boolean} 条件结果
+   * @returns {Object} { result: boolean, failedMessage: string|null } 条件结果和失败消息
+   *
+   * 语义说明：
+   * - 传统 AND 模式：所有条件都为 true 才失败
+   * - 链式检查模式：root 有 message，且任何 .and() 也有独立 message 时
+   *   → 依次检查，第一个为 true 的失败
    */
   _evaluateCondition(conditionObj, data) {
     try {
+      // 检查是否是链式检查模式：
+      // 1. 必须是 message 模式（action='throw'）
+      // 2. root 条件有 message
+      // 3. 有 .and() 条件（不管是否有独立 message）
+      // 4. 没有 .or() 条件（有 OR 就使用传统逻辑）
+      const isMessageMode = conditionObj.action === 'throw';
+      const rootHasMessage = conditionObj.combinedConditions[0]?.message != null;
+      const hasAndConditions = conditionObj.combinedConditions.some(c => c.op === 'and');
+      const hasOrConditions = conditionObj.combinedConditions.some(c => c.op === 'or');
+      const isChainCheckMode = isMessageMode && rootHasMessage && hasAndConditions && !hasOrConditions;
+
       let result = false;
+      let failedMessage = null;
 
       for (let i = 0; i < conditionObj.combinedConditions.length; i++) {
         const combined = conditionObj.combinedConditions[i];
+        let conditionResult = false;
 
         if (combined.op === 'root') {
           // 第一个条件
-          result = combined.fn(data);
+          conditionResult = combined.fn(data);
+          result = conditionResult;
+
+          if (isChainCheckMode) {
+            // 链式检查模式：第一个条件为 true 就失败
+            if (result) {
+              failedMessage = combined.message || conditionObj.message;
+              return { result: true, failedMessage };
+            }
+          } else {
+            // 传统模式
+            failedMessage = combined.message || conditionObj.message;
+
+            // 如果第一个条件为 false，检查是否有 OR 条件
+            if (!result) {
+              const hasOrConditions = conditionObj.combinedConditions.some(c => c.op === 'or');
+              if (!hasOrConditions) {
+                // 没有 OR 条件，直接通过
+                return { result: false, failedMessage: null };
+              }
+              // 有 OR 条件，继续检查
+            }
+          }
         } else if (combined.op === 'and') {
-          // AND 组合
-          result = result && combined.fn(data);
+          conditionResult = combined.fn(data);
+
+          if (isChainCheckMode) {
+            // 链式检查模式：任一条件为 true 就失败
+            if (conditionResult) {
+              // 使用独立消息，如果没有则使用整体消息
+              failedMessage = combined.message || conditionObj.message;
+              return { result: true, failedMessage };
+            }
+            // 条件为 false，继续检查下一个条件
+          } else {
+            // 传统 AND 模式：所有条件都必须为 true 才失败
+            if (!conditionResult) {
+              // AND 条件为 false
+              // 检查是否有 OR 条件
+              if (hasOrConditions) {
+                // 有 OR 条件，将 result 设为 false，继续检查 OR
+                result = false;
+              } else {
+                // 没有 OR 条件，任一 AND 条件为 false 就验证通过
+                return { result: false, failedMessage: null };
+              }
+            } else {
+              // AND 条件为 true，继续累积
+              result = true;
+            }
+          }
         } else if (combined.op === 'or') {
-          // OR 组合
-          result = result || combined.fn(data);
+          // OR 逻辑：任一条件为 true 就失败
+          if (!result) {
+            conditionResult = combined.fn(data);
+
+            if (conditionResult) {
+              // OR 条件为 true
+              result = true;  // 更新 result
+
+              if (isMessageMode) {
+                // message 模式：立即返回失败
+                failedMessage = combined.message || conditionObj.message;
+                return { result: true, failedMessage };
+              }
+              // then/else 模式：继续累积 result（已经设置为true）
+            }
+          }
         }
       }
 
-      return result;
+      // 返回最终结果
+      if (isChainCheckMode) {
+        // 链式检查模式：所有条件都为 false，验证通过
+        return { result: false, failedMessage: null };
+      } else {
+        // 传统模式：返回累积结果
+        return { result, failedMessage };
+      }
     } catch (error) {
       // 条件函数执行出错，视为不满足
-      return false;
+      return { result: false, failedMessage: null };
     }
   }
 

package/lib/core/DslBuilder.js

@@ -383,12 +383,58 @@ class DslBuilder {
   /**
    * 解析约束
    * @private
+   *
+   * @example
+   * // 比较运算符 (v1.2.0+)
+   * _parseConstraint('number', '>0')     // { exclusiveMinimum: 0 }
+   * _parseConstraint('number', '>=18')   // { minimum: 18 }
+   * _parseConstraint('number', '<100')   // { exclusiveMaximum: 100 }
+   * _parseConstraint('number', '<=100')  // { maximum: 100 }
+   * _parseConstraint('number', '=100')   // { enum: [100] }
    */
   _parseConstraint(type, constraint) {
     const result = {};
 
     if (type === 'string' || type === 'number' || type === 'integer') {
-      // 范围约束: min-max
+      // ========== 比较运算符（v1.1.2新增，仅number/integer，最高优先级）==========
+      if (type === 'number' || type === 'integer') {
+        // 1. 大于等于: >=18, >=-10 (支持负数)
+        const gteMatch = constraint.match(/^>=(-?\d+(?:\.\d+)?)$/);
+        if (gteMatch) {
+          result.minimum = parseFloat(gteMatch[1]);
+          return result;
+        }
+
+        // 2. 小于等于: <=100, <=-10 (支持负数)
+        const lteMatch = constraint.match(/^<=(-?\d+(?:\.\d+)?)$/);
+        if (lteMatch) {
+          result.maximum = parseFloat(lteMatch[1]);
+          return result;
+        }
+
+        // 3. 大于: >0, >-10 (不包括边界值，支持负数)
+        const gtMatch = constraint.match(/^>(-?\d+(?:\.\d+)?)$/);
+        if (gtMatch) {
+          result.exclusiveMinimum = parseFloat(gtMatch[1]);
+          return result;
+        }
+
+        // 4. 小于: <100, <-10 (不包括边界值，支持负数)
+        const ltMatch = constraint.match(/^<(-?\d+(?:\.\d+)?)$/);
+        if (ltMatch) {
+          result.exclusiveMaximum = parseFloat(ltMatch[1]);
+          return result;
+        }
+
+        // 5. 等于: =100, =-10 (支持负数)
+        const eqMatch = constraint.match(/^=(-?\d+(?:\.\d+)?)$/);
+        if (eqMatch) {
+          result.enum = [parseFloat(eqMatch[1])];
+          return result;
+        }
+      }
+
+      // ========== 范围约束: min-max ==========
       if (constraint.includes('-')) {
         const [min, max] = constraint.split('-').map(v => v.trim());
 

package/lib/core/Validator.js

@@ -464,16 +464,20 @@ class Validator {
       for (let i = 0; i < conditionalSchema.conditions.length; i++) {
         const cond = conditionalSchema.conditions[i];
 
-        // 执行组合条件（支持 and/or）
-        const matched = conditionalSchema._evaluateCondition(cond, data);
+        // 执行组合条件（支持 and/or），获取结果和失败消息
+        const evaluation = conditionalSchema._evaluateCondition(cond, data);
+        const matched = evaluation.result;
+        const failedMessage = evaluation.failedMessage;
 
         if (cond.action === 'throw') {
           // ✅ message 模式：条件为 true 时抛错，条件为 false 时通过
           if (matched) {
             // ✅ 条件满足（true），抛出错误
+            // 优先使用具体的失败消息，如果没有则使用整体消息
+            const errorMsg = failedMessage || cond.message;
             // 支持多语言：如果 message 是 key（如 'conditional.underAge'），从语言包获取翻译
             // 传递 locale 参数以支持动态语言切换
-            const errorMessage = Locale.getMessage(cond.message, options.messages || {}, locale);
+            const errorMessage = Locale.getMessage(errorMsg, options.messages || {}, locale);
 
             return {
               valid: false,

package/lib/errors/I18nError.js

@@ -0,0 +1,222 @@
+/**
+ * I18nError - 多语言错误工具类
+ *
+ * 提供统一的多语言错误抛出机制，支持：
+ * - 多语言 key 自动翻译
+ * - 参数插值（如 {{field}}, {{limit}}）
+ * - 自定义错误代码
+ * - Express/Koa 集成
+ *
+ * @module lib/errors/I18nError
+ * @version 1.1.1
+ *
+ * @example 基础用法
+ * const { I18nError } = require('schema-dsl');
+ *
+ * // 抛出多语言错误
+ * throw I18nError.create('error.notFound', { resource: '账户' });
+ * // 中文: "找不到账户"
+ * // 英文: "Account not found"
+ *
+ * @example 业务代码中使用
+ * function getAccount(id) {
+ *   const account = db.findAccount(id);
+ *   if (!account) {
+ *     throw I18nError.create('account.notFound', { accountId: id });
+ *   }
+ *   if (account.balance < 100) {
+ *     throw I18nError.create('account.insufficientBalance', {
+ *       balance: account.balance,
+ *       required: 100
+ *     });
+ *   }
+ *   return account;
+ * }
+ *
+ * @example Express 中间件
+ * app.use((error, req, res, next) => {
+ *   if (error instanceof I18nError) {
+ *     return res.status(error.statusCode).json(error.toJSON());
+ *   }
+ *   next(error);
+ * });
+ */
+
+const Locale = require('../core/Locale');
+const MessageTemplate = require('../core/MessageTemplate');
+
+/**
+ * 多语言错误类
+ *
+ * @class I18nError
+ * @extends Error
+ *
+ * @property {string} name - 错误名称（固定为 'I18nError'）
+ * @property {string} message - 错误消息（已翻译）
+ * @property {string} code - 错误代码（多语言 key）
+ * @property {Object} params - 错误参数（用于插值）
+ * @property {number} statusCode - HTTP 状态码（默认 400）
+ * @property {string} locale - 使用的语言环境
+ */
+class I18nError extends Error {
+  /**
+   * 构造函数
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数（用于插值）
+   * @param {number} statusCode - HTTP 状态码（默认 400）
+   * @param {string} locale - 语言环境（默认使用当前语言）
+   */
+  constructor(code, params = {}, statusCode = 400, locale = null) {
+    // 获取翻译后的消息模板
+    const actualLocale = locale || Locale.getLocale();
+    const template = Locale.getMessage(code, {}, actualLocale);
+
+    // 使用 MessageTemplate 进行参数插值
+    const messageTemplate = new MessageTemplate(template);
+    const message = messageTemplate.render(params || {});
+
+    super(message);
+
+    this.name = 'I18nError';
+    this.code = code;
+    this.params = params || {};
+    this.statusCode = statusCode;
+    this.locale = actualLocale;
+
+    // 保持堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, I18nError);
+    }
+  }
+
+  /**
+   * 静态工厂方法 - 创建并抛出错误
+   *
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @returns {I18nError} 错误实例
+   *
+   * @example
+   * // 创建错误（不抛出）
+   * const error = I18nError.create('error.notFound', { resource: '用户' });
+   *
+   * @example
+   * // 直接抛出
+   * throw I18nError.create('error.notFound', { resource: '用户' });
+   */
+  static create(code, params = {}, statusCode = 400) {
+    return new I18nError(code, params, statusCode);
+  }
+
+  /**
+   * 静态工厂方法 - 快速抛出错误
+   *
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 直接抛出错误
+   *
+   * @example
+   * I18nError.throw('error.notFound', { resource: '用户' });
+   * // 等同于：throw I18nError.create('error.notFound', { resource: '用户' });
+   */
+  static throw(code, params = {}, statusCode = 400) {
+    throw new I18nError(code, params, statusCode);
+  }
+
+  /**
+   * 断言方法 - 条件不满足时抛错
+   *
+   * @param {boolean} condition - 条件表达式
+   * @param {string} code - 错误代码（多语言 key）
+   * @param {Object} params - 错误参数
+   * @param {number} statusCode - HTTP 状态码
+   * @throws {I18nError} 条件为 false 时抛出错误
+   *
+   * @example
+   * I18nError.assert(account, 'account.notFound', { accountId: id });
+   * // 等同于：if (!account) throw I18nError.create('account.notFound', { accountId: id });
+   *
+   * @example
+   * I18nError.assert(
+   *   account.balance >= 100,
+   *   'account.insufficientBalance',
+   *   { balance: account.balance, required: 100 }
+   * );
+   */
+  static assert(condition, code, params = {}, statusCode = 400) {
+    if (!condition) {
+      throw new I18nError(code, params, statusCode);
+    }
+  }
+
+  /**
+   * 检查错误是否为指定代码
+   *
+   * @param {string} code - 错误代码
+   * @returns {boolean} 是否匹配
+   *
+   * @example
+   * try {
+   *   // ...
+   * } catch (error) {
+   *   if (error instanceof I18nError && error.is('account.notFound')) {
+   *     // 处理账户不存在的情况
+   *   }
+   * }
+   */
+  is(code) {
+    return this.code === code;
+  }
+
+  /**
+   * 转换为 JSON 格式（用于 API 响应）
+   *
+   * @returns {Object} JSON 对象
+   * @returns {string} return.error - 错误名称
+   * @returns {string} return.code - 错误代码
+   * @returns {string} return.message - 错误消息（已翻译）
+   * @returns {Object} return.params - 错误参数
+   * @returns {number} return.statusCode - 状态码
+   * @returns {string} return.locale - 语言环境
+   *
+   * @example
+   * const json = error.toJSON();
+   * res.status(error.statusCode).json(json);
+   * // {
+   * //   error: 'I18nError',
+   * //   code: 'account.notFound',
+   * //   message: '找不到账户',
+   * //   params: { accountId: '123' },
+   * //   statusCode: 404,
+   * //   locale: 'zh-CN'
+   * // }
+   */
+  toJSON() {
+    return {
+      error: this.name,
+      code: this.code,
+      message: this.message,
+      params: this.params,
+      statusCode: this.statusCode,
+      locale: this.locale
+    };
+  }
+
+  /**
+   * 转换为字符串
+   *
+   * @returns {string} 格式化的错误信息
+   *
+   * @example
+   * console.log(error.toString());
+   * // "I18nError [account.notFound]: 找不到账户"
+   */
+  toString() {
+    return `${this.name} [${this.code}]: ${this.message}`;
+  }
+}
+
+module.exports = I18nError;
+