schema-dsl 1.2.5 → 2.0.1

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
+
+