schema-dsl 2.3.0

package/docs/label-vs-description.md

@@ -0,0 +1,262 @@
+# label vs description 使用指南
+
+## 📋 快速对比
+
+| 属性 | 用途 | 显示位置 | 示例 |
+|------|------|----------|------|
+| **label** | 字段名称 | 错误消息中 | "邮箱地址不能为空" |
+| **description** | 字段说明 | 表单提示/文档 | "用于登录和接收通知" |
+
+---
+
+## 🎯 详细说明
+
+### label（标签）
+
+**作用**: 在错误消息中替换字段名
+
+**使用场景**:
+- 让错误消息更友好
+- 中文化字段名
+- 简化技术字段名
+
+**示例**:
+
+```javascript
+// 不使用label
+email: 'email!'
+// 错误消息: "email is required"  ❌ 不友好
+
+// 使用label
+email: 'email!'.label('邮箱地址')
+// 错误消息: "邮箱地址不能为空"  ✅ 友好
+```
+
+**完整示例**:
+
+```javascript
+const schema = dsl({
+  userEmail: 'email!'
+    .label('用户邮箱')
+    .messages({
+      'required': '{{#label}}不能为空',  // 使用label值
+      'format': '{{#label}}格式不正确'
+    })
+});
+
+// 验证失败时:
+// 错误: "用户邮箱不能为空"
+// 错误: "用户邮箱格式不正确"
+```
+
+---
+
+### description（描述）
+
+**作用**: 提供字段的详细说明
+
+**使用场景**:
+- 表单输入提示
+- API文档生成
+- Schema文档
+- 帮助用户理解字段用途
+
+**示例**:
+
+```javascript
+email: 'email!'
+  .label('邮箱地址')
+  .description('用于登录和接收系统通知')
+```
+
+**在表单中使用**:
+
+```html
+<div class="form-field">
+  <label>邮箱地址</label>  <!-- 来自 label -->
+  <input type="email" />
+  <span class="hint">用于登录和接收系统通知</span>  <!-- 来自 description -->
+</div>
+```
+
+**在API文档中**:
+
+```json
+{
+  "email": {
+    "type": "string",
+    "format": "email",
+    "title": "邮箱地址",           // 来自 label
+    "description": "用于登录和接收系统通知"  // 来自 description
+  }
+}
+```
+
+---
+
+## 💡 最佳实践
+
+### 1. label 是必需的（用户可见字段）
+
+```javascript
+const schema = dsl({
+  // ✅ 好：所有用户可见字段都有label
+  username: 'string:3-32!'.label('用户名'),
+  email: 'email!'.label('邮箱地址'),
+  password: 'string:8-64!'.label('密码'),
+  
+  // ⚠️ 可以：内部字段可以不用label
+  userId: 'uuid!',
+  createdAt: 'date!'
+});
+```
+
+### 2. description 是可选的（需要说明时使用）
+
+```javascript
+const schema = dsl({
+  // ✅ 复杂字段：添加description
+  apiKey: 'string:32!'
+    .label('API密钥')
+    .description('用于调用第三方API，请妥善保管'),
+  
+  // ✅ 简单字段：不需要description
+  name: 'string:1-50!'.label('姓名'),
+  
+  // ✅ 有特殊要求的字段：添加description
+  password: 'string:8-64!'
+    .label('密码')
+    .description('必须包含大小写字母和数字')
+    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
+});
+```
+
+### 3. 组合使用示例
+
+```javascript
+const userSchema = dsl({
+  // 完整的字段定义
+  email: 'email!'
+    .label('邮箱地址')                    // 错误消息中显示
+    .description('用于登录和接收通知')    // 表单提示/文档
+    .messages({
+      'required': '{{#label}}不能为空',
+      'format': '请输入有效的{{#label}}'
+    }),
+  
+  // 简单字段
+  age: 'number:18-120'.label('年龄'),
+  
+  // 复杂字段
+  bio: 'string:500'
+    .label('个人简介')
+    .description('介绍你自己，最多500字'),
+  
+  // 内部字段（无需label/description）
+  userId: 'uuid!',
+  createdAt: 'date!'
+});
+```
+
+---
+
+## 📊 使用场景对比
+
+| 场景 | label | description |
+|------|-------|-------------|
+| **错误消息** | ✅ 必需 | ❌ 不使用 |
+| **表单标签** | ✅ 推荐 | ⚠️ 可选 |
+| **表单提示** | ❌ 不使用 | ✅ 推荐 |
+| **API文档** | ✅ 作为title | ✅ 作为说明 |
+| **Schema文档** | ✅ 字段名 | ✅ 字段说明 |
+| **内部字段** | ⚠️ 可选 | ⚠️ 可选 |
+
+---
+
+## 🎨 实际效果
+
+### 验证错误显示
+
+```javascript
+// Schema定义
+const schema = dsl({
+  email: 'email!'
+    .label('邮箱地址')
+    .messages({
+      'required': '{{#label}}不能为空',
+      'format': '{{#label}}格式不正确'
+    })
+});
+
+// 验证空值
+validator.validate(schema, { email: '' });
+// 错误: "邮箱地址不能为空"  ← 使用了label
+
+// 验证错误格式
+validator.validate(schema, { email: 'invalid' });
+// 错误: "邮箱地址格式不正确"  ← 使用了label
+```
+
+### 表单渲染
+
+```javascript
+const schema = dsl({
+  password: 'string:8-64!'
+    .label('登录密码')
+    .description('8-64位，包含大小写字母和数字')
+    .pattern(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/)
+});
+
+// 渲染为HTML
+<div class="form-field">
+  <label>登录密码</label>                              ← label
+  <input type="password" />
+  <span class="hint">8-64位，包含大小写字母和数字</span>  ← description
+</div>
+```
+
+---
+
+## ✅ 总结
+
+### label
+
+- **必需性**: 用户可见字段推荐使用
+- **用途**: 让错误消息更友好
+- **位置**: 错误消息、表单标签
+- **格式**: 简短的名词（2-6个字）
+
+### description
+
+- **必需性**: 可选，需要说明时使用
+- **用途**: 帮助用户理解字段用途
+- **位置**: 表单提示、API文档
+- **格式**: 完整的句子或短语
+
+### 推荐组合
+
+```javascript
+// 最小配置（简单字段）
+name: 'string:1-50!'.label('姓名')
+
+// 标准配置（常规字段）
+email: 'email!'
+  .label('邮箱地址')
+  .messages({ 'format': '请输入有效的{{#label}}' })
+
+// 完整配置（复杂字段）
+apiKey: 'string:32!'
+  .label('API密钥')
+  .description('用于调用第三方API，请妥善保管')
+  .pattern(/^[A-Za-z0-9]{32}$/)
+  .messages({
+    'required': '{{#label}}不能为空',
+    'pattern': '{{#label}}格式不正确'
+  })
+```
+
+---
+
+**记住**: label用于错误消息，description用于帮助说明！
+
+

package/docs/markdown-exporter.md

@@ -0,0 +1,398 @@
+# Markdown 导出器
+
+> **功能**: 将 JSON Schema 导出为人类可读的 Markdown 文档  
+> **版本**: v2.2.0  
+> **语言支持**: 中文、英文、日文
+
+---
+
+## 📑 目录
+
+- [快速开始](#快速开始)
+- [API 参考](#api-参考)
+- [使用示例](#使用示例)
+- [多语言支持](#多语言支持)
+- [自定义选项](#自定义选项)
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install schema-dsl
+```
+
+### 基本用法
+
+```javascript
+const { dsl, exporters } = require('schema-dsl');
+
+// 定义 Schema
+const schema = dsl({
+  username: 'string:3-32!',
+  email: 'email!',
+  age: 'number:18-120'
+});
+
+// 导出为 Markdown
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: '用户注册 API',
+  locale: 'zh-CN'
+});
+
+console.log(markdown);
+```
+
+**生成的 Markdown**:
+
+```markdown
+# 用户注册 API
+
+## 字段列表
+
+| 字段名 | 类型 | 必填 | 约束 | 说明 |
+|--------|------|------|------|------|
+| username | 字符串 | ✅ | 长度: 3-32 | - |
+| email | 邮箱 | ✅ | - | - |
+| age | 数字 | ❌ | 范围: 18-120 | - |
+
+## 示例数据
+
+\```json
+{
+  "username": "example",
+  "email": "user@example.com"
+}
+\```
+
+## 约束规则
+
+**必填字段**: `username`, `email`
+
+**可选字段**: `age`
+```
+
+---
+
+## API 参考
+
+### MarkdownExporter.export(schema, options)
+
+导出 JSON Schema 为 Markdown 文档。
+
+**参数**:
+
+- `schema` (Object) - JSON Schema 对象
+- `options` (Object) - 导出选项
+  - `title` (String) - 文档标题，默认: `'Schema 文档'`
+  - `locale` (String) - 语言代码，默认: `'zh-CN'`
+    - 支持: `'zh-CN'` (中文), `'en-US'` (英文), `'ja-JP'` (日文)
+  - `includeExample` (Boolean) - 是否包含示例数据，默认: `true`
+  - `includeDescription` (Boolean) - 是否包含描述，默认: `true`
+
+**返回值**: `String` - Markdown 文本
+
+---
+
+## 使用示例
+
+### 示例 1: 基础用法
+
+```javascript
+const schema = dsl({
+  name: 'string:1-50!',
+  email: 'email!'
+});
+
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: '用户信息'
+});
+
+console.log(markdown);
+```
+
+### 示例 2: 使用标签
+
+```javascript
+const schema = dsl({
+  name: 'string:1-50!'.label('姓名'),
+  email: 'email!'.label('邮箱地址'),
+  age: 'number:18-120'.label('年龄')
+});
+
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: '用户注册表单',
+  locale: 'zh-CN'
+});
+```
+
+**生成结果**:
+
+| 字段名 | 类型 | 必填 | 约束 | 说明 |
+|--------|------|------|------|------|
+| name | 字符串 | ✅ | 长度: 1-50 | 姓名 |
+| email | 邮箱 | ✅ | - | 邮箱地址 |
+| age | 数字 | ❌ | 范围: 18-120 | 年龄 |
+
+### 示例 3: 复杂 Schema
+
+```javascript
+const productSchema = dsl({
+  'id': 'string:24!'.label('产品ID'),
+  'name': 'string:1-100!'.label('产品名称'),
+  'price': 'number:0.01-!'.label('价格 (USD)'),
+  'stock': 'integer:0-!'.label('库存数量'),
+  'category': 'electronics|clothing|books|other!'.label('类别'),
+  'tags': 'array:1-10<string:1-20>'.label('标签'),
+  'description': 'string:500'.label('产品描述'),
+  'active': 'boolean'.label('是否上架')
+});
+
+const markdown = exporters.MarkdownExporter.export(productSchema, {
+  title: '产品信息 Schema',
+  locale: 'zh-CN',
+  includeExample: true
+});
+```
+
+### 示例 4: 不包含示例
+
+```javascript
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: 'API 文档',
+  includeExample: false  // 不生成示例数据
+});
+```
+
+---
+
+## 多语言支持
+
+### 支持的语言
+
+| 语言代码 | 语言名称 | 示例 |
+|---------|---------|------|
+| `zh-CN` | 简体中文 | 字符串、数字、必填 |
+| `en-US` | 英文 | String, Number, Required |
+| `ja-JP` | 日文 | 文字列、数値、必須 |
+
+### 中文示例
+
+```javascript
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: '用户注册 API',
+  locale: 'zh-CN'
+});
+```
+
+**输出**:
+- 字段列表 (Fields)
+- 类型: 字符串、数字、布尔值
+- 必填: ✅ / ❌
+
+### 英文示例
+
+```javascript
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: 'User Registration API',
+  locale: 'en-US'
+});
+```
+
+**输出**:
+- Fields
+- Type: String, Number, Boolean
+- Required: ✅ / ❌
+
+### 日文示例
+
+```javascript
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: 'ユーザー登録 API',
+  locale: 'ja-JP'
+});
+```
+
+**输出**:
+- フィールド一覧
+- タイプ: 文字列、数値、ブール値
+- 必須: ✅ / ❌
+
+---
+
+## 自定义选项
+
+### 完整配置示例
+
+```javascript
+const markdown = exporters.MarkdownExporter.export(schema, {
+  // 文档标题
+  title: 'API 文档 - 用户模块',
+  
+  // 语言设置
+  locale: 'zh-CN',
+  
+  // 是否包含示例数据
+  includeExample: true,
+  
+  // 是否包含 Schema 描述
+  includeDescription: true
+});
+```
+
+### 保存为文件
+
+```javascript
+const fs = require('fs');
+
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: 'API Documentation',
+  locale: 'en-US'
+});
+
+// 保存为 Markdown 文件
+fs.writeFileSync('./API.md', markdown, 'utf-8');
+console.log('Markdown 文档已生成: API.md');
+```
+
+---
+
+## 类型映射表
+
+### 基本类型
+
+| Schema 类型 | 中文 | 英文 | 日文 |
+|------------|------|------|------|
+| string | 字符串 | String | 文字列 |
+| number | 数字 | Number | 数値 |
+| integer | 整数 | Integer | 整数 |
+| boolean | 布尔值 | Boolean | ブール値 |
+| array | 数组 | Array | 配列 |
+| object | 对象 | Object | オブジェクト |
+
+### 格式类型
+
+| 格式 | 中文 | 英文 | 日文 |
+|------|------|------|------|
+| email | 邮箱 | Email | メールアドレス |
+| url | 网址 | URL | URL |
+| date | 日期 | Date | 日付 |
+| uuid | UUID | UUID | UUID |
+
+---
+
+## 高级用法
+
+### 与其他导出器结合
+
+```javascript
+const { dsl, exporters } = require('schema-dsl');
+
+const schema = dsl({
+  username: 'string:3-32!',
+  email: 'email!'
+});
+
+// 导出为 Markdown (人类可读)
+const markdown = exporters.MarkdownExporter.export(schema, {
+  title: '用户 Schema',
+  locale: 'zh-CN'
+});
+
+// 导出为 MongoDB Schema
+const mongoSchema = exporters.MongoDBExporter.export(schema, {
+  collectionName: 'users'
+});
+
+// 导出为 MySQL DDL
+const mysqlDDL = exporters.MySQLExporter.export(schema, {
+  tableName: 'users'
+});
+
+console.log('Markdown 文档:\n', markdown);
+console.log('\nMongoDB Schema:\n', mongoSchema);
+console.log('\nMySQL DDL:\n', mysqlDDL);
+```
+
+---
+
+## 常见问题
+
+### Q: 如何自定义字段说明？
+
+A: 使用 `.label()` 方法：
+
+```javascript
+const schema = dsl({
+  email: 'email!'.label('用户邮箱地址')
+});
+```
+
+### Q: 生成的示例数据是什么？
+
+A: 示例数据包含所有**必填字段**，值根据类型和约束自动生成：
+- 邮箱: `user@example.com`
+- 数字: 使用 `minimum` 或 `0`
+- 字符串: `'example'`
+- 布尔值: `true`
+
+### Q: 如何隐藏某些字段？
+
+A: Markdown 导出器会导出所有字段。如需隐藏，请在生成前移除字段。
+
+### Q: 支持嵌套对象吗？
+
+A: 当前版本主要支持扁平结构。嵌套对象会显示为 "对象" 类型。
+
+---
+
+## 完整示例
+
+```javascript
+const { dsl, exporters } = require('schema-dsl');
+const fs = require('fs');
+
+// 定义用户注册 Schema
+const userRegistrationSchema = dsl({
+  // 基本信息
+  'username': 'string:3-32!'.label('用户名'),
+  'email': 'email!'.label('邮箱地址'),
+  'password': 'string:8-32!'.label('密码'),
+  
+  // 个人信息
+  'realName': 'string:1-50'.label('真实姓名'),
+  'age': 'integer:18-120'.label('年龄'),
+  'gender': 'male|female|other'.label('性别'),
+  
+  // 其他
+  'acceptTerms': 'boolean!'.label('同意条款')
+});
+
+// 生成中文文档
+const zhDoc = exporters.MarkdownExporter.export(userRegistrationSchema, {
+  title: '用户注册 API 文档',
+  locale: 'zh-CN',
+  includeExample: true
+});
+
+// 生成英文文档
+const enDoc = exporters.MarkdownExporter.export(userRegistrationSchema, {
+  title: 'User Registration API Documentation',
+  locale: 'en-US',
+  includeExample: true
+});
+
+// 保存文档
+fs.writeFileSync('./docs/USER_REGISTRATION_ZH.md', zhDoc);
+fs.writeFileSync('./docs/USER_REGISTRATION_EN.md', enDoc);
+
+console.log('✅ 文档已生成');
+```
+
+---
+
+**文档更新日期**: 2025-12-29  
+**版本**: v2.2.0
+