schema-dsl 1.0.0

package/lib/core/Validator.js

@@ -0,0 +1,376 @@
+/**
+ * Validator - JSON Schema验证器
+ *
+ * 基于ajv实现，支持JSON Schema Draft 7标准
+ *
+ * @module lib/core/Validator
+ * @version 1.0.0
+ */
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const CacheManager = require('./CacheManager');
+const ErrorFormatter = require('./ErrorFormatter');
+const CustomKeywords = require('../validators/CustomKeywords');
+const Locale = require('./Locale');
+
+/**
+ * 验证器类
+ *
+ * @class Validator
+ * @description 封装ajv，提供统一的验证接口
+ */
+class Validator {
+  /**
+   * 构造函数
+   * @param {Object} options - ajv配置选项
+   * @param {boolean} options.allErrors - 是否返回所有错误（默认true）
+   * @param {boolean} options.useDefaults - 是否使用默认值（默认true）
+   * @param {boolean} options.coerceTypes - 是否自动类型转换（默认false）
+   * @param {boolean} options.removeAdditional - 是否移除额外属性（默认false）
+   */
+  constructor(options = {}) {
+    // ajv配置
+    this.ajvOptions = {
+      allErrors: options.allErrors !== false,
+      useDefaults: options.useDefaults !== false,
+      coerceTypes: options.coerceTypes || false,
+      removeAdditional: options.removeAdditional || false,
+      verbose: true, // 启用详细模式，以便访问 parentSchema
+      ...options
+    };
+
+    // 创建ajv实例
+    this.ajv = new Ajv(this.ajvOptions);
+
+    // 添加格式支持（email、uri、date-time等）
+    addFormats(this.ajv);
+
+    // 注册自定义关键字
+    CustomKeywords.registerAll(this.ajv);
+
+    // 编译缓存
+    this.cache = new CacheManager({
+      maxSize: 100,
+      ttl: 3600000 // 1小时
+    });
+
+    // 错误格式化器
+    this.errorFormatter = new ErrorFormatter();
+
+    // 自定义关键字注册表
+    this.customKeywords = new Map();
+  }
+
+  /**
+   * 编译Schema
+   * @param {Object} schema - JSON Schema对象
+   * @param {string} cacheKey - 缓存键（可选）
+   * @returns {Function} ajv验证函数
+   */
+  compile(schema, cacheKey = null) {
+    // 尝试从缓存获取
+    if (cacheKey) {
+      const cached = this.cache.get(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    try {
+      // 编译Schema
+      const validate = this.ajv.compile(schema);
+
+      // 缓存编译结果
+      if (cacheKey) {
+        this.cache.set(cacheKey, validate);
+      }
+
+      return validate;
+    } catch (error) {
+      throw new Error(`Schema compilation failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * 验证数据
+   * @param {Object} schema - JSON Schema对象或已编译的验证函数
+   * @param {*} data - 待验证的数据
+   * @param {Object} options - 验证选项
+   * @param {boolean} options.format - 是否格式化错误（默认true）
+   * @param {string} options.locale - 动态指定语言（如 'zh-CN', 'en-US'）
+   * @returns {Object} 验证结果 { valid: boolean, errors: Array, data: * }
+   */
+  validate(schema, data, options = {}) {
+    const shouldFormat = options.format !== false;
+    const locale = options.locale || Locale.getLocale();
+
+    // 如果指定了语言，临时切换
+    const originalLocale = options.locale ? Locale.getLocale() : null;
+    if (options.locale) {
+      Locale.setLocale(options.locale);
+    }
+
+    // 如果schema是DslBuilder实例，转换为JSON Schema
+    if (schema && typeof schema.toSchema === 'function') {
+      schema = schema.toSchema();
+    }
+
+    // 检查是否需要移除额外字段 (clean 模式)
+    if (schema && schema._removeAdditional) {
+      // 创建新的 Validator 实例，启用 removeAdditional
+      const tempValidator = new Validator({
+        ...this.ajvOptions,
+        removeAdditional: true
+      });
+
+      // 移除标记字段并深拷贝，避免修改原 schema
+      const cleanSchema = JSON.parse(JSON.stringify(schema));
+      delete cleanSchema._removeAdditional;
+
+      return tempValidator.validate(cleanSchema, data, options);
+    }
+
+    try {
+      // 如果schema是函数，说明已编译
+      let validate;
+      if (typeof schema === 'function') {
+        validate = schema;
+      } else {
+        // 生成缓存键
+        const cacheKey = this._generateCacheKey(schema);
+        validate = this.compile(schema, cacheKey);
+      }
+
+      // 执行验证
+      const valid = validate(data);
+
+      // 格式化错误
+      const errors = valid ? [] : (
+        shouldFormat
+          ? this.errorFormatter.format(validate.errors, locale)
+          : validate.errors
+      );
+
+      return {
+        valid,
+        errors,
+        data // 可能被useDefaults修改过
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [{
+          message: `Validation error: ${error.message}`,
+          path: '',
+          keyword: 'error'
+        }],
+        data
+      };
+    } finally {
+      // 恢复原语言
+      if (originalLocale) {
+        Locale.setLocale(originalLocale);
+      }
+    }
+  }
+
+  /**
+   * 快速验证（不缓存）
+   * @param {Object} schema - JSON Schema对象
+   * @param {*} data - 待验证的数据
+   * @returns {boolean} 是否有效
+   */
+  quickValidate(schema, data) {
+    try {
+      return this.ajv.validate(schema, data);
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * 异步验证方法（验证失败自动抛出异常）
+   *
+   * @param {Object|Function} schema - JSON Schema对象或DslBuilder实例
+   * @param {*} data - 待验证的数据
+   * @param {Object} options - 验证选项（可选）
+   * @param {boolean} options.format - 是否格式化错误（默认true）
+   * @param {string} options.locale - 语言环境（如 'zh-CN', 'en-US'）
+   * @returns {Promise<*>} 验证通过返回处理后的数据
+   * @throws {ValidationError} 验证失败抛出异常
+   *
+   * @example
+   * // 基础使用
+   * try {
+   *   const data = await validator.validateAsync(userSchema, inputData);
+   *   console.log('验证通过:', data);
+   * } catch (error) {
+   *   if (error instanceof ValidationError) {
+   *     console.error('验证失败:', error.errors);
+   *   }
+   * }
+   *
+   * @example
+   * // Express 中使用
+   * app.post('/users', async (req, res, next) => {
+   *   try {
+   *     const data = await validator.validateAsync(userSchema, req.body);
+   *     const user = await db.users.insert(data);
+   *     res.json(user);
+   *   } catch (error) {
+   *     next(error);
+   *   }
+   * });
+   */
+  async validateAsync(schema, data, options = {}) {
+    const result = this.validate(schema, data, options);
+
+    if (!result.valid) {
+      const ValidationError = require('../errors/ValidationError');
+      throw new ValidationError(result.errors, data);
+    }
+
+    return result.data;
+  }
+
+  /**
+   * 批量验证
+   * @param {Object} schema - JSON Schema对象
+   * @param {Array} dataArray - 数据数组
+   * @returns {Array} 验证结果数组
+   */
+  validateBatch(schema, dataArray) {
+    if (!Array.isArray(dataArray)) {
+      throw new Error('Data must be an array');
+    }
+
+    // 编译一次，复用验证函数
+    const cacheKey = this._generateCacheKey(schema);
+    const validate = this.compile(schema, cacheKey);
+
+    return dataArray.map(data => this.validate(validate, data));
+  }
+
+  /**
+   * 添加自定义关键字
+   * @param {string} keyword - 关键字名称
+   * @param {Object} definition - 关键字定义
+   * @returns {Validator} 返回this支持链式调用
+   */
+  addKeyword(keyword, definition) {
+    try {
+      this.ajv.addKeyword(keyword, definition);
+      this.customKeywords.set(keyword, definition);
+      return this;
+    } catch (error) {
+      throw new Error(`Failed to add keyword '${keyword}': ${error.message}`);
+    }
+  }
+
+  /**
+   * 添加自定义格式
+   * @param {string} name - 格式名称
+   * @param {Function|RegExp} validator - 验证函数或正则表达式
+   * @returns {Validator} 返回this支持链式调用
+   */
+  addFormat(name, validator) {
+    try {
+      this.ajv.addFormat(name, validator);
+      return this;
+    } catch (error) {
+      throw new Error(`Failed to add format '${name}': ${error.message}`);
+    }
+  }
+
+  /**
+   * 添加Schema引用
+   * @param {string} uri - Schema URI
+   * @param {Object} schema - JSON Schema对象
+   * @returns {Validator} 返回this支持链式调用
+   */
+  addSchema(uri, schema) {
+    try {
+      this.ajv.addSchema(schema, uri);
+      return this;
+    } catch (error) {
+      throw new Error(`Failed to add schema '${uri}': ${error.message}`);
+    }
+  }
+
+  /**
+   * 移除Schema引用
+   * @param {string} uri - Schema URI
+   * @returns {Validator} 返回this支持链式调用
+   */
+  removeSchema(uri) {
+    this.ajv.removeSchema(uri);
+    return this;
+  }
+
+  /**
+   * 获取ajv实例（高级用法）
+   * @returns {Ajv} ajv实例
+   */
+  getAjv() {
+    return this.ajv;
+  }
+
+  /**
+   * 清空缓存
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+
+  /**
+   * 获取缓存统计
+   * @returns {Object} 缓存统计信息
+   */
+  getCacheStats() {
+    return this.cache.stats();
+  }
+
+  /**
+   * 生成Schema的缓存键
+   * @private
+   * @param {Object} schema - JSON Schema对象
+   * @returns {string} 缓存键
+   */
+  _generateCacheKey(schema) {
+    // 简单实现：使用JSON字符串的hash
+    // 生产环境建议使用更高效的hash算法
+    return JSON.stringify(schema);
+  }
+
+  /**
+   * 静态方法：创建验证器实例
+   * @static
+   * @param {Object} options - 配置选项
+   * @returns {Validator} Validator实例
+   */
+  static create(options) {
+    return new Validator(options);
+  }
+
+  /**
+   * 静态方法：快速验证（不创建实例）
+   * @static
+   * @param {Object} schema - JSON Schema对象
+   * @param {*} data - 待验证的数据
+   * @returns {boolean} 是否有效
+   */
+  static quickValidate(schema, data) {
+    const ajv = new Ajv();
+    return ajv.validate(schema, data);
+  }
+}
+
+// Support calling without new
+const ValidatorProxy = new Proxy(Validator, {
+  apply: function(target, thisArg, argumentsList) {
+    return new target(...argumentsList);
+  }
+});
+
+module.exports = ValidatorProxy;

package/lib/errors/ValidationError.js

@@ -0,0 +1,191 @@
+/**
+ * ValidationError - 验证错误类
+ *
+ * 用于 validateAsync() 方法，验证失败时自动抛出
+ *
+ * @module lib/errors/ValidationError
+ * @version 2.1.0
+ */
+
+/**
+ * 验证错误类
+ *
+ * @class ValidationError
+ * @extends Error
+ *
+ * @property {string} name - 错误名称（固定为 'ValidationError'）
+ * @property {string} message - 错误消息（所有错误的汇总）
+ * @property {Array<Object>} errors - 详细错误列表
+ * @property {*} data - 原始验证数据
+ * @property {number} statusCode - HTTP 状态码（默认 400）
+ *
+ * @example
+ * // 创建错误
+ * const errors = [
+ *   { path: '/name', message: '字段必填', keyword: 'required' }
+ * ];
+ * const error = new ValidationError(errors, inputData);
+ *
+ * @example
+ * // 在 Express 中使用
+ * app.use((error, req, res, next) => {
+ *   if (error instanceof ValidationError) {
+ *     return res.status(error.statusCode).json(error.toJSON());
+ *   }
+ *   next(error);
+ * });
+ */
+class ValidationError extends Error {
+  /**
+   * 构造函数
+   * @param {Array<Object>} errors - 错误列表
+   * @param {string} errors[].path - 字段路径（如 '/name'）
+   * @param {string} errors[].message - 错误消息
+   * @param {string} errors[].keyword - 验证关键字（如 'required', 'format'）
+   * @param {Object} errors[].params - 错误参数
+   * @param {*} data - 原始数据
+   */
+  constructor(errors, data) {
+    // 生成友好的错误消息
+    const messages = errors.map(e => {
+      if (e.path) {
+        const field = e.path.replace(/^\//, '');
+        // 只有字段名非空时才添加前缀
+        return field ? `${field}: ${e.message}` : e.message;
+      }
+      return e.message;
+    }).join('; ');
+
+    // 检查是否所有错误都完全没有 path 属性（而不是空路径）
+    const hasNoPath = errors.every(e => e.path === undefined || e.path === null);
+
+    // 如果都是无 path 属性的错误，使用简单格式；否则使用标准格式
+    super(hasNoPath ? `Validation failed - ${messages}` : `Validation failed: ${messages}`);
+
+    this.name = 'ValidationError';
+    this.errors = errors;
+    this.data = data;
+    this.statusCode = 400;
+
+    // 保持堆栈跟踪
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ValidationError);
+    }
+  }
+
+  /**
+   * 转换为 JSON 格式（用于 API 响应）
+   *
+   * @returns {Object} JSON 对象
+   * @returns {string} return.error - 错误名称
+   * @returns {string} return.message - 错误消息
+   * @returns {number} return.statusCode - 状态码
+   * @returns {Array<Object>} return.details - 详细错误列表
+   *
+   * @example
+   * const json = error.toJSON();
+   * res.status(400).json(json);
+   * // {
+   * //   error: 'ValidationError',
+   * //   message: 'Validation failed: name: 字段必填',
+   * //   statusCode: 400,
+   * //   details: [...]
+   * // }
+   */
+  toJSON() {
+    return {
+      error: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.errors.map(e => ({
+        field: e.path ? e.path.replace(/^\//, '') : null,
+        message: e.message,
+        keyword: e.keyword,
+        params: e.params
+      }))
+    };
+  }
+
+  /**
+   * 获取指定字段的错误
+   *
+   * @param {string} field - 字段名称（如 'name' 或 '/name'）
+   * @returns {Object|null} 错误对象或 null
+   *
+   * @example
+   * const nameError = error.getFieldError('name');
+   * if (nameError) {
+   *   console.log('姓名错误:', nameError.message);
+   * }
+   */
+  getFieldError(field) {
+     // 规范化字段名（移除前导斜杠）
+    const normalizedField = field.replace(/^\//, '');
+
+    // 查找匹配的错误（支持多种路径格式）
+    return this.errors.find(e => {
+      if (!e.path) return false;
+      const errorField = e.path.replace(/^\//, '');
+      return errorField === normalizedField;
+    }) || null;
+  }
+
+  /**
+   * 获取所有字段的错误映射
+   *
+   * @returns {Object} 字段错误映射 { fieldName: errorMessage }
+   *
+   * @example
+   * const fieldErrors = error.getFieldErrors();
+   * // { name: '字段必填', email: '邮箱格式错误' }
+   */
+  getFieldErrors() {
+    const result = {};
+    this.errors.forEach(e => {
+      if (e.path) {
+        const field = e.path.replace(/^\//, '');
+        if (field) {
+          result[field] = e.message;
+        }
+      }
+    });
+    return result;
+  }
+
+  /**
+   * 检查是否包含指定字段的错误
+   *
+   * @param {string} field - 字段名称
+   * @returns {boolean} 是否包含错误
+   *
+   * @example
+   * if (error.hasFieldError('name')) {
+   *   console.log('姓名字段有错误');
+   * }
+   */
+  hasFieldError(field) {
+    return this.getFieldError(field) !== null;
+  }
+
+  /**
+   * 获取错误数量
+   *
+   * @returns {number} 错误数量
+   *
+   * @example
+   * console.log(`共 ${error.getErrorCount()} 个错误`);
+   */
+  getErrorCount() {
+    return this.errors.length;
+  }
+}
+
+// Support calling without new
+const ValidationErrorProxy = new Proxy(ValidationError, {
+  apply: function(target, thisArg, argumentsList) {
+    return new target(...argumentsList);
+  }
+});
+
+module.exports = ValidationErrorProxy;
+