schema-dsl 1.0.7 → 1.0.9

package/docs/i18n.md

@@ -1,7 +1,19 @@
 # 多语言配置指南
 
-**版本**: v1.0.1  
-**最后更新**: 2025-12-31
+**版本**: v1.0.9  
+**最后更新**: 2026-01-04
+
+---
+
+## 📚 多语言文档导航
+
+根据你的需求选择合适的文档：
+
+- 🚀 **新手快速上手**: [i18n.md](./i18n.md)（当前文档）- 5分钟学会基础用法
+- 📖 **完整使用指南**: [i18n-user-guide.md](./i18n-user-guide.md) - 详细的用户指南和最佳实践
+- 🎯 **添加新语言**: [add-custom-locale.md](./add-custom-locale.md) - 添加自定义语言包教程
+- 🔄 **动态切换语言**: [dynamic-locale.md](./dynamic-locale.md) - API开发中的动态语言切换
+- 🌐 **前端集成**: [frontend-i18n-guide.md](./frontend-i18n-guide.md) - 前后端分离项目集成指南
 
 ---
 
@@ -9,10 +21,61 @@
 
 schema-dsl 支持完整的多语言功能，允许你自定义字段标签和错误消息的翻译。
 
+**v1.0.9 新增**：
+- ✅ 支持参数化语言切换（无需修改全局状态）
+- ✅ 支持自定义错误消息（三种格式）
+- ✅ TypeScript 类型定义完整
+
 ---
 
 ## 🚀 快速开始
 
+### 方式1：验证时动态指定语言（推荐）⭐
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+const schema = dsl({ username: 'string:3-32!' });
+
+// 使用中文错误消息
+const result = validate(schema, { username: 'ab' }, { locale: 'zh-CN' });
+// message: "username长度不能少于3个字符"
+
+// 使用英文错误消息
+const result2 = validate(schema, { username: 'ab' }, { locale: 'en-US' });
+// message: "username length must be at least 3"
+```
+
+### 方式2：使用全局配置（向后兼容）
+
+```javascript
+const { Locale } = require('schema-dsl');
+
+// 设置默认语言
+Locale.setLocale('zh-CN');
+
+// 后续验证会使用中文错误消息
+const result = validate(schema, data);
+```
+
+---
+
+## 📝 内置语言支持
+
+schema-dsl 内置了以下语言包：
+
+| 语言代码 | 语言名称 | 支持状态 |
+|---------|---------|---------|
+| `zh-CN` | 简体中文 | ✅ 完整支持 |
+| `en-US` | 英语（美国）| ✅ 完整支持 |
+| `ja-JP` | 日语 | ✅ 完整支持 |
+| `es-ES` | 西班牙语 | ✅ 完整支持 |
+| `fr-FR` | 法语 | ✅ 完整支持 |
+
+---
+
+## 🎯 高级用法
+
 ### 基础配置
 
 ```javascript

package/index.d.ts

@@ -112,6 +112,35 @@ declare module 'schema-dsl' {
     field?: string;
   }
 
+  /**
+   * 验证选项
+   *
+   * @description validate() 和 Validator.validate() 的配置选项
+   *
+   * @example
+   * ```typescript
+   * const options: ValidateOptions = {
+   *   format: true,
+   *   locale: 'zh-CN',
+   *   messages: {
+   *     min: '至少需要 {{#limit}} 个字符'
+   *   }
+   * };
+   *
+   * const result = validate(schema, data, options);
+   * ```
+   */
+  export interface ValidateOptions {
+    /** 是否格式化错误（默认true） */
+    format?: boolean;
+    /** 动态指定语言（如 'zh-CN', 'en-US', 'ja-JP', 'es-ES', 'fr-FR'） */
+    locale?: string;
+    /** 自定义错误消息 */
+    messages?: ErrorMessages;
+    /** 扩展选项 */
+    [key: string]: any;
+  }
+
   /**
    * 错误消息对象
    * 
@@ -1257,9 +1286,27 @@ declare module 'schema-dsl' {
      * 验证数据
      * @param schema - JSON Schema对象
      * @param data - 要验证的数据
+     * @param options - 验证选项
      * @returns 验证结果
+     *
+     * @example
+     * ```typescript
+     * const validator = new Validator();
+     *
+     * // 使用默认语言
+     * const result1 = validator.validate(schema, data);
+     *
+     * // 动态指定语言
+     * const result2 = validator.validate(schema, data, { locale: 'zh-CN' });
+     *
+     * // 自定义错误消息
+     * const result3 = validator.validate(schema, data, {
+     *   locale: 'zh-CN',
+     *   messages: { min: '至少{{#limit}}个字符' }
+     * });
+     * ```
      */
-    validate<T = any>(schema: JSONSchema, data: any): ValidationResult<T>;
+    validate<T = any>(schema: JSONSchema, data: any, options?: ValidateOptions): ValidationResult<T>;
 
     /**
      * 获取底层ajv实例
@@ -1300,14 +1347,25 @@ declare module 'schema-dsl' {
    * import { dsl, validate } from 'schema-dsl';
    *
    * const schema = dsl({ email: 'email!' });
-   * const result = validate(schema, { email: 'test@example.com' });
-   * 
-   * if (result.valid) {
+   *
+   * // 基本验证
+   * const result1 = validate(schema, { email: 'test@example.com' });
+   *
+   * // 指定语言
+   * const result2 = validate(schema, { email: 'invalid' }, { locale: 'zh-CN' });
+   *
+   * if (result2.valid) {
    *   console.log('验证通过');
+   * } else {
+   *   console.log('错误:', result2.errors); // 中文错误消息
    * }
    * ```
    */
-  export function validate<T = any>(schema: JSONSchema | SchemaIO, data: any): ValidationResult<T>;
+  export function validate<T = any>(
+    schema: JSONSchema | SchemaIO,
+    data: any,
+    options?: ValidateOptions
+  ): ValidationResult<T>;
 
   /**
    * 便捷异步验证方法（推荐）

package/index.js

@@ -128,16 +128,25 @@ function getDefaultValidator() {
  * 便捷验证方法（使用默认Validator）
  * @param {Object} schema - JSON Schema对象
  * @param {*} data - 待验证数据
+ * @param {Object} [options] - 验证选项
+ * @param {boolean} [options.format=true] - 是否格式化错误
+ * @param {string} [options.locale] - 动态指定语言（如 'zh-CN', 'en-US'）
+ * @param {Object} [options.messages] - 自定义错误消息
  * @returns {Object} 验证结果
  *
  * @example
  * const { validate, dsl } = require('schema-dsl');
  *
  * const schema = dsl({ email: 'email!' });
- * const result = validate(schema, { email: 'test@example.com' });
+ *
+ * // 基本验证
+ * const result1 = validate(schema, { email: 'test@example.com' });
+ *
+ * // 指定语言
+ * const result2 = validate(schema, { email: 'invalid' }, { locale: 'zh-CN' });
  */
-function validate(schema, data) {
-  return getDefaultValidator().validate(schema, data);
+function validate(schema, data, options) {
+  return getDefaultValidator().validate(schema, data, options);
 }
 
 // ========== 工具函数 ==========

package/lib/core/ErrorFormatter.js

@@ -38,20 +38,41 @@ class ErrorFormatter {
   /**
    * 格式化单个错误或错误数组
    * @param {Object|Array<Object>} error - 错误对象或错误数组
-   * @param {string} [locale] - 动态指定语言（可选）
+   * @param {string|Object} [localeOrOptions] - 语言代码字符串或选项对象
+   * @param {string} [localeOrOptions.locale] - 动态指定语言（可选）
+   * @param {Object} [localeOrOptions.messages] - 自定义错误消息（可选）
    * @returns {string|Array<Object>} 格式化后的错误消息或错误对象数组
    */
-  format(error, locale) {
+  format(error, localeOrOptions) {
+
+    // ✅ 支持两种调用方式：
+    // 1. format(errors, 'zh-CN') - 旧版兼容
+    // 2. format(errors, { locale: 'zh-CN', messages: {...} }) - 新版增强
+    let locale;
+    let customMessages;
+
+    if (typeof localeOrOptions === 'string') {
+      // 旧版：直接传入语言代码
+      locale = localeOrOptions;
+    } else if (typeof localeOrOptions === 'object' && localeOrOptions !== null) {
+      // 新版：传入选项对象
+      locale = localeOrOptions.locale;
+      customMessages = localeOrOptions.messages;
+    }
+
     // 如果是数组，格式化为详细对象数组
     if (Array.isArray(error)) {
-      return this.formatDetailed(error, locale);
+      return this.formatDetailed(error, locale, customMessages);
     }
 
     // 获取当前使用的消息模板
     const messages = locale ? this._loadMessages(locale) : this.messages;
 
+    // 合并自定义消息
+    const finalMessages = customMessages ? { ...messages, ...customMessages } : messages;
+
     // 单个错误对象格式化
-    const template = messages[error.type] || error.message;
+    const template = finalMessages[error.type] || error.message;
     return this._interpolate(template, {
       ...error,
       path: error.path || 'value',
@@ -73,16 +94,42 @@ class ErrorFormatter {
    * 格式化为详细对象
    * @param {Array<Object>} errors - ajv错误数组
    * @param {string} [locale] - 动态指定语言（可选）
+   * @param {Object} [customMessages] - 自定义错误消息（可选）
    * @returns {Array<Object>} 详细错误对象数组
    */
-  formatDetailed(errors, locale) {
+  formatDetailed(errors, locale, customMessages) {
+
     if (!Array.isArray(errors)) {
       errors = [errors];
     }
 
+    // 过滤冗余的包装错误（v1.0.7.1 增强）
+    // 当存在具体字段错误时，移除通用的包装错误
+    const hasConcreteErrors = errors.some(err => {
+      const keyword = err.keyword;
+      // 包装错误关键字：if, anyOf, oneOf, allOf
+      return keyword !== 'if' &&
+        keyword !== 'anyOf' &&
+        keyword !== 'oneOf' &&
+        keyword !== 'error';
+    });
+
+    if (hasConcreteErrors) {
+      // 过滤掉包装错误（这些是通用的组合验证错误）
+      errors = errors.filter(err => {
+        const keyword = err.keyword;
+        return keyword !== 'if' &&
+          keyword !== 'anyOf' &&
+          keyword !== 'oneOf';
+      });
+    }
+
     // 获取当前使用的消息模板
     const messages = locale ? this._loadMessages(locale) : this.messages;
 
+    // ✅ 合并参数传入的自定义消息（在整个 map 循环中使用）
+    const finalMessages = customMessages ? { ...messages, ...customMessages } : messages;
+
     return errors.map(err => {
       // 处理 ajv 错误格式
       const keyword = err.keyword || err.type || 'validation';
@@ -104,22 +151,27 @@ class ErrorFormatter {
 
       if (label) {
         // 如果显式设置了 label，尝试翻译它
-        if (messages[label]) {
-          label = messages[label];
+        if (finalMessages[label]) {
+          label = finalMessages[label];
         }
       } else {
         // 如果没有显式设置 label，尝试自动查找翻译 (label.fieldName)
         // 将路径分隔符 / 转换为 . (例如 address/city -> address.city)
         const autoKey = `label.${fieldName.replace(/\//g, '.')}`;
-        if (messages[autoKey]) {
-          label = messages[autoKey];
+        if (finalMessages[autoKey]) {
+          label = finalMessages[autoKey];
         } else {
           // 没找到翻译，回退到 fieldName
           label = fieldName;
         }
       }
 
-      const customMessages = schema._customMessages || {};
+      // Schema 中的自定义消息
+      const schemaCustomMessages = schema._customMessages || {};
+
+      // ✅ 合并优先级：schemaCustomMessages > finalMessages
+      // schemaCustomMessages 是字段级的自定义消息，优先级最高
+      const mergedMessages = { ...finalMessages, ...schemaCustomMessages };
 
       // 关键字映射 (ajv keyword -> schema-dsl 简写)
       // 支持 min/max 作为 minLength/maxLength 的简写
@@ -139,18 +191,38 @@ class ErrorFormatter {
       const mappedKeyword = keywordMap[keyword] || keyword;
       const type = schema.type || 'string';
 
-      // 查找自定义消息
-      // 优先级:
-      // 1. type.keyword (如 string.pattern)
-      // 2. type.mappedKeyword (如 string.min)
-      // 3. mappedKeyword (如 min)
-      // 4. keyword (如 minLength，向后兼容)
-      // 5. default
-      let message = customMessages[`${type}.${keyword}`] ||
-        customMessages[`${type}.${mappedKeyword}`] ||
-        customMessages[mappedKeyword] ||
-        customMessages[keyword] ||
-        customMessages['default'];
+
+      // ✅ 优化：如果 schema 中有自定义消息，优先使用
+      // 支持三种自定义消息格式：
+      // 1. 键引用：_customMessages.pattern = "pattern.objectId" → 查找语言包中的 "pattern.objectId"
+      // 2. 模板字符串：_customMessages.min = "{{#label}}必须大于{{#limit}}" → 直接使用并插值
+      // 3. 最终消息：_customMessages.pattern = "手机号格式不正确" → 直接使用
+      let message;
+
+      // 1. 首先检查 schema 是否为该 keyword 定义了自定义消息
+      let customValue = schemaCustomMessages[keyword] || schemaCustomMessages[mappedKeyword];
+
+      if (customValue) {
+        // 尝试从 mergedMessages 中查找这个键
+        const lookupResult = mergedMessages[customValue];
+
+        if (lookupResult) {
+          // 找到了，说明它是一个键引用
+          message = lookupResult;
+        } else {
+          // 没找到，说明它本身就是模板或最终消息，直接使用
+          message = customValue;
+        }
+      }
+
+      // 2. 如果没有自定义消息，按照通用查找顺序
+      if (!message) {
+        message = mergedMessages[`${type}.${keyword}`] ||
+          mergedMessages[`${type}.${mappedKeyword}`] ||
+          mergedMessages[mappedKeyword] ||
+          mergedMessages[keyword] ||
+          mergedMessages['default'];
+      }
 
       // 自动查找 format 类型的消息 (例如 format.email)
       if (!message && mappedKeyword === 'format' && err.params && err.params.format) {
@@ -160,25 +232,22 @@ class ErrorFormatter {
 
         const formatKey = `format.${formatName}`;
 
-        // 优先查找 customMessages 中的 format.email
-        if (customMessages[formatKey]) {
-          message = customMessages[formatKey];
-        }
-        // 其次查找全局/语言包中的 format.email
-        else if (messages[formatKey]) {
-          message = messages[formatKey];
+        // 优先查找 mergedMessages 中的 format.email
+        if (mergedMessages[formatKey]) {
+          message = mergedMessages[formatKey];
         }
       }
 
       if (!message) {
         // 使用默认模板
-        const template = messages[mappedKeyword] || messages[keyword] || err.message || 'Validation error';
+        const template = mergedMessages[mappedKeyword] || mergedMessages[keyword] || err.message || 'Validation error';
         message = template;
       } else {
         // 检查 message 是否为 key (包含点号且无空格，或者是已知的 key)
         // 如果是 key，尝试从 messages 中查找
-        if (typeof message === 'string' && (message.includes('.') || messages[message])) {
-          let translated = messages[message];
+        if (typeof message === 'string' && (message.includes('.') || mergedMessages[message])) {
+
+          let translated = mergedMessages[message];
 
           // 尝试回退查找 (例如 pattern.phone.cn -> pattern.phone)
           if (!translated && message.includes('.')) {
@@ -186,7 +255,7 @@ class ErrorFormatter {
             while (parts.length > 1 && !translated) {
               parts.pop();
               const fallbackKey = parts.join('.');
-              translated = messages[fallbackKey];
+              translated = mergedMessages[fallbackKey];
             }
           }
 

package/lib/core/Validator.js

@@ -115,18 +115,7 @@ class Validator {
    * @returns {Object} 验证结果 { valid: boolean, errors: Array, data: * }
    */
   validate(schema, data, options = {}) {
-    // ✅ 性能优化：提前检查语言切换，避免99%的无效操作
-    if (options.locale && options.locale !== Locale.getLocale()) {
-      const originalLocale = Locale.getLocale();
-      Locale.setLocale(options.locale);
-      try {
-        return this._validateInternal(schema, data, options);
-      } finally {
-        Locale.setLocale(originalLocale);
-      }
-    }
-
-    // 正常流程（无需切换语言）
+    // ✅ 优化：直接传递 locale 到内部方法，不再切换全局状态
     return this._validateInternal(schema, data, options);
   }
 
@@ -175,10 +164,13 @@ class Validator {
       // 执行验证
       const valid = validate(data);
 
-      // 格式化错误
+      // ✅ 优化：直接传递 locale 和 messages 到格式化器，不修改全局状态
       const errors = valid ? [] : (
         shouldFormat
-          ? this.errorFormatter.format(validate.errors, locale)
+          ? this.errorFormatter.format(validate.errors, {
+              locale,
+              messages: options.messages
+            })
           : validate.errors
       );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schema-dsl",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "简洁强大的JSON Schema验证库 - DSL语法 + String扩展 + 便捷validate",
   "main": "index.js",
   "exports": {
@@ -57,6 +57,7 @@
     "ajv-formats": "^2.1.1"
   },
   "devDependencies": {
+    "benchmark": "^2.1.4",
     "chai": "^4.5.0",
     "eslint": "^8.57.1",
     "joi": "^18.0.2",
@@ -67,4 +68,4 @@
     "yup": "^1.7.1",
     "zod": "^4.2.1"
   }
-}
+}