schema-dsl 1.1.5 → 1.1.7

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-01-17
+> **最后更新**: 2026-01-27
 
 ---
 
@@ -9,6 +9,8 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [v1.1.7](./changelogs/v1.1.7.md) | 2026-01-27 | 🐛 Bug修复：错误消息路径显示优化 - 所有错误类型的 message 只显示字段名 | [查看](./changelogs/v1.1.7.md) |
+| [v1.1.6](./changelogs/v1.1.6.md) | 2026-01-23 | 🐛 Bug修复：enum和additionalProperties错误消息模板变量未替换 | [查看](./changelogs/v1.1.6.md) |
 | [v1.1.5](./changelogs/v1.1.5.md) | 2026-01-17 | 🚀 新功能：错误配置对象格式支持 - 语言包支持 `{ code, message }` 对象格式 | [查看](./changelogs/v1.1.5.md) |
 | [v1.1.4](./changelogs/v1.1.4.md) | 2026-01-13 | 🔧 TypeScript类型修复：移除重复函数签名 + 多语言文档完善 | [查看](./changelogs/v1.1.4.md) |
 | [v1.1.3](./changelogs/v1.1.3.md) | 2026-01-09 | 🐛 Bug修复：类型错误消息模板变量未替换 | [查看](./changelogs/v1.1.3.md) |
@@ -27,7 +29,7 @@
 | [v1.0.0](./changelogs/v1.0.0.md) | 2025-12-29 | 初始发布版本 | [查看](./changelogs/v1.0.0.md) |
 
 > 💡 **提示**: 重要版本的详细变更记录在 [changelogs/](./changelogs/) 目录中。  
-> 当前已有详细文档的版本：v1.1.5, v1.1.4, v1.1.3, v1.1.2, v1.1.1, v1.1.0, v1.0.9, v1.0.0  
+> 当前已有详细文档的版本：v1.1.7, v1.1.6, v1.1.5, v1.1.4, v1.1.3, v1.1.2, v1.1.1, v1.1.0, v1.0.9, v1.0.0  
 > 其他版本的详细变更信息请参考项目提交历史或联系维护者。
 
 ---
@@ -36,13 +38,42 @@
 
 | 版本系列 | 版本数 | 主要改进方向 |
 |---------|-------|------------|
-| v1.1.x | 6 | 错误配置增强、TypeScript类型完善、多语言支持、数字运算符、联合类型 |
+| v1.1.x | 8 | Bug修复、错误消息优化、错误配置增强、TypeScript类型完善、多语言支持、数字运算符、联合类型 |
 | v1.0.x | 10 | 核心功能、验证器、测试覆盖、文档完善 |
 
 ---
 
 ## 里程碑版本
 
+### v1.1.7 - 错误消息路径显示优化 🐛
+
+**发布日期**: 2026-01-27  
+**重要性**: ⭐⭐⭐⭐
+
+**主要改进**:
+- 🐛 修复嵌套对象错误消息显示完整路径的问题（如 `user/profile/age should be number` → `age should be number`）
+- ✅ 统一所有错误类型的 label 生成逻辑，message 只显示字段名而非完整路径
+- ✅ path 保留完整路径用于定位（符合 JSON Pointer RFC 6901 标准）
+- ✅ 修复范围：required、type、minLength、maxLength、pattern、format、enum、minimum、maximum、minItems、maxItems、additionalProperties 等所有错误类型
+- ✅ 新增 6 个测试用例，测试总数 983 个
+
+**技术细节**:
+- 修改文件：`lib/core/ErrorFormatter.js`
+- 从完整路径中提取最后一级字段名作为 label
+- 遵循 JSON Pointer (RFC 6901) 标准使用 `/` 作为路径分隔符
+- 测试修复：添加 `beforeEach` 钩子重置语言为英文，避免测试污染
+
+### v1.1.6 - ErrorFormatter Bug修复 🐛
+
+**发布日期**: 2026-01-23  
+**重要性**: ⭐⭐⭐⭐
+
+**主要改进**:
+- 🐛 修复 enum 错误消息模板变量 `{{#valids}}` 未替换问题
+- 🐛 修复 additionalProperties 错误消息缺少属性名问题
+- ✅ 新增完整的错误消息插值测试（14个测试用例）
+- ✅ 确保所有 ajv 错误参数正确映射到模板变量
+
 ### v1.1.5 - 错误配置对象格式支持 🚀
 
 **发布日期**: 2026-01-17  

package/changelogs/v1.1.6.md

@@ -0,0 +1,211 @@
+# v1.1.6 - Bug修复与测试增强
+
+**发布日期**: 2026-01-23
+
+## 🐛 Bug 修复
+
+### ErrorFormatter - 参数映射完整性修复
+
+修复了 `ErrorFormatter` 中 ajv 错误参数映射不完整的问题，**支持所有5种内置语言**（en-US, zh-CN, es-ES, fr-FR, ja-JP），确保所有模板变量都能正确替换。
+
+#### 1. **修复 enum 错误消息中的模板变量未替换问题** 🔴
+
+**问题描述**:
+- 当 enum 验证失败时，错误消息显示 `"must be one of: {{#valids}}"` 
+- 模板变量 `{{#valids}}` 没有被实际的枚举值替换
+
+**根本原因**:
+- ajv 返回的 enum 错误参数字段名是 `allowedValues`
+- 错误消息模板使用的是 `{{#valids}}` 和 `{{#allowed}}`
+- ErrorFormatter 没有将 `allowedValues` 映射到这两个变量
+
+**修复方案**:
+```javascript
+// lib/core/ErrorFormatter.js
+const interpolateData = {
+  ...err.params,
+  // ... 其他映射
+  // ✅ 修复 enum 错误：将 allowedValues 映射为 valids 和 allowed
+  valids: err.params && err.params.allowedValues ? err.params.allowedValues.join(', ') : undefined,
+  allowed: err.params && err.params.allowedValues ? err.params.allowedValues.join(', ') : undefined
+};
+```
+
+**修复效果**:
+- 修复前: `"plan_type must be one of: {{#valids}}"`
+- 修复后: `"plan_type must be one of: pro, basic, free"`
+
+#### 2. **修复 additionalProperties 错误消息参数映射**
+
+**问题描述**:
+- additionalProperties 错误消息应该显示未知属性名，但实际没有
+
+**根本原因**:
+- ajv 返回的参数字段名是 `additionalProperty`
+- 模板使用的是 `{{#key}}`
+- ErrorFormatter 没有映射，且语言包中缺少 additionalProperties 的消息模板
+
+**修复方案**:
+1. 在 ErrorFormatter 中添加参数映射:
+```javascript
+// ✅ 修复 additionalProperties 错误：将 additionalProperty 映射为 key
+key: err.params && err.params.additionalProperty ? err.params.additionalProperty : undefined
+```
+
+2. 在**所有5种内置语言包**中添加消息模板:
+```javascript
+// lib/locales/en-US.js (英文)
+'additionalProperties': '{{#label}} must NOT have additional properties: {{#key}}'
+
+// lib/locales/zh-CN.js (中文)
+'additionalProperties': '{{#label}}不允许有额外属性: {{#key}}'
+
+// lib/locales/es-ES.js (西班牙语)
+'additionalProperties': '{{#label}} NO debe tener propiedades adicionales: {{#key}}'
+
+// lib/locales/fr-FR.js (法语)
+'additionalProperties': '{{#label}} NE doit PAS avoir de propriétés supplémentaires : {{#key}}'
+
+// lib/locales/ja-JP.js (日语)
+'additionalProperties': '{{#label}}に追加のプロパティを含めてはいけません: {{#key}}'
+```
+
+**修复效果**:
+- 修复前: `"must NOT have additional properties"`
+- 修复后: `"value must NOT have additional properties: email"`
+
+## ✅ 测试增强
+
+### 新增错误消息插值完整性测试
+
+创建了完整的测试套件，全面验证所有错误类型和所有语言的参数映射：
+
+#### 1. 基础参数映射测试 (`test/unit/error-message-interpolation.test.js`)
+**测试覆盖**:
+- ✅ enum 错误消息（必填/可选/数字枚举/中文）
+- ✅ additionalProperties 错误消息
+- ✅ required 错误消息
+- ✅ minLength/maxLength 错误消息
+- ✅ minimum/maximum 错误消息
+- ✅ type 错误消息
+- ✅ minItems/maxItems 错误消息
+- ✅ format 错误消息
+- ✅ 多语言支持（中文/英文）
+
+#### 2. 多语言完整性测试 (`test/unit/multi-language-error-messages.test.js`)
+**测试覆盖**:
+- ✅ enum 错误消息 - 所有5种语言（en-US, zh-CN, es-ES, fr-FR, ja-JP）
+- ✅ additionalProperties 错误消息 - 所有5种语言
+- ✅ 验证每种语言的模板变量都正确替换
+- ✅ 验证每种语言的错误消息都包含必要信息
+
+#### 3. 三轮深度检查 (`test-three-rounds-check.js`)
+**第一轮 - 所有ajv错误类型验证**（16个错误类型）:
+- ✅ required, minLength, maxLength, minimum, maximum
+- ✅ enum, pattern, format, type
+- ✅ minItems, maxItems, minProperties, maxProperties
+- ✅ additionalProperties, uniqueItems, const
+
+**第二轮 - 边界情况和极端值**（10个测试）:
+- ✅ 空字符串枚举、超长枚举列表（100个值）
+- ✅ 数字0作为枚举值、null作为枚举值
+- ✅ undefined作为数据、非常深的嵌套对象
+- ✅ 包含特殊字符的属性名（`user-name`, `user.email`）
+- ✅ 极大数值（MAX_SAFE_INTEGER）、极小数值（MIN_SAFE_INTEGER）
+- ✅ Infinity值
+
+**第三轮 - 多语言一致性**（4个场景 × 5种语言 = 20个测试）:
+- ✅ enum错误 - 所有语言正确
+- ✅ additionalProperties错误 - 所有语言正确
+- ✅ required错误 - 所有语言正确
+- ✅ type错误 - 所有语言正确
+- ✅ minItems/maxItems 错误消息
+- ✅ format 错误消息
+- ✅ 多语言支持（中文/英文）
+
+**测试原则**:
+- 不仅验证验证结果（valid: true/false）
+- 还验证错误消息内容是否正确
+- 确保所有模板变量都被正确替换
+- 确保不包含未替换的模板语法（如 `{{#xxx}}`）
+
+## 🔍 为什么之前的单元测试没有测试到？
+
+### 问题分析
+
+1. **现有测试只验证验证结果，不验证错误消息**:
+   - 现有的 enum 测试（`test/unit/enum.test.js`）只检查 `result.valid === false`
+   - 没有检查 `error.message` 的具体内容
+   - 因此即使错误消息包含未替换的模板变量，测试也会通过
+
+2. **缺少专门的错误消息格式化测试**:
+   - ErrorFormatter 的测试覆盖不够全面
+   - 没有验证所有 ajv 错误参数类型的映射
+
+### 改进措施
+
+新增的测试确保：
+- ✅ 所有错误消息都检查实际内容
+- ✅ 验证枚举值是否正确显示
+- ✅ 验证模板变量是否完全替换
+- ✅ 覆盖所有 ajv 错误类型的参数映射
+
+## 📝 变更文件
+
+### 核心修复 (6个文件)
+- `lib/core/ErrorFormatter.js` - 添加 enum 和 additionalProperties 参数映射
+- `lib/locales/en-US.js` - 添加 additionalProperties 错误消息模板
+- `lib/locales/zh-CN.js` - 添加 additionalProperties 错误消息模板
+- `lib/locales/es-ES.js` - 添加 additionalProperties 错误消息模板 🆕
+- `lib/locales/fr-FR.js` - 添加 additionalProperties 错误消息模板 🆕
+- `lib/locales/ja-JP.js` - 添加 additionalProperties 错误消息模板 🆕
+
+### 测试增强 (3个文件)
+- `test/unit/error-message-interpolation.test.js` - 基础参数映射测试（14个测试）
+- `test/unit/multi-language-error-messages.test.js` - 多语言完整性测试（10个测试）🆕
+- `test-three-rounds-check.js` - 三轮深度检查脚本（30个检查项）🆕
+
+## 🔄 向后兼容性
+
+✅ **完全向后兼容**
+- 只是修复了错误消息显示的Bug，不影响验证逻辑
+- 所有现有API保持不变
+- 所有现有测试（967个）全部通过
+- 新增10个多语言测试，总计977个测试全部通过
+
+## 📊 测试覆盖
+
+- **原测试数**: 967个
+- **新增测试**: 10个（多语言完整性测试）
+- **总测试数**: 977个
+- **通过率**: 100%
+- **深度检查**: 30个检查项全部通过
+
+## 🎯 影响范围
+
+### 受益场景
+1. 所有使用 enum 验证的场景
+2. 使用 additionalProperties: false 的场景
+3. 需要准确错误消息的场景
+4. 多语言国际化场景
+
+### 用户体验改进
+- ✅ 错误消息更清晰明确
+- ✅ 枚举值正确显示，用户知道可选值
+- ✅ 额外属性名正确显示，用户知道哪个字段不该提交
+- ✅ 多语言错误消息更准确
+
+## 🔗 相关Issue
+
+无（内部发现的Bug）
+
+## 📚 文档更新
+
+无需文档更新（只是Bug修复）
+
+---
+
+**升级建议**: 
+- 建议所有用户升级到 v1.1.6
+- 无需修改任何代码
+- 仅需执行 `npm update schema-dsl`

package/changelogs/v1.1.7.md

@@ -0,0 +1,317 @@
+# v1.1.7 - 错误消息路径显示优化
+
+**发布日期**: 2026-01-27  
+**类型**: Bug修复 🐛  
+**重要性**: ⭐⭐⭐⭐
+
+---
+
+## 📋 概述
+
+本次更新修复了嵌套对象错误消息中显示完整路径的问题，提升了错误消息的可读性和友好性。
+
+**核心改进**：
+- 错误消息 (`message`) 现在只显示字段名，而不是完整路径
+- 错误路径 (`path`) 保留完整路径用于定位
+- 统一所有错误类型的处理逻辑
+
+---
+
+## 🐛 问题描述
+
+### 修复前
+
+嵌套对象的错误消息包含完整路径，冗长且不友好：
+
+```javascript
+{
+  path: 'user/profile/age',
+  message: 'user/profile/age should be number, got string',  // ❌ 包含完整路径
+  keyword: 'type'
+}
+```
+
+### 修复后
+
+错误消息只显示字段名，更加简洁友好：
+
+```javascript
+{
+  path: 'user/profile/age',        // ✅ 保留完整路径用于定位
+  message: 'age should be number, got string',  // ✅ 只显示字段名
+  keyword: 'type'
+}
+```
+
+---
+
+## 🔧 修复内容
+
+### 1. 修复范围
+
+修改了 `lib/core/ErrorFormatter.js`，优化了所有错误类型的 label 生成逻辑：
+
+**修复的错误类型**（全覆盖）：
+- ✅ `required` - 缺少必填字段
+- ✅ `type` - 类型不匹配
+- ✅ `minLength`/`maxLength` - 字符串长度限制
+- ✅ `pattern`/`format` - 格式验证
+- ✅ `enum` - 枚举验证
+- ✅ `minimum`/`maximum` - 数值范围
+- ✅ `minItems`/`maxItems` - 数组长度
+- ✅ `additionalProperties` - 额外属性
+- ✅ 所有其他 ajv 错误类型
+
+### 2. 技术实现
+
+#### 修复1：正确处理 required 错误的字段路径（第139-158行）
+
+```javascript
+let fieldName;
+if (keyword === 'required' && err.params && err.params.missingProperty) {
+  // required 错误：字段名应该是父路径 + 缺失属性
+  const parentPath = instancePath.replace(/^\//, '');
+  const missingProp = err.params.missingProperty;
+  fieldName = parentPath ? `${parentPath}/${missingProp}` : missingProp;
+} else {
+  // 其他错误：直接使用 instancePath
+  fieldName = instancePath.replace(/^\//, '') || 'value';
+}
+```
+
+#### 修复2：统一优化所有错误类型的 label 生成（第160-185行）
+
+```javascript
+let labelKey;
+if (keyword === 'required' && err.params && err.params.missingProperty) {
+  // required 错误：使用 missingProperty（缺失的字段名）
+  labelKey = err.params.missingProperty;
+} else {
+  // 其他错误：从完整路径中提取最后一级字段名
+  // 例如: "user/profile/age" -> "age"
+  //      "user/scores/1" -> "1"
+  const parts = fieldName.split('/');
+  labelKey = parts[parts.length - 1];
+}
+```
+
+---
+
+## 📊 修复效果对比
+
+| 场景 | path（定位） | message（修复前） | message（修复后） |
+|------|-------------|------------------|------------------|
+| 顶层必填 | `name` | `name is required` | `name is required` ✅ |
+| 嵌套必填 | `project/project_id` | `project is required` ❌ | `project_id is required` ✅ |
+| 类型错误 | `user/profile/age` | `user/profile/age should be number` ❌ | `age should be number` ✅ |
+| 长度错误 | `user/profile/username` | `user/profile/username must be at least 3` ❌ | `username must be at least 3` ✅ |
+| 格式错误 | `user/contact/email` | `user/contact/email must be valid` ❌ | `email must be valid` ✅ |
+| 枚举错误 | `user/settings/theme` | `user/settings/theme must be one of: ...` ❌ | `theme must be one of: ...` ✅ |
+| 数组元素 | `user/scores/1` | `user/scores/1 should be number` ❌ | `1 should be number` ✅ |
+
+---
+
+## 🧪 测试
+
+### 新增测试
+
+创建了 `test/unit/required-error-fix.test.js`，包含 **6 个测试用例**：
+
+1. ✅ 顶层必填字段：应该显示正确的错误消息
+2. ✅ 嵌套对象必填字段：path 应该是完整路径，message 只显示字段名
+3. ✅ 多层嵌套必填字段：应该显示正确的路径和消息
+4. ✅ 对象本身是必填：应该显示正确的消息
+5. ✅ 同时缺少多个字段：每个错误应该正确显示
+6. ✅ 用户提供的真实场景：应该正确处理
+
+### 测试修复
+
+**问题**：npm test 失败，但单独运行测试通过
+
+**原因**：其他测试修改了全局语言设置（`Locale.setLocale('zh-CN')`），导致测试污染
+
+**解决方案**：添加 `beforeEach` 钩子，在每个测试前重置语言为英文
+
+```javascript
+beforeEach(function() {
+  Locale.setLocale('en-US');
+});
+```
+
+### 测试结果
+
+- ✅ **983 个测试全部通过**（新增 6 个）
+- ✅ 无回归问题
+- ✅ 覆盖所有错误类型
+
+---
+
+## 📝 路径分隔符说明
+
+### 为什么使用 `/` 而不是 `.`？
+
+**回答**：遵循 **JSON Pointer (RFC 6901)** 标准
+
+#### 对比分析
+
+| 使用 `/`（JSON Pointer） | 使用 `.`（JavaScript 风格） |
+|-------------------------|---------------------------|
+| ✅ 符合 RFC 6901 标准 | ❌ 不是标准格式 |
+| ✅ 与 ajv 原始格式一致 | ❌ 需要额外转换 |
+| ✅ 支持包含 `.` 的字段名 | ❌ 无法区分字段名中的 `.` 和分隔符 |
+| ✅ JSON Schema 生态系统通用 | ❌ 可能与其他工具不兼容 |
+
+#### 示例对比
+
+```javascript
+// ✅ 使用 / (JSON Pointer 标准)
+path: "user/profile/age"           // 清晰
+path: "config/version"             // 明确
+path: "api/v1.2.3/endpoint"        // 字段名包含 . 也没问题
+
+// ❌ 使用 . (JavaScript 风格)
+path: "user.profile.age"           // 非标准
+path: "api.v1.2.3.endpoint"        // 歧义！无法区分
+```
+
+#### AJV 原始格式
+
+```javascript
+{
+  instancePath: "/user/profile",   // ajv 使用 /
+  schemaPath: "#/properties/user/properties/profile/required"
+}
+```
+
+**参考**：
+- [RFC 6901 - JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901)
+- [JSON Schema](https://json-schema.org/)
+- [AJV - JSON Schema Validator](https://ajv.js.org/)
+
+---
+
+## 💡 使用示例
+
+### 基本用法
+
+```javascript
+const { dsl } = require('schema-dsl');
+
+const schema = dsl({
+  user: {
+    profile: {
+      age: "number!"
+    }
+  }
+});
+
+const result = dsl.validate(schema, {
+  user: {
+    profile: {
+      age: "not a number"  // 类型错误
+    }
+  }
+});
+
+if (!result.valid) {
+  console.log(result.errors[0]);
+  // {
+  //   path: 'user/profile/age',           // 完整路径，用于定位
+  //   message: 'age should be number',    // 友好提示，只显示字段名
+  //   keyword: 'type'
+  // }
+}
+```
+
+### 嵌套对象必填字段
+
+```javascript
+const schema = dsl({
+  project: {
+    project_id: "objectId!",
+    trip_id: "objectId!"
+  }
+});
+
+const result = dsl.validate(schema, {
+  project: {
+    // 缺少 project_id
+    trip_id: "69771ab94d7ff6963d1e93ff"
+  }
+});
+
+console.log(result.errors[0]);
+// {
+//   path: 'project/project_id',         // ✅ 完整路径
+//   message: 'project_id is required',  // ✅ 只显示字段名
+//   keyword: 'required'
+// }
+```
+
+---
+
+## 🔄 升级指南
+
+### 破坏性变更
+
+❌ **无破坏性变更**
+
+### 兼容性
+
+✅ **完全向后兼容**
+
+- `path` 仍然包含完整路径
+- `message` 格式更友好（只影响显示）
+- 所有 API 保持不变
+
+### 升级步骤
+
+```bash
+npm install schema-dsl@1.1.7
+```
+
+无需修改代码，直接升级即可。
+
+---
+
+## 📦 修改文件清单
+
+1. **lib/core/ErrorFormatter.js** - 核心修复
+   - 优化 `fieldName` 生成逻辑（第139-158行）
+   - 优化 `label` 生成逻辑（第160-185行）
+
+2. **test/unit/required-error-fix.test.js** - 新增测试
+   - 新增 6 个测试用例
+   - 添加 `beforeEach` 钩子避免测试污染
+
+3. **CHANGELOG.md** - 更新变更日志
+   - 添加 v1.1.7 版本信息
+
+4. **changelogs/v1.1.7.md** - 详细变更文档（本文件）
+
+5. **package.json** - 版本号更新为 1.1.7
+
+---
+
+## 📚 相关资源
+
+- **修复总结文档**: [ERROR-MESSAGE-FIX-SUMMARY.md](../ERROR-MESSAGE-FIX-SUMMARY.md)
+- **测试脚本**: `test-all-errors.js`（验证所有错误类型）
+- **GitHub Issue**: 用户反馈的嵌套对象错误消息问题
+
+---
+
+## 🙏 致谢
+
+感谢用户反馈此问题，帮助我们改进错误消息的可读性！
+
+---
+
+**下一步计划**：
+- 继续优化错误消息格式
+- 完善多语言支持
+- 提升测试覆盖率
+
+**完整变更日志**: [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)