schema-dsl 1.1.6 → 1.1.7

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # 变更日志 (CHANGELOG)
 
 > **说明**: 版本概览摘要，详细变更见 [changelogs/](./changelogs/) 目录  
-> **最后更新**: 2026-01-23
+> **最后更新**: 2026-01-27
 
 ---
 
@@ -9,6 +9,7 @@
 
 | 版本 | 日期 | 变更摘要 | 详细 |
 |------|------|---------|------|
+| [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) |
@@ -28,7 +29,7 @@
 | [v1.0.0](./changelogs/v1.0.0.md) | 2025-12-29 | 初始发布版本 | [查看](./changelogs/v1.0.0.md) |
 
 > 💡 **提示**: 重要版本的详细变更记录在 [changelogs/](./changelogs/) 目录中。  
-> 当前已有详细文档的版本：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  
+> 当前已有详细文档的版本：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  
 > 其他版本的详细变更信息请参考项目提交历史或联系维护者。
 
 ---
@@ -37,13 +38,31 @@
 
 | 版本系列 | 版本数 | 主要改进方向 |
 |---------|-------|------------|
-| v1.1.x | 7 | Bug修复、错误配置增强、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  

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)