schema-dsl 快速上手

阅读时间: 5分钟
目标: 快速掌握 schema-dsl 核心用法

📑 目录

入门指南

🚀 安装
📖 5分钟快速入门

进阶功能

🔧 自定义验证
🗄️ 数据库导出
📚 下一步

🚀 安装

npm install schema-dsl

Node.js 要求：>=18.0.0

当前 TypeScript 重构版以 Node.js >=18.0.0 为唯一运行时基线，不再承诺旧 Node 版本兼容。

📖 5分钟快速入门

1. Hello World（30秒）

const { dsl, validate } = require('schema-dsl');

// 定义Schema
const schema = dsl({
  name: 'string:1-50!',
  email: 'email!'
});

// 验证数据（使用便捷函数）
const result = validate(schema, {
  name: '张三',
  email: 'zhangsan@example.com'
});

console.log(result.valid); // true

解释:

'string:1-50!' - 必填字符串，长度1-50
'email!' - 必填邮箱
! 表示必填

2. DSL 语法速查（1分钟）

// 基本类型
'string'           // 字符串
'number'           // 数字
'integer'          // 整数
'boolean'          // 布尔值
'email'            // 邮箱
'url'              // URL
'date'             // 日期

// 约束
'string:3-32'      // 长度3-32（范围）
'string:100'       // 最大长度100（简写）
'string:-100'      // 最大长度100（明确写法）
'string:10-'       // 最小长度10（无最大限制）
'number:18-120'    // 范围18-120

// 必填
'string!'          // 必填字符串
'email!'           // 必填邮箱

// 枚举
'active|inactive|pending'    // 三选一

// 数组
'array<string>'              // 字符串数组
'array:1-10<string>'         // 1-10个字符串
'array<string:1-50>'         // 带约束的数组元素

语法规则:

type:max → 最大值（简写）
type:min-max → 范围
type:min- → 只限最小
type:-max → 只限最大

3. String 扩展（2分钟）

字符串支持链式调用：

const schema = dsl({
  // 字符串直接链式调用，无需 dsl() 包裹
  email: 'email!'
    .pattern(/custom/)
    .label('邮箱地址'),
  
  username: 'string:3-32!'
    .pattern(/^[a-zA-Z0-9_]+$/)
    .messages({
      'pattern': '只能包含字母、数字和下划线'
    })
    .label('用户名'),
  
  // 简单字段仍然可以用纯DSL
  age: 'number:18-120',
  role: 'user|admin'
});

可用方法:

.pattern(regex) - 正则验证
.label(text) - 字段标签
.messages(obj) - 自定义消息
.description(text) - 描述
.custom(fn) - 自定义验证器

4. 完整示例（2分钟）

const { dsl, validate } = require('schema-dsl');

// 定义用户注册Schema
const registerSchema = dsl({
  // 用户名：正则验证
  username: dsl('string:3-32!')
    .pattern(/^[a-zA-Z0-9_]+$/)
    .label('用户名')
    .error({
      pattern: '只能包含字母、数字和下划线'
    }),
  
  // 邮箱：标签
  email: dsl('email!').label('邮箱地址'),
  
  // 密码：复杂正则
  password: dsl('string:8-64!')
    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
    .label('密码')
    .error({
      pattern: '必须包含大小写字母和数字'
    }),
  
  // 简单字段
  age: 'number:18-120',
  role: 'user|admin'
});

// 验证数据
const testData = {
  username: 'john_doe',
  email: 'john@example.com',
  password: 'Password123',
  age: 25,
  role: 'user'
};

const result = validate(registerSchema, testData);

if (result.valid) {
  console.log('✅ 验证通过！');
} else {
  console.log('❌ 验证失败:', result.errors);
}

💡 最佳实践

1. 简单字段用纯DSL

const schema = dsl({
  name: 'string:1-50!',     // ✅ 简洁
  age: 'number:18-120',     // ✅ 清晰
  role: 'user|admin'        // ✅ 直观
});

2. 复杂字段用String扩展

const schema = dsl({
  email: 'email!'
    .pattern(/custom/)
    .messages({...})
    .label('邮箱'),
  
  username: 'string:3-32!'
    .pattern(/^\w+$/)
    .custom(checkExists)
});

3. 80/20 法则

80%字段用纯DSL，20%字段用String扩展

🎯 常见场景

表单验证

const formSchema = dsl({
  email: 'email!'.label('邮箱地址'),
  password: 'string:8-64!'.label('密码'),
  nickname: 'string:2-20'.label('昵称'),
  bio: 'string:500',
  website: 'url',
  age: 'number:18-120',
  gender: 'male|female|other'
});

自定义验证

.custom() 当前仅支持同步函数；如果需要异步查重，请在 validate() / validateAsync() 通过后于业务层单独执行。

const schema = dsl({
  username: 'string:3-32!'
    .custom((value) => {
      if (value === 'admin') {
        return '用户名已存在';
      }
    })
});

嵌套对象

const schema = dsl({
  user: {
    profile: {
      name: 'string:1-50!'.label('姓名'),
      avatar: 'url'.label('头像'),
      social: {
        twitter: 'url'.pattern(/twitter\.com/),
        github: 'url'.pattern(/github\.com/)
      }
    }
  }
});

📚 下一步

深入学习

示例代码

Quick Start 完整示例

其余主题示例现在都已分别挂到各自文档底部，并统一切到稳定 GitHub 示例链接。

高级功能

🎯 设计理念与性能

为什么选择运行时解析？

Schema-DSL 使用运行时解析 DSL，而非编译时构建（如 Zod），这是有意的设计选择：

✅ 运行时解析的优势

完全动态 - 验证规则可以从配置文件、数据库动态加载

// 从配置读取规则
const rules = await db.findOne({ entity: 'user' });
const schema = dsl({
  username: `string:${rules.min}-${rules.max}!`
});

多租户支持 - 每个租户可以有不同的验证规则

// 租户A: 用户名3-32字符
// 租户B: 用户名5-50字符
function getTenantSchema(tenantId) {
  const rules = tenantConfig[tenantId];
  return dsl({
    username: `string:${rules.min}-${rules.max}!`
  });
}

可序列化 - DSL 字符串可以存储、传输、共享

// 存储到数据库
await db.insert({ 
  formId: 'register', 
  rules: { username: 'string:3-32!', email: 'email!' }
});

// 通过 API 传输
res.json({ validationRules: rules });

// 前后端共享规则

低代码基础 - 支持可视化表单构建器

// 管理员在界面配置验证规则
const formBuilder = {
  fields: [
    { name: 'username', validation: 'string:3-32!' }
  ]
};

⚠️ 性能权衡

S1 有效数据与 Zod 持平，S3 嵌套场景快约 28%，无效数据公平对比快 89x：

库名	性能	场景
Ajv (raw)	4.732M ops/s	底层引擎，无 DSL 层
Schema-DSL	1.301M ops/s（S1有效）	全功能（DSL + i18n + coerce）
Schema-DSL	1.205M ops/s（S2 无效，均无 i18n）	公平对比（均无 i18n）
Zod	1.305M ops/s（S1有效）/ 13.49K（S2 无效）	编译时构建，错误路径异常驱动
Joi	154K ops/s	功能丰富

结论:

✅ S3 嵌套有效场景比 Zod 快 28%；S1 简单有效场景持平（差 <1%）
✅ 无效数据公平对比（均无 i18n）比 Zod 快 89x
✅ 内置缓存，热路径零解析开销

适用场景

✅ 选择 Schema-DSL:

需要动态验证规则（配置驱动、多租户）
需要数据库 Schema 导出
快速开发原型
多语言 SaaS 系统

⚠️ 考虑其他库:

TypeScript 项目需要强类型推断 → Zod
性能是第一优先级 → Ajv 或 Zod
静态验证规则 → Zod

🆘 常见问题

Q: String扩展和纯DSL有什么区别？

纯DSL: 适合简单字段，语法简洁
String扩展: 适合复杂验证，支持链式调用

// 纯DSL（简单）
name: 'string:1-50!'

// String扩展（复杂）
email: 'email!'
  .pattern(/custom/)
  .messages({...})

Q: 如何禁用String扩展？

const { uninstallStringExtensions } = require('schema-dsl');
uninstallStringExtensions();

Q: 支持TypeScript吗？

A: 支持！schema-dsl 提供完整的 TypeScript 类型定义。

🎉 恭喜！

你已经掌握了 schema-dsl 的核心用法！

核心要点:

✅ DSL语法简洁直观
✅ String扩展强大灵活
✅ 80%用DSL，20%用扩展
✅ 字符串可以直接链式调用

开始使用: npm install schema-dsl

对应示例文件

示例入口: quick-start.ts
说明: 覆盖快速上手中的 Hello World、String 扩展、用户注册示例，以及 validate() 与 Validator.compile() 的基础复用路径，可直接运行参考。

最后更新: 2026-05-08

#schema-dsl 快速上手

#📑 目录

#入门指南

#进阶功能

#🚀 安装

#📖 5分钟快速入门

#1. Hello World（30秒）

#2. DSL 语法速查（1分钟）

#3. String 扩展（2分钟）

#4. 完整示例（2分钟）

#💡 最佳实践

#1. 简单字段用纯DSL

#2. 复杂字段用String扩展

#3. 80/20 法则

#🎯 常见场景

#表单验证

#自定义验证

#嵌套对象

#📚 下一步

#深入学习

#示例代码

#高级功能

#🎯 设计理念与性能

#为什么选择运行时解析？

#✅ 运行时解析的优势

#⚠️ 性能权衡

#适用场景

#🆘 常见问题

#Q: String扩展和纯DSL有什么区别？

#Q: 如何禁用String扩展？

#Q: 支持TypeScript吗？

#🎉 恭喜！

#对应示例文件