schema-dsl 1.2.4 → 2.0.0

package/docs/api-reference.md

@@ -1,7 +1,7 @@
 # schema-dsl API 参考文档
 
 
-> **更新时间**: 2025-12-25  
+> **更新时间**: 2026-05-22  
 
 ---
 
@@ -150,21 +150,20 @@ dsl('url').description('个人主页链接')
 
 **参数**:
 - `validator` (**Function**) - 验证函数
-  - 签名：`(value) => boolean | Promise<boolean> | { error, message }`
+  - 签名：`(value) => boolean | string | { error, message } | void`
   - 返回 `true` 表示通过
-  - 返回 `false` 或错误对象表示失败
+  - 返回 `false`、错误消息字符串或错误对象表示失败
+  - 同步验证器由 `validate()` 和 `validateAsync()` 均执行；异步验证器（返回 `Promise`）仅由 `validateAsync()` 执行，`validate()` 调用时会跳过异步 validator
 
 **返回**: **DslBuilder**
 
 **示例**:
 ```javascript
 dsl('string:3-32!')
-  .custom(async (value) => {
-    const exists = await checkUsernameExists(value);
-    if (exists) {
+  .custom((value) => {
+    if (value === 'admin') {
       return { error: 'username.exists', message: '用户名已存在' };
     }
-    return true;
   })
 ```
 
@@ -263,9 +262,9 @@ dsl('number!').phone('cn')  // 自动纠正为 string
 
 #### `.toSchema()`
 
-转换为 JSON Schema 对象。
+转换为 JSON Schema 对象（含内部标记）。
 
-**返回**: **Object** - JSON Schema对象
+**返回**: **Object** - JSON Schema 对象（包含 `_required`、`_customMessages`、`_label` 等 schema-dsl 内部字段）
 
 **示例**:
 ```javascript
@@ -275,13 +274,68 @@ const schema = dsl('email!').label('邮箱').toSchema();
 
 ---
 
-#### `.validate(data, context?)`
+#### `.toJsonSchema()` <sup>v1.2.5+</sup>
+
+转换为纯净的 JSON Schema 对象（无内部标记）。
+
+与 `toSchema()` 不同，`toJsonSchema()` 会自动清理所有 schema-dsl 内部标记：
+- **下划线前缀字段**：`_required`、`_customMessages`、`_label`、`_customValidators`、`_whenConditions`
+- **自定义验证关键字（直接清除）**：`alphanum`、`lowercase`、`uppercase`、`trim`、`jsonString`、`port`、`requiredAll`、`strictSchema`、`noSparse`、`includesRequired`、`dateFormat`、`dateGreater`、`dateLess`、`precision`
+- **`exactLength` 特殊翻译**：不直接清除，而是转换为标准 JSON Schema `{ minLength: N, maxLength: N }`（与 v1 DslBuilder `string:N` 行为兼容）
+
+> ⚠️ `multipleOf` 是标准 JSON Schema 字段，**不会**被清除（v2 修复了 v1 的错误行为）。
+
+返回的对象可直接嵌入 OpenAPI / JSON Schema 等标准文档中，无需下游再做清理。
+
+**返回**: **Object** - 纯净的 JSON Schema 对象
+
+**适用场景**:
+- 生成 OpenAPI 文档
+- 导出给外部系统消费
+- 任何需要标准 JSON Schema 的场景
+
+**示例**:
+```javascript
+// 对比 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 等内部字段
+
+// string:N 单值语法（exactLength → minLength + maxLength）
+const exact = dsl('string:6!');
+exact.toSchema();
+// { type: 'string', exactLength: 6, _required: true }
+exact.toJsonSchema();
+// { type: 'string', minLength: 6, maxLength: 6 }
+// 注：exactLength 自动翻译为标准 JSON Schema 的 minLength + maxLength（v1 兼容行为）
+
+// 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)`
 
 验证数据（便捷方法）。
 
 **参数**:
 - `data` (**any**) - 待验证数据
-- `context` (**Object**, 可选) - 验证上下文
 
 **返回**: **Promise<Object>** - 验证结果
   - `valid` (**boolean**) - 是否通过
@@ -337,273 +391,326 @@ dsl.if('isVip', 'number:0-50', 'number:0-10')
 
 ---
 
+## 运行时辅助函数
+
+### `dsl.config(options)`
+
+全局配置入口，在应用启动时调用一次，设置 i18n、缓存、自定义正则和严格类型解析模式。
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+dsl.config({
+  // i18n：内置语言包路径 / 内联 locale bundle / { localesPath } / { locales }
+  i18n: './locales',
+
+  // 默认语言（默认 'en-US'）
+  defaultLocale: 'zh-CN',
+
+  // 编译缓存配置
+  cache: { maxSize: 2000, ttl: 0, enabled: true },
+
+  // strict: true → 遇到未知类型直接抛出 Error（默认 false：warn + 回退 string）
+  strict: true,
+
+  // 追加自定义正则规则（phone / idCard / creditCard 等）
+  patterns: {
+    phone: { us: /^\+1\d{10}$/ }
+  }
+});
+```
+
+**参数** (`DslConfigOptions`):
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `i18n` | `string \| object` | — | 语言包路径或内联对象 |
+| `defaultLocale` | `string` | `'en-US'` | 默认语言 |
+| `cache` | `CacheOptions` | — | `maxSize` / `ttl` / `enabled` / `statsEnabled` |
+| `strict` | `boolean` | `false` | `true` 时解析未知 DSL 类型抛出 Error |
+| `patterns` | `object` | — | 追加自定义格式正则（phone/idCard/creditCard） |
+
+---
+
+### `getDefaultValidator()`
+
+获取顶层 `validate()` / `validateAsync()` 便捷函数内部复用的默认 `Validator` 单例。
+
+```javascript
+const { getDefaultValidator } = require('schema-dsl');
+
+const validator = getDefaultValidator();
+console.log(validator.getCacheStats());
+```
+
+---
+
+### `resetDefaultValidator()`
+
+重置顶层 `validate()` / `validateAsync()` 使用的默认 `Validator` 单例。
+
+```javascript
+const { resetDefaultValidator } = require('schema-dsl');
+
+resetDefaultValidator();
+```
+
+---
+
+### `installStringExtensions(dslFunction?)`
+
+手动安装 String 扩展。模块导入时默认已自动安装；只有在调用过 `uninstallStringExtensions()` 或需要显式恢复扩展时才需要手动执行。
+
+```javascript
+const { installStringExtensions } = require('schema-dsl');
+
+installStringExtensions();
+```
+
+---
+
+### `uninstallStringExtensions()`
+
+卸载挂载到 `String.prototype` 上的扩展方法。
+
+```javascript
+const { uninstallStringExtensions } = require('schema-dsl');
+
+uninstallStringExtensions();
+```
+
+---
+
 ## Validator 类
 
 **参数**:
-- `dslString` (**string**) - DSL字符串，如 `'string:3-32!'`
+- `options` (**Object**, 可选) - Validator 配置项
 
 ### 方法
 
-#### `.pattern(regex, message?)`
+#### `.compile(schema, cacheKey?)`
 
-添加正则表达式验证。
+编译 Schema 为 AJV 验证函数。
 
 **参数**:
-- `regex` (**RegExp** | **string**) - 正则表达式
-- `message` (**string**, 可选) - 自定义错误消息
+- `schema` (**Object**) - JSON Schema
+- `cacheKey` (**string** | **null**, 可选) - 缓存键
 
-**返回**: **DslBuilder**
+**返回**: **Function** - AJV 验证函数
 
 **示例**:
 ```javascript
-dsl('string:3-32!')
-  .pattern(/^[a-zA-Z0-9_]+$/, '只能包含字母、数字和下划线')
+const validator = new Validator();
+const validate = validator.compile(schema, 'user-schema');
+const ok = validate(data);
 ```
 
 ---
 
-#### `.label(text)`
+#### `.validate(schema, data, options?)`
 
-设置字段标签（用于错误消息）。
+同步验证。
 
 **参数**:
-- `text` (**string**) - 标签文本
+- `schema` (**Object** | **Function**) - JSON Schema 或已编译的验证函数
+- `data` (**any**) - 待验证数据
+- `options` (**Object**, 可选) - 验证选项
 
-**返回**: **DslBuilder**
+**返回**: **Object**
+- `valid` (**boolean**) - 是否通过
+- `errors` (**Array**, 可选) - 错误列表
+- `data` (**any**, 可选) - 经过处理后的数据
 
 **示例**:
 ```javascript
-dsl('email!').label('邮箱地址')
+const validator = new Validator();
+const result = validator.validate(schema, payload);
+console.log(result.valid);
 ```
 
 ---
 
-#### `.messages(messages)`
+#### `.validateAsync(schema, data, options?)`
 
-自定义错误消息。
+异步验证。验证失败时抛出 `ValidationError`。
 
 **参数**:
-- `messages` (**Object**) - 错误消息对象
-  - 键：错误代码（如 `'string.min'`）
-  - 值：错误消息模板
+- `schema` (**Object** | **Function**) - JSON Schema 或已编译的验证函数
+- `data` (**any**) - 待验证数据
+- `options` (**Object**, 可选) - 验证选项
 
-**返回**: **DslBuilder**
+**返回**: **Promise<any>** - 验证通过后的数据
 
 **示例**:
 ```javascript
-dsl('string:3-32!')
-  .messages({
-    'string.min': '至少{{#limit}}个字符',
-    'string.max': '最多{{#limit}}个字符'
-  })
+const validator = new Validator();
+await validator.validateAsync(schema, payload);
 ```
 
 ---
 
-#### `.description(text)`
+#### `.validateBatch(schema, dataArray)`
 
-设置字段描述。
+批量验证。Schema 只编译一次，多次复用。
 
 **参数**:
-- `text` (**string**) - 描述文本
+- `schema` (**Object**) - JSON Schema
+- `dataArray` (**Array**) - 待验证数据数组
 
-**返回**: **DslBuilder**
+**返回**: **Array<Object>** - 每项对应一个验证结果
 
 **示例**:
 ```javascript
-dsl('url').description('个人主页链接')
+const validator = new Validator();
+const results = validator.validateBatch(schema, records);
 ```
 
 ---
 
-#### `.custom(validator)`
+#### `.addKeyword(keyword, definition)`
 
-添加自定义验证器。
+添加 AJV 自定义关键字。
 
 **参数**:
-- `validator` (**Function**) - 验证函数
-  - 签名：`(value) => boolean | Promise<boolean> | { error, message }`
-  - 返回 `true` 表示通过
-  - 返回 `false` 或错误对象表示失败
+- `keyword` (**string**) - 关键字名称
+- `definition` (**Object**) - AJV 关键字定义
 
-**返回**: **DslBuilder**
+**返回**: **Validator**
 
 **示例**:
 ```javascript
-dsl('string:3-32!')
-  .custom(async (value) => {
-    const exists = await checkUsernameExists(value);
-    if (exists) {
-      return { error: 'username.exists', message: '用户名已存在' };
-    }
-    return true;
-  })
+const validator = new Validator();
+validator.addKeyword('isEven', {
+  type: 'number',
+  validate: (_schema, data) => data % 2 === 0
+});
 ```
 
 ---
 
-#### `.default(value)`
+#### `.addFormat(name, validator)`
 
-设置默认值。
+添加 AJV 自定义格式。
 
 **参数**:
-- `value` (**any**) - 默认值
+- `name` (**string**) - 格式名称
+- `validator` (**Function** | **Object**) - AJV format 定义
 
-**返回**: **DslBuilder**
+**返回**: **Validator**
 
 **示例**:
 ```javascript
-dsl('string').default('guest')
+const validator = new Validator();
+validator.addFormat('phone-cn', /^1[3-9]\d{9}$/);
 ```
 
 ---
 
-#### `.username(preset?)`
+#### `.addSchema(uri, schema)`
 
-用户名验证（自动设置长度和正则）。
+添加 schema 引用。
 
 **参数**:
-- `preset` (**string** | **Object**, 可选) - 预设配置
-  - 字符串：`'short'` | `'medium'` | `'long'` | `'5-20'`
-  - 对象：`{ minLength, maxLength, allowUnderscore, allowNumber }`
-  - 默认值：`'medium'` (3-32位)
+- `uri` (**string**) - schema 标识
+- `schema` (**Object**) - JSON Schema
 
-**返回**: **DslBuilder**
+**返回**: **Validator**
 
 **示例**:
 ```javascript
-// 默认 medium (3-32位)
-dsl('string!').username()
-
-// 自定义范围
-dsl('string!').username('5-20')
-
-// 使用预设
-dsl('string!').username('short')  // 3-16位
+const validator = new Validator();
+validator.addSchema('user.schema.json', schema);
 ```
 
 ---
 
-#### `.password(strength?)`
+#### `.removeSchema(uri)`
 
-密码强度验证（自动设置长度和正则）。
+删除 schema 引用。
 
 **参数**:
-- `strength` (**string**, 可选) - 强度级别
-  - `'weak'` - 最少6位
-  - `'medium'` - 8位，字母+数字（默认）
-  - `'strong'` - 8位，大小写+数字
-  - `'veryStrong'` - 10位，大小写+数字+特殊字符
+- `uri` (**string**) - schema 标识
 
-**返回**: **DslBuilder**
+**返回**: **Validator**
 
 **示例**:
 ```javascript
-dsl('string!').password('strong')
+const validator = new Validator();
+validator.removeSchema('user.schema.json');
 ```
 
 ---
 
-#### `.phone(country?)`
+#### `.getAjv()`
 
-手机号验证（自动设置长度和正则）。
+获取底层 AJV 实例。
 
-**参数**:
-- `country` (**string**, 可选) - 国家代码
-  - `'cn'` - 中国（默认）
-  - `'us'` - 美国
-  - `'uk'` - 英国
-  - `'hk'` - 香港
-  - `'tw'` - 台湾
-  - `'international'` - 国际格式
-
-**返回**: **DslBuilder**
-
-**注意**: 自动将类型纠正为 `string`（即使写成 `number` 也会自动修正）
+**返回**: **Ajv**
 
 **示例**:
 ```javascript
-// 推荐写法
-dsl('string!').phone('cn')
-
-// 自动纠正：number → string
-dsl('number!').phone('cn')  // 自动纠正为 string
+const validator = new Validator();
+const ajv = validator.getAjv();
 ```
 
 ---
 
-#### `.toSchema()`
+#### `.clearCache()`
 
-转换为 JSON Schema 对象。
+清空编译缓存。
 
-**返回**: **Object** - JSON Schema对象
+**返回**: `void`
 
 **示例**:
 ```javascript
-const schema = dsl('email!').label('邮箱').toSchema();
-// { type: 'string', format: 'email', _label: '邮箱', _required: true }
+const validator = new Validator();
+validator.clearCache();
 ```
 
 ---
 
-#### `.validate(data, context?)`
-
-验证数据（便捷方法）。
+#### `.getCacheStats()`
 
-**参数**:
-- `data` (**any**) - 待验证数据
-- `context` (**Object**, 可选) - 验证上下文
+获取缓存统计信息。
 
-**返回**: **Promise<Object>** - 验证结果
-  - `valid` (**boolean**) - 是否通过
-  - `errors` (**Array**, 可选) - 错误列表
-  - `data` (**any**, 可选) - 验证通过的数据
+**返回**: **Object**
 
 **示例**:
 ```javascript
-const result = await dsl('email!').validate('user@example.com');
-console.log(result.valid); // true
+const validator = new Validator();
+console.log(validator.getCacheStats());
 ```
 
 ---
 
-### 静态方法 
-
-#### `dsl.match(field, map)```
+### 静态方法
 
-创建条件验证规则（类似 switch-case）。
+#### `Validator.create(options?)`
 
-**参数**:
-- `field` (**string**) - 依赖的字段名
-- `map` (**Object**) - 值与Schema的映射
-  - `[value: string]`: 对应的Schema
-  - `_default` (**optional**): 默认Schema
+创建 `Validator` 实例。
 
-**返回**: **Object** - 内部Match结构
+**返回**: **Validator**
 
 **示例**:
 ```javascript
-dsl.match('type', {
-  email: 'email!',
-  phone: 'string:11!',
-  _default: 'string'
-})
+const validator = Validator.create();
 ```
 
-#### `dsl.if(condition, thenSchema, elseSchema)`
+---
 
-创建简单的条件验证规则。
+#### `Validator.quickValidate(schema, data)`
+
+快速验证。
 
 **参数**:
-- `condition` (**string**) - 条件字段名
-- `thenSchema` (**string|Object**) - 满足条件时的Schema
-- `elseSchema` (**string|Object**, 可选) - 不满足条件时的Schema
+- `schema` (**Object**) - JSON Schema
+- `data` (**any**) - 待验证数据
 
-**返回**: **Object** - 内部If结构
+**返回**: **boolean**
 
 **示例**:
 ```javascript
-dsl.if('isVip', 'number:0-50', 'number:0-10')
+const ok = Validator.quickValidate(schema, data);
 ```
 
 ---
@@ -636,11 +743,11 @@ const command = exporter.generateCommand('users', jsonSchema);
 const { MySQLExporter } = require('schema-dsl');
 
 const exporter = new MySQLExporter();
-const ddl = exporter.export(jsonSchema, { tableName: 'users' });
+const ddl = exporter.export('users', jsonSchema);
 ```
 
 **方法**:
-- `export(schema, options)` - 导出为MySQL DDL
+- `export(tableName, schema)` - 导出为MySQL DDL
 
 ---
 
@@ -652,11 +759,11 @@ const ddl = exporter.export(jsonSchema, { tableName: 'users' });
 const { PostgreSQLExporter } = require('schema-dsl');
 
 const exporter = new PostgreSQLExporter();
-const ddl = exporter.export(jsonSchema, { tableName: 'users' });
+const ddl = exporter.export('users', jsonSchema);
 ```
 
 **方法**:
-- `export(schema, options)` - 导出为PostgreSQL DDL
+- `export(tableName, schema)` - 导出为PostgreSQL DDL
 
 ---
 
@@ -669,7 +776,8 @@ const ddl = exporter.export(jsonSchema, { tableName: 'users' });
 ```javascript
 const { TypeConverter } = require('schema-dsl');
 
-TypeConverter.toJSONSchema(dslSchema);
+TypeConverter.toJSONSchemaType('string');
+TypeConverter.toMongoDBType('integer');
 ```
 
 ---
@@ -687,19 +795,123 @@ SchemaHelper.clone(schema);
 
 ---
 
+### ErrorFormatter
+
+验证错误格式化工具，用于把 Ajv 原始错误数组或简化错误对象转换成统一的错误项结构或消息文本。
+
+```javascript
+const { ErrorFormatter } = require('schema-dsl');
+
+const formatter = new ErrorFormatter('zh-CN');
+const errors = formatter.formatDetailed(ajvValidate.errors);
+console.log(errors[0].message);
+```
+
+**方法**:
+- `new ErrorFormatter(locale?, messages?)` - 创建错误格式化器
+- `format(error, locale?)` - 格式化单个错误为消息字符串
+- `formatDetailed(errors, locale?, customMessages?, alreadyMerged?)` - 格式化错误数组为标准错误项列表
+
+---
+
+### MessageTemplate
+
+错误消息模板封装类，内部委托 `renderTemplate()` 执行占位符替换。
+
+```javascript
+const { MessageTemplate } = require('schema-dsl');
+
+const template = new MessageTemplate('{{#label}} is required');
+console.log(template.render({ label: 'Email' }));
+```
+
+**方法**:
+- `new MessageTemplate(template)` - 创建模板实例
+- `render(context)` - 渲染当前模板
+- `MessageTemplate.render(template, context)` - 静态快速渲染
+- `MessageTemplate.renderBatch(templates, context)` - 批量渲染多个模板
+
+---
+
+### renderTemplate(template, params)
+
+底层模板渲染函数，同时兼容 `{{#key}}` 和 `{key}` 两种占位符格式。
+
+```javascript
+const { renderTemplate } = require('schema-dsl');
+
+const msg = renderTemplate('{field} must be {min}~{max}', {
+  field: 'age',
+  min: 18,
+  max: 65,
+});
+
+console.log(msg); // age must be 18~65
+```
+
+---
+
+### JSONSchemaCore
+
+`JSONSchemaCore` 是 v1 兼容外观类，用于以链式方式构建 JSON Schema，并可直接调用 `validate()` 做快速校验。
+
+```javascript
+const { JSONSchemaCore } = require('schema-dsl');
+
+const schema = new JSONSchemaCore()
+  .type('object')
+  .property('email', { type: 'string', format: 'email' })
+  .required('email')
+  .getSchema();
+```
+
+**常用方法**:
+- `type(typeName)`
+- `property(name, schema)`
+- `properties(properties)`
+- `required(fields)`
+- `format(formatName)`
+- `pattern(pattern)`
+- `items(schema)`
+- `toSchema()` / `getSchema()`
+- `validate(data)`
+
+---
+
+### 类型注册与内部解析边界
+
+`schema-dsl` 的 root API 只保留业务可依赖的稳定入口。DSL 解析器、约束解析器、Schema 编译器和 Adapter 属于内部实现细节，不再作为 root API 文档化导出；业务代码应优先使用 `dsl()`、`DslBuilder`、`Validator` 和 `validate()`。
+
+#### TypeRegistry
+
+统一类型注册表。它是自定义类型扩展的公开入口；如果只需要注册 DSL 类型，也可以优先使用更高层的 `DslBuilder.registerType()`。
+
+- `TypeRegistry.resolve(typeName)`
+- `TypeRegistry.register(name, def)`
+- `TypeRegistry.registerDynamic(name, factory)`
+- `TypeRegistry.unregister(name)`
+- `TypeRegistry.has(typeName)`
+- `TypeRegistry.getInternalKeys()`
+- `TypeRegistry.toJsonSchema(schema)`
+- `TypeRegistry.clearCustomTypes()` — 清空所有自定义类型（含通过 `DslAdapter.registerType()` 注册的类型），适合测试后清理状态
+- `TypeRegistry.setStrict(flag)` — 设置严格模式，等效于 `dsl.config({ strict: flag })`
+
+---
+
 ## DSL 语法快速参考
 
 ### 基本类型
 
-```
+```text
 string, number, integer, boolean
 email, url, uuid, date, datetime
 ```
 
 ### 约束
 
-```
-string:min-max      # 字符串长度
+```text
+string:N            # 精确长度（exactLength = N，等同于 minLength: N, maxLength: N）
+string:min-max      # 字符串长度范围
 number:min-max      # 数字范围
 value1|value2       # 枚举
 !                   # 必填
@@ -707,7 +919,7 @@ value1|value2       # 枚举
 
 ### 数组
 
-```
+```text
 array<type>         # 数组
 array<string:1-50>  # 带约束的数组元素
 ```
@@ -752,6 +964,29 @@ Locale.setLocale('en-US');  // 设置英文
 
 ---
 
+### ConditionalBuilder
+
+`dsl.if(conditionFn)` 返回的链式条件构建器，适用于运行时动态条件校验。
+
+**常用方法**:
+- `if(condition)`
+- `and(condition)`
+- `or(condition)`
+- `elseIf(condition)`
+- `message(msg)`
+- `then(schema)`
+- `else(schema)`
+- `toSchema()`
+- `build()` - `toSchema()` 的别名
+- `validate(data, options?)`
+- `validateAsync(data, options?)`
+- `assert(data, options?)`
+- `check(data)`
+
+更完整的示例和行为说明请参考 [conditional-api.md](./conditional-api.md)。
+
+---
+
 ## 完整示例
 
 ```javascript
@@ -796,10 +1031,17 @@ console.log(result.valid); // true
 
 - [DSL 语法完整指南](./dsl-syntax.md)
 - [错误处理](./error-handling.md)
-- [示例代码](../examples/)
-- [GitHub](https://github.com/yourname/schema-dsl)
+- [示例代码](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/api-reference.ts)
+- [GitHub](https://github.com/vextjs/schema-dsl)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [api-reference.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/api-reference.ts)  
+**说明**: 覆盖 `dsl()`、`validate()`、`validateAsync()`、默认 `Validator` 单例、模板渲染、`JSONSchemaCore`、`ErrorFormatter` 以及底层解析 / 编译工具的可运行调用链。
 
 ---
 
-**最后更新**: 2025-12-29
+**最后更新**: 2026-05-08