schema-dsl 2.3.0

package/examples/middleware-usage.js

@@ -0,0 +1,93 @@
+/**
+ * 中间件使用示例
+ *
+ * 演示如何在 Express/Koa 中使用中间件动态配置 Validator
+ */
+
+const express = require('express');
+const { dsl, Validator, Locale } = require('../index');
+
+// 确保加载所有语言包
+require('../lib/locales/index');
+
+// 扩展语言包以支持 Label 翻译 (可选)
+Locale.addLocale('zh-CN', {
+  'label.username': '用户名',
+  'label.email': '邮箱',
+  'label.age': '年龄'
+});
+Locale.addLocale('en-US', {
+  'label.username': 'Username',
+  'label.email': 'Email',
+  'label.age': 'Age'
+});
+
+const app = express();
+const validator = new Validator();
+
+// ========== 中间件定义 ==========
+
+/**
+ * SchemaIO 验证中间件
+ *
+ * 1. 从请求头获取语言
+ * 2. 创建绑定了语言的 validate 方法
+ * 3. 挂载到 req 对象上
+ */
+const schemaIoMiddleware = (req, res, next) => {
+  // 获取语言 (支持 accept-language 头或 query 参数)
+  const lang = req.query.lang || req.headers['accept-language'] || 'en-US';
+
+  // 简单的语言匹配逻辑 (例如取前两个字符或完整匹配)
+  // 这里假设完整匹配，实际项目中可能需要更复杂的解析
+  const locale = lang.includes('zh') ? 'zh-CN' :
+                 lang.includes('ja') ? 'ja-JP' :
+                 lang.includes('es') ? 'es-ES' :
+                 lang.includes('fr') ? 'fr-FR' : 'en-US';
+
+  // 挂载 validate 方法
+  req.validate = (schema, data) => {
+    return validator.validate(schema, data, { locale });
+  };
+
+  next();
+};
+
+app.use(schemaIoMiddleware);
+app.use(express.json());
+
+// ========== 路由定义 ==========
+
+const userSchema = dsl({
+  username: 'string:3-32!'.username(), // 自动查找 label.username
+  email: 'email!',                     // 自动查找 label.email
+  age: 'integer:0-150'                 // 自动查找 label.age
+});
+
+app.post('/users', (req, res) => {
+  const result = req.validate(userSchema, req.body);
+
+  if (!result.valid) {
+    return res.status(400).json({
+      error: 'Validation Failed',
+      details: result.errors.map(e => e.message)
+    });
+  }
+
+  res.json({ message: 'User created', data: result.data });
+});
+
+// ========== 启动服务器 (仅用于演示) ==========
+
+if (require.main === module) {
+  const port = 3000;
+  app.listen(port, () => {
+    console.log(`Server running at http://localhost:${port}`);
+    console.log('Try sending POST /users with different Accept-Language headers');
+    console.log('Example: curl -X POST http://localhost:3000/users -H "Content-Type: application/json" -H "Accept-Language: zh-CN" -d "{}"');
+  });
+}
+
+module.exports = app;
+
+

package/examples/password-reset/README.md

@@ -0,0 +1,153 @@
+# 密码重置示例
+
+完整的密码重置验证示例，展示 ref() 功能的实际应用。
+
+## 功能展示
+
+- ✅ 字段引用（ref）
+- ✅ 密码强度验证
+- ✅ 密码确认验证
+- ✅ 错误消息定制
+- ✅ 多语言支持
+
+## 文件结构
+
+```
+examples/password-reset/
+├── README.md          # 本文件
+├── schema.js          # Schema定义
+└── test.js            # 测试示例
+```
+
+## Schema定义
+
+```javascript
+const { dsl } = require('schema-dsl');
+const Locale = require('schema-dsl/lib/core/Locale');
+
+// 设置中文
+Locale.setLocale('zh-CN');
+
+const passwordResetSchema = dsl({
+  // 新密码：8-64字符，必须包含大小写字母和数字
+  newPassword: 'string:8-64!'
+    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
+    .label('新密码')
+    .messages({
+      'minLength': '{{#label}}长度不能少于8位',
+      'maxLength': '{{#label}}长度不能超过64位',
+      'pattern': '{{#label}}必须包含大小写字母和数字'
+    }),
+  
+  // 确认密码：必填
+  confirmPassword: 'string:8-64!'
+    .label('确认密码')
+    .custom((value, helpers, { parent }) => {
+      if (value !== parent.newPassword) {
+        return '两次输入的密码不一致';
+      }
+    })
+});
+
+module.exports = passwordResetSchema;
+```
+
+## 使用示例
+
+```javascript
+const passwordResetSchema = require('./schema');
+
+// 成功案例
+const validData = {
+  newPassword: 'Password123',
+  confirmPassword: 'Password123'
+};
+
+const result1 = await passwordResetSchema.validate(validData, {
+  root: validData
+});
+console.log(result1.isValid);  // true
+
+// 失败案例1：密码不一致
+const invalidData1 = {
+  newPassword: 'Password123',
+  confirmPassword: 'Different123'
+};
+
+const result2 = await passwordResetSchema.validate(invalidData1, {
+  root: invalidData1
+});
+console.log(result2.errors[0].message);
+// "两次输入的密码不一致"
+
+// 失败案例2：密码强度不够
+const invalidData2 = {
+  newPassword: 'weak',
+  confirmPassword: 'weak'
+};
+
+const result3 = await passwordResetSchema.validate(invalidData2, {
+  root: invalidData2
+});
+console.log(result3.errors);
+// [
+//   { message: "新密码长度不能少于8位", type: "string.min" },
+//   { message: "新密码必须包含大小写字母和数字", type: "string.pattern" }
+// ]
+```
+
+## Express路由示例
+
+```javascript
+const express = require('express');
+const passwordResetSchema = require('./schema');
+
+const router = express.Router();
+
+router.post('/reset-password', async (req, res) => {
+  const result = await passwordResetSchema.validate(req.body, {
+    root: req.body,
+    abortEarly: false
+  });
+
+  if (!result.isValid) {
+    return res.status(400).json({
+      success: false,
+      errors: result.errors.map(err => ({
+        field: err.path?.join('.') || err.context?.key,
+        message: err.message
+      }))
+    });
+  }
+
+  // 更新密码逻辑...
+  res.json({ success: true, message: '密码重置成功' });
+});
+
+module.exports = router;
+```
+
+## 测试
+
+```bash
+# 安装依赖
+npm install schema-dsl
+
+# 运行测试
+node examples/password-reset/test.js
+```
+
+## 核心要点
+
+1. **ref()功能**: 使用 `ref('newPassword')` 引用新密码字段
+2. **密码强度**: 使用正则表达式验证密码强度
+3. **错误消息**: 自定义友好的中文错误提示
+4. **上下文传递**: 验证时传递 `{ root: data }` 使ref可以解析
+
+## 扩展建议
+
+1. 添加旧密码验证
+2. 添加密码历史检查（不能与最近3次密码相同）
+3. 添加密码强度指示器
+4. 集成验证码验证
+

package/examples/password-reset/schema.js

@@ -0,0 +1,26 @@
+/**
+ * 密码重置Schema定义
+ * 使用DSL语法定义
+ */
+
+const { dsl } = require('../../index');
+const Locale = require('../../lib/core/Locale');
+
+// 设置中文
+Locale.setLocale('zh-CN');
+
+// 使用DSL定义密码重置Schema
+const passwordResetSchema = dsl({
+  // 新密码：8-64字符
+  newPassword: 'string:8-64!',
+
+  // 确认密码：必填
+  confirmPassword: 'string:8-64!'
+});
+
+// 注意：ref功能需要在validate时手动检查
+// 因为DSL目前不直接支持ref，这是一个简化示例
+
+module.exports = passwordResetSchema;
+
+

package/examples/password-reset/test.js

@@ -0,0 +1,101 @@
+/**
+ * 密码重置测试示例
+ */
+
+const passwordResetSchema = require('./schema');
+
+async function runTests() {
+  console.log('========================================');
+  console.log('  密码重置验证测试');
+  console.log('========================================\n');
+
+  // 测试1：成功案例
+  console.log('【测试1】成功案例');
+  const validData = {
+    newPassword: 'Password123',
+    confirmPassword: 'Password123'
+  };
+
+  const result1 = await passwordResetSchema.validate(validData, {
+    root: validData
+  });
+
+  console.log('数据:', validData);
+  console.log('结果:', result1.isValid ? '✅ 验证通过' : '❌ 验证失败');
+  if (!result1.isValid) {
+    console.log('错误:', result1.errors);
+  }
+  console.log('');
+
+  // 测试2：密码不一致
+  console.log('【测试2】密码不一致');
+  const invalidData1 = {
+    newPassword: 'Password123',
+    confirmPassword: 'Different123'
+  };
+
+  const result2 = await passwordResetSchema.validate(invalidData1, {
+    root: invalidData1,
+    abortEarly: false
+  });
+
+  console.log('数据:', invalidData1);
+  console.log('结果:', result2.isValid ? '✅ 验证通过' : '❌ 验证失败');
+  if (!result2.isValid) {
+    result2.errors.forEach(err => {
+      console.log(`  - ${err.message}`);
+    });
+  }
+  console.log('');
+
+  // 测试3：密码强度不够
+  console.log('【测试3】密码强度不够');
+  const invalidData2 = {
+    newPassword: 'weak',
+    confirmPassword: 'weak'
+  };
+
+  const result3 = await passwordResetSchema.validate(invalidData2, {
+    root: invalidData2,
+    abortEarly: false
+  });
+
+  console.log('数据:', invalidData2);
+  console.log('结果:', result3.isValid ? '✅ 验证通过' : '❌ 验证失败');
+  if (!result3.isValid) {
+    result3.errors.forEach(err => {
+      console.log(`  - ${err.message}`);
+    });
+  }
+  console.log('');
+
+  // 测试4：密码太长
+  console.log('【测试4】密码太长');
+  const invalidData3 = {
+    newPassword: 'A'.repeat(65) + 'a1',
+    confirmPassword: 'A'.repeat(65) + 'a1'
+  };
+
+  const result4 = await passwordResetSchema.validate(invalidData3, {
+    root: invalidData3,
+    abortEarly: false
+  });
+
+  console.log('数据: { newPassword: "' + invalidData3.newPassword.substring(0, 20) + '...", ... }');
+  console.log('结果:', result4.isValid ? '✅ 验证通过' : '❌ 验证失败');
+  if (!result4.isValid) {
+    result4.errors.forEach(err => {
+      console.log(`  - ${err.message}`);
+    });
+  }
+  console.log('');
+
+  console.log('========================================');
+  console.log('  测试完成');
+  console.log('========================================');
+}
+
+// 运行测试
+runTests().catch(console.error);
+
+

package/examples/plugin-system.examples.js

@@ -0,0 +1,205 @@
+/**
+ * 插件系统使用示例
+ */
+
+const { dsl, validate, PluginManager } = require('../index');
+
+// ========== 1. 基础使用 ==========
+
+console.log('=== 1. 基础使用 ===\n');
+
+// 创建插件管理器
+const pluginManager = new PluginManager();
+
+// 注册插件
+const customValidatorPlugin = require('../plugins/custom-validator');
+pluginManager.register(customValidatorPlugin);
+
+const customFormatPlugin = require('../plugins/custom-format');
+pluginManager.register(customFormatPlugin);
+
+// 安装插件
+const schemaDsl = require('../index');
+pluginManager.install(schemaDsl);
+
+console.log('已安装插件:', pluginManager.list());
+console.log('');
+
+// ========== 2. 使用自定义格式 ==========
+
+console.log('=== 2. 使用自定义格式 ===\n');
+
+const contactSchema = dsl({
+    phone: 'string!',
+    email: 'email!',
+    wechat: 'string'
+});
+
+// 测试数据
+const validContact = {
+    phone: '13800138000',
+    email: 'test@example.com',
+    wechat: 'my_wechat_id'
+};
+
+const result1 = validate(contactSchema, validContact);
+console.log('验证结果:', result1.valid ? '✅ 通过' : '❌ 失败');
+if (!result1.valid) {
+    console.log('错误:', result1.errors);
+}
+console.log('');
+
+// ========== 3. 使用钩子系统 ==========
+
+console.log('=== 3. 使用钩子系统 ===\n');
+
+// 注册钩子
+pluginManager.hook('onBeforeValidate', (schema, data) => {
+    console.log('[Hook] 验证前:', { schema: '...', data });
+});
+
+pluginManager.hook('onAfterValidate', (result) => {
+    console.log('[Hook] 验证后:', { valid: result.valid });
+});
+
+// 运行钩子
+const testSchema = dsl({ name: 'string!' });
+const testData = { name: 'John' };
+
+pluginManager.runHook('onBeforeValidate', testSchema, testData);
+const result2 = validate(testSchema, testData);
+pluginManager.runHook('onAfterValidate', result2);
+console.log('');
+
+// ========== 4. 自定义插件 ==========
+
+console.log('=== 4. 自定义插件 ===\n');
+
+// 创建自定义插件
+const myPlugin = {
+    name: 'my-plugin',
+    version: '1.0.0',
+    description: '我的自定义插件',
+
+    install(schemaDsl, options, context) {
+        console.log('[Plugin] my-plugin 安装中...');
+        console.log('  选项:', options);
+        console.log('  已注册插件数:', context.plugins.size);
+
+        // 添加自定义方法
+        schemaDsl.myCustomMethod = () => {
+            console.log('  这是自定义方法!');
+        };
+    },
+
+    uninstall(schemaDsl, context) {
+        console.log('[Plugin] my-plugin 卸载中...');
+        delete schemaDsl.myCustomMethod;
+    },
+
+    hooks: {
+        onBeforeValidate(schema, data) {
+            console.log('  [my-plugin] 验证前钩子');
+        }
+    }
+};
+
+// 注册并安装
+pluginManager.register(myPlugin);
+pluginManager.install(schemaDsl, 'my-plugin', { custom: true });
+
+// 使用自定义方法
+if (schemaDsl.myCustomMethod) {
+    schemaDsl.myCustomMethod();
+}
+console.log('');
+
+// ========== 5. 插件管理 ==========
+
+console.log('=== 5. 插件管理 ===\n');
+
+// 查看所有插件
+console.log('所有插件:', pluginManager.list());
+
+// 检查插件是否存在
+console.log('my-plugin 是否存在:', pluginManager.has('my-plugin'));
+
+// 获取插件数量
+console.log('插件数量:', pluginManager.size);
+console.log('');
+
+// ========== 6. 实用插件示例 ==========
+
+console.log('=== 6. 实用插件示例 ===\n');
+
+// 日志插件
+const loggingPlugin = {
+    name: 'logging',
+    version: '1.0.0',
+
+    install(schemaDsl, options, context) {
+        // 包装 validate 方法
+        const originalValidate = schemaDsl.validate;
+        schemaDsl.validate = function (...args) {
+            console.log('[Logging] 开始验证');
+            const start = Date.now();
+            const result = originalValidate.apply(this, args);
+            const duration = Date.now() - start;
+            console.log(`[Logging] 验证完成，耗时 ${duration}ms，结果: ${result.valid ? '通过' : '失败'}`);
+            return result;
+        };
+    }
+};
+
+pluginManager.register(loggingPlugin);
+pluginManager.install(schemaDsl, 'logging');
+
+// 测试日志插件
+const schema = dsl({ email: 'email!' });
+validate(schema, { email: 'test@example.com' });
+console.log('');
+
+// ========== 7. 卸载插件 ==========
+
+console.log('=== 7. 卸载插件 ===\n');
+
+pluginManager.uninstall('my-plugin', schemaDsl);
+console.log('my-plugin 已卸载');
+console.log('当前插件数:', pluginManager.size);
+console.log('');
+
+// ========== 8. 批量插件 ==========
+
+console.log('=== 8. 批量插件 ===\n');
+
+// 清空所有插件
+pluginManager.clear(schemaDsl);
+console.log('所有插件已清空');
+console.log('当前插件数:', pluginManager.size);
+console.log('');
+
+// 批量注册多个插件
+const plugins = [
+    customValidatorPlugin,
+    customFormatPlugin
+];
+
+plugins.forEach(plugin => pluginManager.register(plugin));
+pluginManager.install(schemaDsl); // 安装所有插件
+
+console.log('批量安装完成:', pluginManager.list());
+console.log('');
+
+// ========== 总结 ==========
+
+console.log('=== 总结 ===\n');
+console.log('✅ 插件系统支持:');
+console.log('  - 动态注册/卸载插件');
+console.log('  - 生命周期钩子');
+console.log('  - 自定义验证器和格式');
+console.log('  - 插件间通信');
+console.log('  - 事件监听');
+console.log('');
+console.log('示例运行完成！');
+
+

package/examples/simple-example.js

@@ -0,0 +1,122 @@
+/**
+ * SchemaIO v2.0.1 - 简洁示例
+ *
+ * 展示最简洁、最直观的用法
+ */
+
+const { dsl, validate, SchemaUtils } = require('../index');
+
+console.log('========== SchemaIO v2.0.1 简洁示例 ==========\n');
+
+// ========== 1. 数组验证 - 超简洁 ==========
+console.log('✨ 1. 数组验证');
+
+const articleSchema = dsl({
+  title: 'string:5-100!',
+  tags: 'array!1-10'  // ✨ 简洁：必填，1-10个元素
+});
+
+console.log('验证文章:', validate(articleSchema, {
+  title: 'Hello World',
+  tags: ['javascript', 'nodejs']
+}).valid);
+console.log('');
+
+// ========== 2. when条件 - 超直观 ==========
+console.log('✨ 2. 条件验证');
+
+const contactSchema = dsl({
+  type: 'email|phone',
+  contact: dsl.match('type', {
+    email: 'email!',
+    phone: 'phone:cn!'
+  })
+});
+
+console.log('验证邮箱:', validate(contactSchema, { type: 'email', contact: 'test@example.com' }).valid);
+console.log('验证手机:', validate(contactSchema, { type: 'phone', contact: '13800138000' }).valid);
+console.log('');
+
+// ========== 3. 快捷方法 - 不用找正则 ==========
+console.log('✨ 3. 快捷方法');
+
+const userSchema = dsl({
+  mobile: 'string!'.phoneNumber('cn'),
+  id: 'string!'.idCard('cn')
+});
+
+console.log('验证快捷方法:', validate(userSchema, {
+  mobile: '13800138000',
+  id: '110101199003071234'
+}).valid);
+console.log('');
+
+// ========== 4. Schema复用 - 不重复代码 ==========
+console.log('✨ 4. Schema复用');
+
+// 定义一次，到处使用
+const emailField = SchemaUtils.reusable(() => dsl('email!'));
+
+const loginForm = dsl({ email: emailField() });
+const registerForm = dsl({ email: emailField(), name: 'string!' });
+
+console.log('复用Schema成功');
+console.log('');
+
+// ========== 5. Schema合并 - 灵活组合 ==========
+console.log('✨ 5. Schema合并');
+
+const baseUser = dsl({ name: 'string!', email: 'email!' });
+const withAge = dsl({ age: 'number:18-120' });
+
+const fullUser = SchemaUtils.merge(baseUser, withAge);
+
+console.log('合并后字段:', Object.keys(fullUser.properties));
+console.log('');
+
+// ========== 6. 批量验证 - 快50倍 ==========
+console.log('✨ 6. 批量验证');
+
+const users = [
+  { email: 'user1@example.com' },
+  { email: 'invalid' },
+  { email: 'user3@example.com' }
+];
+
+const { Validator } = require('../index');
+const batchResult = SchemaUtils.validateBatch(
+  dsl({ email: 'email!' }),
+  users,
+  new Validator() // 批量验证需要 Validator 实例以复用编译结果
+);
+
+console.log('批量验证:', {
+  总数: batchResult.summary.total,
+  有效: batchResult.summary.valid,
+  无效: batchResult.summary.invalid,
+  耗时: `${batchResult.summary.duration}ms`
+});
+console.log('');
+
+// ========== 总结 ==========
+console.log('========== 核心理念 ==========');
+console.log(`
+✨ SchemaIO v2.0.1 三大特点：
+
+1. 简洁
+   'array!1-10'           // 一眼看懂
+   .phoneNumber('cn')     // 不用找正则
+
+2. 直观
+   dsl.match('type', {    // 清晰的条件映射
+     email: 'email!',
+     phone: 'string:11!'
+   })
+
+3. 强大
+   SchemaUtils.merge()    // 灵活组合
+   validateBatch()        // 快50倍
+
+🎉 简洁 + 直观 + 强大 = 完美验证库！
+`);
+