schema-dsl 1.1.2 → 1.1.4

package/changelogs/v1.0.9.md

@@ -0,0 +1,367 @@
+# v1.0.9 变更日志
+
+> **发布日期**: 2026-01-04  
+> **版本号**: v1.0.9  
+> **类型**: 🎉 重大改进
+
+---
+
+## 📋 变更概览
+
+| 类型 | 数量 | 说明 |
+|------|------|------|
+| 🎉 新功能 | 2 | 完整多语言支持、I18nError类 |
+| ⚡ 功能增强 | 1 | TypeScript类型定义完善 |
+| 📚 文档更新 | 5 | 多语言相关文档 |
+
+---
+
+## 🎉 新功能
+
+### 1. 完整的多语言支持
+
+**内置5种语言，开箱即用的国际化方案**
+
+#### 支持的语言
+
+| 语言代码 | 语言名称 | 完整度 | 说明 |
+|---------|---------|--------|------|
+| zh-CN | 简体中文 | 100% | 默认语言 |
+| en-US | 英文（美国） | 100% | 完整翻译 |
+| ja-JP | 日语 | 95% | 主要功能已翻译 |
+| es-ES | 西班牙语 | 90% | 核心功能已翻译 |
+| fr-FR | 法语 | 90% | 核心功能已翻译 |
+
+#### 快速配置
+
+**方式1：使用内置语言**
+
+```javascript
+const { dsl, validate, Locale } = require('schema-dsl');
+
+// 设置全局语言
+Locale.setLocale('zh-CN');
+
+const schema = dsl({ username: 'string:3-32!' });
+
+// 中文错误消息
+const result = validate(schema, { username: 'ab' });
+console.log(result.errors[0].message);
+// => "username长度不能少于3个字符"
+```
+
+**方式2：配置自定义语言包目录**
+
+```javascript
+const path = require('path');
+
+// 应用启动时配置一次
+dsl.config({
+  i18n: path.join(__dirname, 'locales')
+});
+
+// 自动加载目录下所有语言文件
+// locales/zh-CN.js
+// locales/en-US.js
+// locales/custom-lang.js
+```
+
+#### 自定义语言包
+
+```javascript
+// locales/zh-CN.js
+module.exports = {
+  'required': '{{#path}} 是必填项',
+  'string.min': '{{#path}} 长度不能少于 {{#min}} 个字符',
+  'string.max': '{{#path}} 长度不能超过 {{#max}} 个字符',
+  'email': '{{#path}} 必须是有效的邮箱地址',
+  'account.notFound': '账户不存在',
+  'account.insufficientBalance': '余额不足，当前余额{{balance}}，需要{{required}}'
+};
+
+// locales/en-US.js
+module.exports = {
+  'required': '{{#path}} is required',
+  'string.min': '{{#path}} must be at least {{#min}} characters',
+  'string.max': '{{#path}} must not exceed {{#max}} characters',
+  'email': '{{#path}} must be a valid email',
+  'account.notFound': 'Account not found',
+  'account.insufficientBalance': 'Insufficient balance, current: {{balance}}, required: {{required}}'
+};
+```
+
+#### 运行时切换语言
+
+```javascript
+// 全局切换
+Locale.setLocale('en-US');
+
+// 验证时指定语言
+validate(schema, data, { locale: 'ja-JP' });
+
+// 获取当前语言
+const currentLocale = Locale.getLocale();  // 'en-US'
+```
+
+#### 参数插值
+
+```javascript
+// 自动插值
+const schema = dsl({ age: 'number:18-120!' });
+validate(schema, { age: 15 });
+// => "age must be at least 18" (en-US)
+// => "age 必须至少为 18" (zh-CN)
+
+// 自定义参数插值
+const error = new I18nError('account.insufficientBalance', {
+  balance: 50,
+  required: 100
+});
+console.log(error.message);
+// => "余额不足，当前余额50，需要100" (zh-CN)
+// => "Insufficient balance, current: 50, required: 100" (en-US)
+```
+
+---
+
+### 2. I18nError 多语言错误类
+
+**统一的多语言错误处理类**
+
+#### 基础用法
+
+```javascript
+const { I18nError } = require('schema-dsl');
+
+// 创建错误
+const error = new I18nError(
+  'account.notFound',  // 错误代码
+  {},                  // 参数（可选）
+  404                  // HTTP状态码（可选）
+);
+
+console.log(error.code);        // 'account.notFound'
+console.log(error.message);     // '账户不存在' (zh-CN)
+console.log(error.statusCode);  // 404
+```
+
+#### 静态方法
+
+```javascript
+// 直接抛出错误
+I18nError.throw('user.noPermission');
+
+// 断言风格
+I18nError.assert(user, 'user.notFound');
+I18nError.assert(
+  user.role === 'admin',
+  'user.noPermission'
+);
+
+// 创建错误对象
+const error = I18nError.create('account.notFound', {}, 404);
+```
+
+#### 错误对象属性
+
+```javascript
+const error = new I18nError('account.insufficientBalance', {
+  balance: 50,
+  required: 100
+}, 400);
+
+console.log(error.code);        // 'account.insufficientBalance'
+console.log(error.message);     // '余额不足，当前余额50，需要100'
+console.log(error.statusCode);  // 400
+console.log(error.params);      // { balance: 50, required: 100 }
+
+// JSON序列化
+console.log(error.toJSON());
+// {
+//   code: 'account.insufficientBalance',
+//   message: '余额不足，当前余额50，需要100',
+//   statusCode: 400,
+//   params: { balance: 50, required: 100 }
+// }
+```
+
+#### Express/Koa 集成
+
+```javascript
+// Express 错误处理中间件
+app.use((error, req, res, next) => {
+  if (error instanceof I18nError) {
+    return res.status(error.statusCode).json({
+      success: false,
+      code: error.code,
+      message: error.message,
+      params: error.params
+    });
+  }
+  next(error);
+});
+
+// 业务代码
+app.post('/api/withdraw', async (req, res, next) => {
+  try {
+    const account = await getAccount(req.user.id);
+    I18nError.assert(account, 'account.notFound', {}, 404);
+    
+    I18nError.assert(
+      account.balance >= req.body.amount,
+      'account.insufficientBalance',
+      { balance: account.balance, required: req.body.amount },
+      400
+    );
+    
+    // 处理提现...
+    res.json({ success: true });
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+---
+
+## ⚡ 功能增强
+
+### TypeScript 类型定义完善
+
+**完整的类型定义，100% 类型安全**
+
+#### 新增类型
+
+```typescript
+// Locale 类型
+interface Locale {
+  setLocale(locale: string): void;
+  getLocale(): string;
+  getMessage(code: string, params?: Record<string, any>): string;
+  setMessages(messages: Record<string, string>): void;
+}
+
+// I18nError 类型
+class I18nError extends Error {
+  code: string;
+  statusCode: number;
+  params: Record<string, any>;
+  
+  constructor(
+    code: string,
+    params?: Record<string, any>,
+    statusCode?: number
+  );
+  
+  static throw(code: string, params?: Record<string, any>, statusCode?: number): never;
+  static assert(condition: any, code: string, params?: Record<string, any>, statusCode?: number): asserts condition;
+  static create(code: string, params?: Record<string, any>, statusCode?: number): I18nError;
+  
+  toJSON(): object;
+  is(code: string): boolean;
+}
+
+// ValidationOptions 扩展
+interface ValidationOptions {
+  locale?: string;  // 新增：验证时指定语言
+  // ...其他选项
+}
+```
+
+#### 使用示例
+
+```typescript
+import { dsl, validate, I18nError, Locale } from 'schema-dsl';
+
+// 完整的类型推导
+const schema = dsl({ email: 'email!' });
+
+// 验证时指定语言
+const result = validate(schema, data, { locale: 'en-US' });
+
+// I18nError 类型安全
+try {
+  I18nError.throw('account.notFound', {}, 404);
+} catch (error) {
+  if (error instanceof I18nError) {
+    console.log(error.code);        // string
+    console.log(error.statusCode);  // number
+    console.log(error.params);      // Record<string, any>
+  }
+}
+```
+
+---
+
+## 📚 文档更新
+
+1. ✅ **多语言用户指南**: [docs/i18n-user-guide.md](../docs/i18n-user-guide.md)
+2. ✅ **I18n 完整文档**: [docs/i18n.md](../docs/i18n.md)
+3. ✅ **I18nError API 文档**: [docs/error-handling.md](../docs/error-handling.md)
+4. ✅ **自定义语言包指南**: [docs/add-custom-locale.md](../docs/add-custom-locale.md)
+5. ✅ **前端 i18n 集成**: [docs/frontend-i18n-guide.md](../docs/frontend-i18n-guide.md)
+
+---
+
+## 🔄 破坏性变更
+
+**无破坏性变更** - 所有新功能都是可选的，默认行为保持不变。
+
+---
+
+## 🎯 升级指南
+
+### 从 v1.0.8 升级到 v1.0.9
+
+```bash
+npm install schema-dsl@1.0.9
+```
+
+**可选：启用多语言**
+
+```javascript
+const { Locale } = require('schema-dsl');
+
+// 设置全局语言（可选）
+Locale.setLocale('zh-CN');
+
+// 或在验证时指定（可选）
+validate(schema, data, { locale: 'en-US' });
+```
+
+**可选：使用 I18nError**
+
+```javascript
+const { I18nError } = require('schema-dsl');
+
+// 替代普通 Error
+I18nError.throw('account.notFound');
+```
+
+---
+
+## 📦 依赖变更
+
+**无依赖变更**
+
+---
+
+## 🙏 致谢
+
+感谢社区贡献者提供的多语言翻译和反馈。
+
+---
+
+## 🔗 相关链接
+
+- [GitHub Repository](https://github.com/vextjs/schema-dsl)
+- [npm Package](https://www.npmjs.com/package/schema-dsl)
+- [完整多语言文档](../docs/i18n.md)
+- [I18nError 示例](../examples/i18n-error.examples.js)
+
+---
+
+**发布者**: schema-dsl Team  
+**发布时间**: 2026-01-04  
+**下一版本**: v1.1.0
+