schema-dsl 1.2.4 → 2.0.0

package/docs/error-handling.md

@@ -280,13 +280,13 @@ dsl.config({
 #### 方式3：从目录加载（大型项目）
 
 **目录结构**:
-```
+```text
 project/
-├── lib/
-│   └── locales/
-│       ├── zh-CN.js
-│       ├── en-US.js
-│       └── ja-JP.js
+├── i18n/
+│   └── errors/
+│       ├── zh-CN.cjs
+│       ├── en-US.jsonc
+│       └── ja-JP.json5
 └── app.js
 ```
 
@@ -295,11 +295,11 @@ project/
 const path = require('path');
 
 dsl.config({
-  i18n: path.join(__dirname, 'lib/locales')
+  i18n: path.join(__dirname, 'i18n/errors')
 });
 ```
 
-**语言包文件** (`lib/locales/zh-CN.js`):
+**语言包文件**（例如 `i18n/errors/zh-CN.cjs`）:
 ```javascript
 module.exports = {
   'account.notFound': {
@@ -329,7 +329,7 @@ module.exports = {
 ```javascript
 const { Locale } = require('schema-dsl');
 
-// 设置默认语言为中文
+// 按应用需要切换默认语言
 Locale.setLocale('zh-CN');
 
 // 获取当前语言
@@ -374,7 +374,7 @@ const app = express();
 
 // 中间件：提取客户端语言
 app.use((req, res, next) => {
-  req.locale = req.headers['accept-language']?.split(',')[0] || 'zh-CN';
+  req.locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
   next();
 });
 
@@ -478,7 +478,7 @@ dsl.error.throw('account.notFound');
 app.get('/api/account/:id', async (req, res) => {
   try {
     const account = await findAccount(req.params.id);
-    const locale = req.headers['accept-language'] || 'zh-CN';
+    const locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
     
     // 🎯 简化语法：只需2个参数
     dsl.error.assert(account, 'account.notFound', locale);
@@ -528,7 +528,7 @@ Locale.addLocale('en-US', {
 
 // ========== 中间件：提取语言 ==========
 app.use((req, res, next) => {
-  req.locale = req.headers['accept-language']?.split(',')[0] || 'zh-CN';
+  req.locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
   next();
 });
 
@@ -604,7 +604,7 @@ Locale.addLocale('zh-CN', {
 
 // ========== 中间件：提取语言 ==========
 app.use(async (ctx, next) => {
-  ctx.locale = ctx.headers['accept-language']?.split(',')[0] || 'zh-CN';
+  ctx.locale = ctx.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
   await next();
 });
 
@@ -657,7 +657,7 @@ Locale.addLocale('zh-CN', {
 const server = http.createServer((req, res) => {
   try {
     // 提取语言
-    const locale = req.headers['accept-language']?.split(',')[0] || 'zh-CN';
+    const locale = req.headers['accept-language']?.split(',')[0]?.trim() || 'zh-CN';
     
     // 业务逻辑
     const order = getOrder(req.url);
@@ -962,7 +962,7 @@ async function apiCall() {
 ```javascript
 const { Locale } = require('schema-dsl');
 
-// 启动时设置默认语言
+// 启动时按应用需要设置默认语言
 Locale.setLocale('zh-CN');
 
 // 获取当前默认语言
@@ -1041,7 +1041,7 @@ app.use((error, req, res, next) => {
 
 ### 基础结构
 
-SchemaI-DSL 验证返回的错误对象结构：
+schema-dsl 验证返回的错误对象结构：
 
 ```javascript
 const { dsl, validate } = require('schema-dsl');
@@ -1054,14 +1054,14 @@ const result = validate(schema, { username: 'ab' });
 
 // 返回结构
 {
-  valid: false,           // 验证是否通过
-  errors: [              // 错误数组（基于 ajv）
+  valid: false,
+  errors: [
     {
-      instancePath: '/username',
-      schemaPath: '#/properties/username/minLength',
+      path: 'username',
+      field: 'username',
       keyword: 'minLength',
       params: { limit: 3 },
-      message: 'must NOT have fewer than 3 characters'
+      message: '用户名长度不能少于3个字符'
     }
   ]
 }
@@ -1089,8 +1089,8 @@ const result = validate(schema, {
 });
 
 // 错误路径
-console.log(result.errors[0].instancePath); // '/user/profile/email'
-console.log(result.errors[0].message);      // 'must match format "email"'
+console.log(result.errors[0].path);    // 'user/profile/email'
+console.log(result.errors[0].message); // '邮箱必须是有效的邮箱地址'
 ```
 
 ### 数组项错误
@@ -1107,7 +1107,7 @@ const result = validate(schema, {
 });
 
 // 错误路径
-console.log(result.errors[0].instancePath); // '/items/0'
+console.log(result.errors[0].path); // 'items/0'
 ```
 
 ---
@@ -1183,7 +1183,7 @@ Locale.setMessages({
 
 ### 内置错误码（简化版）
 
-SchemaI-DSL 对 ajv 的错误关键字进行了简化映射，使其更易用：
+schema-dsl 对 Ajv 的错误关键字进行了统一格式化，使其更易用：
 
 #### 字符串错误码
 
@@ -1278,8 +1278,8 @@ const result = validate(schema, {
 });
 
 // 错误示例
-// result.errors[0].instancePath: '/user/address/city'
-// result.errors[1].instancePath: '/user/address/street'
+// result.errors[0].path: 'user/address/city'
+// result.errors[1].path: 'user/address/street'
 ```
 
 ### 数组验证
@@ -1297,7 +1297,7 @@ const result = validate(schema, {
 });
 
 // 错误路径
-console.log(result.errors[0].instancePath); // '/items/0'
+console.log(result.errors[0].path); // 'items/0'
 ```
 
 ---
@@ -1355,7 +1355,7 @@ function validateBody(schema) {
         code: 'VALIDATION_ERROR',
         message: '请检查输入信息',
         errors: result.errors.map(err => ({
-          field: err.instancePath.replace(/^\//, '').replace(/\//g, '.'),
+          field: err.path.replace(/\//g, '.'),
           message: err.message,
           keyword: err.keyword,
           params: err.params
@@ -1402,7 +1402,7 @@ function validateBody(schema) {
         code: 'VALIDATION_ERROR',
         message: '数据验证失败',
         errors: result.errors.map(err => ({
-          field: err.instancePath.replace(/^\//, '').replace(/\//g, '.'),
+          field: err.path.replace(/\//g, '.'),
           message: err.message,
           keyword: err.keyword
         }))
@@ -1591,7 +1591,7 @@ function logValidationError(req, result) {
     url: req.url,
     method: req.method,
     errors: result.errors.map(err => ({
-      path: err.path.join('.'),
+      path: err.path.replace(/\//g, '.'),
       type: err.type,
       message: err.message
     })),
@@ -1652,8 +1652,8 @@ const { dsl } = require('schema-dsl');
 // ✅ 推荐：返回错误消息字符串
 const schema = dsl({
   username: 'string:3-32!'
-    .custom(async (value) => {
-      if (await userExists(value)) {
+    .custom((value) => {
+      if (value === 'admin') {
         return '用户名已被占用';
       }
       // 验证通过时无需返回
@@ -1685,9 +1685,9 @@ logger.warn('验证失败', {
 
 ```javascript
 // 统一的错误格式化函数
-function formatValidationErrors(ajvErrors) {
-  return ajvErrors.map(err => ({
-    field: err.instancePath.replace(/^\//, '').replace(/\//g, '.'),
+function formatValidationErrors(errors) {
+  return errors.map(err => ({
+    field: err.path.replace(/\//g, '.'),
     message: err.message,
     keyword: err.keyword,
     params: err.params
@@ -1716,7 +1716,7 @@ if (!result.valid) {
 
 **语言包配置**:
 ```javascript
-// lib/locales/zh-CN.js (或自定义语言包)
+// i18n/errors/zh-CN.cjs（或任意 .json/.jsonc/.json5 自定义语言包文件）
 module.exports = {
   // 字符串格式（向后兼容）
   'user.notFound': '用户不存在',
@@ -1770,13 +1770,13 @@ try {
 不同语言使用相同的数字 `code`，便于前端统一处理：
 
 ```javascript
-// zh-CN.js
+// zh-CN.cjs
 'account.notFound': {
   code: 40001,  // ← 数字 code 一致
   message: '账户不存在'
 }
 
-// en-US.js
+// en-US.cjs
 'account.notFound': {
   code: 40001,  // ← 数字 code 一致
   message: 'Account not found'
@@ -1794,6 +1794,8 @@ switch (error.code) {
     showPaymentDialog();
     break;
 }
+```
+
 #### 3. 增强的 error.is() 方法
 
 同时支持 `originalKey` 和数字 `code` 判断：
@@ -1944,9 +1946,9 @@ function handleError(error) {
 
 ### 更多信息
 
-- [v1.1.5 完整变更日志](../changelogs/v1.1.5.md)
-- [升级指南](../changelogs/v1.1.5.md#升级指南)
-- [最佳实践](../changelogs/v1.1.5.md#最佳实践)
+- [v1.1.5 完整变更日志](https://github.com/vextjs/schema-dsl/blob/main/changelogs/v1.1.5.md)
+- [升级指南](https://github.com/vextjs/schema-dsl/blob/main/changelogs/v1.1.5.md#升级指南)
+- [最佳实践](https://github.com/vextjs/schema-dsl/blob/main/changelogs/v1.1.5.md#最佳实践)
 
 ---
 
@@ -1956,11 +1958,18 @@ function handleError(error) {
 - [DSL 语法指南](./dsl-syntax.md)
 - [String 扩展文档](./string-extensions.md)
 - [多语言配置](./dynamic-locale.md)
-- [v1.1.5 变更日志](../changelogs/v1.1.5.md)
+- [v1.1.5 变更日志](https://github.com/vextjs/schema-dsl/blob/main/changelogs/v1.1.5.md)
+
+---
+
+## 对应示例文件
+
+**示例入口**: [error-handling.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/error-handling.ts)  
+**说明**: 覆盖 `validate()` 产生的字段错误、`I18nError` 业务错误对象、`toJSON()` 输出与错误码判断。
 
 ---
 
-**最后更新**: 2026-01-17  
+**最后更新**: 2026-05-08  
 **版本**: v1.1.5
 
 

package/docs/export-guide.md

@@ -1,9 +1,9 @@
-# 数据库导出完整指南
+# 导出完整指南
 
-> **用途**: Schema 到数据库 DDL 的完整导出指南  
+> **用途**: Schema 到多种输出格式的完整导出指南  
 > **阅读时间**: 10分钟
 
-> ⚠️ **重要提示**: 并非所有 SchemaI-DSL 特性都能导出到数据库。请先阅读 [导出限制说明](export-limitations.md) 了解哪些特性不支持导出。
+> ⚠️ **重要提示**: 并非所有 schema-dsl 特性都能导出到数据库。请先阅读 [导出限制说明](export-limitations.md) 了解哪些特性不支持导出。
 
 ---
 
@@ -14,6 +14,7 @@
 - [MongoDB 导出](#mongodb-导出)
 - [MySQL 导出](#mysql-导出)
 - [PostgreSQL 导出](#postgresql-导出)
+- [Markdown 导出](#markdown-导出)
 - [导出对比](#导出对比)
 - [最佳实践](#最佳实践)
 
@@ -21,15 +22,18 @@
 
 ## 概述
 
-SchemaI-DSL 支持将 JSON Schema 导出为多种数据库的 DDL 语句，实现"一次定义，多处使用"。
+schema-dsl 支持将 JSON Schema 导出为多种数据库结构或文档格式，实现“一次定义，多处使用”。
 
-### 支持的数据库
+### 支持的导出格式
 
-| 数据库 | 导出器 | 输出格式 |
-|--------|--------|----------|
+| 类型 | 导出器 | 输出格式 |
+|------|--------|----------|
 | MongoDB | `MongoDBExporter` | `$jsonSchema` 验证文档 |
 | MySQL | `MySQLExporter` | `CREATE TABLE` DDL |
 | PostgreSQL | `PostgreSQLExporter` | `CREATE TABLE` DDL + COMMENT |
+| Markdown | `MarkdownExporter` | 面向人类阅读的 Markdown 文档 |
+
+其中 `MarkdownExporter` 更适合生成接口字段说明、表单文档或内部规范文档，完整用法见 [Markdown 导出器](./markdown-exporter.md)。
 
 ---
 
@@ -51,14 +55,42 @@ const userSchema = dsl({
   createdAt: 'datetime!'
 });
 
-// 导出到不同数据库
+// 导出到不同目标
 const mongoSchema = new exporters.MongoDBExporter().export(userSchema);
 const mysqlDdl = new exporters.MySQLExporter().export('users', userSchema);
 const pgDdl = new exporters.PostgreSQLExporter().export('users', userSchema);
+const markdownDoc = exporters.MarkdownExporter.export(userSchema, {
+  title: '用户 Schema 文档'
+});
 ```
 
 ---
 
+## Markdown 导出
+
+如果你的目标不是数据库，而是给研发、测试、产品或接口使用方生成一份可直接阅读的字段说明文档，可以使用 `MarkdownExporter`：
+
+```javascript
+const { dsl, exporters } = require('schema-dsl');
+
+const schema = dsl({
+  username: 'string:3-32!'.description('登录账号'),
+  email: 'email!'.description('联系邮箱'),
+  age: 'number:18-120'.description('年龄')
+});
+
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: '用户注册字段说明',
+  locale: 'zh-CN'
+});
+
+console.log(markdown);
+```
+
+更完整的选项、示例和多语言输出说明见 [Markdown 导出器](./markdown-exporter.md)。
+
+---
+
 ## MongoDB 导出
 
 ### 基本用法
@@ -460,3 +492,10 @@ console.log('导出完成！');
 - [TypeConverter](type-converter.md)
 - [DSL 语法](dsl-syntax.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [export-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/export-guide.ts)  
+**说明**: 覆盖同一组 schema 同时导出到 MongoDB、MySQL 和 PostgreSQL 的最小工作流，便于对照多导出器结果。
+

package/docs/export-limitations.md

@@ -49,7 +49,7 @@ const schema = dsl({
 
 **替代方案**:
 - 导出为最宽松的类型（`VARCHAR(255)`）
-- 验证逻辑保留在应用层（使用 SchemaI-DSL 验证器）
+- 验证逻辑保留在应用层（使用 schema-dsl 验证器）
 
 ---
 
@@ -74,8 +74,8 @@ const schema = dsl({
 | 关键字 | 说明 | 导出行为 |
 |--------|------|----------|
 | `allOf` | 所有 Schema 都满足 | ❌ 忽略 |
-| `anyOf` | 满足任一 Schema | ❌ 忽略 |
-| `oneOf` | 仅满足一个 Schema | ❌ 忽略 |
+| `anyOf` | 满足任一 Schema | ⚠️ 仅当所有分支映射到同一 SQL 类型时可导出；否则抛错 |
+| `oneOf` | 仅满足一个 Schema | ⚠️ 仅当所有分支映射到同一 SQL 类型时可导出；否则抛错 |
 | `not` | 不满足某 Schema | ❌ 忽略 |
 | `if/then/else` | 条件 Schema | ❌ 忽略 |
 | `dependencies` | 字段依赖关系 | ❌ 忽略 |
@@ -83,16 +83,25 @@ const schema = dsl({
 **示例**:
 
 ```javascript
-// ❌ 这些结构无法导出
+// ⚠️ 这些结构无法直接稳定导出到单一 SQL 列类型
 const schema = {
   type: 'object',
-  allOf: [
-    { properties: { name: { type: 'string' } } },
-    { properties: { age: { type: 'number' } } }
-  ]
+  properties: {
+    value: {
+      anyOf: [
+        { type: 'string' },
+        { type: 'number' }
+      ]
+    }
+  }
 };
 ```
 
+**当前行为**:
+
+- `ipv4 | ipv6` 这类所有分支最终都映射为同一 SQL 列类型的联合，仍可导出
+- `string | number` 这类会落到不同 SQL 列类型的联合，MySQL / PostgreSQL 导出器会**显式抛错**，而不是静默取第一项
+
 ---
 
 ### 3. 自定义验证器 ❌
@@ -329,9 +338,9 @@ const schema = dsl('string!')
 
 ### 1. 分层验证策略 🎯
 
-```
+```text
 ┌─────────────────────────────────────────┐
-│  应用层（SchemaI-DSL 完整验证）             │
+│  应用层（schema-dsl 完整验证）               │
 │  - 条件逻辑（match/if）                 │
 │  - 自定义验证器                         │
 │  - 复杂约束（正则、范围等）              │
@@ -449,7 +458,7 @@ module.exports = {
 ```markdown
 ## 数据验证说明
 
-### 应用层验证（SchemaI-DSL）
+### 应用层验证（schema-dsl）
 - ✅ `contact` 字段根据 `contactType` 动态验证
 - ✅ 用户名正则验证（`^[a-zA-Z0-9_]+$`）
 - ✅ 自定义业务规则验证
@@ -549,3 +558,10 @@ dsl('active|inactive|banned')
 - [PostgreSQL 导出器](postgresql-exporter.md)
 - [最佳实践](best-practices.md)
 
+---
+
+## 对应示例文件
+
+**示例入口**: [export-limitations.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/export-limitations.ts)  
+**说明**: 展示“完整应用层 schema”与“数据库导出专用简化 schema”的分工，以及三类导出器对静态 schema 的落地结果。
+