schema-dsl API 参考文档
更新时间: 2025-12-25
📑 目录
dsl() 函数
描述
DSL 主入口函数，支持字符串和对象两种定义方式。
语法
dsl(definition: string | object): DslBuilder | JSONSchema
参数
definition (string | object) - DSL定义
- 字符串：返回 DslBuilder 实例（可链式调用）
- 对象：返回 JSON Schema 对象
返回值
- DslBuilder - 当参数为字符串时
- Object - 当参数为对象时（JSON Schema）
示例
// 字符串：返回 DslBuilder
const builder = dsl('email!');
builder.pattern(/custom/).label('邮箱');
// 对象：返回 JSON Schema
const schema = dsl({
username: 'string:3-32!',
email: 'email!'
});
DslBuilder 类
描述
Schema 构建器类，支持链式调用添加验证规则。
构造函数
new DslBuilder(dslString: string)
参数:
dslString (string) - DSL字符串，如 'string:3-32!'
方法
.pattern(regex, message?)
添加正则表达式验证。
参数:
regex (RegExp | string) - 正则表达式message (string, 可选) - 自定义错误消息
返回: DslBuilder
示例:
dsl('string:3-32!')
.pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')
.label(text)
设置字段标签（用于错误消息）。
参数:
返回: DslBuilder
示例:
dsl('email!').label('邮箱地址')
.messages(messages)
自定义错误消息。
参数:
messages (Object) - 错误消息对象
- 键：错误代码（如
'string.min'）
- 值：错误消息模板
返回: DslBuilder
示例:
dsl('string:3-32!')
.messages({
'min': '至少{{#limit}}个字符',
'max': '最多{{#limit}}个字符'
})
.description(text)
设置字段描述。
参数:
返回: DslBuilder
示例:
dsl('url').description('个人主页链接')
.custom(validator)
添加自定义验证器。
参数:
validator (Function) - 验证函数
- 签名：
(value) => boolean | string | { error, message } | void
- 返回
true 表示通过
- 返回
false、错误消息字符串或错误对象表示失败
- ⚠️ 当前运行时仅支持同步自定义验证；异步校验请在
validate() / validateAsync() 通过后于业务层单独执行
返回: DslBuilder
示例:
dsl('string:3-32!')
.custom((value) => {
if (value === 'admin') {
return { error: 'username.exists', message: '用户名已存在' };
}
})
.default(value)
设置默认值。
参数:
返回: DslBuilder
示例:
dsl('string').default('guest')
.username(preset?)
用户名验证（自动设置长度和正则）。
参数:
preset (string | Object, 可选) - 预设配置
- 字符串：
'short' | 'medium' | 'long' | '5-20'
- 对象：
{ minLength, maxLength, allowUnderscore, allowNumber }
- 默认值：
'medium' (3-32位)
返回: DslBuilder
示例:
// 默认 medium (3-32位)
dsl('string!').username()
// 自定义范围
dsl('string!').username('5-20')
// 使用预设
dsl('string!').username('short') // 3-16位
.password(strength?)
密码强度验证（自动设置长度和正则）。
参数:
strength (string, 可选) - 强度级别
'weak' - 最少6位'medium' - 8位，字母+数字（默认）'strong' - 8位，大小写+数字'veryStrong' - 10位，大小写+数字+特殊字符
返回: DslBuilder
示例:
dsl('string!').password('strong')
.phone(country?)
手机号验证（自动设置长度和正则）。
参数:
country (string, 可选) - 国家代码
'cn' - 中国（默认）'us' - 美国'uk' - 英国'hk' - 香港'tw' - 台湾'international' - 国际格式
返回: DslBuilder
注意: 自动将类型纠正为 string（即使写成 number 也会自动修正）
示例:
// 推荐写法
dsl('string!').phone('cn')
// 自动纠正：number → string
dsl('number!').phone('cn') // 自动纠正为 string
.toSchema()
转换为 JSON Schema 对象（含内部标记）。
返回: Object - JSON Schema 对象（包含 _required、_customMessages、_label 等 schema-dsl 内部字段）
示例:
const schema = dsl('email!').label('邮箱').toSchema();
// { type: 'string', format: 'email', _label: '邮箱', _required: true }
.toJsonSchema() v1.2.5+
转换为纯净的 JSON Schema 对象（无内部标记）。
与 toSchema() 不同，toJsonSchema() 会自动清理所有 schema-dsl 内部标记：
- 下划线前缀字段：
_required、_customMessages、_label、_customValidators、_whenConditions
- 自定义验证关键字：
exactLength、alphanum、lowercase、uppercase、trim、jsonString、port、requiredAll、strictSchema、noSparse、includesRequired、dateFormat、dateGreater、dateLess、precision、multipleOf
返回的对象可直接嵌入 OpenAPI / JSON Schema 等标准文档中，无需下游再做清理。
返回: Object - 纯净的 JSON Schema 对象
适用场景:
- 生成 OpenAPI 文档
- 导出给外部系统消费
- 任何需要标准 JSON Schema 的场景
示例:
// 对比 toSchema() 与 toJsonSchema()
const builder = dsl('string:3-32!').label('用户名').messages({ min: '至少3个字符' });
builder.toSchema();
// { type: 'string', minLength: 3, maxLength: 32, _required: true, _label: '用户名', _customMessages: { min: '至少3个字符' } }
builder.toJsonSchema();
// { type: 'string', minLength: 3, maxLength: 32 }
// 注意：不含 _required、_label、_customMessages 等内部字段
// enum 示例
const enumBuilder = dsl('enum:admin,user,guest!');
enumBuilder.toJsonSchema();
// { type: 'string', enum: ['admin', 'user', 'guest'] }
// 用于 OpenAPI 文档生成
const schema = dsl({
username: 'string:3-32!',
email: 'email!',
age: 'number:0-120'
});
// 遍历各字段调用 toJsonSchema() 即可获得标准 JSON Schema
.validate(data)
验证数据（便捷方法）。
参数:
返回: Promise