schema-dsl 2.0.0 → 2.0.1

package/docs/design-philosophy.md

@@ -1,606 +1,606 @@
-# Schema-DSL 设计理念与架构
-
-> **更新时间**: 2026-05-07  
-> **目的**: 阐述 Schema-DSL 的设计理念、架构优势与性能定位
-
----
-
-## 📑 目录
-
-- [核心设计理念](#核心设计理念)
-- [为什么选择运行时解析](#为什么选择运行时解析)
-- [编译时构建的局限性](#编译时构建的局限性)
-- [性能对比与权衡](#性能对比与权衡)
-- [架构设计](#架构设计)
-- [适用场景](#适用场景)
-- [与其他库对比](#与其他库对比)
-
----
-
-## 核心设计理念
-
-### 设计优先级
-
-```text
-性能强劲 · 简单易学 · 功能强大
-```
-
-Schema-DSL v2 完成全量 TypeScript 重构，在三个维度上均达到行业领先水平：
-
-1. **性能强劲** — 有效数据路径超越 Zod，无效数据公平对比快 **109 倍**；底层 AJV + 全链路 WeakMap 缓存，V8 优化充分
-2. **简单易学** — DSL 语法极简，`'string:3-32!'` vs `z.string().min(3).max(32)`，5 分钟上手
-3. **功能强大** — 动态验证、i18n 多语言、DB 导出、条件验证、插件系统，完整 TypeScript 类型安全
-
----
-
-## 为什么选择运行时解析？
-
-### 关键决策：运行时 vs 编译时
-
-Schema-DSL 选择**运行时解析 DSL**，而非**编译时构建**（如 Zod），这是有意为之的设计选择。
-
-### ✅ 运行时解析的 5 大优势
-
-#### 1. 完全动态性
-
-**问题**: 编译时构建的 Schema 在运行时无法修改
-
-**Schema-DSL 的解决方案**:
-```javascript
-// ✅ 从配置文件读取验证规则
-const config = require('./validation-config.json');
-const schema = dsl({
-  username: `string:${config.username.min}-${config.username.max}!`
-});
-
-// ✅ 从数据库读取验证规则
-const rules = await db.collection('validation_rules').findOne({ 
-  entity: 'user' 
-});
-const schema = dsl({
-  username: `string:${rules.username.min}-${rules.username.max}!`,
-  email: 'email!',
-  age: `number:${rules.age.min}-${rules.age.max}`
-});
-
-// ✅ 根据环境动态调整
-const maxLength = process.env.NODE_ENV === 'development' ? 100 : 32;
-const schema = dsl({
-  username: `string:3-${maxLength}!`
-});
-
-// ✅ 根据用户角色动态调整
-function getUserSchema(userRole) {
-  const maxLength = userRole === 'admin' ? 100 : 32;
-  return dsl({
-    username: `string:3-${maxLength}!`
-  });
-}
-```
-
-**Zod 的限制**:
-```typescript
-// ❌ Schema 必须在编译时确定
-const schema = z.object({
-  username: z.string().min(3).max(32)  // 固定值
-});
-
-// ❌ 无法运行时动态调整
-```
-
----
-
-#### 2. 多租户 SaaS 系统支持
-
-**真实场景**: 每个租户有不同的验证规则
-
-**Schema-DSL 的解决方案**:
-```javascript
-// ✅ 租户配置存储在数据库
-const tenantRules = {
-  'tenant-a': { username: { min: 3, max: 32 } },
-  'tenant-b': { username: { min: 5, max: 50 } },
-  'tenant-c': { username: { min: 2, max: 20 } }
-};
-
-// ✅ 动态生成 Schema
-function getTenantSchema(tenantId) {
-  const rules = tenantRules[tenantId];
-  return dsl({
-    username: `string:${rules.username.min}-${rules.username.max}!`,
-    email: 'email!'
-  });
-}
-
-// ✅ 新增租户 = 插入数据库记录，零代码修改
-```
-
-**Zod 的限制**:
-```typescript
-// ❌ 必须为每个租户硬编码 Schema
-const tenantASchema = z.object({ username: z.string().min(3).max(32) });
-const tenantBSchema = z.object({ username: z.string().min(5).max(50) });
-// ... 新增租户 = 修改代码 = 重新部署
-```
-
----
-
-#### 3. 可序列化（存储、传输、共享）
-
-**问题**: 编译时构建的 Schema 是 JavaScript 对象，无法序列化
-
-**Schema-DSL 的解决方案**:
-```javascript
-// ✅ DSL 是字符串，可以序列化
-const schemaConfig = {
-  username: 'string:3-32!',
-  email: 'email!',
-  age: 'number:18-120'
-};
-
-// ✅ 可以存储到：
-// - JSON 文件
-fs.writeFileSync('schema.json', JSON.stringify(schemaConfig));
-
-// - 数据库
-await db.collection('schemas').insert({
-  entity: 'user',
-  rules: schemaConfig
-});
-
-// - Redis
-redis.set('user:schema', JSON.stringify(schemaConfig));
-
-// - 配置中心（Nacos/Apollo）
-await nacos.publishConfig({
-  dataId: 'user-validation',
-  group: 'DEFAULT_GROUP',
-  content: JSON.stringify(schemaConfig)
-});
-
-// ✅ 可以通过 HTTP API 传输
-app.get('/api/validation-rules/:entity', async (req, res) => {
-  const rules = await db.findOne({ entity: req.params.entity });
-  res.json(rules);  // 直接返回 DSL
-});
-
-// ✅ 前后端共享规则
-// 后端定义规则 → API 传输 → 前端使用相同的 DSL
-fetch('/api/validation-rules/user')
-  .then(res => res.json())
-  .then(rules => {
-    const schema = dsl(rules);  // 前后端验证规则完全一致
-  });
-```
-
-**Zod 的限制**:
-```typescript
-// ❌ Schema 是对象，无法序列化
-const schema = z.object({
-  username: z.string().min(3).max(32)
-});
-
-// ❌ JSON.stringify(schema) → 无法正确序列化
-// ❌ 无法存储到数据库
-// ❌ 无法通过 API 传输
-```
-
----
-
-#### 4. 数据库驱动的验证规则
-
-**真实场景**: 后台管理系统，管理员可配置表单验证规则
-
-**Schema-DSL 的解决方案**:
-```javascript
-// ✅ 管理员在后台界面配置验证规则
-// 后台界面：
-// - 字段名：username
-// - 类型：string
-// - 最小长度：3
-// - 最大长度：32
-// - 必填：是
-
-// ✅ 规则存储到数据库
-await db.collection('form_rules').insert({
-  formId: 'user_registration',
-  fields: {
-    username: 'string:3-32!',
-    email: 'email!',
-    age: 'number:18-120'
-  }
-});
-
-// ✅ 应用使用最新规则（无需重启）
-app.post('/api/users', async (req, res) => {
-  // 从数据库读取最新规则
-  const formRules = await db.collection('form_rules').findOne({ 
-    formId: 'user_registration' 
-  });
-  
-  // 动态生成 Schema
-  const schema = dsl(formRules.fields);
-  
-  // 验证
-  const result = validate(schema, req.body);
-  if (!result.valid) {
-    return res.status(400).json({ errors: result.errors });
-  }
-  
-  // ... 业务逻辑
-});
-
-// ✅ 管理员修改规则后，立即生效，无需重启服务
-```
-
-**Zod 的限制**:
-```typescript
-// ❌ 无法从数据库动态加载规则
-// ❌ 验证规则必须硬编码在代码中
-// ❌ 修改规则 = 修改代码 = 重新部署
-```
-
----
-
-#### 5. 低代码/无代码平台基础
-
-**真实场景**: 可视化表单构建器
-
-**Schema-DSL 的解决方案**:
-```javascript
-// ✅ 可视化表单构建器配置
-const formBuilder = {
-  formId: 'contact',
-  title: '联系我们',
-  fields: [
-    {
-      name: 'name',
-      label: '姓名',
-      type: 'text',
-      validation: 'string:2-50!',  // ← 在 UI 中配置
-      placeholder: '请输入您的姓名'
-    },
-    {
-      name: 'email',
-      label: '邮箱',
-      type: 'email',
-      validation: 'email!',
-      placeholder: '请输入您的邮箱'
-    },
-    {
-      name: 'message',
-      label: '留言',
-      type: 'textarea',
-      validation: 'string:10-500!',
-      placeholder: '请输入您的留言'
-    }
-  ]
-};
-
-// ✅ 自动生成验证 Schema
-const schema = dsl(
-  formBuilder.fields.reduce((acc, field) => {
-    acc[field.name] = field.validation;
-    return acc;
-  }, {})
-);
-
-// ✅ 自动生成前端表单
-function renderForm(formBuilder) {
-  return formBuilder.fields.map(field => (
-    `<div>
-      <label>${field.label}</label>
-      <input name="${field.name}" placeholder="${field.placeholder}" />
-    </div>`
-  ));
-}
-
-// ✅ 这是低代码平台的基础能力
-// - 用户在界面拖拽表单
-// - 配置验证规则（无需写代码）
-// - 自动生成前后端代码
-```
-
----
-
-### ⚠️ 其他场景
-
-#### A/B 测试验证规则
-
-```javascript
-// ✅ 从配置中心读取 A/B 测试配置
-const abTestConfig = await configCenter.get('user_validation_ab_test');
-
-const schema = dsl({
-  username: abTestConfig.userInGroupA 
-    ? 'string:2-50!'   // A 组：宽松规则
-    : 'string:5-20!'   // B 组：严格规则
-});
-
-// 修改配置中心的值，立即生效，无需重新部署
-```
-
-#### 灰度发布
-
-```javascript
-// ✅ 根据灰度比例动态选择规则
-const grayConfig = await configCenter.get('validation_gray_config');
-const useNewRules = Math.random() < grayConfig.grayRatio;
-
-const schema = dsl(useNewRules ? newRules : oldRules);
-```
-
----
-
-## 编译时构建的局限性
-
-### Zod 等编译时库的限制
-
-| 限制 | 说明 | 影响 |
-|------|------|------|
-| **无法动态调整** | Schema 在编译时固定 | 无法根据配置/环境/用户动态生成 |
-| **无法序列化** | Schema 是 JavaScript 对象 | 无法存储、传输、共享 |
-| **多租户困难** | 必须为每个租户写代码 | 新增租户 = 修改代码 = 重新部署 |
-| **数据库驱动困难** | 无法从数据库读取规则 | 后台配置表单验证无法实现 |
-| **配置驱动困难** | 必须硬编码 Schema | 无法从配置文件/API 动态生成 |
-| **前后端共享困难** | 无法通过 API 传输 | 前后端验证规则容易不一致 |
-| **低代码平台不适合** | 无法可视化配置 | 不适合低代码/无代码场景 |
-
----
-
-## 性能对比与权衡
-
-### 真实性能测试结果（v2 基准，分场景对比）
-
-**测试环境**: Node.js v20.20.2, tinybench，JSON Schema 同维度对比
-
-| 场景 | Schema-DSL | vs Zod | Zod | Ajv (raw) | Joi |
-|------|-----------|:------:|-----|-----------|-----|
-| S1 简单有效 | **1.301M ops/s** | ≈ 持平（差 <1%） | 1.305M ops/s | 4.732M ops/s | 154K ops/s |
-| S2 无效（均无 i18n）| **1.205M ops/s** | **🏆 +89x** | 13.49K ops/s | 4.874M ops/s | 92.32K ops/s |
-| S3 嵌套有效 | **1.085M ops/s** | **🏆 +28%** | 846.81K ops/s | 3.974M ops/s | 125.35K ops/s |
-
-> ℹ️ 绝对 ops/s 数值随测试机器 CPU 性能而变化；**相对倍数（vs Zod 列）是稳定的跨机器指标**，以下分析均基于倍数。  
-> ℹ️ S2 使用 `validate(schema, data, { format: false })` 关闭 i18n 格式化，与其他库保持相同条件（均不做 i18n 模板渲染），是真正的苹果对苹果比较。  
-> ℹ️ Ajv (raw) 是 schema-dsl 的底层引擎，差值即为 schema-dsl 自身层（DSL 解析 + coerce + 缓存）的开销。
-
-### 性能分析
-
-**Schema-DSL vs Zod 对比结论**
-
-- **有效数据场景（S1）**：schema-dsl 与 Zod **基本持平**；**S3 嵌套场景**快约 **28%**
-- **无效数据公平对比（S2，均无 i18n 格式化）**：schema-dsl **1.205M** vs Zod **13.49K** — schema-dsl 快约 **89x**
-
-> ⚠️ **Zod 在无效数据场景极慢的根因**：Zod 的错误收集路径使用异常驱动机制（`try/catch` 控制流），每个无效字段抛出一次 Error，4 个错误字段 = 4 次 Error 实例创建 + 4 次堆栈捕获，这是其约 13.49K ops/s 的直接原因。相比之下 schema-dsl 基于 AJV 的无异常收集路径，无格式化时达 1.205M ops/s。
-
-```text
-Schema-DSL 的执行流程（含内置缓存）：
-  DSL 字符串
-    ↓ 缓存命中（热路径，无解析开销）
-  验证函数
-    ↓ 执行验证 (~0.5-1μs)
-  结果
-
-冷路径（首次）：
-  DSL 字符串 → 解析 → JSON Schema → Ajv 编译 → 缓存并执行
-```
-
-**性能瓶颈分布（冷启动）**:
-1. DSL 解析（40-50%）
-2. JSON Schema 转换（20-30%）
-3. 多语言处理（10-20%）
-4. Ajv 编译（10-15%）
-
----
-
-### 性能权衡分析
-
-**与 Ajv (raw) 的差距**:
-```text
-- 比 Ajv (raw) 慢约 3.6-4.0x（DSL 层自身开销）
-  S1 简单场景：3.64x，S3 嵌套场景：3.66x
-- ajv (raw) 是底层引擎，无 DSL 解析/i18n/coerce 功能
-```
-
-**换来的价值**:
-```text
-✅ 代码量减少 65%
-   'string:3-32!' vs z.string().min(3).max(32)
-   
-✅ 完全动态的验证规则
-   可从配置/数据库/API 动态生成
-   
-✅ 多租户支持
-   每个租户不同规则，零代码修改
-   
-✅ 可序列化
-   可存储、传输、共享
-   
-✅ 前后端共享规则
-   一套规则，两端使用
-   
-✅ 低代码平台基础
-   可视化配置表单验证
-   
-✅ 数据库驱动
-   管理员后台配置，立即生效
-```
-
-### 性能优化措施
-
-### 缓存优化
-```javascript
-// Schema 缓存：5000条（提升 5倍）
-// 正则缓存：500条（提升 2.5倍）
-// LRU 驱逐机制
-
-// 效果：
-// - 大型项目（3000 Schema）：3倍提升
-// - 超大型项目（10000 Schema）：5-10倍提升
-```
-
----
-
-## 架构设计
-
-### 核心组件
-
-```text
-┌─────────────────────────────────────┐
-│         DSL 字符串                  │
-│   'string:3-32!', 'email!'         │
-└──────────────┬──────────────────────┘
-               │
-               ↓
-┌─────────────────────────────────────┐
-│       DslAdapter (解析器)           │
-│   正则解析 → DSL 对象               │
-└──────────────┬──────────────────────┘
-               │
-               ↓
-┌─────────────────────────────────────┐
-│     JSONSchemaCore (转换器)         │
-│   DSL 对象 → JSON Schema            │
-└──────────────┬──────────────────────┘
-               │
-               ↓
-┌─────────────────────────────────────┐
-│        Ajv (验证引擎)               │
-│   JSON Schema → 验证函数            │
-└──────────────┬──────────────────────┘
-               │
-               ↓
-┌─────────────────────────────────────┐
-│    ErrorFormatter (错误格式化)      │
-│   Ajv 错误 → 友好消息 → 多语言     │
-└──────────────┬──────────────────────┘
-               │
-               ↓
-┌─────────────────────────────────────┐
-│         ValidationResult            │
-│    { valid, errors, data }          │
-└─────────────────────────────────────┘
-```
-
-### 缓存机制
-
-```javascript
-// Schema 缓存
-SCHEMA_CACHE: LRU(5000)  // DSL → JSONSchema
-REGEX_CACHE: LRU(500)    // 正则表达式
-
-// 缓存命中：0μs 开销
-// 缓存未命中：12-21μs 开销
-```
-
----
-
-## 适用场景
-
-### ✅ 选择 Schema-DSL
-
-**最适合的场景**:
-
-1. **多租户 SaaS 系统**
-   - 每个租户不同验证规则
-   - 新增租户零代码修改
-
-2. **后台管理系统**
-   - 管理员配置表单验证
-   - 规则立即生效，无需重启
-
-3. **配置驱动开发**
-   - 验证规则存储在配置文件/数据库
-   - 可通过 API 动态获取
-
-4. **低代码/无代码平台**
-   - 可视化表单构建器
-   - 拖拽配置验证规则
-
-5. **快速原型开发**
-   - 5分钟上手
-   - 代码量最少
-
-6. **前后端共享验证**
-   - 一套规则，两端使用
-   - 通过 API 传输
-
-7. **A/B 测试/灰度发布**
-   - 动态切换验证规则
-   - 配置驱动
-
-### ⚠️ 以下场景可能有更优选择
-
-1. **追求代码生成级极致吞吐量**
-   - 需要 fastest-validator 级别性能（compile 为原生 JS 函数）
-   - 推荐：**fastest-validator**（但需放弃 JSON Schema 标准兼容）
-
-2. **以 Schema → 静态类型推断为核心目标**
-   - 需要从 Schema 自动导出精确的 TypeScript 类型（如 `z.infer<typeof schema>`）
-   - 推荐：**Zod**（schema-dsl 提供完整 TypeScript API 类型安全，但不做 Schema → 类型推断）
-
-3. **静态规则 + 团队已深度投入 Zod**
-   - 迁移成本大于收益时，保持现状即可
-
----
-
-## 与其他库对比
-
-### 综合对比
-
-| 维度 | Schema-DSL | Zod | Ajv | Joi |
-|------|-----------|-----|-----|-----|
-| **有效路径性能** | ✅ **S1 持平，S3 快约 28%** | baseline | 🥇 3.6-4.0x 更快 | 7-9x 更慢 |
-| **无效路径性能** | 🏆 **Zod 的 89x** | 极慢（异常驱动）| 🥇 最快 | 中等 |
-| **动态性** | ✅✅ 完全动态 | ❌ 编译时固定 | ⚠️ 部分动态 | ⚠️ 部分动态 |
-| **语法简洁性** | ✅✅ 最简洁 | ⚠️ 较冗长 | ❌ 最冗长 | ⚠️ 较冗长 |
-| **TypeScript** | ✅ 完整（v2 全量 TS 重构）| ✅✅ 强（Schema→类型推断）| ⚠️ 基础 | ⚠️ 基础 |
-| **序列化** | ✅✅ 支持 | ❌ 不支持 | ⚠️ 部分支持 | ❌ 不支持 |
-| **多租户** | ✅✅ 容易 | ❌ 困难 | ⚠️ 可以 | ⚠️ 可以 |
-| **配置驱动** | ✅✅ 完美 | ❌ 不支持 | ⚠️ 可以 | ⚠️ 可以 |
-| **数据库导出** | ✅✅ 唯一 | ❌ | ❌ | ❌ |
-| **学习曲线** | ✅✅ 5分钟 | ⚠️ 30分钟 | ❌ 1小时 | ⚠️ 30分钟 |
-
----
-
-## 结论
-
-### Schema-DSL 的价值主张
-
-**性能强劲 · 简单易学 · 功能强大**:
-
-```text
-性能优势（vs Zod 公平对比）：
-  ✅ S1 有效数据：快 23%
-  ✅ S3 嵌套有效：快 98%（接近 2 倍）
-  ✅ S2 无效数据：快 109 倍（Zod 异常驱动 vs AJV 无异常路径）
-
-易用性优势：
-  ✅ 语法最简洁（代码量减少 65%）
-  ✅ 5 分钟上手，学习曲线最平
-  ✅ 全量 TypeScript 重构（v2），完整类型安全
-
-功能优势：
-  ✅ 唯一支持：动态规则 / 配置驱动 / DB 导出 / i18n 多语言
-  ✅ 多租户 SaaS、低代码平台的首选验证库
-
-理性权衡：
-  ⚠️ 比 Ajv (raw) 慢约 2–3x（DSL 层自身开销：解析 + coerce + 缓存）
-  ⚠️ 不做 Schema → 静态类型推断（如需此能力仍推荐 Zod）
-
-定位：
-  性能、易用、功能三角均衡的现代 TypeScript 验证库
-  动态规则场景的最优选择
-```
-
----
-
-**更新日期**: 2026-05-08
-
----
-
-## 对应示例文件
-
-**示例入口**: [design-philosophy.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/design-philosophy.ts)  
-**说明**: 通过“配置生成 DSL → 序列化 → 反序列化 → 再验证”的完整闭环，展示运行时解析和可序列化这两个核心设计点。
-
+# Schema-DSL 设计理念与架构
+
+> **更新时间**: 2026-05-07  
+> **目的**: 阐述 Schema-DSL 的设计理念、架构优势与性能定位
+
+---
+
+## 📑 目录
+
+- [核心设计理念](#核心设计理念)
+- [为什么选择运行时解析](#为什么选择运行时解析)
+- [编译时构建的局限性](#编译时构建的局限性)
+- [性能对比与权衡](#性能对比与权衡)
+- [架构设计](#架构设计)
+- [适用场景](#适用场景)
+- [与其他库对比](#与其他库对比)
+
+---
+
+## 核心设计理念
+
+### 设计优先级
+
+```text
+性能强劲 · 简单易学 · 功能强大
+```
+
+Schema-DSL v2 完成全量 TypeScript 重构，在三个维度上均达到行业领先水平：
+
+1. **性能强劲** — 有效数据路径超越 Zod，无效数据公平对比快 **109 倍**；底层 AJV + 全链路 WeakMap 缓存，V8 优化充分
+2. **简单易学** — DSL 语法极简，`'string:3-32!'` vs `z.string().min(3).max(32)`，5 分钟上手
+3. **功能强大** — 动态验证、i18n 多语言、DB 导出、条件验证、插件系统，完整 TypeScript 类型安全
+
+---
+
+## 为什么选择运行时解析？
+
+### 关键决策：运行时 vs 编译时
+
+Schema-DSL 选择**运行时解析 DSL**，而非**编译时构建**（如 Zod），这是有意为之的设计选择。
+
+### ✅ 运行时解析的 5 大优势
+
+#### 1. 完全动态性
+
+**问题**: 编译时构建的 Schema 在运行时无法修改
+
+**Schema-DSL 的解决方案**:
+```javascript
+// ✅ 从配置文件读取验证规则
+const config = require('./validation-config.json');
+const schema = dsl({
+  username: `string:${config.username.min}-${config.username.max}!`
+});
+
+// ✅ 从数据库读取验证规则
+const rules = await db.collection('validation_rules').findOne({ 
+  entity: 'user' 
+});
+const schema = dsl({
+  username: `string:${rules.username.min}-${rules.username.max}!`,
+  email: 'email!',
+  age: `number:${rules.age.min}-${rules.age.max}`
+});
+
+// ✅ 根据环境动态调整
+const maxLength = process.env.NODE_ENV === 'development' ? 100 : 32;
+const schema = dsl({
+  username: `string:3-${maxLength}!`
+});
+
+// ✅ 根据用户角色动态调整
+function getUserSchema(userRole) {
+  const maxLength = userRole === 'admin' ? 100 : 32;
+  return dsl({
+    username: `string:3-${maxLength}!`
+  });
+}
+```
+
+**Zod 的限制**:
+```typescript
+// ❌ Schema 必须在编译时确定
+const schema = z.object({
+  username: z.string().min(3).max(32)  // 固定值
+});
+
+// ❌ 无法运行时动态调整
+```
+
+---
+
+#### 2. 多租户 SaaS 系统支持
+
+**真实场景**: 每个租户有不同的验证规则
+
+**Schema-DSL 的解决方案**:
+```javascript
+// ✅ 租户配置存储在数据库
+const tenantRules = {
+  'tenant-a': { username: { min: 3, max: 32 } },
+  'tenant-b': { username: { min: 5, max: 50 } },
+  'tenant-c': { username: { min: 2, max: 20 } }
+};
+
+// ✅ 动态生成 Schema
+function getTenantSchema(tenantId) {
+  const rules = tenantRules[tenantId];
+  return dsl({
+    username: `string:${rules.username.min}-${rules.username.max}!`,
+    email: 'email!'
+  });
+}
+
+// ✅ 新增租户 = 插入数据库记录，零代码修改
+```
+
+**Zod 的限制**:
+```typescript
+// ❌ 必须为每个租户硬编码 Schema
+const tenantASchema = z.object({ username: z.string().min(3).max(32) });
+const tenantBSchema = z.object({ username: z.string().min(5).max(50) });
+// ... 新增租户 = 修改代码 = 重新部署
+```
+
+---
+
+#### 3. 可序列化（存储、传输、共享）
+
+**问题**: 编译时构建的 Schema 是 JavaScript 对象，无法序列化
+
+**Schema-DSL 的解决方案**:
+```javascript
+// ✅ DSL 是字符串，可以序列化
+const schemaConfig = {
+  username: 'string:3-32!',
+  email: 'email!',
+  age: 'number:18-120'
+};
+
+// ✅ 可以存储到：
+// - JSON 文件
+fs.writeFileSync('schema.json', JSON.stringify(schemaConfig));
+
+// - 数据库
+await db.collection('schemas').insert({
+  entity: 'user',
+  rules: schemaConfig
+});
+
+// - Redis
+redis.set('user:schema', JSON.stringify(schemaConfig));
+
+// - 配置中心（Nacos/Apollo）
+await nacos.publishConfig({
+  dataId: 'user-validation',
+  group: 'DEFAULT_GROUP',
+  content: JSON.stringify(schemaConfig)
+});
+
+// ✅ 可以通过 HTTP API 传输
+app.get('/api/validation-rules/:entity', async (req, res) => {
+  const rules = await db.findOne({ entity: req.params.entity });
+  res.json(rules);  // 直接返回 DSL
+});
+
+// ✅ 前后端共享规则
+// 后端定义规则 → API 传输 → 前端使用相同的 DSL
+fetch('/api/validation-rules/user')
+  .then(res => res.json())
+  .then(rules => {
+    const schema = dsl(rules);  // 前后端验证规则完全一致
+  });
+```
+
+**Zod 的限制**:
+```typescript
+// ❌ Schema 是对象，无法序列化
+const schema = z.object({
+  username: z.string().min(3).max(32)
+});
+
+// ❌ JSON.stringify(schema) → 无法正确序列化
+// ❌ 无法存储到数据库
+// ❌ 无法通过 API 传输
+```
+
+---
+
+#### 4. 数据库驱动的验证规则
+
+**真实场景**: 后台管理系统，管理员可配置表单验证规则
+
+**Schema-DSL 的解决方案**:
+```javascript
+// ✅ 管理员在后台界面配置验证规则
+// 后台界面：
+// - 字段名：username
+// - 类型：string
+// - 最小长度：3
+// - 最大长度：32
+// - 必填：是
+
+// ✅ 规则存储到数据库
+await db.collection('form_rules').insert({
+  formId: 'user_registration',
+  fields: {
+    username: 'string:3-32!',
+    email: 'email!',
+    age: 'number:18-120'
+  }
+});
+
+// ✅ 应用使用最新规则（无需重启）
+app.post('/api/users', async (req, res) => {
+  // 从数据库读取最新规则
+  const formRules = await db.collection('form_rules').findOne({ 
+    formId: 'user_registration' 
+  });
+  
+  // 动态生成 Schema
+  const schema = dsl(formRules.fields);
+  
+  // 验证
+  const result = validate(schema, req.body);
+  if (!result.valid) {
+    return res.status(400).json({ errors: result.errors });
+  }
+  
+  // ... 业务逻辑
+});
+
+// ✅ 管理员修改规则后，立即生效，无需重启服务
+```
+
+**Zod 的限制**:
+```typescript
+// ❌ 无法从数据库动态加载规则
+// ❌ 验证规则必须硬编码在代码中
+// ❌ 修改规则 = 修改代码 = 重新部署
+```
+
+---
+
+#### 5. 低代码/无代码平台基础
+
+**真实场景**: 可视化表单构建器
+
+**Schema-DSL 的解决方案**:
+```javascript
+// ✅ 可视化表单构建器配置
+const formBuilder = {
+  formId: 'contact',
+  title: '联系我们',
+  fields: [
+    {
+      name: 'name',
+      label: '姓名',
+      type: 'text',
+      validation: 'string:2-50!',  // ← 在 UI 中配置
+      placeholder: '请输入您的姓名'
+    },
+    {
+      name: 'email',
+      label: '邮箱',
+      type: 'email',
+      validation: 'email!',
+      placeholder: '请输入您的邮箱'
+    },
+    {
+      name: 'message',
+      label: '留言',
+      type: 'textarea',
+      validation: 'string:10-500!',
+      placeholder: '请输入您的留言'
+    }
+  ]
+};
+
+// ✅ 自动生成验证 Schema
+const schema = dsl(
+  formBuilder.fields.reduce((acc, field) => {
+    acc[field.name] = field.validation;
+    return acc;
+  }, {})
+);
+
+// ✅ 自动生成前端表单
+function renderForm(formBuilder) {
+  return formBuilder.fields.map(field => (
+    `<div>
+      <label>${field.label}</label>
+      <input name="${field.name}" placeholder="${field.placeholder}" />
+    </div>`
+  ));
+}
+
+// ✅ 这是低代码平台的基础能力
+// - 用户在界面拖拽表单
+// - 配置验证规则（无需写代码）
+// - 自动生成前后端代码
+```
+
+---
+
+### ⚠️ 其他场景
+
+#### A/B 测试验证规则
+
+```javascript
+// ✅ 从配置中心读取 A/B 测试配置
+const abTestConfig = await configCenter.get('user_validation_ab_test');
+
+const schema = dsl({
+  username: abTestConfig.userInGroupA 
+    ? 'string:2-50!'   // A 组：宽松规则
+    : 'string:5-20!'   // B 组：严格规则
+});
+
+// 修改配置中心的值，立即生效，无需重新部署
+```
+
+#### 灰度发布
+
+```javascript
+// ✅ 根据灰度比例动态选择规则
+const grayConfig = await configCenter.get('validation_gray_config');
+const useNewRules = Math.random() < grayConfig.grayRatio;
+
+const schema = dsl(useNewRules ? newRules : oldRules);
+```
+
+---
+
+## 编译时构建的局限性
+
+### Zod 等编译时库的限制
+
+| 限制 | 说明 | 影响 |
+|------|------|------|
+| **无法动态调整** | Schema 在编译时固定 | 无法根据配置/环境/用户动态生成 |
+| **无法序列化** | Schema 是 JavaScript 对象 | 无法存储、传输、共享 |
+| **多租户困难** | 必须为每个租户写代码 | 新增租户 = 修改代码 = 重新部署 |
+| **数据库驱动困难** | 无法从数据库读取规则 | 后台配置表单验证无法实现 |
+| **配置驱动困难** | 必须硬编码 Schema | 无法从配置文件/API 动态生成 |
+| **前后端共享困难** | 无法通过 API 传输 | 前后端验证规则容易不一致 |
+| **低代码平台不适合** | 无法可视化配置 | 不适合低代码/无代码场景 |
+
+---
+
+## 性能对比与权衡
+
+### 真实性能测试结果（v2 基准，分场景对比）
+
+**测试环境**: Node.js v20.20.2, tinybench，JSON Schema 同维度对比
+
+| 场景 | Schema-DSL | vs Zod | Zod | Ajv (raw) | Joi |
+|------|-----------|:------:|-----|-----------|-----|
+| S1 简单有效 | **1.301M ops/s** | ≈ 持平（差 <1%） | 1.305M ops/s | 4.732M ops/s | 154K ops/s |
+| S2 无效（均无 i18n）| **1.205M ops/s** | **🏆 +89x** | 13.49K ops/s | 4.874M ops/s | 92.32K ops/s |
+| S3 嵌套有效 | **1.085M ops/s** | **🏆 +28%** | 846.81K ops/s | 3.974M ops/s | 125.35K ops/s |
+
+> ℹ️ 绝对 ops/s 数值随测试机器 CPU 性能而变化；**相对倍数（vs Zod 列）是稳定的跨机器指标**，以下分析均基于倍数。  
+> ℹ️ S2 使用 `validate(schema, data, { format: false })` 关闭 i18n 格式化，与其他库保持相同条件（均不做 i18n 模板渲染），是真正的苹果对苹果比较。  
+> ℹ️ Ajv (raw) 是 schema-dsl 的底层引擎，差值即为 schema-dsl 自身层（DSL 解析 + coerce + 缓存）的开销。
+
+### 性能分析
+
+**Schema-DSL vs Zod 对比结论**
+
+- **有效数据场景（S1）**：schema-dsl 与 Zod **基本持平**；**S3 嵌套场景**快约 **28%**
+- **无效数据公平对比（S2，均无 i18n 格式化）**：schema-dsl **1.205M** vs Zod **13.49K** — schema-dsl 快约 **89x**
+
+> ⚠️ **Zod 在无效数据场景极慢的根因**：Zod 的错误收集路径使用异常驱动机制（`try/catch` 控制流），每个无效字段抛出一次 Error，4 个错误字段 = 4 次 Error 实例创建 + 4 次堆栈捕获，这是其约 13.49K ops/s 的直接原因。相比之下 schema-dsl 基于 AJV 的无异常收集路径，无格式化时达 1.205M ops/s。
+
+```text
+Schema-DSL 的执行流程（含内置缓存）：
+  DSL 字符串
+    ↓ 缓存命中（热路径，无解析开销）
+  验证函数
+    ↓ 执行验证 (~0.5-1μs)
+  结果
+
+冷路径（首次）：
+  DSL 字符串 → 解析 → JSON Schema → Ajv 编译 → 缓存并执行
+```
+
+**性能瓶颈分布（冷启动）**:
+1. DSL 解析（40-50%）
+2. JSON Schema 转换（20-30%）
+3. 多语言处理（10-20%）
+4. Ajv 编译（10-15%）
+
+---
+
+### 性能权衡分析
+
+**与 Ajv (raw) 的差距**:
+```text
+- 比 Ajv (raw) 慢约 3.6-4.0x（DSL 层自身开销）
+  S1 简单场景：3.64x，S3 嵌套场景：3.66x
+- ajv (raw) 是底层引擎，无 DSL 解析/i18n/coerce 功能
+```
+
+**换来的价值**:
+```text
+✅ 代码量减少 65%
+   'string:3-32!' vs z.string().min(3).max(32)
+   
+✅ 完全动态的验证规则
+   可从配置/数据库/API 动态生成
+   
+✅ 多租户支持
+   每个租户不同规则，零代码修改
+   
+✅ 可序列化
+   可存储、传输、共享
+   
+✅ 前后端共享规则
+   一套规则，两端使用
+   
+✅ 低代码平台基础
+   可视化配置表单验证
+   
+✅ 数据库驱动
+   管理员后台配置，立即生效
+```
+
+### 性能优化措施
+
+### 缓存优化
+```javascript
+// Schema 缓存：5000条（提升 5倍）
+// 正则缓存：500条（提升 2.5倍）
+// LRU 驱逐机制
+
+// 效果：
+// - 大型项目（3000 Schema）：3倍提升
+// - 超大型项目（10000 Schema）：5-10倍提升
+```
+
+---
+
+## 架构设计
+
+### 核心组件
+
+```text
+┌─────────────────────────────────────┐
+│         DSL 字符串                  │
+│   'string:3-32!', 'email!'         │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│       DslAdapter (解析器)           │
+│   正则解析 → DSL 对象               │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│     JSONSchemaCore (转换器)         │
+│   DSL 对象 → JSON Schema            │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│        Ajv (验证引擎)               │
+│   JSON Schema → 验证函数            │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│    ErrorFormatter (错误格式化)      │
+│   Ajv 错误 → 友好消息 → 多语言     │
+└──────────────┬──────────────────────┘
+               │
+               ↓
+┌─────────────────────────────────────┐
+│         ValidationResult            │
+│    { valid, errors, data }          │
+└─────────────────────────────────────┘
+```
+
+### 缓存机制
+
+```javascript
+// Schema 缓存
+SCHEMA_CACHE: LRU(5000)  // DSL → JSONSchema
+REGEX_CACHE: LRU(500)    // 正则表达式
+
+// 缓存命中：0μs 开销
+// 缓存未命中：12-21μs 开销
+```
+
+---
+
+## 适用场景
+
+### ✅ 选择 Schema-DSL
+
+**最适合的场景**:
+
+1. **多租户 SaaS 系统**
+   - 每个租户不同验证规则
+   - 新增租户零代码修改
+
+2. **后台管理系统**
+   - 管理员配置表单验证
+   - 规则立即生效，无需重启
+
+3. **配置驱动开发**
+   - 验证规则存储在配置文件/数据库
+   - 可通过 API 动态获取
+
+4. **低代码/无代码平台**
+   - 可视化表单构建器
+   - 拖拽配置验证规则
+
+5. **快速原型开发**
+   - 5分钟上手
+   - 代码量最少
+
+6. **前后端共享验证**
+   - 一套规则，两端使用
+   - 通过 API 传输
+
+7. **A/B 测试/灰度发布**
+   - 动态切换验证规则
+   - 配置驱动
+
+### ⚠️ 以下场景可能有更优选择
+
+1. **追求代码生成级极致吞吐量**
+   - 需要 fastest-validator 级别性能（compile 为原生 JS 函数）
+   - 推荐：**fastest-validator**（但需放弃 JSON Schema 标准兼容）
+
+2. **以 Schema → 静态类型推断为核心目标**
+   - 需要从 Schema 自动导出精确的 TypeScript 类型（如 `z.infer<typeof schema>`）
+   - 推荐：**Zod**（schema-dsl 提供完整 TypeScript API 类型安全，但不做 Schema → 类型推断）
+
+3. **静态规则 + 团队已深度投入 Zod**
+   - 迁移成本大于收益时，保持现状即可
+
+---
+
+## 与其他库对比
+
+### 综合对比
+
+| 维度 | Schema-DSL | Zod | Ajv | Joi |
+|------|-----------|-----|-----|-----|
+| **有效路径性能** | ✅ **S1 持平，S3 快约 28%** | baseline | 🥇 3.6-4.0x 更快 | 7-9x 更慢 |
+| **无效路径性能** | 🏆 **Zod 的 89x** | 极慢（异常驱动）| 🥇 最快 | 中等 |
+| **动态性** | ✅✅ 完全动态 | ❌ 编译时固定 | ⚠️ 部分动态 | ⚠️ 部分动态 |
+| **语法简洁性** | ✅✅ 最简洁 | ⚠️ 较冗长 | ❌ 最冗长 | ⚠️ 较冗长 |
+| **TypeScript** | ✅ 完整（v2 全量 TS 重构）| ✅✅ 强（Schema→类型推断）| ⚠️ 基础 | ⚠️ 基础 |
+| **序列化** | ✅✅ 支持 | ❌ 不支持 | ⚠️ 部分支持 | ❌ 不支持 |
+| **多租户** | ✅✅ 容易 | ❌ 困难 | ⚠️ 可以 | ⚠️ 可以 |
+| **配置驱动** | ✅✅ 完美 | ❌ 不支持 | ⚠️ 可以 | ⚠️ 可以 |
+| **数据库导出** | ✅✅ 唯一 | ❌ | ❌ | ❌ |
+| **学习曲线** | ✅✅ 5分钟 | ⚠️ 30分钟 | ❌ 1小时 | ⚠️ 30分钟 |
+
+---
+
+## 结论
+
+### Schema-DSL 的价值主张
+
+**性能强劲 · 简单易学 · 功能强大**:
+
+```text
+性能优势（vs Zod 公平对比）：
+  ✅ S1 有效数据：快 23%
+  ✅ S3 嵌套有效：快 98%（接近 2 倍）
+  ✅ S2 无效数据：快 109 倍（Zod 异常驱动 vs AJV 无异常路径）
+
+易用性优势：
+  ✅ 语法最简洁（代码量减少 65%）
+  ✅ 5 分钟上手，学习曲线最平
+  ✅ 全量 TypeScript 重构（v2），完整类型安全
+
+功能优势：
+  ✅ 唯一支持：动态规则 / 配置驱动 / DB 导出 / i18n 多语言
+  ✅ 多租户 SaaS、低代码平台的首选验证库
+
+理性权衡：
+  ⚠️ 比 Ajv (raw) 慢约 2–3x（DSL 层自身开销：解析 + coerce + 缓存）
+  ⚠️ 不做 Schema → 静态类型推断（如需此能力仍推荐 Zod）
+
+定位：
+  性能、易用、功能三角均衡的现代 TypeScript 验证库
+  动态规则场景的最优选择
+```
+
+---
+
+**更新日期**: 2026-05-08
+
+---
+
+## 对应示例文件
+
+**示例入口**: [design-philosophy.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/design-philosophy.ts)  
+**说明**: 通过“配置生成 DSL → 序列化 → 反序列化 → 再验证”的完整闭环，展示运行时解析和可序列化这两个核心设计点。
+