schema-dsl 1.2.4 → 2.0.0

package/docs/api.md

@@ -0,0 +1,13 @@
+# API 参考入口
+
+完整 API 参考请见：[api-reference.md](./api-reference.md)。
+
+本文件用于兼容历史文档中的 `./api.md` 链接。
+
+---
+
+## 对应示例文件
+
+**示例入口**: [api.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/api.ts)  
+**说明**: 以最小入口串起 `dsl()`、`validate()`、`Validator.validateAsync()` 和 `TypeConverter` 这些最常用公开 API。
+

package/docs/best-practices-project-structure.md

@@ -2,7 +2,7 @@
 
 ## 推荐的项目结构
 
-```
+```text
 your-project/
 ├── schemas/              # ✅ 所有 schema 定义（项目启动时加载）
 │   ├── index.js          # 统一导出
@@ -49,7 +49,7 @@ const userSchemas = {
         'string.email': '请输入有效的邮箱地址'
       }),
     
-    password: dsl('password:strong!')
+    password: dsl('string!').password('strong')
       .label('密码')
       .messages({
         'string.password': '密码必须包含大小写字母、数字和特殊字符'
@@ -82,7 +82,7 @@ const userSchemas = {
   // 修改密码 schema
   changePassword: dsl({
     oldPassword: 'string!',
-    newPassword: 'password:strong!'
+    newPassword: dsl('string!').password('strong')
   })
 };
 
@@ -236,7 +236,7 @@ app.use('/api/product', require('./routes/product'));
 const PORT = process.env.PORT || 3000;
 app.listen(PORT, () => {
   console.log(`✅ Server started on port ${PORT}`);
-  console.log('✅ All schemas are pre-compiled and ready to use');
+  console.log('✅ All schemas are loaded and ready to validate');
 });
 
 module.exports = app;
@@ -255,7 +255,7 @@ router.post('/register', (req, res) => {
     {  // ❌ 每次请求都转换
       username: 'string:3-32!',
       email: 'email!',
-      password: 'password:strong!'
+      password: dsl('string!').password('strong')
     },
     req.body
   );
@@ -297,9 +297,9 @@ router.post('/register', (req, res) => {
 | **生产环境 API** | ✅ 项目启动时配置 | `const schemas = require('./schemas')` | 避免每次请求都转换 |
 | **高并发服务** | ✅ 项目启动时配置 | 同上 | 3-5% 的性能损失会被放大 |
 | **微服务** | ✅ 项目启动时配置 | 同上 | 保证响应时间稳定 |
-| **单次脚本** | ✅ 直接用 DSL 对象 | `validate({ email: 'email!' }, data)` | 只执行一次，性能影响可忽略 |
-| **原型开发** | ✅ 直接用 DSL 对象 | 同上 | 快速迭代，无需在意性能 |
-| **测试代码** | ✅ 直接用 DSL 对象 | 同上 | 简洁清晰，易于维护 |
+| **单次脚本** | ✅ 直接用 DSL 对象（当前版便捷函数支持） | `validate({ email: 'email!' }, data)` | 只执行一次，性能影响可忽略 |
+| **原型开发** | ✅ 直接用 DSL 对象（当前版便捷函数支持） | 同上 | 快速迭代，无需在意性能 |
+| **测试代码** | ✅ 直接用 DSL 对象（当前版便捷函数支持） | 同上 | 简洁清晰，易于维护 |
 
 ---
 
@@ -365,9 +365,11 @@ export const userSchemas = {
   register: dsl({
     username: dsl('string:3-32!')
       .pattern(/^[a-zA-Z0-9_]+$/)
-      .messages({ 'string.pattern': '只能包含字母、数字和下划线' }),
+      .error({ pattern: '只能包含字母、数字和下划线' }),
     email: 'email!',
-    password: 'password:strong!',
+    password: dsl('string:8-64!')
+      .pattern(/^(?=.*[A-Za-z])(?=.*\d).{8,}$/)
+      .error({ pattern: '密码至少 8 位且必须包含字母和数字' }),
     age: 'number:18-120'
   }),
   
@@ -406,3 +408,10 @@ router.post('/register', (req, res) => {
 - 集中管理所有验证规则
 - 易于维护和修改
 - 类型安全（TypeScript）
+
+---
+
+## 对应示例文件
+
+**示例入口**: [best-practices-project-structure.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/best-practices-project-structure.ts)  
+**说明**: 用一个最小的 `userSchemas` 对象模拟集中定义 / 路由复用结构，直接验证注册与登录两条路径。

package/docs/best-practices.md

@@ -1,7 +1,7 @@
 # schema-dsl 最佳实践
 
 > **用途**: 帮助你写出高质量、高性能的 Schema 代码  
-> **更新**: 2025-12-26  
+> **更新**: 2026-05-08  
 
 ---
 
@@ -33,7 +33,7 @@ const schema = dsl({
 **不推荐**（过度复杂）:
 ```javascript
 const schema = dsl({
-  username: dsl('string').minLength(3).maxLength(32).required(),
+  username: dsl('string').min(3).max(32).required(),
   // 太冗长了！
 });
 ```
@@ -67,9 +67,8 @@ const schema = dsl({
     }),
   
   email: 'email!'
-    .custom(async (value) => {
-      const exists = await checkEmailExists(value);
-      if (exists) return '邮箱已被占用';
+    .custom((value) => {
+      if (value.endsWith('@blocked.example')) return '该邮箱域名不允许注册';
     })
     .label('邮箱地址')
 });
@@ -79,7 +78,7 @@ const schema = dsl({
 
 ### 3. 使用预设验证器
 
-SchemaI-DSL 提供了常用的预设验证器，开箱即用：
+schema-dsl 提供了常用的预设验证器，开箱即用：
 
 ```javascript
 const schema = dsl({
@@ -164,6 +163,7 @@ app.post('/api/user', (req, res) => {
 **推荐**（预编译）:
 ```javascript
 // 在应用启动时编译一次
+const validator = new Validator();
 const userSchema = dsl({ username: 'string!' });
 const validateUser = validator.compile(userSchema);
 
@@ -172,15 +172,24 @@ app.post('/api/user', (req, res) => {
 });
 ```
 
-**性能提升**: 预编译可以提升 **10-100 倍** 的性能！
+**收益**: 复用已编译结果可以显著减少重复编译成本，尤其适合热点路由和高频校验路径。
 
 ---
 
 ### 2. 启用缓存
 
 ```javascript
-const validator = new Validator({ 
-  cache: true  // 启用编译缓存
+const validator = new Validator({
+  cache: true  // ✅ 简写：启用默认编译缓存配置
+});
+
+// 需要更细粒度时，使用对象配置
+const tunedValidator = new Validator({
+  cache: {
+    enabled: true,
+    maxSize: 500,
+    ttl: 60 * 60 * 1000
+  }
 });
 
 // 或者使用全局单例（默认启用缓存）
@@ -205,10 +214,15 @@ records.forEach(record => {
 
 **推荐**（批量验证）:
 ```javascript
-const result = validator.validateBatch(schema, records);
-// 一次性验证所有记录，性能更好
+const { SchemaUtils, Validator } = require('schema-dsl');
+
+const validator = new Validator();
+const result = SchemaUtils.validateBatch(schema, records, validator.getAjv());
+// 当你已经复用 Validator 底层 Ajv 实例时，这条路径适合批量校验
 ```
 
+> ℹ️ 如果你确实要直接传入自己创建的 Ajv 实例，请先确保它已经注册了与 schema-dsl 生成 schema 匹配的格式和关键字；对大多数项目来说，直接复用 `validator.getAjv()` 更稳妥。
+
 ---
 
 ### 4. 优化正则表达式
@@ -312,13 +326,17 @@ return res.status(400).json({
 ### 3. 限制 Schema 复杂度
 
 ```javascript
-const validator = new Validator({
-  maxNestingDepth: 10,  // 限制嵌套深度
-  maxSchemaSize: 10000  // 限制 Schema 大小（建议）
-});
+const MAX_SCHEMA_SIZE = 10000;
+
+if (JSON.stringify(schema).length > MAX_SCHEMA_SIZE) {
+  throw new Error('Schema 体积过大，建议拆分');
+}
 
 // 在 validate 前检查
-DslBuilder.validateNestingDepth(schema, 10);
+const depthCheck = DslBuilder.validateNestingDepth(schema, 10);
+if (!depthCheck.valid) {
+  throw new Error(depthCheck.message);
+}
 ```
 
 ---
@@ -394,7 +412,7 @@ const schema = dsl({
 ```
 
 **效果**:
-```
+```text
 ❌ 用户名不能为空
 ❌ 用户名至少需要3个字符
 ✅ 清晰明了，用户友好
@@ -402,22 +420,33 @@ const schema = dsl({
 
 ---
 
-### 3. 处理异步验证错误
+### 3. 处理外部异步校验错误
+
+> `.custom()` 当前仅支持同步函数；涉及数据库、RPC、HTTP 等异步检查时，请在基础校验通过后于业务层单独执行。
 
 ```javascript
 const schema = dsl({
-  email: 'email!'.custom(async (value) => {
-    try {
-      const exists = await checkEmailExists(value);
-      if (exists) return '邮箱已被占用';
-    } catch (error) {
-      // 记录错误但不阻止验证
-      console.error('Email check failed:', error);
-      // 可以选择跳过此验证或返回提示
-      return; // 跳过
-    }
-  })
+  email: 'email!'.label('邮箱地址')
 });
+
+async function validateUser(data) {
+  const result = validate(schema, data);
+  if (!result.valid) return result;
+
+  try {
+    const exists = await checkEmailExists(data.email);
+    if (exists) {
+      return {
+        valid: false,
+        errors: [{ field: 'email', keyword: 'business', message: '邮箱已被占用' }]
+      };
+    }
+  } catch (error) {
+    console.error('Email check failed:', error);
+  }
+
+  return result;
+}
 ```
 
 ---
@@ -427,7 +456,7 @@ const schema = dsl({
 ### 1. 集中管理 Schema
 
 **推荐的项目结构**:
-```
+```text
 src/
 ├── schemas/
 │   ├── index.js         # 导出所有 Schema
@@ -498,25 +527,27 @@ router.post('/register', (req, res) => {
 
 ### 2. Schema 复用
 
-**使用 SchemaHelper**:
+**使用 SchemaUtils**:
 ```javascript
-const { SchemaHelper } = require('schema-dsl');
+const { SchemaUtils, dsl } = require('schema-dsl');
 
 // 创建可复用字段库
-const fields = SchemaHelper.createLibrary({
-  email: 'email!',
-  phone: dsl('string!').phone('cn'),
-  password: dsl('string!').password('strong')
+const fields = SchemaUtils.createLibrary({
+  email: () => 'email!',
+  phone: () => dsl('string!').phone('cn'),
+  password: () => dsl('string!').password('strong')
 });
 
 // 在多个 Schema 中复用
 const registerSchema = dsl({
-  ...fields.pick(['email', 'password']),
+  email: fields.email(),
+  password: fields.password(),
   username: 'string:3-32!'
 });
 
 const profileSchema = dsl({
-  ...fields.pick(['email', 'phone']),
+  email: fields.email(),
+  phone: fields.phone(),
   bio: 'string:500'
 });
 ```
@@ -535,12 +566,16 @@ const config = {
   development: {
     verbose: true,
     allErrors: true,
-    cache: false // 开发时不缓存，便于调试
+    cache: false // ✅ 简写：关闭缓存，便于调试
   },
   production: {
     verbose: false,
     allErrors: false, // 只返回第一个错误
-    cache: true      // 生产环境启用缓存
+    cache: {
+      enabled: true,
+      maxSize: 1000,
+      ttl: 60 * 60 * 1000
+    }
   }
 };
 
@@ -601,7 +636,7 @@ app.get('/health', (req, res) => {
     res.json({ 
       status: 'ok',
       validator: 'operational',
-      cacheSize: validator.getCacheSize()
+      cacheStats: validator.getCacheStats()
     });
   } catch (error) {
     res.status(500).json({ 
@@ -639,23 +674,21 @@ setInterval(() => {
 
 ## 性能基准参考
 
-基于 SchemaI-DSL 的性能测试：
+缓存命中前后通常能显著降低重复编译开销，但绝对耗时会受到机器性能、Node 版本、schema 复杂度、数据规模和命中率影响，不建议把某组固定毫秒数当成通用基准。
+
+**更稳定的结论**:
 
-| 操作 | 性能指标 |
-|------|---------|
-| 简单验证（未缓存） | ~0.1ms |
-| 简单验证（已缓存） | ~0.01ms |
-| 复杂嵌套（未缓存） | ~1ms |
-| 复杂嵌套（已缓存） | ~0.1ms |
-| 批量验证（1000条） | ~100ms |
+- 复用同一个 schema 对象或 `Validator` 实例，通常比每次请求都重新编译更快
+- schema 越复杂、重复验证次数越多，缓存收益通常越明显
+- 批量验证总耗时主要取决于单条 schema 复杂度和数据规模，不应使用固定毫秒数做容量承诺
 
-**结论**: 合理使用缓存可以提升 **10-100倍** 性能。
+如需当前可复查的吞吐量对比，请以维护中的 benchmark 结果和 FAQ 中同步的性能数据为准。
 
 ---
 
 ## 总结
 
-遵循这些最佳实践，你的 SchemaI-DSL 代码将具备：
+遵循这些最佳实践，你的 schema-dsl 代码将具备：
 
 ✅ **高性能** - 通过预编译和缓存  
 ✅ **高安全性** - 避免常见安全陷阱  
@@ -666,7 +699,14 @@ setInterval(() => {
 
 ## 延伸阅读
 
-- [性能优化指南](performance-guide.md)（待创建）
-- [安全检查清单](security-checklist.md)（待创建）
+- [性能优化指南](performance-guide.md)
+- [安全检查清单](security-checklist.md)
 - [故障排查指南](troubleshooting.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [best-practices.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/best-practices.ts)  
+**说明**: 展示“简单字段用纯 DSL、复杂字段局部使用 Builder、字段库复用”的推荐组合，以及成功 / 失败两条验证路径。
+

package/docs/cache-manager.md

@@ -1,6 +1,6 @@
 # CacheManager 缓存管理器
 
-> **模块**: `lib/core/CacheManager.js`  
+> **模块**: `src/core/CacheManager.ts`（公开导出：`require('schema-dsl').CacheManager`）  
 
 > **用途**: 高性能 Schema 编译缓存，支持 LRU 淘汰和 TTL 过期
 
@@ -19,7 +19,7 @@
 
 ## 概述
 
-`CacheManager` 是 SchemaI-DSL 的内部缓存系统，用于缓存编译后的 Schema 验证函数，避免重复编译带来的性能开销。
+`CacheManager` 是 schema-dsl 的内部缓存系统，用于缓存编译后的 Schema 验证函数，避免重复编译带来的性能开销。
 
 ### 核心功能
 
@@ -34,11 +34,11 @@
 ## 快速开始
 
 ```javascript
-const CacheManager = require('schema-dsl/lib/core/CacheManager');
+const { CacheManager } = require('schema-dsl');
 
 // 创建缓存实例
 const cache = new CacheManager({
-  maxSize: 100,    // 最大缓存数量
+  maxSize: 5000,   // 默认最大缓存数量
   ttl: 3600000     // 1小时过期
 });
 
@@ -71,7 +71,7 @@ new CacheManager(options)
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `options.maxSize` | number | `100` | 最大缓存条目数 |
+| `options.maxSize` | number | `5000` | 最大缓存条目数 |
 | `options.ttl` | number | `3600000` | 缓存生存时间（毫秒） |
 | `options.enabled` | boolean | `true` | 是否启用缓存 |
 | `options.statsEnabled` | boolean | `true` | 是否启用统计 |
@@ -162,9 +162,10 @@ console.log(stats);
 //   sets: 100,       // 设置次数
 //   deletes: 5,      // 删除次数
 //   clears: 1,       // 清空次数
-//   hitRate: 0.833,  // 命中率 (83.3%)
+//   hitRate: '83.33', // 命中率百分比字符串
 //   size: 80,        // 当前缓存数量
-//   maxSize: 100     // 最大容量
+//   maxSize: 5000,   // 最大容量
+//   enabled: true    // 是否启用缓存
 // }
 ```
 
@@ -180,12 +181,12 @@ cache.resetStats();
 
 ---
 
-### `getSize()`
+### `size()`
 
 获取当前缓存条目数量。
 
 ```javascript
-console.log(`当前缓存: ${cache.getSize()} 条`);
+console.log(`当前缓存: ${cache.size()} 条`);
 ```
 
 ---
@@ -235,12 +236,12 @@ function analyzeCachePerformance(cache) {
   console.log('=== 缓存性能分析 ===');
   console.log(`命中次数: ${stats.hits}`);
   console.log(`未命中次数: ${stats.misses}`);
-  console.log(`命中率: ${(stats.hitRate * 100).toFixed(1)}%`);
+  console.log(`命中率: ${stats.hitRate}%`);
   console.log(`缓存使用率: ${(stats.size / stats.maxSize * 100).toFixed(1)}%`);
   console.log(`淘汰次数: ${stats.evictions}`);
 
   // 性能建议
-  if (stats.hitRate < 0.5) {
+  if (Number(stats.hitRate) < 50) {
     console.log('⚠️ 命中率较低，考虑增加缓存大小');
   }
   if (stats.evictions > stats.sets * 0.5) {
@@ -254,13 +255,13 @@ function analyzeCachePerformance(cache) {
 ```javascript
 function printCacheDashboard(cache) {
   const stats = cache.getStats();
-  const hitRate = (stats.hitRate * 100).toFixed(1);
+  const hitRate = `${stats.hitRate}%`;
   const usage = (stats.size / stats.maxSize * 100).toFixed(1);
 
   console.log('┌─────────────────────────────┐');
   console.log('│     缓存状态仪表板          │');
   console.log('├─────────────────────────────┤');
-  console.log(`│ 命中率:     ${hitRate.padStart(6)}%          │`);
+  console.log(`│ 命中率:   ${hitRate.padStart(8)}          │`);
   console.log(`│ 使用率:     ${usage.padStart(6)}%          │`);
   console.log(`│ 当前条目:   ${String(stats.size).padStart(6)}           │`);
   console.log(`│ 最大容量:   ${String(stats.maxSize).padStart(6)}           │`);
@@ -293,7 +294,7 @@ const cache = new CacheManager({
 ```javascript
 setInterval(() => {
   const stats = cache.getStats();
-  if (stats.hitRate < 0.8) {
+  if (Number(stats.hitRate) < 80) {
     console.warn('缓存命中率低于80%');
   }
 }, 60000);
@@ -317,7 +318,7 @@ function updateSchema(name, newSchema) {
 
 当缓存达到最大容量时，自动淘汰最久未使用的条目：
 
-```
+```text
 缓存操作顺序：
 1. set('A', ...) → [A]
 2. set('B', ...) → [A, B]
@@ -334,3 +335,10 @@ function updateSchema(name, newSchema) {
 - [性能优化指南](validation-guide.md#性能优化)
 - [API 参考](api-reference.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [cache-manager.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/cache-manager.ts)  
+**说明**: 覆盖 `set/get/has`、LRU 淘汰、统计信息读取和 `resetStats()` 的实际行为。
+

package/docs/compile.md

@@ -0,0 +1,45 @@
+# compile 方法
+
+`Validator.compile(schema, cacheKey?)` 会将 JSON Schema 编译为 AJV 验证函数，并在传入 `cacheKey` 时复用缓存。
+
+## 方法签名
+
+```javascript
+validator.compile(schema, cacheKey?)
+```
+
+## 参数
+
+- `schema` - JSON Schema 对象
+- `cacheKey` - 可选缓存键；传入后，同一个 `Validator` 实例内可复用已编译结果
+
+## 返回值
+
+返回 AJV 验证函数，可直接像普通函数一样调用；执行结果为 `true / false`，错误详情挂在 `validate.errors` 上。
+
+```javascript
+const { Validator, dsl } = require('schema-dsl');
+const validator = new Validator();
+const schema = dsl({ name: 'string!' });
+const validate = validator.compile(schema, 'user-schema');
+console.log(validate({ name: 'Rocky' }));
+```
+
+## 适用场景
+
+- 同一份 schema 需要重复校验多次时，先 `compile()` 再复用编译结果
+- 需要自己控制缓存键，避免重复编译开销
+- 想把编译和执行拆开，接入自定义流程
+
+## 注意事项
+
+- `cacheKey` 的缓存作用域是当前 `Validator` 实例，不跨实例共享
+- 如果只是对同一份 schema 做批量校验，也可以直接使用 `validator.validateBatch()`
+
+---
+
+## 对应示例文件
+
+**示例入口**: [compile.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/compile.ts)  
+**说明**: 覆盖 `compile()` 的编译结果复用、`cacheKey` 命中，以及失败场景下从验证函数读取错误详情。
+

package/docs/conditional-api.md

@@ -1,7 +1,7 @@
 # 链式条件 API - ConditionalBuilder
 
-> **版本**: v1.1.1  
-> **更新日期**: 2026-01-06  
+> **版本**: schema-dsl v2.0.0-beta.2  
+> **更新日期**: 2026-05-08  
 > **状态**: ✅ 稳定
 
 ---
@@ -22,6 +22,8 @@
 
 `ConditionalBuilder` 提供流畅的链式条件判断 API，类似 JavaScript 的 if-else 语句，用于在验证时根据实际数据动态调整验证规则。
 
+> 关键语义：当你使用 `.message()` / `.assert()` / `.check()` 这类“失败即返回”的模式时，条件函数应该写成**失败条件**，因为条件返回 `true` 才会被判定为失败。
+
 ### 核心特性
 
 - ✅ **链式调用** - 流畅的 API，类似 JavaScript if-else
@@ -218,21 +220,21 @@ const { dsl, validate } = require('schema-dsl');
 // 方式1：传统方式（需要 validate 函数）
 const schema1 = dsl({
   age: 'number!',
-  status: dsl.if((data) => data.age >= 18)
+  status: dsl.if((data) => data.age < 18)
     .message('未成年用户不能注册')
 });
 
 validate(schema1, { age: 16, status: 'active' });
-// => { valid: false, errors: [{ message: '未成年用户不能注册' }] }
+// => { valid: false, errors: [{ message: '未成年用户不能注册' }], data: { age: 16, status: 'active' } }
 
 // ✅ 方式2：快捷方式（一行代码验证）
-const result = dsl.if((data) => data.age >= 18)
+const result = dsl.if((data) => data.age < 18)
   .message('未成年用户不能注册')
   .validate({ age: 16 });
-// => { valid: false, errors: [{ message: '未成年用户不能注册' }] }
+// => { valid: false, errors: [{ message: '未成年用户不能注册' }], data: { age: 16 } }
 
 // ✅ 方式3：.check() 快速判断
-const isValid = dsl.if((data) => data.age >= 18)
+const isValid = dsl.if((data) => data.age < 18)
   .message('未成年用户不能注册')
   .check({ age: 16 });
 // => false
@@ -421,6 +423,26 @@ dsl.if(d => d.age < 18)
 
 ---
 
+### .build()
+
+将当前 `ConditionalBuilder` 输出为可直接交给 `Validator` / `validate()` 使用的 schema 对象。
+
+`.build()` 是 `.toSchema()` 的别名，适合在你想显式拿到最终 schema 时使用。
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+const conditionalSchema = dsl.if(data => data.age >= 18)
+  .then('email!')
+  .else('email')
+  .build();
+
+const result = validate(conditionalSchema, 'user@example.com');
+console.log(result.valid);
+```
+
+---
+
 ### .elseIf(condition)
 
 添加 else-if 分支。
@@ -458,11 +480,11 @@ dsl.if((data) => data.userType === 'admin')
 
 **基础示例**:
 ```javascript
-dsl.if((data) => data.age >= 18)
+dsl.if((data) => data.age < 18)
   .message('未成年用户不能注册')
 
 // 支持多语言 key
-dsl.if((data) => data.age >= 18)
+dsl.if((data) => data.age < 18)
   .message('error.underage')
 ```
 
@@ -666,7 +688,7 @@ try {
 
 **返回**: `*` - 验证通过返回数据
 
-**抛出**: `Error` - 验证失败抛出错误（name: 'ValidationError'）
+**抛出**: `ValidationError` - 验证失败时直接抛出 `ValidationError`
 
 **特性**: 同步版本的断言验证，适合快速失败场景
 
@@ -1237,7 +1259,7 @@ validate(contactSchema, 'user@example.com');  // ✅ 作为邮箱验证
 validate(contactSchema, '13800138000');       // ✅ 作为手机号验证
 ```
 
-**完整示例**: 参见 `examples/conditional-non-object.js`
+**完整示例**: 参见 `test/unit/conditional-non-object.test.ts`
 
 ---
 
@@ -1276,3 +1298,10 @@ validate(contactSchema, '13800138000');       // ✅ 作为手机号验证
 - [API 参考](./api-reference.md)
 - [最佳实践](./best-practices.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [conditional-api.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/conditional-api.ts)  
+**说明**: 同时覆盖失败谓词模式下的 `.check()` / `.assert()`，以及字段名版本 `dsl.if(field, then, else)` 和 `dsl.match()` 映射。
+