schema-dsl 1.1.3 → 1.1.5

package/docs/error-handling.md

@@ -688,16 +688,261 @@ if (!result.valid) {
 
 ---
 
+## v1.1.5 新功能：对象格式错误配置
+
+### 概述
+
+从 v1.1.5 开始，语言包支持对象格式 `{ code, message }`，实现统一的错误代码管理。
+
+### 基础用法
+
+**语言包配置**:
+```javascript
+// lib/locales/zh-CN.js (或自定义语言包)
+module.exports = {
+  // 字符串格式（向后兼容）
+  'user.notFound': '用户不存在',
+  
+  // 对象格式（v1.1.5 新增）✨ - 使用数字错误码
+  'account.notFound': {
+    code: 40001,
+    message: '账户不存在'
+  },
+  'account.insufficientBalance': {
+    code: 40002,
+    message: '余额不足，当前余额{{#balance}}，需要{{#required}}'
+  },
+  'order.notPaid': {
+    code: 50001,
+    message: '订单未支付'
+  }
+};
+```
+
+**使用示例**:
+```javascript
+const { dsl } = require('schema-dsl');
+
+try {
+  dsl.error.throw('account.notFound');
+} catch (error) {
+  console.log(error.originalKey);  // 'account.notFound'
+  console.log(error.code);         // 40001 ✨ 数字错误码
+  console.log(error.message);      // '账户不存在'
+}
+```
+
+### 核心特性
+
+#### 1. originalKey 字段（新增）
+
+保留原始的 key，便于调试和日志追踪：
+
+```javascript
+try {
+  dsl.error.throw('account.notFound');
+} catch (error) {
+  error.originalKey  // 'account.notFound' (原始 key)
+  error.code         // 40001 (数字错误码)
+}
+```
+
+#### 2. 多语言共享 code
+
+不同语言使用相同的数字 `code`，便于前端统一处理：
+
+```javascript
+// zh-CN.js
+'account.notFound': {
+  code: 40001,  // ← 数字 code 一致
+  message: '账户不存在'
+}
+
+// en-US.js
+'account.notFound': {
+  code: 40001,  // ← 数字 code 一致
+  message: 'Account not found'
+}
+
+// 前端处理 - 不受语言影响
+switch (error.code) {
+  case 40001:
+    redirectToLogin();
+    break;
+  case 40002:
+    showTopUpDialog();
+    break;
+  case 50001:
+    showPaymentDialog();
+    break;
+}
+#### 3. 增强的 error.is() 方法
+
+同时支持 `originalKey` 和数字 `code` 判断：
+
+```javascript
+try {
+  dsl.error.throw('account.notFound');
+} catch (error) {
+  // 两种方式都可以
+  if (error.is('account.notFound')) { }  // ✅ 使用 originalKey
+  if (error.is(40001)) { }               // ✅ 使用数字 code
+}
+```
+
+#### 4. toJSON 包含 originalKey
+
+```javascript
+const json = error.toJSON();
+// {
+//   error: 'I18nError',
+//   originalKey: 'account.notFound',  // ✨ v1.1.5 新增
+//   code: 'ACCOUNT_NOT_FOUND',
+//   message: '账户不存在',
+//   params: {},
+//   statusCode: 400,
+//   locale: 'zh-CN'
+// }
+```
+
+### 向后兼容
+
+**完全向后兼容** ✅ - 字符串格式自动转换：
+
+```javascript
+// 字符串格式（原有）
+'user.notFound': '用户不存在'
+
+// 自动转换为对象
+dsl.error.throw('user.notFound');
+// error.code = 'user.notFound' (使用 key 作为 code)
+// error.originalKey = 'user.notFound'
+// error.message = '用户不存在'
+```
+
+### 最佳实践
+
+#### 1. 何时使用对象格式
+
+**推荐使用对象格式**:
+- ✅ 需要在多语言中统一处理的错误
+- ✅ 需要前端统一判断的错误
+- ✅ 核心业务错误（账户、订单、支付等）
+
+**可以使用字符串格式**:
+- ✅ 简单的验证错误
+- ✅ 内部错误（不暴露给前端）
+- ✅ 不需要统一处理的错误
+
+#### 2. 错误代码命名规范
+
+推荐使用**数字错误码**，按模块分段：
+
+```javascript
+// 错误码规范（5位数字）
+// 4xxxx - 客户端错误
+// 5xxxx - 业务逻辑错误  
+// 6xxxx - 系统错误
+
+'account.notFound': {
+  code: 40001,  // ✅ 推荐：账户模块，序号001
+  message: '账户不存在'
+}
+
+'account.insufficientBalance': {
+  code: 40002,  // 账户模块，序号002
+  message: '余额不足'
+}
+
+'order.notPaid': {
+  code: 50001,  // ✅ 订单模块，序号001
+  message: '订单未支付'
+}
+
+'order.cancelled': {
+  code: 50002,  // 订单模块，序号002
+  message: '订单已取消'
+}
+
+'database.connectionError': {
+  code: 60001,  // ✅ 系统错误
+  message: '数据库连接失败'
+}
+```
+
+**错误码分段建议**：
+- `40001-49999` - 客户端错误（账户、权限、参数验证等）
+- `50001-59999` - 业务逻辑错误（订单、支付、库存等）
+- `60001-69999` - 系统错误（数据库、服务不可用等）
+
+#### 3. 前端统一错误处理
+
+```javascript
+// API 调用
+try {
+  const response = await fetch('/api/account');
+  const data = await response.json();
+} catch (error) {
+  // 使用数字 code 统一处理，不受语言影响
+  switch (error.code) {
+    case 40001:  // ACCOUNT_NOT_FOUND
+      showNotFoundPage();
+      break;
+    case 40002:  // INSUFFICIENT_BALANCE
+      showTopUpDialog(error.params);
+      break;
+    case 50001:  // ORDER_NOT_PAID
+      showPaymentDialog();
+      break;
+    case 60001:  // SYSTEM_ERROR
+      showSystemErrorPage();
+      break;
+    default:
+      showGenericError(error.message);
+  }
+}
+```
+
+**更优雅的方式 - 错误码映射**：
+```javascript
+// errorCodeMap.js
+const ERROR_HANDLERS = {
+  40001: () => router.push('/account-not-found'),
+  40002: (error) => showDialog('topup', error.params),
+  50001: (error) => showDialog('payment', error.params),
+  60001: () => showSystemErrorPage(),
+};
+
+// 统一错误处理
+function handleError(error) {
+  const handler = ERROR_HANDLERS[error.code];
+  if (handler) {
+    handler(error);
+  } else {
+    showGenericError(error.message);
+  }
+}
+```
+
+### 更多信息
+
+- [v1.1.5 完整变更日志](../changelogs/v1.1.5.md)
+- [升级指南](../changelogs/v1.1.5.md#升级指南)
+- [最佳实践](../changelogs/v1.1.5.md#最佳实践)
+
+---
+
 ## 相关文档
 
 - [API 参考文档](./api-reference.md)
 - [DSL 语法指南](./dsl-syntax.md)
 - [String 扩展文档](./string-extensions.md)
 - [多语言配置](./dynamic-locale.md)
+- [v1.1.5 变更日志](../changelogs/v1.1.5.md)
 
 ---
 
-
-**最后更新**: 2025-12-25
+**最后更新**: 2026-01-17  
+**版本**: v1.1.5
 
 

package/docs/optional-marker-guide.md

@@ -0,0 +1,321 @@
+# 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
+