schema-dsl 2.3.0

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========== 示例完成 ==========');
+

package/examples/i18n-memory-safety.examples.js

@@ -0,0 +1,268 @@
+/**
+ * i18n 内存安全示例
+ * 
+ * 演示如何使用 LRU 缓存防止内存泄漏
+ * 正确实现：缓存完整的语言包对象，而非单个消息
+ * 
+ * @version 2.2.1
+ */
+
+const { Validator, Locale } = require('../index');
+const LRUCache = require('../lib/utils/LRUCache');
+
+console.log('========== i18n 内存安全示例 ==========\n');
+
+// ========== 1. 问题：无限制缓存导致内存泄漏 ==========
+
+console.log('❌ 问题场景：无限制语言包缓存');
+console.log('-----------------------------------');
+
+class UnsafeLocale {
+    static languagePackCache = new Map();  // ⚠️ 无容量限制
+
+    static getLanguagePack(locale) {
+        if (!this.languagePackCache.has(locale)) {
+            // 模拟加载整个语言包（包含所有错误消息）
+            const pack = this.loadLanguagePack(locale);
+            this.languagePackCache.set(locale, pack);  // ⚠️ 永远不清理
+        }
+
+        return this.languagePackCache.get(locale);
+    }
+
+    static loadLanguagePack(locale) {
+        // 模拟加载完整语言包（10个错误类型）
+        const pack = {};
+        const errorTypes = ['required', 'minLength', 'maxLength', 'pattern', 'email',
+            'url', 'type', 'enum', 'minimum', 'maximum'];
+        errorTypes.forEach(type => {
+            pack[type] = `[${locale}] ${type} error message`;
+        });
+        return pack;
+    }
+
+    static getMessage(locale, key) {
+        const pack = this.getLanguagePack(locale);
+        return pack[key] || `Unknown error: ${key}`;
+    }
+}
+
+// 模拟多租户场景：100个租户使用50种不同语言
+console.log('\n模拟 100 个租户，使用 50 种不同语言...');
+const locales = [];
+for (let i = 1; i <= 50; i++) {
+    locales.push(`lang-${i}`);
+}
+
+for (let tenant = 1; tenant <= 100; tenant++) {
+    const locale = locales[tenant % 50];  // 每个租户使用不同语言
+    UnsafeLocale.getMessage(locale, 'required');
+}
+
+console.log(`缓存语言包数: ${UnsafeLocale.languagePackCache.size}`);
+console.log('⚠️ 风险：50种语言 = 50个语言包缓存，无限增长');
+
+// ========== 2. 解决方案：LRU 缓存语言包 ==========
+
+console.log('\n\n✅ 解决方案：LRU 缓存（推荐）');
+console.log('-----------------------------------');
+console.log('关键：一个语言只有一个缓存（缓存完整语言包对象）\n');
+
+class SafeLocale {
+    // ✅ 使用 LRU 缓存，最多缓存 10 个语言包
+    static languagePackCache = new LRUCache({
+        maxSize: 10,
+        enableStats: true
+    });
+
+    static getLanguagePack(locale) {
+        // 尝试从缓存获取
+        let pack = this.languagePackCache.get(locale);
+
+        if (!pack) {
+            // 缓存未命中，加载语言包
+            pack = this.loadLanguagePack(locale);
+            this.languagePackCache.set(locale, pack);  // ✅ 自动清理最少使用的语言包
+            console.log(`  [加载] 语言包: ${locale}`);
+        }
+
+        return pack;
+    }
+
+    static loadLanguagePack(locale) {
+        // 模拟加载完整语言包
+        const pack = {};
+        const errorTypes = ['required', 'minLength', 'maxLength', 'pattern', 'email',
+            'url', 'type', 'enum', 'minimum', 'maximum'];
+        errorTypes.forEach(type => {
+            pack[type] = `[${locale}] ${type} error message`;
+        });
+        return pack;
+    }
+
+    static getMessage(locale, key) {
+        const pack = this.getLanguagePack(locale);
+        return pack[key] || `Unknown error: ${key}`;
+    }
+
+    static getStats() {
+        return this.languagePackCache.getStats();
+    }
+}
+
+// 模拟相同场景：100个租户使用50种语言
+console.log('模拟 100 个租户，使用 50 种不同语言...');
+for (let tenant = 1; tenant <= 100; tenant++) {
+    const locale = locales[tenant % 50];
+    SafeLocale.getMessage(locale, 'required');
+}
+
+const stats = SafeLocale.getStats();
+console.log(`\n缓存语言包数: ${SafeLocale.languagePackCache.size} / 10 (maxSize)`);
+console.log(`加载次数: ${stats.sets}`);
+console.log(`命中次数: ${stats.hits}`);
+console.log(`未命中次数: ${stats.misses}`);
+console.log(`驱逐次数: ${stats.evictions}`);
+const hitRate = stats.hits + stats.misses > 0
+    ? (stats.hits / (stats.hits + stats.misses) * 100).toFixed(2)
+    : '0.00';
+console.log(`命中率: ${hitRate}%`);
+console.log('✅ 优势：最多只缓存10个语言包，内存恒定可控');
+console.log('💡 说明：50种语言但只缓存最常用的10种，冷门语言自动清理');
+
+// ========== 3. 并发场景测试 ==========
+
+console.log('\n\n🔄 并发场景测试');
+console.log('-----------------------------------');
+
+class ConcurrentSafeLocale {
+    static languagePackCache = new LRUCache({ maxSize: 5, enableStats: true });
+
+    static getLanguagePack(locale) {
+        let pack = this.languagePackCache.get(locale);
+        if (!pack) {
+            pack = { required: `[${locale}] required`, email: `[${locale}] email` };
+            this.languagePackCache.set(locale, pack);
+        }
+        return pack;
+    }
+}
+
+// 模拟并发请求：10个并发请求，使用不同语言
+console.log('模拟 10 个并发请求...');
+const concurrentRequests = [];
+const testLocales = ['zh-CN', 'en-US', 'ja-JP', 'es-ES', 'fr-FR', 'ko-KR', 'de-DE', 'it-IT'];
+
+for (let i = 0; i < 10; i++) {
+    const locale = testLocales[i % testLocales.length];
+    concurrentRequests.push(
+        Promise.resolve().then(() => {
+            const pack = ConcurrentSafeLocale.getLanguagePack(locale);
+            return { requestId: i + 1, locale, message: pack.required };
+        })
+    );
+}
+
+Promise.all(concurrentRequests).then(results => {
+    console.log('\n并发请求结果:');
+    results.forEach(r => {
+        console.log(`  请求${r.requestId}: ${r.locale} → ${r.message}`);
+    });
+
+    const concStats = ConcurrentSafeLocale.languagePackCache.getStats();
+    console.log(`\n缓存状态: ${ConcurrentSafeLocale.languagePackCache.size} 个语言包`);
+    console.log(`最多缓存: 5 个语言包 (maxSize)`);
+    console.log('✅ 验证：8种语言访问，只缓存最近使用的5种');
+
+    continueDemo();
+}).catch(err => {
+    console.error('并发测试错误:', err);
+    continueDemo();
+});
+
+function continueDemo() {
+    // ========== 4. 内存监控示例 ==========
+
+    console.log('\n\n📊 内存监控示例');
+    console.log('-----------------------------------');
+
+    function formatBytes(bytes) {
+        return (bytes / 1024 / 1024).toFixed(2) + ' MB';
+    }
+
+    const memBefore = process.memoryUsage();
+    console.log(`初始内存: ${formatBytes(memBefore.heapUsed)}`);
+
+    // 创建大量语言包测试内存占用
+    const testCache = new LRUCache({ maxSize: 10 });
+    for (let i = 0; i < 1000; i++) {
+        // 模拟语言包对象（包含50个错误消息）
+        const languagePack = {};
+        for (let j = 0; j < 50; j++) {
+            languagePack[`error_${j}`] = `Language ${i} error message ${j}`;
+        }
+        testCache.set(`lang-${i}`, languagePack);
+    }
+
+    const memAfter = process.memoryUsage();
+    console.log(`处理后内存: ${formatBytes(memAfter.heapUsed)}`);
+    console.log(`内存增长: ${formatBytes(memAfter.heapUsed - memBefore.heapUsed)}`);
+    console.log(`缓存语言包: ${testCache.size} / 10 (maxSize)`);
+    console.log('✅ 验证：1000种语言加载，只缓存最近的10种');
+
+    // ========== 5. 最佳实践建议 ==========
+
+    console.log('\n\n📚 最佳实践建议');
+    console.log('-----------------------------------');
+    console.log(`
+🔑 核心原则：一个语言只有一个缓存（缓存完整语言包对象）
+
+1️⃣ 使用 LRU 缓存防止内存泄漏
+   ✅ 缓存语言包对象，不是单个消息
+   ✅ 设置合理的 maxSize（推荐 10-20种语言）
+   ✅ 启用统计功能监控命中率
+   ✅ 生产环境定期检查内存使用
+
+2️⃣ 正确的缓存策略
+   ✅ 缓存键：locale（如 "zh-CN"）
+   ✅ 缓存值：完整语言包 { required: "...", minLength: "..." }
+   ❌ 错误：缓存 "zh-CN:required" 这样的组合键
+   
+   示例：
+   // ✅ 正确
+   cache.set('zh-CN', { required: '必填', email: '邮箱格式' });
+   
+   // ❌ 错误（浪费内存）
+   cache.set('zh-CN:required', '必填');
+   cache.set('zh-CN:email', '邮箱格式');
+
+3️⃣ 多租户场景推荐方案
+   选项 A：实例级配置（每个请求创建独立 Validator）⭐⭐⭐⭐⭐
+   选项 B：请求级传参（validator.validate(data, { locale })）⭐⭐⭐⭐
+   选项 C：中间件统一处理（req.locale）⭐⭐⭐
+
+4️⃣ 前端动态切换语言
+   ⚠️ 避免使用全局 Locale.setLocale()
+   ✅ 通过请求头传递 Accept-Language
+   ✅ 每个请求创建独立验证器实例
+
+5️⃣ 内存监控
+   • 开发环境：启用 enableStats 追踪缓存效率
+   • 生产环境：定期检查 process.memoryUsage()
+   • 告警阈值：堆内存超过容器限制的 80%
+
+6️⃣ 性能优化
+   • 热门语言保持在缓存中（中文、英文）
+   • 冷门语言按需加载，自动驱逐
+   • 命中率目标：> 90%（取决于语言分布）
+   • maxSize 建议：支持语言数 × 0.5 ~ 1.0
+
+详细文档：
+- docs/i18n-analysis.md - 完整架构分析
+- docs/frontend-i18n-guide.md - 前端集成指南
+`);
+
+    console.log('\n✅ i18n 内存安全示例完成！');
+    console.log('💡 提示：运行 npm test 验证所有功能');
+}
+

package/examples/markdown-export.js

@@ -0,0 +1,71 @@
+/**
+ * Markdown 导出器示例
+ *
+ * 演示如何将 Schema 导出为 Markdown 文档
+ */
+
+const { dsl, exporters } = require('../index');
+
+console.log('========== Markdown 导出器示例 ==========\n');
+
+// 示例 1: 简单用户 Schema
+console.log('【示例 1】用户注册 API\n');
+
+const userSchema = dsl({
+  username: 'string:3-32!',
+  email: 'email!',
+  age: 'number:18-120',
+  role: 'admin|user|guest'
+});
+
+const zhMarkdown = exporters.MarkdownExporter.export(userSchema, {
+  title: '用户注册 API',
+  locale: 'zh-CN',
+  includeExample: true
+});
+
+console.log(zhMarkdown);
+console.log('\n' + '='.repeat(60) + '\n');
+
+// 示例 2: 带标签的 Schema
+console.log('【示例 2】带标签的产品 Schema\n');
+
+const productSchema = dsl({
+  'name': 'string:1-100!'.label('产品名称'),
+  'price': 'number:0.01-!'.label('价格'),
+  'description': 'string:500'.label('产品描述'),
+  'category': 'electronics|clothing|books'.label('类别'),
+  'tags': 'array:1-10<string:1-20>'.label('标签')
+});
+
+const productMarkdown = exporters.MarkdownExporter.export(productSchema, {
+  title: '产品信息 Schema',
+  locale: 'zh-CN'
+});
+
+console.log(productMarkdown);
+console.log('\n' + '='.repeat(60) + '\n');
+
+// 示例 3: 英文文档
+console.log('【示例 3】英文文档\n');
+
+const enMarkdown = exporters.MarkdownExporter.export(userSchema, {
+  title: 'User Registration API',
+  locale: 'en-US',
+  includeExample: true
+});
+
+console.log(enMarkdown);
+console.log('\n' + '='.repeat(60) + '\n');
+
+// 示例 4: 日文文档
+console.log('【示例 4】日文文档\n');
+
+const jaMarkdown = exporters.MarkdownExporter.export(userSchema, {
+  title: 'ユーザー登録 API',
+  locale: 'ja-JP',
+  includeExample: true
+});
+
+console.log(jaMarkdown);
+