schema-dsl 1.1.2 → 1.1.4

package/changelogs/v1.1.0.md

@@ -0,0 +1,389 @@
+# v1.1.0 变更日志
+
+> **发布日期**: 2026-01-05  
+> **版本号**: v1.1.0  
+> **类型**: 🎉 重大功能发布
+
+---
+
+## 📋 变更概览
+
+| 类型 | 数量 | 说明 |
+|------|------|------|
+| 🎉 新功能 | 2 | 跨类型联合验证、运行时多语言支持 |
+| ⚡ 功能增强 | 1 | 插件系统增强 |
+| 📚 文档更新 | 3 | 新增联合类型、运行时多语言、插件文档 |
+
+---
+
+## 🎉 新功能
+
+### 1. 跨类型联合验证 (Union Types)
+
+**一行代码支持多种类型，告别繁琐的类型判断**
+
+#### 基础用法
+
+```javascript
+const { dsl, validate } = require('schema-dsl');
+
+// 字段可以是字符串或数字
+const schema = dsl({
+  value: 'types:string|number'
+});
+
+validate(schema, { value: 'hello' });  // ✅ 通过
+validate(schema, { value: 123 });      // ✅ 通过
+validate(schema, { value: true });     // ❌ 失败
+```
+
+#### 带约束的联合类型
+
+```javascript
+// 邮箱或手机号
+const schema1 = dsl({
+  contact: 'types:email|phone!'
+});
+
+// 数字价格或"面议"字符串
+const schema2 = dsl({
+  price: 'types:number:0-|string:1-20'
+});
+
+// 枚举或空值
+const schema3 = dsl({
+  status: 'types:active|inactive|null'
+});
+```
+
+#### 实际应用场景
+
+**场景1：用户注册 - 支持邮箱或手机号**
+```javascript
+const registerSchema = dsl({
+  username: 'string:3-20!',
+  contact: 'types:email|phone!',  // 灵活的联系方式
+  password: 'string:8-32!',
+  age: 'types:integer:1-150|null' // 年龄可选
+});
+
+// ✅ 使用邮箱注册
+validate(registerSchema, {
+  username: 'john',
+  contact: 'john@example.com',
+  password: '12345678',
+  age: 25
+});
+
+// ✅ 使用手机号注册
+validate(registerSchema, {
+  username: 'jane',
+  contact: '13800138000',
+  password: 'abcd1234',
+  age: null
+});
+```
+
+**场景2：商品价格 - 数字或"面议"**
+```javascript
+const productSchema = dsl({
+  name: 'string:1-100!',
+  price: 'types:number:0-|string:1-20',  // 价格或"面议"
+  stock: 'integer:0-'
+});
+
+// ✅ 数字价格
+validate(productSchema, {
+  name: '商品A',
+  price: 99.99,
+  stock: 100
+});
+
+// ✅ "面议"价格
+validate(productSchema, {
+  name: '商品B',
+  price: '面议',
+  stock: 0
+});
+```
+
+**场景3：API参数 - 单个ID或ID数组**
+```javascript
+const querySchema = dsl({
+  id: 'types:string|array<string>'  // 单个或多个ID
+});
+
+// ✅ 单个ID
+validate(querySchema, { id: '123' });
+
+// ✅ ID数组
+validate(querySchema, { id: ['123', '456', '789'] });
+```
+
+#### 技术实现
+
+- ✅ 支持基础类型联合：`string|number|boolean`
+- ✅ 支持格式类型联合：`email|phone|url`
+- ✅ 支持带约束的联合：`number:0-100|string:1-20`
+- ✅ 支持null值：`string|null`
+- ✅ 支持数组类型：`string|array<string>`
+
+---
+
+### 2. 运行时多语言支持
+
+**无需修改全局设置，每次调用时指定语言**
+
+#### 核心API
+
+**dsl.error.create()** - 创建多语言错误
+```javascript
+dsl.error.create(
+  code: string,          // 错误代码（如 'account.notFound'）
+  params?: object,       // 参数插值（如 { balance: 50 }）
+  statusCode?: number,   // HTTP 状态码（默认 400）
+  locale?: string        // 🆕 运行时语言（如 'en-US'）
+): I18nError
+```
+
+**dsl.error.throw()** - 抛出多语言错误
+```javascript
+dsl.error.throw(
+  code: string,
+  params?: object,
+  statusCode?: number,
+  locale?: string        // 🆕 运行时语言
+): never
+```
+
+**dsl.error.assert()** - 断言多语言错误
+```javascript
+dsl.error.assert(
+  condition: any,
+  code: string,
+  params?: object,
+  statusCode?: number,
+  locale?: string        // 🆕 运行时语言
+): void
+```
+
+#### 使用示例
+
+**方式1：根据请求头动态返回不同语言**
+```javascript
+app.post('/api/account', (req, res) => {
+  const locale = req.headers['accept-language'] || 'en-US';
+  const account = getAccount(req.user.id);
+  
+  try {
+    // 运行时指定语言，不影响全局设置
+    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
+    
+    dsl.error.assert(
+      account.balance >= 100,
+      'account.insufficientBalance',
+      { balance: account.balance, required: 100 },
+      400,
+      locale
+    );
+    
+    // 验证通过，继续处理...
+    res.json({ success: true });
+  } catch (error) {
+    // 错误消息已经是请求的语言
+    res.status(error.statusCode).json(error.toJSON());
+  }
+});
+```
+
+**方式2：同一请求中使用多种语言**
+```javascript
+// 创建不同语言的错误消息
+const error1 = dsl.error.create('account.notFound', {}, 404, 'zh-CN');
+console.log(error1.message);  // "账户不存在"
+console.log(error1.locale);   // "zh-CN"
+
+const error2 = dsl.error.create('account.notFound', {}, 404, 'en-US');
+console.log(error2.message);  // "Account not found"
+console.log(error2.locale);   // "en-US"
+
+const error3 = dsl.error.create('account.notFound', {}, 404, 'ja-JP');
+console.log(error3.message);  // "アカウントが見つかりません"
+console.log(error3.locale);   // "ja-JP"
+```
+
+**方式3：微服务架构 - 错误传递保持原语言**
+```javascript
+// 服务A抛出错误（带语言信息）
+class ServiceA {
+  async getAccount(id, locale) {
+    const account = await db.findAccount(id);
+    dsl.error.assert(account, 'account.notFound', {}, 404, locale);
+    return account;
+  }
+}
+
+// 服务B接收错误（保持原语言）
+class ServiceB {
+  async processAccount(accountId, locale) {
+    try {
+      const account = await serviceA.getAccount(accountId, locale);
+      // 处理账户...
+    } catch (error) {
+      if (error instanceof I18nError) {
+        // 错误消息保持原语言
+        console.log(error.locale);   // locale 参数传入的语言
+        console.log(error.message);  // 该语言的错误消息
+        
+        // 转发给客户端
+        throw error;
+      }
+    }
+  }
+}
+```
+
+#### 适用场景
+
+- ✅ **多语言 API**: 根据请求头 `Accept-Language` 动态返回
+- ✅ **微服务架构**: 错误在服务间传递时保持原语言
+- ✅ **国际化应用**: 同一请求中需要多种语言的错误消息
+- ✅ **A/B测试**: 不同用户组使用不同语言
+
+#### 与全局语言设置的对比
+
+| 特性 | 全局设置 | 运行时指定 |
+|------|---------|-----------|
+| **使用场景** | 单一语言应用 | 多语言API |
+| **切换方式** | `Locale.setLocale()` | 每次调用指定 |
+| **影响范围** | 全局所有错误 | 仅当前错误 |
+| **线程安全** | ⚠️ 需注意并发 | ✅ 完全安全 |
+| **推荐度** | 简单应用 | **API开发** |
+
+---
+
+### 3. 插件系统增强
+
+**简化自定义类型注册流程**
+
+#### 改进前（v1.0.x）
+
+```javascript
+// 需要手动处理注册逻辑
+const customValidator = {
+  name: 'slug',
+  validate: (value) => /^[a-z0-9-]+$/.test(value)
+};
+
+// 手动添加到验证器
+validator.addCustomType('slug', customValidator);
+```
+
+#### 改进后（v1.1.0+）
+
+```javascript
+// 使用插件系统统一管理
+const slugPlugin = {
+  name: 'slug-validator',
+  version: '1.0.0',
+  install(core) {
+    core.registerType('slug', {
+      validate: (value) => /^[a-z0-9-]+$/.test(value),
+      message: 'must be a valid slug (lowercase, numbers, hyphens)'
+    });
+  }
+};
+
+// 注册插件
+pluginManager.register(slugPlugin);
+pluginManager.install(schemaCore);
+
+// 使用自定义类型
+const schema = dsl({ url: 'slug!' });
+```
+
+#### 新增功能
+
+- ✅ 插件生命周期管理（install/uninstall）
+- ✅ 插件版本控制
+- ✅ 插件依赖检查
+- ✅ 插件热重载（开发环境）
+
+---
+
+## 📚 文档更新
+
+1. ✅ **联合类型文档**: [docs/union-types.md](../docs/union-types.md)
+2. ✅ **运行时多语言文档**: [docs/runtime-locale-support.md](../docs/runtime-locale-support.md)
+3. ✅ **插件系统文档**: [docs/plugin-system.md](../docs/plugin-system.md)
+
+---
+
+## 🔄 破坏性变更
+
+**无破坏性变更** - 所有新功能都是向后兼容的。
+
+---
+
+## 🎯 升级指南
+
+### 从 v1.0.x 升级到 v1.1.0
+
+```bash
+npm install schema-dsl@1.1.0
+```
+
+**可选：启用新功能**
+
+1. **使用联合类型**（可选）
+   ```javascript
+   // 之前
+   const schema = dsl({ value: 'string' });
+   
+   // 现在（可选使用）
+   const schema = dsl({ value: 'types:string|number' });
+   ```
+
+2. **使用运行时多语言**（可选）
+   ```javascript
+   // 之前
+   I18nError.throw('account.notFound');
+   
+   // 现在（可选使用）
+   I18nError.throw('account.notFound', {}, 404, 'en-US');
+   ```
+
+---
+
+## 📦 依赖变更
+
+**无依赖变更**
+
+---
+
+## 📊 性能影响
+
+- ✅ 联合类型验证：性能损失 <5%（可接受）
+- ✅ 运行时多语言：无性能影响（仅参数传递）
+- ✅ 插件系统：初始化性能优化 10%
+
+---
+
+## 🙏 致谢
+
+感谢社区贡献者提出联合类型验证的需求和反馈。
+
+---
+
+## 🔗 相关链接
+
+- [GitHub Repository](https://github.com/vextjs/schema-dsl)
+- [npm Package](https://www.npmjs.com/package/schema-dsl)
+- [完整文档](../docs/INDEX.md)
+
+---
+
+**发布者**: schema-dsl Team  
+**发布时间**: 2026-01-05  
+**下一版本**: v1.1.1
+

package/changelogs/v1.1.1.md

@@ -0,0 +1,308 @@
+# v1.1.1 变更日志
+
+> **发布日期**: 2026-01-06  
+> **版本号**: v1.1.1  
+> **类型**: 🎉 新功能
+
+---
+
+## 📋 变更概览
+
+| 类型 | 数量 | 说明 |
+|------|------|------|
+| 🎉 新功能 | 1 | ConditionalBuilder 独立消息支持 |
+| ⚡ 功能增强 | 1 | I18nError 多语言错误抛出 |
+
+---
+
+## 🎉 新功能
+
+### ConditionalBuilder 独立消息支持
+
+**让条件验证的每个分支都有独立的错误消息**
+
+#### 问题场景
+
+在 v1.1.0 之前，条件验证只能有一个统一的错误消息：
+
+```javascript
+// ❌ v1.1.0：所有条件失败都显示同一消息
+dsl.if(d => !d)
+  .and(d => d.status !== 'active')
+  .and(d => d.balance < 100)
+  .message('验证失败')  // 无法区分具体哪个条件失败
+  .assert(account);
+```
+
+#### 解决方案
+
+v1.1.1 支持为每个条件分支设置独立的消息：
+
+```javascript
+// ✅ v1.1.1：每个条件都有清晰的错误消息
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')  // 第一个条件的消息
+  .and(d => d.status !== 'active')
+  .message('ACCOUNT_INACTIVE')   // 第二个条件的消息
+  .and(d => d.balance < 100)
+  .message('INSUFFICIENT_BALANCE')  // 第三个条件的消息
+  .assert(account);
+```
+
+#### 实际应用场景
+
+**场景1：账户验证 - 多重检查**
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+// 检查账户的多个条件
+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);
+}
+
+// 使用示例
+try {
+  validateAccount(null, 100);
+} catch (error) {
+  console.log(error.message);  // "账户不存在" (ACCOUNT_NOT_FOUND)
+}
+
+try {
+  validateAccount({ status: 'suspended', balance: 200 }, 100);
+} catch (error) {
+  console.log(error.message);  // "账户未激活" (ACCOUNT_INACTIVE)
+}
+
+try {
+  validateAccount({ status: 'active', balance: 50 }, 100);
+} catch (error) {
+  console.log(error.message);  // "余额不足" (INSUFFICIENT_BALANCE)
+}
+```
+
+**场景2：权限检查 - 分层验证**
+
+```javascript
+function checkPermission(user, resource) {
+  dsl.if(d => !d)
+    .message('USER_NOT_FOUND')
+    .and(d => d.role !== 'admin' && d.role !== 'moderator')
+    .message('INSUFFICIENT_ROLE')
+    .and(d => !d.permissions.includes(resource))
+    .message('PERMISSION_DENIED')
+    .assert(user);
+}
+```
+
+**场景3：订单验证 - 业务规则**
+
+```javascript
+function validateOrder(order) {
+  dsl.if(d => !d)
+    .message('ORDER_NOT_FOUND')
+    .and(d => d.status === 'cancelled')
+    .message('ORDER_CANCELLED')
+    .and(d => d.status === 'completed')
+    .message('ORDER_ALREADY_COMPLETED')
+    .and(d => d.payment === null)
+    .message('PAYMENT_MISSING')
+    .and(d => !d.payment.isPaid)
+    .message('ORDER_NOT_PAID')
+    .assert(order);
+}
+```
+
+#### API 增强
+
+**ConditionalBuilder.message()**
+
+```typescript
+message(
+  code: string,           // 错误代码（支持多语言）
+  params?: object         // 参数插值（可选）
+): ConditionalBuilder
+```
+
+**链式调用示例**
+
+```javascript
+dsl.if(condition1)
+  .message('ERROR_1')
+  .and(condition2)
+  .message('ERROR_2', { param: 'value' })
+  .and(condition3)
+  .message('ERROR_3')
+  .assert(data);
+```
+
+---
+
+## ⚡ 功能增强
+
+### I18nError 统一多语言错误抛出
+
+**业务代码中统一的多语言错误处理**
+
+#### 核心 API
+
+```javascript
+const { I18nError, dsl } = require('schema-dsl');
+
+// 方式1：直接抛出
+I18nError.throw('account.notFound');
+
+// 方式2：带参数插值
+I18nError.throw('account.insufficientBalance', {
+  balance: 50,
+  required: 100
+});
+
+// 方式3：断言风格（推荐）
+I18nError.assert(account, 'account.notFound');
+I18nError.assert(
+  account.balance >= 100,
+  'account.insufficientBalance',
+  { balance: account.balance, required: 100 }
+);
+
+// 方式4：快捷方法
+dsl.error.throw('user.noPermission');
+dsl.error.assert(user.role === 'admin', 'user.noPermission');
+```
+
+#### Express/Koa 集成
+
+```javascript
+// 错误处理中间件
+app.use((error, req, res, next) => {
+  if (error instanceof I18nError) {
+    return res.status(error.statusCode).json(error.toJSON());
+  }
+  next(error);
+});
+
+// 业务代码中使用
+app.post('/withdraw', (req, res) => {
+  const account = getAccount(req.user.id);
+  I18nError.assert(account, 'account.notFound');
+  I18nError.assert(
+    account.balance >= req.body.amount,
+    'account.insufficientBalance',
+    { balance: account.balance, required: req.body.amount }
+  );
+  // 验证通过，继续处理...
+});
+```
+
+#### 内置错误代码
+
+**通用错误**:
+- `error.notFound` - 资源不存在
+- `error.forbidden` - 禁止访问
+- `error.unauthorized` - 未授权
+
+**账户错误**:
+- `account.notFound` - 账户不存在
+- `account.insufficientBalance` - 余额不足
+- `account.inactive` - 账户未激活
+
+**用户错误**:
+- `user.notFound` - 用户不存在
+- `user.noPermission` - 无权限
+
+**订单错误**:
+- `order.notPaid` - 订单未支付
+- `order.paymentMissing` - 缺少支付信息
+
+---
+
+## 📚 文档更新
+
+- ✅ 新增条件验证独立消息文档
+- ✅ 新增 I18nError 使用指南
+- ✅ 更新 Express/Koa 集成示例
+- ✅ 添加内置错误代码列表
+
+---
+
+## 🔄 破坏性变更
+
+**无破坏性变更** - 所有新功能都是向后兼容的。
+
+旧的用法仍然有效：
+
+```javascript
+// ✅ 旧用法仍然有效
+dsl.if(condition)
+  .message('ERROR')  // 统一消息
+  .and(condition2)
+  .assert(data);
+```
+
+---
+
+## 🎯 升级指南
+
+### 从 v1.1.0 升级到 v1.1.1
+
+```bash
+npm install schema-dsl@1.1.1
+```
+
+**可选：使用独立消息**
+
+```javascript
+// 之前（v1.1.0）：统一消息
+dsl.if(d => !d)
+  .and(d => d.status !== 'active')
+  .message('验证失败')
+  .assert(account);
+
+// 现在（v1.1.1）：独立消息（推荐）
+dsl.if(d => !d)
+  .message('ACCOUNT_NOT_FOUND')
+  .and(d => d.status !== 'active')
+  .message('ACCOUNT_INACTIVE')
+  .assert(account);
+```
+
+**可选：使用 I18nError**
+
+```javascript
+// 之前：手动抛出错误
+if (!account) {
+  throw new Error('账户不存在');
+}
+
+// 现在：使用 I18nError（支持多语言）
+I18nError.assert(account, 'account.notFound');
+```
+
+---
+
+## 📦 依赖变更
+
+**无依赖变更**
+
+---
+
+## 🔗 相关链接
+
+- [GitHub Repository](https://github.com/vextjs/schema-dsl)
+- [npm Package](https://www.npmjs.com/package/schema-dsl)
+- [条件验证文档](../docs/conditional-api.md)
+- [I18nError 示例](../examples/i18n-error.examples.js)
+
+---
+
+**发布者**: schema-dsl Team  
+**发布时间**: 2026-01-06  
+**下一版本**: v1.1.2
+