schema-dsl 1.2.4 → 2.0.0

package/docs/doc-index.md

@@ -0,0 +1,324 @@
+# schema-dsl 文档索引
+
+> **更新时间**: 2026-05-06  
+> **用途**: 所有文档的快速导航  
+> **在线文档**: https://schema-dsl.github.io  
+> **文档数量**: `README.md + docs/*.md` 共 58 份
+
+---
+
+## 📑 目录
+
+### 快速导航
+- [快速开始](#doc-index-quick-start) - 入门必读
+- [核心文档](#doc-index-core-docs) - 主要功能文档
+- [功能索引](#doc-index-feature-map) - 按功能查找
+- [导出器](#doc-index-exporters) - 数据库 Schema 导出
+- [工具类](#doc-index-utilities) - 辅助工具
+- [使用指南](#doc-index-guides) - 完整教程
+- [补充文档](#doc-index-supplemental) - 其余未在专题区展开的文档
+- [故障排查](#doc-index-troubleshooting) - 问题解决
+- [示例代码](#doc-index-examples) - 完整示例
+- [常见问题](#doc-index-faq) - FAQ
+
+---
+
+<a id="doc-index-quick-start"></a>
+
+## 🚀 快速开始
+
+| 文档 | 阅读时间 | 说明 |
+|------|----------|------|
+| [README.md](https://github.com/vextjs/schema-dsl/blob/main/README.md) | 3分钟 | 项目介绍、安装和快速开始 ⭐ |
+| [quick-start.md](quick-start.md) | 5分钟 | 5分钟快速上手教程 ⭐ |
+| [design-philosophy.md](design-philosophy.md) | 15分钟 | **设计理念与性能权衡** ⭐⭐⭐ |
+| [FEATURE-INDEX.md](FEATURE-INDEX.md) | 10分钟 | 完整功能索引 ⭐ |
+| [best-practices.md](best-practices.md) | 15分钟 | 最佳实践指南 ⭐⭐⭐ |
+| [faq.md](faq.md) | 5分钟 | 常见问题解答 |
+
+---
+
+<a id="doc-index-core-docs"></a>
+
+## 📖 核心文档
+
+### DSL 语法（核心功能）
+
+| 文档 | 说明 |
+|------|------|
+| [dsl-syntax.md](dsl-syntax.md) | **DSL语法完整指南**（最重要）⭐⭐⭐ |
+| [string-extensions.md](string-extensions.md) | **String扩展文档** ⭐⭐ |
+| [plugin-system.md](plugin-system.md) | **插件系统指南** ⭐⭐ |
+| [api-reference.md](api-reference.md) | API完整参考 ⭐⭐ |
+| [validate.md](validate.md) | validate方法详解 ⭐ |
+| [**validate-async.md**](validate-async.md) | **异步验证方法详解** ⭐⭐⭐ |
+| [**schema-utils-chaining.md**](schema-utils-chaining.md) | **Schema链式复用方法** ⭐⭐⭐ |
+| [**schema-utils-best-practices.md**](schema-utils-best-practices.md) | **SchemaUtils最佳实践与常见陷阱** ⭐⭐⭐ |
+| [**schema-utils-advanced-issues.md**](schema-utils-advanced-issues.md) | **SchemaUtils深入问题分析** ⭐⭐ |
+
+---
+
+<a id="doc-index-feature-map"></a>
+
+## 🎯 功能索引
+
+### 核心API
+
+| 功能 | 文档 | 代码位置 |
+|------|------|---------|
+| dsl() 函数 | [api-reference.md](api-reference.md#dsl-函数) | `src/index.ts` / `src/adapters/DslAdapter.ts` |
+| DslBuilder 类 | [api-reference.md](api-reference.md#dslbuilder-类) | `src/core/DslBuilder.ts` |
+| String 扩展 | [string-extensions.md](string-extensions.md) | `src/core/StringExtensions.ts` |
+| Validator 类 | [validate.md](validate.md) | `src/core/Validator.ts` |
+| validate() 函数 | [api-reference.md](api-reference.md) | `src/index.ts` |
+| validateAsync() 函数 | [validate-async.md](validate-async.md) | `src/index.ts` |
+| ValidationError 类 | [validate-async.md](validate-async.md#validationerror) | `src/errors/ValidationError.ts` |
+| SchemaUtils 链式调用 | [schema-utils-chaining.md](schema-utils-chaining.md) | `src/utils/SchemaUtils.ts` |
+
+
+---
+
+<a id="doc-index-exporters"></a>
+
+## 🗄️ 导出器
+
+> 将 JSON Schema 转换为数据库 DDL 和验证规则
+
+> ⚠️ **重要提示**: 请先阅读 [**导出限制说明**](export-limitations.md)，了解哪些特性无法导出到数据库 Schema。
+
+### 导出限制说明 ⚠️
+
+| 文档 | 说明 |
+|------|------|
+| [**export-limitations.md**](export-limitations.md) | **导出限制完整说明**（必读）⭐⭐⭐ |
+
+**主要内容**:
+- ❌ 不支持导出的特性（条件验证、自定义验证器等）
+- ⚠️ 部分支持的特性（正则、范围、枚举等）
+- ✅ 完全支持的特性（基础类型、必填约束等）
+- 数据库特定限制对比（MongoDB/MySQL/PostgreSQL）
+- 最佳实践建议（分层验证、文档化约束等）
+
+### MongoDB 导出器
+
+| 文档 | 说明 |
+|------|------|
+| [mongodb-exporter.md](mongodb-exporter.md) | MongoDB 导出器完整指南 |
+
+**主要功能**:
+- `export()` - 导出 $jsonSchema 验证规则
+- `generateCreateCommand()` - 生成创建集合命令（含验证）
+- `generateCommand()` - 生成完整 runCommand 命令
+- `MongoDBExporter.export()` - 静态快速导出方法
+
+### MySQL 导出器
+
+| 文档 | 说明 |
+|------|------|
+| [mysql-exporter.md](mysql-exporter.md) | MySQL 导出器完整指南 |
+
+**主要功能**:
+- `export()` - 导出 CREATE TABLE DDL
+- `generateIndex()` - 生成 CREATE INDEX DDL
+- 支持 ENGINE、CHARSET、COLLATE 配置
+
+### PostgreSQL 导出器
+
+| 文档 | 说明 |
+|------|------|
+| [postgresql-exporter.md](postgresql-exporter.md) | PostgreSQL 导出器完整指南 |
+
+**主要功能**:
+- `export()` - 导出 CREATE TABLE DDL（含 CHECK 约束）
+- `generateIndex()` - 生成索引 DDL（支持 btree/gin/gist/hash）
+- 支持 Schema 命名空间和 COMMENT
+
+---
+
+<a id="doc-index-utilities"></a>
+
+## 🛠️ 工具类（Utilities）
+
+| 文档 | 说明 |
+|------|------|
+| [type-converter.md](type-converter.md) | TypeConverter - 类型转换工具 |
+| [schema-helper.md](schema-helper.md) | SchemaHelper - Schema 辅助工具 |
+| [cache-manager.md](cache-manager.md) | CacheManager - LRU缓存管理 |
+
+### TypeConverter 主要功能
+- `toMongoDBType()` - 转换为 MongoDB 类型
+- `toMySQLType()` - 转换为 MySQL 类型  
+- `toPostgreSQLType()` - 转换为 PostgreSQL 类型
+- `extractConstraints()` - 提取约束信息
+- `mergeSchemas()` - 合并多个 Schema
+
+### SchemaHelper 主要功能
+- `isValidSchema()` - 验证 Schema 合法性
+- `cloneSchema()` - 深度克隆 Schema
+- `flattenSchema()` - 扁平化嵌套 Schema
+- `getFieldPaths()` - 获取所有字段路径
+- `summarizeSchema()` - 生成 Schema 摘要
+
+### CacheManager 主要功能
+- LRU 缓存策略（最近最少使用淘汰）
+- TTL 过期支持
+- 缓存统计（命中率、大小等）
+- 线程安全设计
+
+---
+
+<a id="doc-index-guides"></a>
+
+## 📖 使用指南（Guides）
+
+| 文档 | 说明 |
+|------|------|
+| [validation-guide.md](validation-guide.md) | 数据验证完整指南 |
+| [export-guide.md](export-guide.md) | 数据库导出完整指南 |
+| [error-handling.md](error-handling.md) | 错误处理最佳实践 |
+
+### 验证指南内容
+- 基础验证流程
+- 字段类型验证（字符串/数字/布尔/数组/对象）
+- 常用业务验证模式
+- 批量验证与性能优化
+- 错误处理最佳实践
+
+### 导出指南内容
+- MongoDB/MySQL/PostgreSQL 导出对比
+- 配置与自定义选项
+- 自动化迁移脚本
+- 版本管理与最佳实践
+- **⚠️ [导出限制说明](export-limitations.md) - 哪些特性无法导出** ⭐⭐⭐
+
+
+- 数据库导出概述
+- MongoDB/MySQL/PostgreSQL 导出教程
+- 多数据库同步方案
+- 类型映射参考表
+- 最佳实践与常见问题
+
+---
+
+<a id="doc-index-supplemental"></a>
+
+## 🧩 补充文档
+
+> 上方专题区主要按学习路径和主题组织；以下补充索引列出当前尚未在专题区单独展开的其余文档，确保导航覆盖 `docs/*.md` 全量文档。
+
+| 文档 | 标题 / 说明 |
+|------|-------------|
+| [add-custom-locale.md](add-custom-locale.md) | 添加自定义语言包指南 |
+| [add-keyword.md](add-keyword.md) | addKeyword 方法 |
+| [api.md](api.md) | API 参考入口 |
+| [best-practices-project-structure.md](best-practices-project-structure.md) | Schema-DSL 项目最佳实践示例 |
+| [compile.md](compile.md) | compile 方法 |
+| [conditional-api.md](conditional-api.md) | 链式条件 API - ConditionalBuilder |
+| [custom-extensions-guide.md](custom-extensions-guide.md) | 自定义扩展指南 |
+| [dynamic-locale.md](dynamic-locale.md) | 动态多语言配置指南 |
+| [enum.md](enum.md) | 枚举功能文档 |
+| [frontend-i18n-guide.md](frontend-i18n-guide.md) | 前端动态切换语言 - 最佳实践指南 |
+| [i18n-user-guide.md](i18n-user-guide.md) | 多语言支持用户指南 |
+| [i18n.md](i18n.md) | 多语言配置指南 |
+| [index.md](index.md) | 站点首页文案（文件内未单独声明 H1） |
+| [json-schema-basics.md](json-schema-basics.md) | JSON Schema 基础 |
+| [label-vs-description.md](label-vs-description.md) | label vs description 使用指南 |
+| [markdown-exporter.md](markdown-exporter.md) | Markdown 导出器 |
+| [multi-language.md](multi-language.md) | 多语言支持 |
+| [multi-type-support.md](multi-type-support.md) | 多类型支持设计说明 |
+| [number-operators.md](number-operators.md) | 数字比较运算符 (v1.1.2+) |
+| [optional-marker-guide.md](optional-marker-guide.md) | schema-dsl 可选标记 ? 支持 |
+| [performance-guide.md](performance-guide.md) | 性能优化指南 |
+| [plugin-type-registration.md](plugin-type-registration.md) | 自定义类型注册 |
+| [runtime-locale-support.md](runtime-locale-support.md) | 运行时多语言支持 - schema-dsl |
+| [schema-utils.md](schema-utils.md) | Schema 工具函数文档 |
+| [security-checklist.md](security-checklist.md) | 安全检查清单 |
+| [troubleshooting.md](troubleshooting.md) | 常见问题排查指南 |
+| [type-reference.md](type-reference.md) | schema-dsl 类型参考 |
+| [typescript-guide.md](typescript-guide.md) | TypeScript 使用指南 |
+| [union-type-guide.md](union-type-guide.md) | 一个字段支持多种类型 |
+| [union-types.md](union-types.md) | 跨类型联合验证 - types: 语法 |
+| [validate-batch.md](validate-batch.md) | validateBatch 方法 |
+| [validate-dsl-object-support.md](validate-dsl-object-support.md) | validate() 函数支持 DSL 对象说明 |
+| [validator.md](validator.md) | Validator 类概述 |
+
+---
+
+<a id="doc-index-examples"></a>
+
+## 📝 示例代码（Examples）
+
+| 文件 | 说明 |
+|------|------|
+| [quick-start.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/quick-start.ts) | 快速开始示例 |
+| [dsl-syntax.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/dsl-syntax.ts) | DSL 风格完整示例 |
+| [string-extensions.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/string-extensions.ts) | String 扩展示例 |
+| [troubleshooting.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/troubleshooting.ts) | 排障与错误定位示例 |
+
+---
+
+<a id="doc-index-faq"></a>
+
+## ❓ 常见问题（FAQ）
+
+| 文档 | 说明 |
+|------|------|
+| [faq.md](faq.md) | 常见问题与解答 |
+
+**热门问题**:
+- DSL 语法与 Joi 语法的区别？
+- 如何自定义验证规则？
+- 如何优化验证性能？
+- 不同数据库的类型映射？
+- 如何处理验证错误？
+
+---
+
+<a id="doc-index-troubleshooting"></a>
+
+## 🔧 开发指南
+
+| 文档 | 说明 |
+|------|------|
+| [CONTRIBUTING.md](https://github.com/vextjs/schema-dsl/blob/main/CONTRIBUTING.md) | 贡献指南 |
+
+---
+
+## 📊 版本信息
+
+| 文档 | 说明 |
+|------|------|
+| [STATUS.md](https://github.com/vextjs/schema-dsl/blob/main/STATUS.md) | 项目状态（当前测试与发布状态）|
+| [CHANGELOG.md](https://github.com/vextjs/schema-dsl/blob/main/CHANGELOG.md) | 更新日志 |
+
+---
+
+## 📁 文档统计
+
+| 指标 | 当前值 |
+|------|--------|
+| `docs/*.md` 文档数 | **58** |
+| `README.md + docs/*.md` 文档数 | **59** |
+| 文档总行数 | **持续演进（以仓库实时内容为准）** |
+| 测试文件数 | **67** |
+| 最近一次全量验证 | **67 files / 1052 tests passed** |
+
+---
+
+**图例说明**:
+- ⭐ 重点推荐文档
+- ⭐⭐ 核心文档
+- ⭐⭐⭐ 必读文档
+
+---
+
+## 对应示例文件
+
+**示例入口**: [doc-index.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/doc-index.ts)  
+**说明**: 用一个最小入口脚本串起快速开始、编译校验和文档导出，帮助读者从索引页直接落到可运行示例。
+
+---
+
+**最后更新**: 2026-05-08
+
+

package/docs/dsl-syntax.md

@@ -1,6 +1,6 @@
 # DSL 语法完整指南
 
-> **更新时间**: 2025-12-25  
+> **更新时间**: 2026-05-22  
 
 ---
 
@@ -57,14 +57,35 @@ const schema = dsl({
 |------|-----|------|
 | 邮箱 | `email` | 邮箱地址 |
 | URL | `url` | 网址 |
+| URI | `uri` | URI 地址 |
 | UUID | `uuid` | UUID格式 |
 | 日期 | `date` | YYYY-MM-DD |
 | 日期时间 | `datetime` | ISO 8601 |
 | 时间 | `time` | HH:mm:ss |
+| 主机名 | `hostname` | 主机名 |
+| IP（IPv4 / IPv6） | `ip` | 自动接受 IPv4 或 IPv6 |
 | IPv4 | `ipv4` | IPv4地址 |
 | IPv6 | `ipv6` | IPv6地址 |
 | 二进制 | `binary` | Base64编码 |
 
+### 特殊类型
+
+| 类型 | DSL | 说明 |
+|------|-----|------|
+| ObjectId | `objectId` | MongoDB ObjectId |
+| 十六进制颜色 | `hexColor` | CSS 十六进制颜色 |
+| MAC 地址 | `macAddress` | MAC 地址 |
+| Cron 表达式 | `cron` | 标准 Cron 表达式 |
+| URL Slug | `slug` | 小写字母/数字/中横线组成的 URL 友好标识 |
+| 中文姓名 | `chineseName` | 2 到 10 个中文字符 |
+| 纯中文文本 | `chinese` | 仅允许中文字符 |
+| 邮箱域名校验 | `emailDomain` | 邮箱格式基础上的域名约束类型 |
+| 字母数字 | `alphanum` | 仅字母与数字 |
+| 全小写字符串 | `lower` | 自动约束为小写字符串 |
+| 全大写字符串 | `upper` | 自动约束为大写字符串 |
+| JSON 字符串 | `json` | 内容需为合法 JSON 字符串 |
+| 端口号 | `port` | 整数端口号 |
+
 
 ---
 
@@ -100,9 +121,9 @@ const schema = dsl({
 ```
 
 **说明**：
-- `!` - 必填标记，字段不能为空
-- `?` - 可选标记，字段可以为空（默认行为）
-- 不加标记 - 默认可选
+- `!` - 必填标记，字段必须存在
+- `?` - 可选标记，字段可省略（显式表达）
+- 不加标记 - 默认可选（字段可省略）
 
 **推荐**：
 - 使用 `!` 明确标记必填字段
@@ -137,10 +158,10 @@ const schema2 = dsl({
 ### 1. 字符串长度
 
 ```javascript
-'string:10'       // 最大长度10
-'string:-10'      // 最大长度10（明确语法）
-'string:3-32'     // 长度3-32
-'string:10-'      // 最小长度10
+'string:10'       // 精确长度10（exactLength：minLength=10, maxLength=10）
+'string:-10'      // 最大长度10
+'string:3-32'     // 长度范围3-32
+'string:10-'      // 最小长度10（无最大限制）
 ```
 
 **示例**:
@@ -181,7 +202,26 @@ const schema = dsl({
 });
 ```
 
-### 4. 特殊约束
+### 4. `types:` 联合类型
+
+当一个字段需要接受多种不同类型时，可以使用 `types:` 前缀生成联合类型：
+
+```javascript
+const schema = dsl({
+  contact: 'types:email|phone',
+  price: 'types:number:0-|string:1-20',
+  payload: 'types:object|array<object>'
+});
+```
+
+这个语法会被编译为 `oneOf` 结构，适合表达“满足其中任意一种类型即可”的场景。
+
+**适用场景**:
+- 联系方式允许邮箱或手机号
+- 价格字段允许数值或说明字符串
+- 兼容历史接口中同字段的多种输入格式
+
+### 5. 特殊约束
 
 支持特定格式的约束：
 
@@ -380,6 +420,8 @@ const schema = dsl({
 
 ### 1. 链式调用
 
+> ⚠️ `.custom()` 当前仅支持同步自定义逻辑；异步业务校验请在验证通过后单独执行。
+
 ```javascript
 const schema = dsl({
   username: 'string:3-32!'
@@ -392,9 +434,8 @@ const schema = dsl({
   email: 'email!'
     .label('邮箱地址')
     .description('用于登录和接收通知')
-    .custom(async (value) => {
-      const exists = await checkEmailExists(value);
-      if (exists) return '邮箱已被占用';
+    .custom((value) => {
+      if (value.endsWith('@blocked.example')) return '该邮箱域名不允许注册';
     })
 });
 ```
@@ -479,16 +520,18 @@ const schema = dsl({
 'string!@custom'  // ❌ 不支持
 ```
 
-**解决方案**: 使用 `.custom()` 方法
+**解决方案**: 使用 `.custom()` 方法承载**同步**自定义逻辑
 ```javascript
-'string!'.custom(async (value) => {
-  // 自定义逻辑
-  if (await checkExists(value)) {
-    return '已存在';
+'string!'.custom((value) => {
+  // 自定义同步逻辑
+  if (value === 'reserved') {
+    return '该值不可用';
   }
 })
 ```
 
+异步校验（如数据库查重）请在 `validate()` / `validateAsync()` 通过后于业务层单独执行。
+
 ---
 
 ### 5. 对象数组详细定义
@@ -659,6 +702,13 @@ dsl.match('vipLevel', { gold: 'number:0-50', silver: 'number:0-20' })
 
 ---
 
-**最后更新**: 2025-12-29  
-**作者**: SchemaI-DSL Team
+## 对应示例文件
+
+**示例入口**: [dsl-syntax.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/dsl-syntax.ts)  
+**说明**: 覆盖 Batch 1 中 DSL 语法的基础类型、约束、枚举、数组和嵌套对象写法，可直接运行参考。
+
+---
+
+**最后更新**: 2026-05-08  
+**作者**: schema-dsl Team
 

package/docs/dynamic-locale.md

@@ -18,7 +18,7 @@
 
 ## 基本原理
 
-SchemaI-DSL 的 `Validator` 支持在验证时动态指定语言，无需全局切换。
+schema-dsl 的 `Validator` 支持在验证时动态指定语言，无需全局切换。
 
 ### 核心方法
 
@@ -45,7 +45,7 @@ const path = require('path');
 // ========== 应用启动时配置（只执行一次）==========
 
 // 方式一：传入目录路径（推荐）⭐
-// 自动扫描目录下的所有 .js 和 .json 文件
+// Node >=18：自动扫描目录下的 .js（CommonJS）、.cjs、.json、.jsonc、.json5 文件
 dsl.config({
   i18n: path.join(__dirname, 'locales')
 });
@@ -128,7 +128,7 @@ const userSchema = dsl({
 // ========== Express 路由 ==========
 app.post('/api/user/register', (req, res) => {
   // 从请求头获取语言偏好
-  const locale = req.headers['accept-language'] || 'en-US';
+  const locale = parseAcceptLanguage(req.headers['accept-language']);
   
   // 验证数据（直接切换语言，无需重新加载）
   const result = validate(userSchema, req.body, { locale });
@@ -210,7 +210,7 @@ function validateWithLocale(validator, schema, data, locale) {
 
 // 使用
 app.post('/api/user/register', (req, res) => {
-  const locale = req.headers['accept-language'] || 'en-US';
+  const locale = parseAcceptLanguage(req.headers['accept-language']);
   
   const result = validateWithLocale(validator, schema, req.body, locale);
   
@@ -234,7 +234,7 @@ const validator = new Validator();
 
 const schemaIoMiddleware = (req, res, next) => {
   // 1. 自动获取语言
-  const lang = req.headers['accept-language'] || 'en-US';
+  const lang = req.headers['accept-language']?.split(',')[0]?.trim() || 'en-US';
   // 简单匹配逻辑 (实际可使用 accept-language-parser)
   const locale = lang.includes('zh') ? 'zh-CN' : 
                  lang.includes('ja') ? 'ja-JP' : 
@@ -264,12 +264,14 @@ app.post('/users', (req, res) => {
 });
 ```
 
-完整示例请参考 `examples/middleware-usage.js`。
+完整示例请参考 [dynamic-locale.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/dynamic-locale.ts)。
 
 ### 3.2 Koa 中间件
 
 ```javascript
-const { Locale } = require('schema-dsl');
+const { Locale, Validator } = require('schema-dsl');
+
+const validator = new Validator();
 
 /**
  * Koa 语言中间件
@@ -282,10 +284,8 @@ function localeMiddleware() {
     // 保存到上下文
     ctx.locale = locale;
     
-    // 创建验证辅助函数
+    // 复用共享 Validator，避免每个请求都重新建立实例和缓存
     ctx.validate = function(schema, data) {
-      const { Validator } = require('schema-dsl');
-      const validator = new Validator();
       return validator.validate(schema, data, { locale: ctx.locale });
     };
     
@@ -368,11 +368,12 @@ function parseAcceptLanguage(acceptLanguage) {
 
 // ========== 3. 中间件 ==========
 
+const validator = new Validator();
+
 function localeMiddleware(req, res, next) {
   req.locale = parseAcceptLanguage(req.headers['accept-language']);
   
   req.validate = function(schema, data) {
-    const validator = new Validator();
     return validator.validate(schema, data, { locale: req.locale });
   };
   
@@ -525,7 +526,7 @@ if (!result.valid) {
 |------|------|------|--------|
 | **方案1: 验证时指定** | ✅ 无竞态问题<br>✅ 支持并发<br>✅ 代码简洁 | - | ⭐⭐⭐⭐⭐ |
 | 方案2: 临时切换 | ✅ 实现简单 | ⚠️ 并发竞态问题 | ⭐⭐⭐ |
-| 方案3: 中间件 | ✅ 自动化<br>✅ 统一管理 | - | ⭐⭐⭐⭐⭐ |
+| 方案3: 中间件 | ✅ 自动化<br>✅ 统一管理<br>✅ 可复用共享 Validator 缓存 | - | ⭐⭐⭐⭐⭐ |
 
 **推荐**: 方案1 + 方案3（中间件封装）
 
@@ -537,6 +538,8 @@ if (!result.valid) {
 
 **A**: 回退到默认语言
 
+不要直接把原始 `Accept-Language` 头透传给 `locale`；浏览器常见值会带 `q=` 权重，应该先解析再回退。
+
 ```javascript
 function parseAcceptLanguage(acceptLanguage) {
   // ...解析逻辑
@@ -592,7 +595,14 @@ const schema = dsl({
 
 ---
 
-**最后更新**: 2025-12-25  
-**作者**: SchemaI-DSL Team
+## 对应示例文件
+
+**示例入口**: [dynamic-locale.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/dynamic-locale.ts)  
+**说明**: 覆盖 `Accept-Language` 解析、运行时 locale 选择，以及同一 schema 在不同请求语言下的验证入口。
+
+---
+
+**最后更新**: 2026-05-08  
+**作者**: schema-dsl Team
 
 

package/docs/enum.md

@@ -450,10 +450,17 @@ const schema = dsl({
 
 ## 📖 相关文档
 
-- [基础用法](./README.md)
-- [验证规则](./docs/validation.md)
-- [API 参考](./docs/api.md)
-- [示例代码](../examples/enum.examples.js)
+- [基础用法](https://github.com/vextjs/schema-dsl/blob/main/README.md)
+- [验证规则](./validation-guide.md)
+- [API 参考](./api-reference.md)
+- [示例代码](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/enum.ts)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [enum.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/enum.ts)  
+**说明**: 覆盖字符串、数字、布尔值和数组元素枚举的成功/失败路径，并展示自定义枚举错误消息。
 
 ---
 
@@ -470,6 +477,6 @@ const schema = dsl({
 
 ---
 
-**文档生成时间**: 2025-12-31  
+**文档生成时间**: 2026-05-08  
 **版本**: v1.1.0