schema-dsl 2.3.0 → 2.3.1

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/new-features-comparison.js

@@ -0,0 +1,315 @@
+/**
+ * SchemaIO v2.1.0 新旧 API 对比示例
+ *
+ * 展示新功能如何简化代码和提升开发体验
+ */
+
+const { dsl, validate, validateAsync, ValidationError, SchemaUtils } = require('../index');
+
+console.log('========================================');
+console.log('SchemaIO v2.1.0 新旧 API 对比');
+console.log('========================================\n');
+
+// ==========================================
+// 场景 1：异步验证方法
+// ==========================================
+
+console.log('【场景 1】异步验证方法 - 自动抛出错误\n');
+
+const userSchema = dsl({
+  name: 'string:1-50!',
+  email: 'email!',
+  age: 'integer:18-120'
+});
+
+// --- 旧方法 ---
+console.log('❌ 旧方法（手动检查 valid）：');
+function validateUserOldWay(data) {
+  const result = validate(userSchema, data);
+
+  if (!result.valid) {
+    const errors = result.errors.map(e => e.message).join(', ');
+    throw new Error(`验证失败: ${errors}`);
+  }
+
+  return result.data;
+}
+
+try {
+  validateUserOldWay({ name: '', email: 'invalid' });
+} catch (error) {
+  console.log('  错误:', error.message);
+}
+
+// --- 新方法 ---
+console.log('\n✅ 新方法（自动抛出错误）：');
+async function validateUserNewWay(data) {
+  return await validateAsync(userSchema, data);
+}
+
+(async () => {
+  try {
+    await validateUserNewWay({ name: '', email: 'invalid' });
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      console.log('  错误:', error.message);
+      console.log('  详细:', error.toJSON());
+    }
+  }
+})();
+
+console.log('\n代码行数对比：');
+console.log('  旧方法: 8 行代码');
+console.log('  新方法: 2 行代码（减少 75%）\n');
+
+// ==========================================
+// 场景 2：Express 路由
+// ==========================================
+
+console.log('【场景 2】Express 路由 - 统一错误处理\n');
+
+// --- 旧方法 ---
+console.log('❌ 旧方法（每个路由都要检查）：');
+console.log(`
+app.post('/users', (req, res) => {
+  const result = validate(userSchema, req.body);
+  
+  if (!result.valid) {
+    return res.status(400).json({
+      error: 'Validation Failed',
+      details: result.errors
+    });
+  }
+  
+  // 继续处理...
+});
+`);
+
+// --- 新方法 ---
+console.log('✅ 新方法（统一错误处理）：');
+console.log(`
+// 全局错误处理中间件（只写一次）
+app.use((error, req, res, next) => {
+  if (error instanceof ValidationError) {
+    return res.status(400).json(error.toJSON());
+  }
+  next(error);
+});
+
+// 路由中使用（简洁）
+app.post('/users', async (req, res, next) => {
+  try {
+    const data = await validateAsync(userSchema, req.body);
+    const user = await db.users.insert(data);
+    res.json(user);
+  } catch (error) {
+    next(error);
+  }
+});
+`);
+
+console.log('优势：');
+console.log('  ✓ 错误处理代码减少 60%');
+console.log('  ✓ 统一错误响应格式');
+console.log('  ✓ 代码更易维护\n');
+
+// ==========================================
+// 场景 3：Schema 复用 - 严格验证
+// ==========================================
+
+console.log('【场景 3】Schema 复用 - 处理额外字段\n');
+
+const baseUserSchema = dsl({
+  name: 'string:1-50!',
+  email: 'email!'
+});
+
+const testData = {
+  name: 'John Doe',
+  email: 'john@example.com',
+  avatar: 'https://example.com/avatar.jpg' // 额外字段
+};
+
+// --- 旧方法 ---
+console.log('❌ 旧方法（无法灵活处理额外字段）：');
+const result1 = validate(baseUserSchema, testData);
+console.log('  验证结果:', result1.valid ? '通过' : '失败');
+console.log('  问题: 需要手动筛选字段\n');
+
+// --- 新方法: omit ---
+console.log('✅ 新方法 - omit（排除敏感字段）：');
+const publicSchema = SchemaUtils.omit(baseUserSchema, ['password']);
+const result2 = validate(publicSchema, testData);
+console.log('  验证结果:', result2.valid ? '通过' : '失败');
+console.log('  返回数据（自动移除password）:', result2.data);
+
+// --- 新方法: extend ---
+console.log('\n✅ 新方法 - extend（扩展字段）：');
+const extendedSchema = SchemaUtils.extend(
+  baseUserSchema,
+  { avatar: 'url' }
+);
+const result4 = validate(extendedSchema, testData);
+console.log('  验证结果:', result4.valid ? '通过' : '失败');
+console.log('  avatar 被验证:', result4.data.avatar);
+
+console.log('\n提供的模式：');
+console.log('  1. strict()  - 严格验证，拒绝额外字段');
+console.log('  2. loose()   - 宽松模式，允许额外字段');
+console.log('  3. clean()   - 清理模式，移除额外字段');
+console.log('  4. extend()  - 扩展模式，验证指定字段');
+console.log('  5. partial() - 部分验证，只验证指定字段\n');
+
+// ==========================================
+// 场景 4：CRUD 完整示例
+// ==========================================
+
+console.log('【场景 4】CRUD 完整示例\n');
+
+const fullUserSchema = dsl({
+  id: 'objectId!',
+  name: 'string:1-50!',
+  email: 'email!',
+  password: 'string:8-32!',
+  age: 'integer:0-150',
+  createdAt: 'date',
+  updatedAt: 'date'
+});
+
+// --- 旧方法 ---
+console.log('❌ 旧方法（为每个场景重复定义 Schema）：');
+console.log(`
+// POST /users
+const createUserSchemaOld = dsl({
+  name: 'string:1-50!',
+  email: 'email!',
+  password: 'string:8-32!',
+  age: 'integer:0-150'
+});
+
+// PATCH /users/:id
+const updateUserSchemaOld = dsl({
+  name: 'string:1-50',
+  age: 'integer:0-150'
+});
+
+// GET /users/:id
+const publicUserSchemaOld = dsl({
+  id: 'objectId!',
+  name: 'string:1-50!',
+  email: 'email!',
+  age: 'integer:0-150',
+  createdAt: 'date',
+  updatedAt: 'date'
+});
+
+问题：重复代码多，修改不便
+`);
+
+// --- 新方法 ---
+console.log('✅ 新方法（复用 + 灵活处理）：');
+console.log(`
+// 定义一次
+const fullUserSchema = dsl({ ... });
+
+// POST /users - 排除系统字段
+const createSchema = SchemaUtils.omit(fullUserSchema, ['id', 'createdAt', 'updatedAt']);
+
+// PATCH /users/:id - 部分更新
+const updateSchema = SchemaUtils.partial(fullUserSchema, ['name', 'age']);
+
+// GET /users/:id - 排除敏感字段
+const publicSchema = SchemaUtils.omit(fullUserSchema, ['password']);
+
+优势：
+  ✓ 单一数据源，修改方便
+  ✓ 代码量减少 70%
+  ✓ 灵活的字段处理
+`);
+
+// ==========================================
+// 场景 5：业务逻辑
+// ==========================================
+
+console.log('【场景 5】业务逻辑 - Service 层\n');
+
+// --- 旧方法 ---
+console.log('❌ 旧方法（手动检查）：');
+console.log(`
+class UserService {
+  create(data) {
+    const result = validate(createUserSchema, data);
+    
+    if (!result.valid) {
+      const errors = result.errors.map(e => e.message).join(', ');
+      throw new Error(\`验证失败: \${errors}\`);
+    }
+    
+    return db.users.insert(result.data);
+  }
+  
+  update(id, data) {
+    const result = validate(updateUserSchema, data);
+    
+    if (!result.valid) {
+      const errors = result.errors.map(e => e.message).join(', ');
+      throw new Error(\`验证失败: \${errors}\`);
+    }
+    
+    return db.users.update(id, result.data);
+  }
+}
+`);
+
+// --- 新方法 ---
+console.log('✅ 新方法（自动抛出）：');
+console.log(`
+class UserService {
+  async create(data) {
+    const validData = await validateAsync(createUserSchema, data);
+    return await db.users.insert(validData);
+  }
+  
+  async update(id, data) {
+    const validData = await validateAsync(updateUserSchema, data);
+    return await db.users.update(id, validData);
+  }
+}
+
+优势：
+  ✓ 代码行数减少 60%
+  ✓ 逻辑更清晰
+  ✓ 无需重复错误处理代码
+`);
+
+// ==========================================
+// 总结
+// ==========================================
+
+console.log('\n========================================');
+console.log('总结');
+console.log('========================================\n');
+
+console.log('异步验证方法（validateAsync）：');
+console.log('  ✓ 减少 75% 的验证代码');
+console.log('  ✓ 统一错误处理');
+console.log('  ✓ 更符合异步编程习惯\n');
+
+console.log('灵活的 Schema 复用：');
+console.log('  ✓ 5 种模式覆盖所有场景');
+console.log('  ✓ 代码量减少 70%');
+console.log('  ✓ 单一数据源，易于维护\n');
+
+console.log('迁移成本：');
+console.log('  ✓ 100% 向后兼容');
+console.log('  ✓ 无需修改现有代码');
+console.log('  ✓ 可选择性使用新 API\n');
+
+console.log('========================================\n');
+
+module.exports = {
+  userSchema,
+  baseUserSchema,
+  fullUserSchema
+};
+