schema-dsl 1.1.0 → 1.1.1

package/docs/conditional-api.md

@@ -1,7 +1,7 @@
 # 链式条件 API - ConditionalBuilder
 
-> **版本**: v1.1.0  
-> **更新日期**: 2026-01-05  
+> **版本**: v1.1.1  
+> **更新日期**: 2026-01-06  
 > **状态**: ✅ 稳定
 
 ---
@@ -9,6 +9,7 @@
 ## 📋 目录
 
 - [概述](#概述)
+- [🆕 v1.1.1 新功能](#-v110-新功能)
 - [快速开始](#快速开始)
 - [API 参考](#api-参考)
 - [使用场景](#使用场景)
@@ -26,11 +27,153 @@
 - ✅ **链式调用** - 流畅的 API，类似 JavaScript if-else
 - ✅ **运行时执行** - 在验证时根据实际数据判断
 - ✅ **多条件组合** - 支持 and/or 逻辑组合
+- ✅ **🆕 独立消息** - v1.1.1+ 每个 .and()/.or() 可有独立错误消息
 - ✅ **else 可选** - 不写 else 就不验证
 - ✅ **简化设计** - message 自动抛错，无需 throwError()
 - ✅ **完全兼容** - 不影响现有 API
 
-### 与现有方法的区别
+---
+
+## 🆕 v1.1.1 新功能
+
+### 独立消息支持 - `.and()/.or()` 后可调用 `.message()`
+
+**每个条件都可以有自己的错误消息**
+
+v1.1.1 开始，支持在 `.and()` 和 `.or()` 后调用 `.message()` 设置独立的错误消息，让错误提示更精确。
+
+#### 基础用法
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// ✅ v1.1.1+ 新功能：每个条件独立消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+
+// 工作原理：
+// - 第一个条件为 true → 返回 'ACCOUNT_NOT_FOUND'
+// - 第二个条件为 true → 返回 'INSUFFICIENT_TRADABLE_CREDITS'
+// - 所有条件为 false → 验证成功
+```
+
+#### 多个 .and() 条件
+
+```javascript
+// 多层验证，每层都有清晰的错误消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.status !== 'active')
+  .message('ACCOUNT_INACTIVE')
+  .and(d => d.tradable_credits < amount)
+  .message('INSUFFICIENT_TRADABLE_CREDITS')
+  .assert(account);
+
+// 依次检查，第一个为 true 的条件返回其消息
+```
+
+#### .or() 条件独立消息
+
+```javascript
+// OR 条件也支持独立消息
+dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .or(d => d.isBlocked)
+  .message('账户已被封禁')
+  .assert(data);
+
+// 任一条件为 true 就失败，返回对应消息
+```
+
+#### 链式检查模式
+
+v1.1.1 引入了**链式检查模式**，当满足以下条件时自动启用：
+
+1. 使用 `.message()` 模式（不是 `.then()`/`.else()`）
+2. root 条件有 `.message()`
+3. 有 `.and()` 条件
+4. 没有 `.or()` 条件
+
+**链式检查模式特点**：
+- 依次检查每个条件
+- 第一个为 `true` 的条件失败，返回其消息
+- 所有条件为 `false` 时验证通过
+
+**示例对比**：
+
+```javascript
+// ✅ 启用链式检查（纯 AND 场景）
+dsl.if(d => !d).message('A').and(d => d < 100).message('B')
+
+// ❌ 不启用（有 .or()，使用传统 AND/OR 逻辑）
+dsl.if(d => !d).message('A').and(d => d < 100).or(d => d > 200).message('B')
+
+// ❌ 不启用（使用 .then()/.else()，不是 message 模式）
+dsl.if(d => d.age >= 18).and(d => d.role === 'admin').then('email!')
+```
+
+#### 向后兼容性
+
+**100% 向后兼容**，不影响现有代码：
+
+```javascript
+// ✅ 原有用法继续工作
+dsl.if(d => d.age >= 18).and(d => d.role === 'admin').message('不符合条件')
+
+// ✅ .and() 后不调用 .message() 也可以
+dsl.if(d => !d).message('整体错误').and(d => d < 100).assert(50)
+// → 使用整体消息 '整体错误'
+```
+
+#### 实际应用场景
+
+**场景1：账户验证**
+```javascript
+function validateAccount(account, amount) {
+  dsl.if(d => !d)
+    .message('ACCOUNT_NOT_FOUND')
+    .and(d => d.status !== 'active')
+    .message('ACCOUNT_INACTIVE')
+    .and(d => d.balance < amount)
+    .message('INSUFFICIENT_BALANCE')
+    .assert(account);
+}
+
+// 每个失败点都有清晰的错误消息
+```
+
+**场景2：用户权限验证**
+```javascript
+function validateUserPermission(user) {
+  dsl.if(d => d.role !== 'admin')
+    .message('NO_ADMIN_PERMISSION')
+    .and(d => !d.isVerified)
+    .message('USER_NOT_VERIFIED')
+    .and(d => d.isBanned)
+    .message('USER_BANNED')
+    .assert(user);
+}
+```
+
+**场景3：订单状态检查**
+```javascript
+function validateOrder(order) {
+  dsl.if(d => d.status !== 'paid')
+    .message('ORDER_NOT_PAID')
+    .and(d => !d.payment)
+    .message('PAYMENT_INFO_MISSING')
+    .and(d => !d.shippingAddress)
+    .message('SHIPPING_ADDRESS_MISSING')
+    .assert(order);
+}
+```
+
+---
+
+## 与现有方法的区别
 
 `dsl.if()` 提供两种使用方式，根据参数类型自动选择：
 
@@ -180,19 +323,59 @@ dsl.if((data) => data.status === 'active' && data.verified)
 
 添加 AND 条件（与前一个条件组合）。
 
+> **v1.1.1+** 支持在 `.and()` 后调用 `.message()` 设置独立的错误消息
+
 **参数**:
 - `condition` {Function} - 条件函数
 
 **返回**: `this` - 支持链式调用
 
-**示例**:
+**基础示例**:
 ```javascript
+// 传统用法：所有条件共享一个消息
 dsl.if((data) => data.age >= 18)
   .and((data) => data.userType === 'admin')
-  .then('email!')
+  .message('不符合条件')
+```
+
+**v1.1.1+ 独立消息**:
+```javascript
+// ✅ 每个条件都有自己的错误消息
+dsl.if((data) => !data)
+  .message('账户不存在')
+  .and((data) => data.balance < 100)
+  .message('余额不足')
+  .assert(account);
+
+// 工作原理：
+// - 第一个条件为 true → 返回 '账户不存在'
+// - 第二个条件为 true → 返回 '余额不足'
+// - 所有条件为 false → 验证成功
+```
+
+**多个 .and() 条件**:
+```javascript
+// 支持多个 .and() 条件，每个都有独立消息
+dsl.if(d => !d)
+  .message('NOT_FOUND')
+  .and(d => d.status !== 'active')
+  .message('INACTIVE')
+  .and(d => d.balance < 100)
+  .message('INSUFFICIENT')
+  .assert(account);
+
+// 依次检查，第一个为 true 的条件返回其消息
 ```
 
-**逻辑**: `(condition1 AND condition2)`
+**逻辑**: 
+- 传统模式：`(condition1 AND condition2)` - 所有条件为 true 才失败
+- 链式检查模式 (v1.1.1+)：依次检查，第一个为 true 的失败
+
+**链式检查模式触发条件**:
+1. 使用 `.message()` 模式
+2. root 条件有 `.message()`
+3. 有 `.and()` 条件
+4. 没有 `.or()` 条件
 
 ---
 
@@ -200,19 +383,41 @@ dsl.if((data) => data.age >= 18)
 
 添加 OR 条件（与前一个条件组合）。
 
+> **v1.1.1+** 支持在 `.or()` 后调用 `.message()` 设置独立的错误消息
+
 **参数**:
 - `condition` {Function} - 条件函数
 
 **返回**: `this` - 支持链式调用
 
-**示例**:
+**基础示例**:
 ```javascript
+// 传统用法：所有条件共享一个消息
 dsl.if((data) => data.age < 18)
   .or((data) => data.status === 'blocked')
   .message('不允许注册')
 ```
 
-**逻辑**: `(condition1 OR condition2)`
+**v1.1.1+ 独立消息**:
+```javascript
+// ✅ 每个 OR 条件都有自己的错误消息
+dsl.if(d => d.age < 18)
+  .message('未成年用户不能注册')
+  .or(d => d.isBlocked)
+  .message('账户已被封禁')
+  .assert(data);
+
+// 工作原理：
+// - 第一个条件为 true → 返回 '未成年用户不能注册'
+// - 第二个条件为 true → 返回 '账户已被封禁'
+// - 所有条件为 false → 验证成功
+```
+
+**逻辑**: `(condition1 OR condition2)` - 任一条件为 true 就失败
+
+**注意**: 
+- 如果有 `.or()` 条件，不会启用链式检查模式
+- 使用传统 AND/OR 组合逻辑
 
 ---
 
@@ -242,14 +447,16 @@ dsl.if((data) => data.userType === 'admin')
 
 设置错误消息（支持多语言 key）。
 
+> **v1.1.1+** 支持为 `.and()` 和 `.or()` 条件设置独立消息
+
 **参数**:
 - `msg` {string} - 错误消息或多语言 key
 
 **返回**: `this` - 支持链式调用
 
-**行为**: 不满足条件时自动抛出此错误（无需 `.throwError()`）
+**行为**: 条件为 true 时自动抛出此错误（无需 `.throwError()`）
 
-**示例**:
+**基础示例**:
 ```javascript
 dsl.if((data) => data.age >= 18)
   .message('未成年用户不能注册')
@@ -259,6 +466,45 @@ dsl.if((data) => data.age >= 18)
   .message('error.underage')
 ```
 
+**v1.1.1+ 为 .and() 设置独立消息**:
+```javascript
+// ✅ 每个条件都有自己的错误消息
+dsl.if((data) => !data)
+  .message('账户不存在')
+  .and((data) => data.balance < 100)
+  .message('余额不足')
+  .assert(account);
+```
+
+**v1.1.1+ 为 .or() 设置独立消息**:
+```javascript
+// ✅ OR 条件也支持独立消息
+dsl.if(d => d.age < 18)
+  .message('未成年')
+  .or(d => d.isBlocked)
+  .message('已封禁')
+  .assert(data);
+```
+
+**链式检查模式说明** (v1.1.1+):
+
+当满足以下条件时，自动启用链式检查模式：
+1. 使用 `.message()` 模式（不是 `.then()`/`.else()`）
+2. root 条件有 `.message()`
+3. 有 `.and()` 条件
+4. 没有 `.or()` 条件
+
+```javascript
+// ✅ 启用链式检查（纯 AND 场景）
+dsl.if(d => !d).message('A').and(d => d < 100).message('B')
+
+// ❌ 不启用（有 .or()）
+dsl.if(d => !d).message('A').and(d => d < 100).or(d => d > 200).message('B')
+
+// ❌ 不启用（使用 .then()/.else()）
+dsl.if(d => d.age >= 18).and(d => d.role === 'admin').then('email!')
+```
+
 ---
 
 ### .then(schema)
@@ -1011,7 +1257,7 @@ validate(contactSchema, '13800138000');       // ✅ 作为手机号验证
 
 ## 更新日志
 
-### v1.1.0 (2026-01-05)
+### v1.1.1 (2026-01-05)
 
 - ✅ 新增 `ConditionalBuilder` 类
 - ✅ 新增 `dsl.if()` 链式条件 API

package/examples/i18n-error.examples.js

@@ -0,0 +1,181 @@
+/**
+ * I18nError 使用示例
+ *
+ * 统一的多语言错误抛出机制
+ *
+ * @version 1.1.1
+ */
+
+const { I18nError, dsl, Locale } = require('../index');
+
+console.log('=== I18nError 使用示例 ===\n');
+
+// ========== 1. 基础用法 ==========
+console.log('1. 基础用法：');
+try {
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  console.log('错误:', error.message); // "账户不存在"
+  console.log('代码:', error.code); // "account.notFound"
+}
+
+// ========== 2. 带参数的错误 ==========
+console.log('\n2. 带参数的错误：');
+try {
+  throw I18nError.create('account.insufficientBalance', {
+    balance: 50,
+    required: 100
+  });
+} catch (error) {
+  console.log('错误:', error.message); // "余额不足，当前余额50，需要100"
+}
+
+// ========== 3. 使用 throw 方法 ==========
+console.log('\n3. 使用 throw 方法（直接抛错）：');
+try {
+  I18nError.throw('user.noPermission');
+} catch (error) {
+  console.log('错误:', error.message); // "没有管理员权限"
+}
+
+// ========== 4. 使用 assert 断言 ==========
+console.log('\n4. 使用 assert 断言：');
+const account = { balance: 50 };
+
+try {
+  I18nError.assert(account.balance >= 100, 'account.insufficientBalance', {
+    balance: account.balance,
+    required: 100
+  });
+} catch (error) {
+  console.log('错误:', error.message);
+}
+
+// ========== 5. dsl.error 快捷方法 ==========
+console.log('\n5. dsl.error 快捷方法：');
+try {
+  dsl.error.throw('order.notPaid');
+} catch (error) {
+  console.log('错误:', error.message); // "订单未支付"
+}
+
+// ========== 6. 多语言支持 ==========
+console.log('\n6. 多语言支持：');
+try {
+  // 中文
+  Locale.setLocale('zh-CN');
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  console.log('中文:', error.message); // "账户不存在"
+}
+
+try {
+  // 英文
+  Locale.setLocale('en-US');
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  console.log('英文:', error.message); // "Account not found"
+}
+
+// 恢复中文
+Locale.setLocale('zh-CN');
+
+// ========== 7. 实际业务场景 =========
+console.log('\n7. 实际业务场景：');
+
+// 场景1：账户验证函数
+function getAccount(id) {
+  const account = id === '123' ? { id: '123', balance: 50, status: 'active' } : null;
+
+  // 断言账户存在
+  I18nError.assert(account, 'account.notFound');
+
+  // 断言账户状态
+  I18nError.assert(account.status === 'active', 'account.inactive');
+
+  // 断言余额充足
+  I18nError.assert(
+    account.balance >= 100,
+    'account.insufficientBalance',
+    { balance: account.balance, required: 100 }
+  );
+
+  return account;
+}
+
+try {
+  getAccount('123');
+} catch (error) {
+  console.log('业务错误:', error.message);
+  console.log('错误代码:', error.code);
+}
+
+// 场景2：与 dsl.if 结合
+console.log('\n8. 与 dsl.if 结合使用：');
+function validateUser(user) {
+  // 使用 dsl.if 进行数据验证
+  dsl.if(d => !d)
+    .message('user.notFound')
+    .and(d => !d.isVerified)
+    .message('user.notVerified')
+    .assert(user);
+
+  // 使用 I18nError 进行业务逻辑验证
+  I18nError.assert(user.role === 'admin', 'user.noPermission');
+}
+
+try {
+  validateUser({ isVerified: true, role: 'user' });
+} catch (error) {
+  console.log('验证错误:', error.message);
+}
+
+// ========== 9. Express/Koa 中间件 ==========
+console.log('\n9. Express/Koa 错误处理：');
+
+// Express 错误处理中间件
+function expressErrorHandler(error, req, res, next) {
+  if (error instanceof I18nError) {
+    return res.status(error.statusCode).json(error.toJSON());
+  }
+  next(error);
+}
+
+// 模拟使用
+const mockError = I18nError.create('account.notFound', {}, 404);
+const mockRes = {
+  status: (code) => {
+    console.log('HTTP Status:', code);
+    return mockRes;
+  },
+  json: (data) => {
+    console.log('Response:', JSON.stringify(data, null, 2));
+    return mockRes;
+  }
+};
+
+expressErrorHandler(mockError, {}, mockRes, () => {});
+
+// ========== 10. 自定义状态码 ==========
+console.log('\n10. 自定义状态码：');
+try {
+  throw I18nError.create('user.notFound', {}, 404);
+} catch (error) {
+  console.log('状态码:', error.statusCode); // 404
+  console.log('错误:', error.message);
+}
+
+// ========== 11. 错误检查 ==========
+console.log('\n11. 错误类型检查：');
+try {
+  throw I18nError.create('account.notFound');
+} catch (error) {
+  if (error instanceof I18nError) {
+    console.log('是 I18nError:', true);
+    console.log('是账户不存在:', error.is('account.notFound'));
+    console.log('是用户不存在:', error.is('user.notFound'));
+  }
+}
+
+console.log('\n=== 示例完成 ===');
+