schema-dsl 1.2.4 → 2.0.0

package/changelogs/v1.1.8.md

@@ -1,376 +0,0 @@
-# schema-dsl v1.1.8 变更日志
-
-> **发布日期**: 2026-01-30  
-> **类型**: 功能增强 🚀  
-> **重要性**: ⭐⭐⭐⭐⭐
-
----
-
-## 📋 本版本概览
-
-### 🎯 核心更新
-
-**智能参数识别 - 简化语法支持**
-
-支持简化的错误抛出语法，从4个参数减少到2个参数，使API调用更加简洁直观。
-
-```javascript
-// ✅ 新增：简化语法
-dsl.error.throw('account.notFound', 'zh-CN');
-
-// ✅ 保持：标准语法（完全兼容）
-dsl.error.throw('account.notFound', {}, 404, 'zh-CN');
-```
-
----
-
-## 🚀 新增功能
-
-### 1. 智能参数识别
-
-**问题背景**：原有API需要4个参数，即使不需要参数对象也要传空对象 `{}`
-
-```javascript
-// ❌ 原有方式：必须传递空对象
-dsl.error.throw('account.notFound', {}, 404, 'zh-CN');
-```
-
-**解决方案**：智能识别第2个参数类型，自动判断是语言参数还是参数对象
-
-```javascript
-// ✅ 简化语法：直接传语言
-dsl.error.throw('account.notFound', 'zh-CN');
-dsl.error.throw('account.notFound', 'zh-CN', 404);
-
-// ✅ 标准语法：传参数对象（完全兼容）
-dsl.error.throw('account.notFound', { id: '123' }, 404, 'zh-CN');
-```
-
-**识别规则**：
-- 第2个参数是 `string` → 识别为语言参数
-- 第2个参数是 `object` → 识别为参数对象
-- 第2个参数是 `null/undefined/数组` → 使用默认值
-
-### 2. 所有错误方法都支持
-
-```javascript
-// dsl.error.create() - 创建错误
-const error = dsl.error.create('account.notFound', 'zh-CN');
-
-// dsl.error.throw() - 抛出错误
-dsl.error.throw('account.notFound', 'zh-CN');
-
-// dsl.error.assert() - 断言式错误
-dsl.error.assert(account, 'account.notFound', 'zh-CN');
-dsl.error.assert(account, 'account.notFound', 'zh-CN', 404);
-
-// I18nError 直接调用
-I18nError.throw('account.notFound', 'zh-CN');
-I18nError.create('account.notFound', 'zh-CN');
-I18nError.assert(account, 'account.notFound', 'zh-CN');
-```
-
----
-
-## 🔧 技术实现
-
-### 新增工具函数
-
-```javascript
-/**
- * 智能参数识别工具函数
- * @private
- */
-function normalizeParams(paramsOrLocale, statusCode, locale) {
-  let params = {};
-  let actualStatusCode = 400;
-  let actualLocale = null;
-  
-  if (typeof paramsOrLocale === 'string') {
-    // 字符串 → 语言参数
-    actualLocale = paramsOrLocale;
-    actualStatusCode = typeof statusCode === 'number' ? statusCode : 400;
-  } else if (paramsOrLocale && typeof paramsOrLocale === 'object' && !Array.isArray(paramsOrLocale)) {
-    // 对象（非数组）→ 参数对象
-    params = paramsOrLocale;
-    actualStatusCode = typeof statusCode === 'number' ? statusCode : 400;
-    actualLocale = locale;
-  } else {
-    // null/undefined/数组 → 使用默认值
-    actualStatusCode = typeof statusCode === 'number' ? statusCode : 400;
-    actualLocale = locale;
-  }
-  
-  return { params, statusCode: actualStatusCode, locale: actualLocale };
-}
-```
-
-### 修改的方法
-
-- `I18nError.create()`
-- `I18nError.throw()`
-- `I18nError.assert()`
-- `dsl.error.create()`
-- `dsl.error.throw()`
-- `dsl.error.assert()`
-
----
-
-## 📖 使用示例
-
-### Express API 示例
-
-```javascript
-const { dsl, Locale } = require('schema-dsl');
-
-// 配置语言包
-Locale.addLocale('zh-CN', {
-  'account.notFound': {
-    code: 40001,
-    message: '账户不存在'
-  }
-});
-
-Locale.addLocale('en-US', {
-  'account.notFound': {
-    code: 40001,
-    message: 'Account not found'
-  }
-});
-
-// API 路由
-app.get('/api/account/:id', async (req, res) => {
-  try {
-    const account = await findAccount(req.params.id);
-    const locale = req.headers['accept-language'] || 'zh-CN';
-    
-    // 🎯 简化语法：只需2个参数
-    dsl.error.assert(account, 'account.notFound', locale);
-    
-    res.json(account);
-  } catch (error) {
-    res.status(error.statusCode).json(error.toJSON());
-  }
-});
-```
-
-### 对比示例
-
-```javascript
-// 之前：4个参数
-dsl.error.throw('account.notFound', {}, 404, 'zh-CN');
-dsl.error.assert(account, 'account.notFound', {}, 404, 'zh-CN');
-
-// 现在：2个参数（无需参数对象时）
-dsl.error.throw('account.notFound', 'zh-CN', 404);
-dsl.error.assert(account, 'account.notFound', 'zh-CN', 404);
-
-// 或者：3个参数（带参数对象）
-dsl.error.throw('account.insufficientBalance', 
-  { balance: 50, required: 100 }, 
-  'zh-CN'
-);
-```
-
----
-
-## ✅ 向后兼容性
-
-### 完全向后兼容
-
-所有原有调用方式都完全正常工作，无需修改任何现有代码。
-
-| 原有调用方式 | 兼容性 | 说明 |
-|-------------|--------|------|
-| `throw('key')` | ✅ 完全兼容 | 使用全局语言 |
-| `throw('key', {})` | ✅ 完全兼容 | 空参数对象 |
-| `throw('key', {}, 404)` | ✅ 完全兼容 | 带状态码 |
-| `throw('key', {}, 404, 'zh')` | ✅ 完全兼容 | 完整4参数 |
-| `throw('key', {params}, 404, 'zh')` | ✅ 完全兼容 | 带参数对象 |
-| `throw('key', null, 404, 'zh')` | ✅ 完全兼容 | null 参数 |
-
-### 测试验证
-
-- **17个测试用例**，全部通过
-- **零破坏性变更**
-- **100%向后兼容**
-
----
-
-## 🎨 优势
-
-### 1. 用户体验提升
-
-- **参数减少**：从4个参数减少到2个（不需要参数对象时）
-- **语法简洁**：`throw('key', 'locale')` 更直观
-- **易于理解**：参数含义更清晰
-
-### 2. 减少错误
-
-- **避免混淆**：不再需要传递空对象 `{}`
-- **类型安全**：智能识别参数类型
-- **降低学习成本**：新手更容易上手
-
-### 3. 保持兼容
-
-- **渐进式增强**：新旧语法并存
-- **零风险升级**：现有代码无需修改
-- **平滑过渡**：可以逐步迁移到简化语法
-
----
-
-## 📊 性能影响
-
-**无性能损失**
-
-- 参数识别逻辑简单（类型检查）
-- 运行时开销可忽略不计
-- 不影响错误抛出性能
-
----
-
-## 📦 修改文件清单
-
-### 核心文件
-
-1. **lib/errors/I18nError.js**
-   - 新增 `normalizeParams()` 工具函数
-   - 修改 `create()` 方法
-   - 修改 `throw()` 方法
-   - 修改 `assert()` 方法
-
-2. **index.js**
-   - 更新 `dsl.error` 的 JSDoc 文档
-
-### 文档文件
-
-3. **README.md**
-   - 添加简化语法示例
-
-4. **CHANGELOG.md**
-   - 添加 v1.1.8 版本信息
-
-5. **changelogs/v1.1.8.md**
-   - 详细变更文档（本文件）
-
-6. **docs/error-handling.md**
-   - 更新错误处理指南
-
-7. **docs/runtime-locale-support.md**
-   - 更新运行时语言文档
-
----
-
-## 🔗 相关文档
-
-- [错误处理完整指南](../docs/error-handling.md)
-- [运行时多语言支持](../docs/runtime-locale-support.md)
-- [API 参考文档](../docs/api-reference.md)
-- [实现原理分析](../docs/i18n-implementation-analysis.md)
-- [兼容性分析](../docs/api-compatibility-analysis.md)
-
----
-
-## 📝 升级指南
-
-### 如何升级
-
-```bash
-npm install schema-dsl@1.1.8
-# 或
-yarn add schema-dsl@1.1.8
-```
-
-### 是否需要修改代码？
-
-**不需要！** 本版本完全向后兼容，现有代码无需任何修改。
-
-### 推荐的迁移方式
-
-可以逐步将代码迁移到简化语法：
-
-```javascript
-// 旧代码（继续有效）
-dsl.error.throw('account.notFound', {}, 404, 'zh-CN');
-
-// 新代码（推荐）
-dsl.error.throw('account.notFound', 'zh-CN', 404);
-```
-
----
-
-## 🧪 测试覆盖
-
-### 测试用例
-
-创建了完整的测试套件 `test-smart-params.js`，包含17个测试用例：
-
-1. ✅ 简化语法 - 中文
-2. ✅ 简化语法 - 英文 + 404
-3. ✅ 标准语法 - 4参数
-4. ✅ 标准语法 - 带参数对象
-5. ✅ 省略所有参数 - 使用全局语言
-6. ✅ create() 方法 - 简化语法
-7. ✅ create() 方法 - 带状态码
-8. ✅ assert() 方法 - 简化语法
-9. ✅ assert() 方法 - 不应该抛错
-10. ✅ assert() 方法 - 带状态码
-11. ✅ assert() 方法 - 带参数对象
-12. ✅ 边缘情况 - null 参数
-13. ✅ 边缘情况 - undefined 参数
-14. ✅ 边缘情况 - 数组参数
-15. ✅ I18nError.throw() 直接调用
-16. ✅ I18nError.create() 直接调用
-17. ✅ I18nError.assert() 直接调用
-
-### 测试结果
-
-```
-📊 测试结果总结:
-✅ 通过: 17 个测试
-❌ 失败: 0 个测试
-📈 通过率: 100.0%
-
-🎉 所有测试都通过了！智能参数识别功能完全正常！
-```
-
----
-
-## 🐛 已知问题
-
-无已知问题。
-
----
-
-## 🎯 下一步计划
-
-- 更新所有文档示例
-- 添加更多使用场景
-- 完善 TypeScript 类型定义
-
----
-
-## 👥 贡献者
-
-感谢以下贡献者对本版本的贡献：
-
-- AI Assistant - 功能设计与实现
-
----
-
-## 📢 致谢
-
-感谢社区用户的反馈和建议，帮助我们不断改进 API 设计！
-
----
-
-**发布日期**: 2026-01-30  
-**版本**: v1.1.8  
-**上一版本**: v1.1.7 (错误消息路径显示优化)  
-**下一版本预告**: 计划改进文档和示例代码
-
----
-
-**完整变更日志**: [CHANGELOG.md](../CHANGELOG.md)  
-**GitHub**: [https://github.com/vextjs/schema-dsl](https://github.com/vextjs/schema-dsl)  
-**npm**: [https://www.npmjs.com/package/schema-dsl](https://www.npmjs.com/package/schema-dsl)

package/changelogs/v1.2.3.md

@@ -1,124 +0,0 @@
-# schema-dsl v1.2.3 变更日志
-
-> **发布日期**: 2026-03-03  
-> **类型**: 功能增强 🚀 + Bug修复 🐛  
-> **重要性**: ⭐⭐⭐⭐⭐
-
----
-
-## 📋 本版本概览
-
-### 🎯 核心更新
-
-**1. i18n 多语言子目录合并支持（新功能）**
-
-多人协作开发时，支持将多语言文件按模块拆分到子目录，启动时自动递归合并，解决 code 码冲突和 Git merge 冲突问题。
-
-**2. 三个测试状态污染 Bug 修复**
-
-修复全量测试时因跨文件 `Locale` 状态污染导致的 3 个 failing，1003 个测试全部通过。
-
----
-
-## ✨ 新功能：i18n 子目录合并
-
-### F1：递归子目录扫描
-
-`dsl.config({ i18n: path })` 现在支持递归扫描子目录，每个子目录作为模块组织层，同语言文件自动合并：
-
-```javascript
-// 目录结构
-locales/
-├── core/zh-CN.js       // 公共 code: 1000-1999
-├── account/zh-CN.js    // 账户模块 code: 10000-10999（开发者A）
-├── order/zh-CN.js      // 订单模块 code: 20000-20999（开发者B）
-└── payment/zh-CN.js    // 支付模块 code: 30000-30999（开发者C）
-
-// 一行配置，自动递归合并
-dsl.config({
-  i18n: path.join(__dirname, 'locales')
-});
-```
-
-### F2：同名 key 冲突检测
-
-默认模式打印 WARN，`strict: true` 直接抛错阻断启动（推荐 CI 环境）：
-
-```javascript
-// 默认：WARN 日志
-dsl.config({ i18n: './locales' });
-// [schema-dsl] i18n key 冲突 in locale 'zh-CN'
-//   冲突 key: account.notFound
-//   来源文件: /project/locales/account/zh-CN.js
-
-// 严格模式：抛出 Error
-dsl.config({ i18n: './locales', strict: true });
-```
-
-### F3：语言文件名格式校验
-
-只加载符合语言代码格式（`zh-CN.js`、`en.js` 等）的文件，自动跳过 `index.js`、`utils.js`、`CODE-SEGMENTS.js` 等工具文件。
-
-### 兼容修复：`localesPath` 对象用法真正生效
-
-文档中记载的 `{ localesPath: './path' }` 对象用法之前静默失败，现在已修复：
-
-```javascript
-// 之前：静默失败（localesPath 被当成语言 key 处理）
-// 现在：真正生效
-dsl.config({
-  i18n: { localesPath: path.join(__dirname, 'locales') }
-});
-```
-
----
-
-## 🐛 Bug 修复：测试状态污染
-
-### 问题根因
-
-`test/unit/i18n-subdir.test.js` 使用了根级别的 `beforeEach(() => Locale.reset())`，导致全量测试时清除了其他测试文件 `before()` 中注册的自定义语言 key，造成以下 3 个测试 failing：
-
-| 测试文件 | 失败原因 |
-|---------|---------|
-| `test/unit/core/custom-features.test.js` | `min` key 被 reset 后走内置消息而非自定义 `太短` |
-| `test/unit/error-message-interpolation.test.js` | `zh-CN` enum 消息在 reset 后丢失 |
-| `test/unit/label-translation.test.js` | `label.test_field` key 被 reset 清除 |
-
-### 修复方案
-
-将 `i18n-subdir.test.js` 的所有测试包裹在顶级 `describe('i18n 子目录合并')` 内，将 `beforeEach(Locale.reset)` 改为 `describe` 作用域内的 `afterEach(Locale.reset)`，确保状态清理严格限制在本文件的测试范围内，不泄漏到其他文件。
-
----
-
-## 📊 测试统计
-
-| 指标 | v1.2.2 | v1.2.3 | 变化 |
-|------|--------|--------|------|
-| 通过 | 989 | **1003** | +14 |
-| 失败 | 14 | **0** | -14 ✅ |
-| 新增测试 | — | 20 (i18n-subdir) | +20 |
-
----
-
-## 📁 变更文件
-
-| 文件 | 操作 | 说明 |
-|------|------|------|
-| `index.js` | 修改 | 新增 `loadLocalesFromDir` 内部函数，支持递归扫描 + 冲突检测 |
-| `index.d.ts` | 修改 | `I18nConfig` 类型扩展 + `strict?: boolean` 选项 |
-| `test/unit/i18n-subdir.test.js` | 新增 | 20 个单元测试（F1/F2/F3 + 向后兼容回归）|
-| `docs/add-custom-locale.md` | 修改 | 新增子目录多人协作章节 + Code 段划分建议 |
-
----
-
-## 🔄 向后兼容性
-
-✅ **100% 向后兼容**，现有所有用法零改动：
-
-| 现有用法 | 兼容性 |
-|---------|--------|
-| `i18n: '/path'`（平铺目录）| ✅ 完全兼容（行为超集）|
-| `i18n: { 'zh-CN': {...} }` | ✅ 完全兼容 |
-| `strict` 未传 | ✅ 默认 false，现有行为零变化 |
-