schema-dsl 1.2.4 → 2.0.0

package/docs/performance-quick-reference.md

@@ -1,123 +0,0 @@
-# Schema-DSL 性能优化快速参考
-
-## 🚀 核心原则
-
-**生产环境：在项目启动时配置好所有 schema，避免每次请求都重复转换**
-
----
-
-## ❌ 错误示例（性能差）
-
-```javascript
-// ❌ 每次请求都转换（性能损失 3-5%）
-app.post('/api/user', (req, res) => {
-  const result = validate(
-    { email: 'email!', age: 'number!' },  // ❌ 每次都转换
-    req.body
-  );
-});
-```
-
----
-
-## ✅ 正确示例（性能最优）
-
-### 步骤1：定义 Schema（schemas/user.js）
-
-```javascript
-const { dsl } = require('schema-dsl');
-
-// ✅ 项目启动时转换一次
-module.exports = {
-  register: dsl({
-    email: 'email!',
-    password: 'password:strong!',
-    age: 'number:18-'
-  }),
-  
-  login: dsl({
-    email: 'email!',
-    password: 'string!'
-  })
-};
-```
-
-### 步骤2：在路由中使用（routes/user.js）
-
-```javascript
-const userSchemas = require('../schemas/user');
-const { validate } = require('schema-dsl');
-
-// ✅ 直接使用，不再转换
-app.post('/api/register', (req, res) => {
-  const result = validate(userSchemas.register, req.body);
-  // ...
-});
-
-app.post('/api/login', (req, res) => {
-  const result = validate(userSchemas.login, req.body);
-  // ...
-});
-```
-
----
-
-## 📊 性能对比
-
-| 方式 | 1000次请求 | 转换次数 | 适用场景 |
-|------|-----------|---------|---------|
-| ❌ 每次转换 | ~3.4秒 | 1000次 | 原型、测试 |
-| ✅ 启动配置 | ~3.3秒 | 1次 | **生产环境** |
-
-**性能差异：约 3-5%**
-
----
-
-## 📁 推荐项目结构
-
-```
-your-project/
-├── schemas/              # ✅ 所有 schema 定义
-│   ├── index.js          # 统一导出
-│   ├── user.js
-│   └── order.js
-├── routes/               # 路由使用 schemas/
-│   ├── user.js
-│   └── order.js
-└── app.js                # 启动时加载 schemas
-```
-
----
-
-## 🎯 使用场景
-
-| 场景 | 推荐方式 |
-|------|---------|
-| 生产环境 API | ✅ 项目启动时配置 |
-| 高并发服务 | ✅ 项目启动时配置 |
-| 微服务 | ✅ 项目启动时配置 |
-| 单次脚本 | ✅ 直接用 DSL 对象 |
-| 原型开发 | ✅ 直接用 DSL 对象 |
-| 测试代码 | ✅ 直接用 DSL 对象 |
-
----
-
-## 💡 记住
-
-**生产环境 = 启动时配置 = 性能最优**
-
-```javascript
-// ✅ 这样做
-const schemas = require('./schemas');  // 启动时加载
-validate(schemas.user.register, data);  // 直接使用
-
-// ❌ 不要这样
-validate({ email: 'email!' }, data);  // 每次都转换
-```
-
----
-
-## 📚 完整文档
-
-- `best-practices-project-structure.md` - 完整示例
-- `validate-dsl-object-support.md` - 功能说明

package/docs/user-questions-answered.md

@@ -1,353 +0,0 @@
-# 用户问题解答总结
-
-## 您的三个问题
-
-### 问题1：DSL 对象中可以使用链式调用吗？
-
-```javascript
-dsl.validate(
-  {
-    user: {
-      name: dsl('string:3-32!').messages({ 'string.min': '名字太短了' }),
-      email: 'email!'
-    }
-  },
-  {
-    user: {
-      name: 'John',
-      email: 'john@example.com'
-    }
-  }
-)
-```
-
-**答：可以！✅**
-
-- ✅ DSL 对象支持混合使用 DslBuilder 实例和 DSL 字符串
-- ✅ 嵌套对象中也完全支持
-- ✅ 自定义消息、label、pattern 等链式方法都可以使用
-
-**完整示例**：
-
-```javascript
-const { dsl, validate } = require('schema-dsl');
-
-// ✅ 混合使用
-const result = validate(
-  {
-    username: dsl('string:3-32!')
-      .pattern(/^[a-zA-Z0-9_]+$/)
-      .messages({ 'string.pattern': '只能包含字母、数字和下划线' }),
-    email: 'email!',  // 纯 DSL 字符串
-    age: 'number:18-',
-    profile: {
-      name: dsl('string!').label('姓名'),
-      bio: 'string:0-500'
-    }
-  },
-  data
-);
-```
-
-**测试验证**：
-
-```javascript
-// 测试：触发自定义错误消息
-const result = validate(
-  {
-    username: dsl('string:3-32!')
-      .pattern(/^[a-zA-Z0-9_]+$/)
-      .messages({ 'string.pattern': '自定义错误消息' })
-  },
-  { username: 'john-doe' }  // 包含非法字符 -
-);
-
-console.log(result.errors[0].message);
-// 输出: "自定义错误消息"
-```
-
----
-
-### 问题2：直接用对象会有什么影响？
-
-**性能影响**：
-
-```javascript
-// 性能测试（1000次验证）
-// 方式1：每次传 DSL 对象    → ~3.4秒
-// 方式2：复用 schema         → ~3.3秒
-// 性能差异：约 3-5%
-```
-
-**详细对比**：
-
-| 方面 | 每次传 DSL 对象 | 提前转换复用 schema |
-|------|----------------|-------------------|
-| **简洁性** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
-| **性能** | ⭐⭐⭐⭐ (损失3-5%) | ⭐⭐⭐⭐⭐ |
-| **可读性** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
-| **复用性** | ⭐⭐ (每次转换) | ⭐⭐⭐⭐⭐ |
-
-**使用建议**：
-
-```javascript
-// ❌ 不推荐：高并发场景每次转换
-app.post('/api/user', (req, res) => {
-  const result = validate(
-    { email: 'email!', age: 'number!' },  // 每次都转换
-    req.body
-  );
-});
-
-// ✅ 推荐：提前转换，复用 schema
-const userSchema = dsl({ email: 'email!', age: 'number!' });
-
-app.post('/api/user', (req, res) => {
-  const result = validate(userSchema, req.body);  // 直接使用
-});
-
-// ✅ 适合：原型开发/脚本/低并发场景
-const result = validate({ email: 'email!' }, data);  // 简洁
-```
-
-**性能影响总结**：
-
-1. **开销来源**：
-   - DSL 对象 → JSON Schema 的转换
-   - 对象遍历、类型检测、递归处理
-
-2. **影响程度**：
-   - 简单 schema（2-3个字段）：3-5% 性能损失
-   - 复杂 schema（10+字段）：可能更高
-
-3. **何时影响明显**：
-   - ❌ 高并发 API（每秒数千请求）
-   - ❌ 循环中重复验证（数千次）
-   - ✅ 原型开发/脚本（可忽略）
-   - ✅ 低并发场景（可忽略）
-
----
-
-### 问题3：为什么之前不这样设计？
-
-**历史设计原因**：
-
-1. **职责分离**（设计哲学）
-   
-   ```javascript
-   // 之前的设计：明确的两个步骤
-   const schema = dsl({ email: 'email!' });  // 步骤1：转换
-   const result = validate(schema, data);     // 步骤2：验证
-   ```
-   
-   这种设计让每个函数的职责更清晰：
-   - `dsl()` 负责转换
-   - `validate()` 只负责验证
-
-2. **避免隐式转换**（最小惊喜原则）
-   
-   ```javascript
-   // 用户传入什么类型，就按什么类型处理
-   validate(jsonSchema, data);   // JSON Schema
-   validate(dslBuilder, data);   // DslBuilder
-   validate({ email: 'email!' }, data);  // ❌ 会被当作 JSON Schema 报错
-   ```
-   
-   避免"魔法"行为，用户不会困惑"为什么我传入的对象被自动转换了"。
-
-3. **类型安全考虑**（TypeScript）
-   
-   ```typescript
-   // 明确的类型定义（v1.1.6）
-   function validate(
-     schema: JSONSchema | DslBuilder,  // 明确的类型
-     data: any
-   ): ValidationResult;
-   
-   // 如果支持任意对象（v1.1.7）
-   function validate(
-     schema: JSONSchema | DslBuilder | Record<string, any>,  // 太宽泛
-     data: any
-   ): ValidationResult;
-   ```
-   
-   太宽泛的类型定义会让 TypeScript 无法提供准确的类型检查。
-
-4. **性能考虑**（避免误用）
-   
-   ```javascript
-   // 避免用户不经意写出性能差的代码
-   for (let i = 0; i < 10000; i++) {
-     validate({ email: 'email!' }, data);  // 每次都转换（性能差）
-   }
-   ```
-   
-   强制用户显式转换，可以让他们意识到"转换是有开销的"。
-
-**为什么现在改变了？**
-
-1. **用户反馈强烈**
-   - 很多用户抱怨"为什么不能直接传对象"
-   - "每次都要写 `dsl()` 太繁琐了"
-
-2. **技术成熟**
-   - 实现了智能检测函数 `_isDslObject()`
-   - 可以准确区分 DSL 对象和 JSON Schema
-
-3. **性能可接受**
-   - 测试表明性能损失只有 3-5%
-   - 对大多数场景可以忽略
-
-4. **向后兼容**
-   - 不影响现有代码
-   - 所有原有用法都继续工作
-
-5. **使用体验优先**
-   - 简化常见场景的使用
-   - 降低学习成本
-
-**设计权衡对比**：
-
-| 设计方案 | 优点 | 缺点 | 适用场景 |
-|---------|------|------|---------|
-| **显式转换**（v1.1.6） | 职责清晰<br>类型安全<br>性能最优 | 代码冗长<br>学习成本高 | 大型项目<br>类型严格 |
-| **自动转换**（v1.1.7） | 简洁直观<br>学习成本低 | 隐式行为<br>类型宽泛 | 原型开发<br>快速验证 |
-
-**最终选择**：**两者都支持，让用户自由选择！**
-
-```javascript
-// ✅ 简单场景：直接用 DSL 对象（新增）
-validate({ email: 'email!' }, data);
-
-// ✅ 复杂场景：显式转换（保留）
-const schema = dsl({ email: 'email!' });
-validate(schema, data);
-```
-
----
-
-## 实现细节
-
-### 智能检测函数 `_isDslObject()`
-
-```javascript
-function _isDslObject(obj) {
-  // 1. 排除非对象
-  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
-    return false;
-  }
-
-  // 2. 排除 DslBuilder（顶层）
-  if (typeof obj.toSchema === 'function') {
-    return false;
-  }
-
-  // 3. 排除 ConditionalBuilder
-  if (obj._isConditional) {
-    return false;
-  }
-
-  // 4. 排除标准 JSON Schema
-  if (obj.type && ['string', 'number', ...].includes(obj.type)) {
-    return false;
-  }
-
-  // 5. 检测 DSL 特征
-  const values = Object.values(obj);
-  
-  // 5.1 检测 DslBuilder 实例（属性值）
-  const hasDslBuilder = values.some(v => 
-    v && typeof v === 'object' && typeof v.toSchema === 'function'
-  );
-  
-  // 5.2 检测 DSL 字符串
-  const hasDslString = values.some(v =>
-    typeof v === 'string' && (
-      v.includes(':') || v.includes('!') || ...
-    )
-  );
-
-  // 5.3 检测嵌套 DSL 对象
-  const hasNestedDslObject = values.some(v => _isDslObject(v));
-
-  return hasDslBuilder || hasDslString || hasNestedDslObject;
-}
-```
-
-### 自动转换流程
-
-```javascript
-function validate(schema, data, options = {}) {
-  // ✅ 自动检测并转换
-  if (_isDslObject(schema)) {
-    schema = DslAdapter.parseObject(schema);
-  }
-  
-  const validator = new Validator(options);
-  return validator.validate(schema, data, options);
-}
-```
-
----
-
-## 测试验证
-
-### 功能测试（8项全部通过）
-
-```javascript
-✅ 纯 DSL 字符串对象
-✅ 混合 DslBuilder 和 DSL 字符串
-✅ 嵌套对象中使用 DslBuilder
-✅ 触发自定义错误消息
-✅ 标准 JSON Schema 仍然工作
-✅ DslBuilder 实例仍然工作
-✅ 复杂嵌套场景
-✅ validateAsync 也支持 DSL 对象
-```
-
-### 性能测试
-
-```
-方式1: 每次传 DSL 对象: 3.412s (1000次)
-方式2: 复用 schema:      3.378s (1000次)
-性能差异: 约 1% (3.4ms)
-```
-
----
-
-## 总结
-
-### 三个问题的答案
-
-1. **DSL 对象中可以使用链式调用吗？**
-   - ✅ 可以！支持混合使用 DslBuilder 实例和 DSL 字符串
-
-2. **直接用对象会有什么影响？**
-   - 性能损失：3-5%
-   - 适用场景：原型开发、脚本、低并发
-   - 高并发场景：建议提前转换复用
-
-3. **为什么之前不这样设计？**
-   - 设计哲学：职责分离、避免隐式转换
-   - 现在改变：用户反馈 + 技术成熟 + 向后兼容
-
-### 推荐使用方式
-
-```javascript
-// ✅ 原型开发/脚本：直接用 DSL 对象
-validate({ email: 'email!' }, data);
-
-// ✅ 生产环境/高并发：提前转换
-const schema = dsl({ email: 'email!' });
-validate(schema, data);
-
-// ✅ 需要链式调用：混合使用
-validate({
-  username: dsl('string:3-32!').pattern(/^[a-zA-Z0-9_]+$/),
-  email: 'email!'
-}, data);
-```
-
----
-
-**完整文档**: [validate-dsl-object-support.md](./validate-dsl-object-support.md)