schema-dsl 1.0.0

package/examples/express-integration.js

@@ -0,0 +1,376 @@
+/**
+ * Express 集成示例 - 异步验证与 Schema 链式调用
+ * 
+ * 展示如何在 Express 中使用：
+ * 1. validateAsync 异步验证
+ * 2. ValidationError 错误处理
+ * 3. SchemaUtils 链式调用
+ * 4. 完整 CRUD 场景
+ * 
+ * @version 2.1.0
+ * @date 2025-12-29
+ */
+
+const express = require('express');
+const { dsl, validateAsync, ValidationError, SchemaUtils } = require('../index');
+
+const app = express();
+app.use(express.json());
+
+// ===== 模拟数据库 =====
+const db = {
+  users: [],
+  nextId: 1
+};
+
+// ===== 定义完整 User Schema =====
+const fullUserSchema = dsl({
+  id: 'objectId!',
+  name: 'string:1-50!',
+  email: 'email!',
+  password: 'string:8-32!',
+  age: 'integer:18-120',
+  role: 'admin|user|guest',
+  createdAt: 'date',
+  updatedAt: 'date'
+});
+
+// ===== 派生各种 Schema =====
+
+// POST /users - 创建用户 Schema（排除系统字段）
+const createUserSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+// GET /users/:id - 公开用户 Schema（移除敏感字段）
+const publicUserSchema = SchemaUtils.omit(fullUserSchema, ['password']);
+
+// PATCH /users/:id - 更新用户 Schema（部分验证）
+const updateUserSchema = SchemaUtils
+  .pick(fullUserSchema, ['name', 'age'])
+  .partial();
+
+// PUT /users/:id - 替换用户 Schema（排除系统字段）
+const replaceUserSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+// ===== 路由实现 =====
+
+/**
+ * POST /users - 创建用户
+ * 
+ * 使用 createUserSchema：
+ * - 排除系统字段（id, createdAt, updatedAt）
+ */
+app.post('/users', async (req, res, next) => {
+  try {
+    console.log('\n[POST /users] 创建用户');
+    console.log('请求体:', req.body);
+    
+    // 使用 validateAsync 验证
+    const data = await validateAsync(createUserSchema, req.body);
+    
+    console.log('验证通过，数据:', data);
+    
+    // 保存到数据库
+    const user = {
+      id: String(db.nextId++),
+      ...data,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+    
+    db.users.push(user);
+    
+    // 返回公开信息
+    const { validate } = require('../index');
+    const result = validate(publicUserSchema, user);
+    
+    console.log('返回数据:', result.data);
+    
+    res.status(201).json({
+      success: true,
+      user: result.data
+    });
+    
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * GET /users - 获取所有用户
+ * 
+ * 使用 publicUserSchema 自动移除敏感字段
+ */
+app.get('/users', (req, res) => {
+  console.log('\n[GET /users] 获取所有用户');
+  
+  const { validate } = require('../index');
+  
+  // 对每个用户应用 publicUserSchema
+  const publicUsers = db.users.map(user => {
+    const result = validate(publicUserSchema, user);
+    return result.data;
+  });
+  
+  console.log(`返回 ${publicUsers.length} 个用户`);
+  
+  res.json({
+    success: true,
+    count: publicUsers.length,
+    users: publicUsers
+  });
+});
+
+/**
+ * GET /users/:id - 获取单个用户
+ * 
+ * 使用 publicUserSchema 移除敏感字段
+ */
+app.get('/users/:id', (req, res) => {
+  console.log(`\n[GET /users/${req.params.id}] 获取用户`);
+  
+  const user = db.users.find(u => u.id === req.params.id);
+  
+  if (!user) {
+    console.log('用户不存在');
+    return res.status(404).json({
+      success: false,
+      error: '用户不存在'
+    });
+  }
+  
+  // 使用 clean 模式自动移除敏感字段
+  const { validate } = require('../index');
+  const result = validate(publicUserSchema, user);
+  
+  console.log('返回数据:', result.data);
+  
+  res.json({
+    success: true,
+    user: result.data
+  });
+});
+
+/**
+ * PATCH /users/:id - 部分更新用户
+ * 
+ * 使用 updateUserSchema：
+ * - 只验证 name 和 age
+ * - 部分验证（可选）
+ * - 宽松模式（允许额外字段）
+ */
+app.patch('/users/:id', async (req, res, next) => {
+  try {
+    console.log(`\n[PATCH /users/${req.params.id}] 部分更新用户`);
+    console.log('请求体:', req.body);
+    
+    const user = db.users.find(u => u.id === req.params.id);
+    
+    if (!user) {
+      console.log('用户不存在');
+      return res.status(404).json({
+        success: false,
+        error: '用户不存在'
+      });
+    }
+    
+    // 验证部分数据
+    const data = await validateAsync(updateUserSchema, req.body);
+    
+    console.log('验证通过，更新字段:', data);
+    
+    // 更新用户
+    Object.assign(user, data, {
+      updatedAt: new Date().toISOString()
+    });
+    
+    // 返回公开信息
+    const { validate } = require('../index');
+    const result = validate(publicUserSchema, user);
+    
+    console.log('返回数据:', result.data);
+    
+    res.json({
+      success: true,
+      user: result.data
+    });
+    
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * PUT /users/:id - 替换用户
+ * 
+ * 使用 replaceUserSchema：
+ * - 排除系统字段
+ * - 严格模式（必填字段必须全部提供）
+ */
+app.put('/users/:id', async (req, res, next) => {
+  try {
+    console.log(`\n[PUT /users/${req.params.id}] 替换用户`);
+    console.log('请求体:', req.body);
+    
+    const userIndex = db.users.findIndex(u => u.id === req.params.id);
+    
+    if (userIndex === -1) {
+      console.log('用户不存在');
+      return res.status(404).json({
+        success: false,
+        error: '用户不存在'
+      });
+    }
+    
+    // 验证完整数据
+    const data = await validateAsync(replaceUserSchema, req.body);
+    
+    console.log('验证通过，替换用户:', data);
+    
+    // 替换用户（保留 id 和 createdAt）
+    const oldUser = db.users[userIndex];
+    db.users[userIndex] = {
+      id: oldUser.id,
+      ...data,
+      createdAt: oldUser.createdAt,
+      updatedAt: new Date().toISOString()
+    };
+    
+    // 返回公开信息
+    const { validate } = require('../index');
+    const result = validate(publicUserSchema, db.users[userIndex]);
+    
+    console.log('返回数据:', result.data);
+    
+    res.json({
+      success: true,
+      user: result.data
+    });
+    
+  } catch (error) {
+    next(error);
+  }
+});
+
+/**
+ * DELETE /users/:id - 删除用户
+ */
+app.delete('/users/:id', (req, res) => {
+  console.log(`\n[DELETE /users/${req.params.id}] 删除用户`);
+  
+  const userIndex = db.users.findIndex(u => u.id === req.params.id);
+  
+  if (userIndex === -1) {
+    console.log('用户不存在');
+    return res.status(404).json({
+      success: false,
+      error: '用户不存在'
+    });
+  }
+  
+  db.users.splice(userIndex, 1);
+  
+  console.log('删除成功');
+  
+  res.json({
+    success: true,
+    message: '用户已删除'
+  });
+});
+
+// ===== 全局错误处理中间件 =====
+
+/**
+ * ValidationError 错误处理
+ * 
+ * 自动捕获 validateAsync 抛出的 ValidationError
+ * 返回友好的错误信息
+ */
+app.use((error, req, res, next) => {
+  if (error instanceof ValidationError) {
+    console.log('\n[错误] ValidationError 被捕获');
+    console.log('错误数量:', error.getErrorCount());
+    console.log('字段错误:', error.getFieldErrors());
+    
+    return res.status(error.statusCode).json(error.toJSON());
+  }
+  
+  // 其他错误
+  console.error('\n[错误] 服务器错误:', error);
+  res.status(500).json({
+    error: 'Internal Server Error',
+    message: error.message
+  });
+});
+
+// ===== 启动服务器 =====
+
+const PORT = 3000;
+
+app.listen(PORT, () => {
+  console.log(`\n========================================`);
+  console.log(`  Express 集成示例服务器已启动`);
+  console.log(`  监听端口: ${PORT}`);
+  console.log(`========================================\n`);
+  console.log(`可用的 API 端点:`);
+  console.log(`  POST   http://localhost:${PORT}/users - 创建用户`);
+  console.log(`  GET    http://localhost:${PORT}/users - 获取所有用户`);
+  console.log(`  GET    http://localhost:${PORT}/users/:id - 获取单个用户`);
+  console.log(`  PATCH  http://localhost:${PORT}/users/:id - 部分更新用户`);
+  console.log(`  PUT    http://localhost:${PORT}/users/:id - 替换用户`);
+  console.log(`  DELETE http://localhost:${PORT}/users/:id - 删除用户`);
+  console.log(`\n========================================\n`);
+  
+  // 打印测试命令
+  printTestCommands();
+});
+
+// ===== 测试命令 =====
+
+function printTestCommands() {
+  console.log(`测试命令（使用 curl）:\n`);
+  
+  console.log(`# 1. 创建用户（成功）`);
+  console.log(`curl -X POST http://localhost:${PORT}/users \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"name":"John Doe","email":"john@example.com","password":"password123","age":30,"role":"user"}'\n`);
+  
+  console.log(`# 2. 创建用户（失败 - 缺少必填字段）`);
+  console.log(`curl -X POST http://localhost:${PORT}/users \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"name":"Jane"}'\n`);
+  
+  console.log(`# 3. 创建用户（失败 - 额外字段被拒绝）`);
+  console.log(`curl -X POST http://localhost:${PORT}/users \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"name":"Bob","email":"bob@example.com","password":"password123","extraField":"not allowed"}'\n`);
+  
+  console.log(`# 4. 获取所有用户`);
+  console.log(`curl http://localhost:${PORT}/users\n`);
+  
+  console.log(`# 5. 获取单个用户（替换 ID）`);
+  console.log(`curl http://localhost:${PORT}/users/1\n`);
+  
+  console.log(`# 6. 部分更新用户（成功 - 只更新 name）`);
+  console.log(`curl -X PATCH http://localhost:${PORT}/users/1 \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"name":"John Updated"}'\n`);
+  
+  console.log(`# 7. 部分更新用户（成功 - 允许额外字段）`);
+  console.log(`curl -X PATCH http://localhost:${PORT}/users/1 \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"age":31,"extraField":"allowed"}'\n`);
+  
+  console.log(`# 8. 替换用户（成功 - 必须提供所有必填字段）`);
+  console.log(`curl -X PUT http://localhost:${PORT}/users/1 \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"name":"John Replaced","email":"john.new@example.com","password":"newpassword123","age":32}'\n`);
+  
+  console.log(`# 9. 删除用户`);
+  console.log(`curl -X DELETE http://localhost:${PORT}/users/1\n`);
+  
+  console.log(`========================================\n`);
+}
+
+// 导出 app 用于测试
+module.exports = app;
+

package/examples/i18n-full-demo.js

@@ -0,0 +1,310 @@
+/**
+ * 完整的多语言配置示例
+ *
+ * 演示如何使用 dsl.config() 配置用户自定义语言包
+ * 以及如何在 Express 应用中实现动态语言切换
+ */
+
+const express = require('express');
+const { dsl, validate, Locale } = require('../index');
+const path = require('path');
+
+console.log('========== 多语言配置完整示例 ==========\n');
+
+// ========================================
+// 步骤 1：应用启动时配置
+// ========================================
+console.log('【步骤 1】配置用户语言包和缓存\n');
+
+dsl.config({
+  // 用户语言包配置
+  i18n: {
+    // 方式 A：从目录加载（推荐用于大型项目）
+    // localesPath: path.join(__dirname, 'i18n/labels'),
+
+    // 方式 B：直接传入对象（推荐用于小型项目）
+    locales: {
+      'zh-CN': {
+        // 字段标签
+        'username': '用户名',
+        'email': '邮箱地址',
+        'password': '密码',
+        'age': '年龄',
+        'phone': '手机号',
+
+        // 嵌套字段
+        'address.city': '城市',
+        'address.street': '街道',
+
+        // 自定义错误消息
+        'custom.invalidEmail': '邮箱格式不正确，请重新输入',
+        'custom.emailTaken': '该邮箱已被注册',
+        'custom.usernameTaken': '该用户名已被使用',
+        'custom.passwordWeak': '密码强度不够，请包含大小写字母和数字'
+      },
+      'en-US': {
+        // Field labels
+        'username': 'Username',
+        'email': 'Email Address',
+        'password': 'Password',
+        'age': 'Age',
+        'phone': 'Phone Number',
+
+        // Nested fields
+        'address.city': 'City',
+        'address.street': 'Street',
+
+        // Custom error messages
+        'custom.invalidEmail': 'Invalid email format, please try again',
+        'custom.emailTaken': 'This email is already registered',
+        'custom.usernameTaken': 'This username is already taken',
+        'custom.passwordWeak': 'Password is too weak, please include uppercase, lowercase and numbers'
+      },
+      'ja-JP': {
+        // フィールドラベル
+        'username': 'ユーザー名',
+        'email': 'メールアドレス',
+        'password': 'パスワード',
+        'age': '年齢',
+        'phone': '電話番号',
+
+        // ネストされたフィールド
+        'address.city': '都市',
+        'address.street': '通り',
+
+        // カスタムエラーメッセージ
+        'custom.invalidEmail': 'メール形式が正しくありません',
+        'custom.emailTaken': 'このメールは既に登録されています',
+        'custom.usernameTaken': 'このユーザー名は既に使用されています',
+        'custom.passwordWeak': 'パスワードが弱すぎます'
+      }
+    }
+  },
+
+  // 缓存配置（可选，大型项目推荐）
+  cache: {
+    maxSize: 10000,   // 大型项目：1万个 Schema
+    ttl: 7200000      // 2 小时
+  }
+});
+
+console.log('✅ 配置完成\n');
+
+// ========================================
+// 步骤 2：定义 Schema（使用 key 引用语言包）
+// ========================================
+console.log('【步骤 2】定义 Schema\n');
+
+const userSchema = dsl({
+  username: 'string:3-32!'.label('username'),
+  email: 'email!'.label('email').messages({
+    'format': 'custom.invalidEmail'
+  }),
+  password: 'string:8-32!'.label('password'),
+  age: 'number:18-120'.label('age'),
+  phone: 'string'.label('phone'),
+  address: dsl({
+    city: 'string!'.label('address.city'),
+    street: 'string!'.label('address.street')
+  })
+});
+
+console.log('✅ Schema 定义完成\n');
+
+// ========================================
+// 步骤 3：测试不同语言的验证
+// ========================================
+console.log('【步骤 3】测试多语言验证\n');
+
+const testData = {
+  username: 'ab',
+  email: 'invalid-email',
+  password: '123',
+  age: 15,
+  address: {}
+};
+
+// 中文
+console.log('--- 中文验证 ---');
+let result = validate(userSchema, testData, { locale: 'zh-CN' });
+console.log('有效:', result.valid);
+console.log('错误:');
+result.errors.forEach(err => {
+  console.log(`  - ${err.path}: ${err.message}`);
+});
+
+console.log('\n--- 英文验证 ---');
+result = validate(userSchema, testData, { locale: 'en-US' });
+console.log('有效:', result.valid);
+console.log('错误:');
+result.errors.forEach(err => {
+  console.log(`  - ${err.path}: ${err.message}`);
+});
+
+console.log('\n--- 日文验证 ---');
+result = validate(userSchema, testData, { locale: 'ja-JP' });
+console.log('有效:', result.valid);
+console.log('错误:');
+result.errors.forEach(err => {
+  console.log(`  - ${err.path}: ${err.message}`);
+});
+
+console.log('\n========================================');
+console.log('【步骤 4】Express 集成示例');
+console.log('========================================\n');
+
+// ========================================
+// Express 应用示例
+// ========================================
+
+const app = express();
+app.use(express.json());
+
+// 中间件：提取语言参数
+app.use((req, res, next) => {
+  // 优先级：URL 参数 > Accept-Language 头 > 默认
+  req.locale = req.query.lang ||
+               req.headers['accept-language'] ||
+               'zh-CN';
+
+  // 只取主语言代码
+  if (req.locale.includes(',')) {
+    req.locale = req.locale.split(',')[0].trim();
+  }
+
+  next();
+});
+
+// API 路由：用户注册
+app.post('/api/register', (req, res) => {
+  console.log(`\n[POST /api/register] 语言: ${req.locale}`);
+
+  // 使用全局 validate，传递 locale 参数
+  const result = validate(userSchema, req.body, {
+    locale: req.locale
+  });
+
+  if (!result.valid) {
+    return res.status(400).json({
+      success: false,
+      errors: result.errors
+    });
+  }
+
+  // 注册逻辑...
+  res.json({
+    success: true,
+    message: '注册成功'
+  });
+});
+
+// 健康检查
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+// 启动服务器
+const PORT = 3000;
+const server = app.listen(PORT, () => {
+  console.log(`✅ Express 服务器启动成功`);
+  console.log(`   地址: http://localhost:${PORT}`);
+  console.log(`\n测试 API:`);
+  console.log(`   curl -X POST http://localhost:${PORT}/api/register \\`);
+  console.log(`     -H "Content-Type: application/json" \\`);
+  console.log(`     -H "Accept-Language: zh-CN" \\`);
+  console.log(`     -d '{"username":"ab","email":"bad"}'`);
+  console.log(`\n按 Ctrl+C 停止服务器\n`);
+});
+
+// 优雅关闭
+process.on('SIGINT', () => {
+  console.log('\n\n正在关闭服务器...');
+  server.close(() => {
+    console.log('服务器已关闭');
+    process.exit(0);
+  });
+});
+
+// ========================================
+// 前端集成示例（React）
+// ========================================
+
+console.log('========================================');
+console.log('【步骤 5】前端集成示例（React）');
+console.log('========================================\n');
+
+const frontendExample = `
+// src/api/validation.js
+export async function validateUser(formData, locale = 'zh-CN') {
+  const response = await fetch('http://localhost:3000/api/register', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept-Language': locale  // ← 传递语言
+    },
+    body: JSON.stringify(formData)
+  });
+  
+  return response.json();
+}
+
+// src/components/RegisterForm.jsx
+import { useState } from 'react';
+import { validateUser } from '../api/validation';
+
+function RegisterForm() {
+  const [locale, setLocale] = useState('zh-CN');
+  const [errors, setErrors] = useState([]);
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    
+    const formData = {
+      username: e.target.username.value,
+      email: e.target.email.value,
+      password: e.target.password.value,
+      age: Number(e.target.age.value)
+    };
+
+    const result = await validateUser(formData, locale);
+    
+    if (!result.success) {
+      setErrors(result.errors);
+    } else {
+      alert('注册成功！');
+    }
+  };
+
+  return (
+    <div>
+      {/* 语言切换 */}
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        <option value="zh-CN">中文</option>
+        <option value="en-US">English</option>
+        <option value="ja-JP">日本語</option>
+      </select>
+
+      <form onSubmit={handleSubmit}>
+        <input name="username" placeholder="用户名" />
+        <input name="email" type="email" placeholder="邮箱" />
+        <input name="password" type="password" placeholder="密码" />
+        <input name="age" type="number" placeholder="年龄" />
+        <button type="submit">注册</button>
+      </form>
+
+      {/* 错误显示 */}
+      {errors.map(err => (
+        <div key={err.path} style={{ color: 'red' }}>
+          {err.message}  {/* 已经是对应语言 */}
+        </div>
+      ))}
+    </div>
+  );
+}
+`;
+
+console.log('React 示例代码:');
+console.log(frontendExample);
+
+console.log('\n========== 示例完成 ==========');
+