schema-dsl
  • 简体中文

      • schema-dsl 可选标记 ? 支持

      📋 功能概述

      schema-dsl 现在支持使用 ? 显式标记可选字段，提供更清晰的语义表达。

      支持的标记

      标记含义示例说明
      !必填string!字段必须存在
      ?可选string?字段可省略（显式表达）
      无标记可选（默认）string字段可省略（默认行为）

      ✅ 支持的语法

      1. 基础类型 + ?

      import { s, validate } from 'schema-dsl/pure';

const schema = s({
  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. 带约束的类型 + ?

      const schema = s({
  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. 格式类型 + ?

      const schema = s({
  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. 数组类型 + ?

      const schema = s({
  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?

      虽然两者行为相同（都是可选），但语义不同：

      // 方式1: 隐式可选（默认）
const schema1 = s({
  nickname: 'string'
});

// 方式2: 显式可选（推荐）
const schema2 = s({
  nickname: 'string?'
});

      推荐使用 ? 的场景：

      • 需要明确表达"此字段是故意设计为可选的"
      • 与其他必填字段对比时，增强代码可读性
      • 团队规范要求显式标记可选字段

      示例：

      // ❌ 不清晰：哪些是有意可选？哪些是遗漏了必填标记？
const schema = s({
  username: 'string!',
  nickname: 'string',
  bio: 'string',
  email: 'email!'
});

// ✅ 清晰：明确表达设计意图
const schema = s({
  username: 'string!',    // 必填
  nickname: 'string?',    // 可选
  bio: 'string?',         // 可选
  email: 'email!'         // 必填
});

      ⚠️ 注意事项

      1. 枚举类型中的 ?

      当 ? 出现在枚举值中时，需要特别注意：

      // ❌ 错误：? 会被当作枚举值的一部分
const schema1 = s({
  status: 'active|inactive?'
});
// 解析为: enum ['active', 'inactive?']
// 'inactive' 会验证失败！

// ✅ 正确：枚举默认就是可选的
const schema2 = s({
  status: 'active|inactive'
});

// ✅ 正确：枚举必填时使用 !
const schema3 = s({
  status: 'active|inactive!'
});

      2. 优先级规则

      当 ! 和 ? 同时出现时（虽然不推荐），! 优先：

      // ⚠️ 不推荐：同时使用 ! 和 ?
const schema = s({
  field: 'string!?'     // ! 优先，字段必填
});

      3. 对象字段的可选

      // 对象本身可选，内部字段必填
const schema1 = s({
  user: {
    name: 'string!',      // 当user存在时，name必填
    email: 'email!'       // 当user存在时，email必填
  }
});

// 对象本身可选（显式），内部字段必填
const schema2 = s({
  'user?': {              // 显式可选
    name: 'string!',
    email: 'email!'
  }
});

// 对象本身必填，内部字段可选
const schema3 = s({
  'user!': {              // 对象必填
    name: 'string?',      // 可选
    email: 'email?'       // 可选
  }
});

      📊 实际测试结果

      测试统计

      • ✅ string? - 支持
      • ✅ string:3-32? - 支持
      • ✅ email? - 支持
      • ✅ number:18-? - 支持
      • ✅ array? - 支持
      • ✅ 相关单元测试已覆盖

      测试代码

      import { s, validate } from 'schema-dsl/pure';

// 测试1: string?
const schema1 = s({ name: 'string?' });
console.log(validate(schema1, {}).valid);              // true
console.log(validate(schema1, { name: 'test' }).valid); // true

// 测试2: email?
const schema2 = s({ 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 = s({ 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 标记处理

      // 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 两条入口都能识别可选标记。

      📝 最佳实践

      推荐的使用方式

      import { s } from 'schema-dsl/pure';

// ✅ 推荐：显式标记所有字段
const schema = s({
  // 必填字段 - 使用 !
  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? 这类枚举 DSL：这里的 ? 属于最后一个枚举值，不代表整个字段可选。

      🔄 版本兼容性

      • v1.1.3 及之前：? 被忽略，但不影响功能（因为默认可选）
      • v1.1.4+：? 被显式处理，语义更清晰

      向后兼容：✅ 完全兼容，所有现有代码无需修改

      📚 相关文档

      对应示例文件

      示例入口: optional-marker-guide.ts
      说明: 覆盖 ! / ? 的基础字段、对象字段和默认可选枚举场景，直接展示成功 / 失败路径。