schema-dsl 1.2.5 → 2.0.1

package/docs/optional-marker-guide.md

@@ -1,321 +1,326 @@
-# schema-dsl 可选标记 ? 支持
-
-**版本**: v1.1.4+  
-**更新日期**: 2026-01-13
-
----
-
-## 📋 功能概述
-
-schema-dsl 现在支持使用 `?` 显式标记可选字段，提供更清晰的语义表达。
-
-### 支持的标记
-
-| 标记 | 含义 | 示例 | 说明 |
-|------|------|------|------|
-| `!` | 必填 | `string!` | 字段不能为空 |
-| `?` | 可选 | `string?` | 字段可以为空（显式表达） |
-| 无标记 | 可选（默认） | `string` | 字段可以为空（默认行为） |
-
----
-
-## ✅ 支持的语法
-
-### 1. 基础类型 + ?
-
-```javascript
-const { dsl, validate } = require('schema-dsl');
-
-const schema = dsl({
-  username: 'string!',      // 必填字符串
-  nickname: 'string',       // 可选字符串（默认）
-  bio: 'string?',           // 显式可选字符串
-  email: 'email?'           // 可选邮箱
-});
-
-// 验证
-validate(schema, {});                                // ✅ 通过（只有username必填）
-validate(schema, { username: 'test' });              // ✅ 通过
-validate(schema, { username: 'test', bio: 'hi' });   // ✅ 通过
-validate(schema, { username: 'test', email: 'invalid' }); // ❌ 失败（email格式错误）
-```
-
-### 2. 带约束的类型 + ?
-
-```javascript
-const schema = dsl({
-  username: 'string:3-32!',   // 必填，长度3-32
-  nickname: 'string:3-32?',   // 可选，有值时长度3-32
-  age: 'number:18-?',         // 可选，有值时≥18
-  score: 'number:0-100?'      // 可选，有值时0-100
-});
-
-validate(schema, { username: 'test' });              // ✅ 通过
-validate(schema, { username: 'test', age: 16 });     // ❌ 失败（age<18）
-validate(schema, { username: 'test', age: 20 });     // ✅ 通过
-```
-
-### 3. 格式类型 + ?
-
-```javascript
-const schema = dsl({
-  email: 'email?',            // 可选邮箱
-  url: 'url?',                // 可选URL
-  uuid: 'uuid?',              // 可选UUID
-  date: 'date?',              // 可选日期
-  phone: 'phone:cn?'          // 可选中国手机号
-});
-
-validate(schema, {});                          // ✅ 通过（全部可选）
-validate(schema, { email: 'test@example.com' }); // ✅ 通过
-validate(schema, { email: 'invalid' });        // ❌ 失败（格式错误）
-```
-
-### 4. 数组类型 + ?
-
-```javascript
-const schema = dsl({
-  tags: 'array<string>?',     // 可选字符串数组
-  items: 'array:1-10?',       // 可选数组，长度1-10
-  numbers: 'array<number>?'   // 可选数字数组
-});
-
-validate(schema, {});                          // ✅ 通过
-validate(schema, { tags: ['a', 'b'] });        // ✅ 通过
-validate(schema, { tags: [] });                // ✅ 通过（空数组）
-```
-
----
-
-## 🎯 语义对比
-
-### string vs string?
-
-虽然两者行为相同（都是可选），但语义不同：
-
-```javascript
-// 方式1: 隐式可选（默认）
-const schema1 = dsl({
-  nickname: 'string'
-});
-
-// 方式2: 显式可选（推荐）
-const schema2 = dsl({
-  nickname: 'string?'
-});
-```
-
-**推荐使用 `?` 的场景**：
-- 需要明确表达"此字段是故意设计为可选的"
-- 与其他必填字段对比时，增强代码可读性
-- 团队规范要求显式标记可选字段
-
-**示例**：
-
-```javascript
-// ❌ 不清晰：哪些是有意可选？哪些是遗漏了必填标记？
-const schema = dsl({
-  username: 'string!',
-  nickname: 'string',
-  bio: 'string',
-  email: 'email!'
-});
-
-// ✅ 清晰：明确表达设计意图
-const schema = dsl({
-  username: 'string!',    // 必填
-  nickname: 'string?',    // 可选
-  bio: 'string?',         // 可选
-  email: 'email!'         // 必填
-});
-```
-
----
-
-## ⚠️ 注意事项
-
-### 1. 枚举类型中的 ?
-
-当 `?` 出现在枚举值中时，需要特别注意：
-
-```javascript
-// ❌ 错误：? 会被当作枚举值的一部分
-const schema1 = dsl({
-  status: 'active|inactive?'
-});
-// 解析为: enum ['active', 'inactive?']
-// 'inactive' 会验证失败！
-
-// ✅ 正确：枚举默认就是可选的
-const schema2 = dsl({
-  status: 'active|inactive'
-});
-
-// ✅ 正确：枚举必填时使用 !
-const schema3 = dsl({
-  status: 'active|inactive!'
-});
-```
-
-### 2. 优先级规则
-
-当 `!` 和 `?` 同时出现时（虽然不推荐），`!` 优先：
-
-```javascript
-// ⚠️ 不推荐：同时使用 ! 和 ?
-const schema = dsl({
-  field: 'string!?'     // ! 优先，字段必填
-});
-```
-
-### 3. 对象字段的可选
-
-```javascript
-// 对象本身可选，内部字段必填
-const schema1 = dsl({
-  user: {
-    name: 'string!',      // 当user存在时，name必填
-    email: 'email!'       // 当user存在时，email必填
-  }
-});
-
-// 对象本身可选（显式），内部字段必填
-const schema2 = dsl({
-  'user?': {              // 显式可选
-    name: 'string!',
-    email: 'email!'
-  }
-});
-
-// 对象本身必填，内部字段可选
-const schema3 = dsl({
-  'user!': {              // 对象必填
-    name: 'string?',      // 可选
-    email: 'email?'       // 可选
-  }
-});
-```
-
----
-
-## 📊 实际测试结果
-
-### 测试统计
-
-- ✅ **string?** - 支持
-- ✅ **string:3-32?** - 支持
-- ✅ **email?** - 支持
-- ✅ **number:18-?** - 支持
-- ✅ **array<string>?** - 支持
-- ✅ **所有单元测试通过** - 949/949
-
-### 测试代码
-
-```javascript
-const { dsl, validate } = require('schema-dsl');
-
-// 测试1: string?
-const schema1 = dsl({ name: 'string?' });
-console.log(validate(schema1, {}).valid);              // true
-console.log(validate(schema1, { name: 'test' }).valid); // true
-
-// 测试2: email?
-const schema2 = dsl({ email: 'email?' });
-console.log(validate(schema2, {}).valid);                        // true
-console.log(validate(schema2, { email: 'test@ex.com' }).valid); // true
-console.log(validate(schema2, { email: 'invalid' }).valid);     // false ✅
-
-// 测试3: string:3-32?
-const schema3 = dsl({ username: 'string:3-32?' });
-console.log(validate(schema3, {}).valid);                   // true
-console.log(validate(schema3, { username: 'ab' }).valid);   // false ✅
-console.log(validate(schema3, { username: 'test' }).valid); // true
-```
-
----
-
-## 🔧 实现细节
-
-### DslBuilder 构造函数
-
-```javascript
-constructor(dslString) {
-  // ...
-  
-  // 🔴 处理必填标记 ! 和可选标记 ?
-  // 优先级：! > ?（如果同时存在，! 优先）
-  this._required = processedDsl.endsWith('!');
-  this._optional = processedDsl.endsWith('?') && !this._required;
-  
-  let dslWithoutMarker = processedDsl;
-  if (this._required) {
-    dslWithoutMarker = processedDsl.slice(0, -1);
-  } else if (this._optional) {
-    dslWithoutMarker = processedDsl.slice(0, -1);
-  }
-  
-  // ...
-}
-```
-
----
-
-## 📝 最佳实践
-
-### 推荐的使用方式
-
-```javascript
-const { dsl } = require('schema-dsl');
-
-// ✅ 推荐：显式标记所有字段
-const schema = dsl({
-  // 必填字段 - 使用 !
-  username: 'string:3-32!',
-  password: 'string:8-!',
-  email: 'email!',
-  
-  // 可选字段 - 使用 ?
-  nickname: 'string:3-32?',
-  bio: 'string:500?',
-  avatar: 'url?',
-  phone: 'phone:cn?',
-  
-  // 对象字段
-  'profile!': {           // 对象必填
-    age: 'number:18-?',   // 年龄可选
-    gender: 'male|female|other?', // 性别可选
-  }
-});
-```
-
-### 代码审查清单
-
-在代码审查时，检查以下事项：
-
-- [ ] 所有必填字段都使用 `!` 标记
-- [ ] 可选字段根据团队规范决定是否使用 `?`
-- [ ] 枚举类型中没有错误地使用 `?`（如 `active|inactive?`）
-- [ ] 复杂约束的可选字段正确使用（如 `string:3-32?`）
-
----
-
-## 🔄 版本兼容性
-
-- **v1.1.3 及之前**：`?` 被忽略，但不影响功能（因为默认可选）
-- **v1.1.4+**：`?` 被显式处理，语义更清晰
-
-**向后兼容**：✅ 完全兼容，所有现有代码无需修改
-
----
-
-## 📚 相关文档
-
-- [DSL 语法完整指南](./dsl-syntax.md)
-- [TypeScript 类型定义](../index.d.ts)
-- [单元测试](../test/unit/dsl-adapter.test.js)
-
----
-
-**最后更新**: 2026-01-13  
-**作者**: schema-dsl Team
-
+# schema-dsl 可选标记 ? 支持
+
+**版本**: v1.1.4+  
+**更新日期**: 2026-01-13
+
+---
+
+## 📋 功能概述
+
+schema-dsl 现在支持使用 `?` 显式标记可选字段，提供更清晰的语义表达。
+
+### 支持的标记
+
+| 标记 | 含义 | 示例 | 说明 |
+|------|------|------|------|
+| `!` | 必填 | `string!` | 字段必须存在 |
+| `?` | 可选 | `string?` | 字段可省略（显式表达） |
+| 无标记 | 可选（默认） | `string` | 字段可省略（默认行为） |
+
+---
+
+## ✅ 支持的语法
+
+### 1. 基础类型 + ?
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+const schema = dsl({
+  username: 'string!',      // 必填字符串
+  nickname: 'string',       // 可选字符串（默认）
+  bio: 'string?',           // 显式可选字符串
+  email: 'email?'           // 可选邮箱
+});
+
+// 验证
+validate(schema, {});                                // ✅ 通过（只有username必填）
+validate(schema, { username: 'test' });              // ✅ 通过
+validate(schema, { username: 'test', bio: 'hi' });   // ✅ 通过
+validate(schema, { username: 'test', email: 'invalid' }); // ❌ 失败（email格式错误）
+```
+
+### 2. 带约束的类型 + ?
+
+```javascript
+const schema = dsl({
+  username: 'string:3-32!',   // 必填，长度3-32
+  nickname: 'string:3-32?',   // 可选，有值时长度3-32
+  age: 'number:18-?',         // 可选，有值时≥18
+  score: 'number:0-100?'      // 可选，有值时0-100
+});
+
+validate(schema, { username: 'test' });              // ✅ 通过
+validate(schema, { username: 'test', age: 16 });     // ❌ 失败（age<18）
+validate(schema, { username: 'test', age: 20 });     // ✅ 通过
+```
+
+### 3. 格式类型 + ?
+
+```javascript
+const schema = dsl({
+  email: 'email?',            // 可选邮箱
+  url: 'url?',                // 可选URL
+  uuid: 'uuid?',              // 可选UUID
+  date: 'date?',              // 可选日期
+  phone: 'phone:cn?'          // 可选中国手机号
+});
+
+validate(schema, {});                          // ✅ 通过（全部可选）
+validate(schema, { email: 'test@example.com' }); // ✅ 通过
+validate(schema, { email: 'invalid' });        // ❌ 失败（格式错误）
+```
+
+### 4. 数组类型 + ?
+
+```javascript
+const schema = dsl({
+  tags: 'array<string>?',     // 可选字符串数组
+  items: 'array:1-10?',       // 可选数组，长度1-10
+  numbers: 'array<number>?'   // 可选数字数组
+});
+
+validate(schema, {});                          // ✅ 通过
+validate(schema, { tags: ['a', 'b'] });        // ✅ 通过
+validate(schema, { tags: [] });                // ✅ 通过（空数组）
+```
+
+---
+
+## 🎯 语义对比
+
+### string vs string?
+
+虽然两者行为相同（都是可选），但语义不同：
+
+```javascript
+// 方式1: 隐式可选（默认）
+const schema1 = dsl({
+  nickname: 'string'
+});
+
+// 方式2: 显式可选（推荐）
+const schema2 = dsl({
+  nickname: 'string?'
+});
+```
+
+**推荐使用 `?` 的场景**：
+- 需要明确表达"此字段是故意设计为可选的"
+- 与其他必填字段对比时，增强代码可读性
+- 团队规范要求显式标记可选字段
+
+**示例**：
+
+```javascript
+// ❌ 不清晰：哪些是有意可选？哪些是遗漏了必填标记？
+const schema = dsl({
+  username: 'string!',
+  nickname: 'string',
+  bio: 'string',
+  email: 'email!'
+});
+
+// ✅ 清晰：明确表达设计意图
+const schema = dsl({
+  username: 'string!',    // 必填
+  nickname: 'string?',    // 可选
+  bio: 'string?',         // 可选
+  email: 'email!'         // 必填
+});
+```
+
+---
+
+## ⚠️ 注意事项
+
+### 1. 枚举类型中的 ?
+
+当 `?` 出现在枚举值中时，需要特别注意：
+
+```javascript
+// ❌ 错误：? 会被当作枚举值的一部分
+const schema1 = dsl({
+  status: 'active|inactive?'
+});
+// 解析为: enum ['active', 'inactive?']
+// 'inactive' 会验证失败！
+
+// ✅ 正确：枚举默认就是可选的
+const schema2 = dsl({
+  status: 'active|inactive'
+});
+
+// ✅ 正确：枚举必填时使用 !
+const schema3 = dsl({
+  status: 'active|inactive!'
+});
+```
+
+### 2. 优先级规则
+
+当 `!` 和 `?` 同时出现时（虽然不推荐），`!` 优先：
+
+```javascript
+// ⚠️ 不推荐：同时使用 ! 和 ?
+const schema = dsl({
+  field: 'string!?'     // ! 优先，字段必填
+});
+```
+
+### 3. 对象字段的可选
+
+```javascript
+// 对象本身可选，内部字段必填
+const schema1 = dsl({
+  user: {
+    name: 'string!',      // 当user存在时，name必填
+    email: 'email!'       // 当user存在时，email必填
+  }
+});
+
+// 对象本身可选（显式），内部字段必填
+const schema2 = dsl({
+  'user?': {              // 显式可选
+    name: 'string!',
+    email: 'email!'
+  }
+});
+
+// 对象本身必填，内部字段可选
+const schema3 = dsl({
+  'user!': {              // 对象必填
+    name: 'string?',      // 可选
+    email: 'email?'       // 可选
+  }
+});
+```
+
+---
+
+## 📊 实际测试结果
+
+### 测试统计
+
+- ✅ **string?** - 支持
+- ✅ **string:3-32?** - 支持
+- ✅ **email?** - 支持
+- ✅ **number:18-?** - 支持
+- ✅ **array<string>?** - 支持
+- ✅ **相关单元测试已覆盖**
+
+### 测试代码
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+// 测试1: string?
+const schema1 = dsl({ name: 'string?' });
+console.log(validate(schema1, {}).valid);              // true
+console.log(validate(schema1, { name: 'test' }).valid); // true
+
+// 测试2: email?
+const schema2 = dsl({ email: 'email?' });
+console.log(validate(schema2, {}).valid);                        // true
+console.log(validate(schema2, { email: 'test@ex.com' }).valid); // true
+console.log(validate(schema2, { email: 'invalid' }).valid);     // false ✅
+
+// 测试3: string:3-32?
+const schema3 = dsl({ username: 'string:3-32?' });
+console.log(validate(schema3, {}).valid);                   // true
+console.log(validate(schema3, { username: 'ab' }).valid);   // false ✅
+console.log(validate(schema3, { username: 'test' }).valid); // true
+```
+
+---
+
+## 🔧 实现细节
+
+### DslParser / DslBuilder 标记处理
+
+```javascript
+// DslParser.parseString()
+if (s.endsWith('!')) {
+  required = true;
+  s = s.slice(0, -1);
+} else if (s.endsWith('?')) {
+  s = s.slice(0, -1);
+}
+
+// DslBuilder constructor（兼容链式入口）
+this._required = s.endsWith('!');
+this._optional = s.endsWith('?') && !this._required;
+if (this._required || this._optional) s = s.slice(0, -1);
+}
+```
+
+当前版本会在 `DslParser.parseString()` 中统一剥离末尾 `!` / `?`，同时 `DslBuilder` 构造函数保留相同的兼容处理，因此字符串 DSL 和链式 Builder 两条入口都能识别可选标记。
+
+---
+
+## 📝 最佳实践
+
+### 推荐的使用方式
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// ✅ 推荐：显式标记所有字段
+const schema = dsl({
+  // 必填字段 - 使用 !
+  username: 'string:3-32!',
+  password: 'string:8-!',
+  email: 'email!',
+  
+  // 可选字段 - 使用 ?
+  nickname: 'string:3-32?',
+  bio: 'string:500?',
+  avatar: 'url?',
+  phone: 'phone:cn?',
+  
+  // 对象字段
+  'profile!': {           // 对象必填
+    age: 'number:18-?',   // 年龄可选
+    gender: 'male|female|other?', // 性别可选
+  }
+});
+```
+
+### 代码审查清单
+
+在代码审查时，检查以下事项：
+
+- [ ] 所有必填字段都使用 `!` 标记
+- [ ] 可选字段根据团队规范决定是否使用 `?`
+- [ ] 枚举类型中没有错误地使用 `?`（如 `active|inactive?`）
+- [ ] 复杂约束的可选字段正确使用（如 `string:3-32?`）
+
+---
+
+## 🔄 版本兼容性
+
+- **v1.1.3 及之前**：`?` 被忽略，但不影响功能（因为默认可选）
+- **v1.1.4+**：`?` 被显式处理，语义更清晰
+
+**向后兼容**：✅ 完全兼容，所有现有代码无需修改
+
+---
+
+## 📚 相关文档
+
+- [DSL 语法完整指南](./dsl-syntax.md)
+- [类型参考](./type-reference.md)
+- [跨类型联合验证](./union-types.md)
+
+---
+
+**最后更新**: 2026-01-13  
+**作者**: schema-dsl Team
+
+---
+
+## 对应示例文件
+
+**示例入口**: [optional-marker-guide.ts](https://github.com/vextjs/schema-dsl/blob/main/examples/docs/optional-marker-guide.ts)  
+**说明**: 覆盖 `!` / `?` 的基础字段、对象字段和默认可选枚举场景，直接展示成功 / 失败路径。
+