AJV 验证器从v6到v8版本迁移指南

AJV 验证器从v6到v8版本迁移指南

ajv The fastest JSON schema Validator. Supports JSON Schema draft-04/06/07/2019-09/2020-12 and JSON Type Definition (RFC8927) 项目地址: https://gitcode.com/gh_mirrors/aj/ajv

AJV（Another JSON Schema Validator）是一个高性能的JSON Schema验证器，广泛应用于Node.js和浏览器环境中。本文将详细介绍从AJV v6.12.6升级到v8.0.0版本的主要变化、新特性以及迁移过程中可能遇到的挑战。

核心新特性

1. 支持更多Schema规范

AJV v8版本新增了对以下Schema规范的支持：

• JSON Type Definition (JTD)：一种更简洁的Schema定义方式
• JSON Schema draft-2020-12：新增了prefixItems关键字，修改了items关键字的语义
• JSON Schema draft-2019-09：新增了unevaluatedProperties和unevaluatedItems等关键字
• OpenAPI：新增了discriminator关键字支持

2. 性能优化功能

• 编译解析器：基于JTD Schema生成的解析器，性能与原生JSON.parse相当
• 序列化器：比JSON.stringify快10倍以上
• 独立验证代码：支持将Schema编译为独立的验证模块

3. 严格模式

新增的严格模式可以有效减少Schema中的错误和意外的验证结果，包括：

• 禁止使用被忽略或模糊的JSON Schema元素
• 严格的类型检查
• 防止不完整的元组Schema
• 确保required属性在properties中有定义

4. 安全增强

• 完全重写的代码生成机制，防止不受信任的Schema注入代码
• Schema现在默认编译为ES6代码（可通过选项生成ES5代码）

5. TypeScript支持

• 代码库已迁移到TypeScript
• 改进了类型守卫功能
• 新增了Schema实用类型：
  • JSONSchemaType<T>：为类型接口生成JSON Schema类型
  • JTDSchemaType<T>：为类型接口生成JTD Schema类型
  • JTDDataType<T>：为JTD Schema类型生成数据类型

迁移注意事项

1. 不再支持的功能

• JSON-Schema draft-04：不再支持"id"属性，必须替换为"$id"
• 内置格式验证：所有格式验证已移至单独的包，需要显式添加
• 非new实例化：AJV现在必须使用new关键字实例化

2. 行为变更

• 验证顺序变更：适用于所有类型的关键字（如allOf）现在会在类型特定关键字之前验证
• 正则表达式处理：pattern和patternProperties中的正则表达式现在默认使用unicode标志
• 错误报告格式变更：
  • dataPath替换为instancePath
  • 错误消息中的"should"替换为"must"
  • 从"propertyName"关键字错误消息中移除了属性名

3. 性能考量

• Schema编译现在更安全但比v6慢
• Schema对象现在用作编译函数的关键字，而不是序列化字符串

API变更详解

新增API

• addVocabulary：新增方法，允许添加关键字定义数组

变更API

• addKeyword：关键字名称现在需要在定义对象中作为属性传递
• 关键字定义格式变更：移除了"inline"关键字支持，现在可以使用"code"关键字定义代码生成关键字

新增选项

• strict：控制严格模式的各种限制
• allowUnionTypes：允许在"type"关键字中使用多个非null类型
• allowMatchingProperties：允许"properties"和"patternProperties"关键字重叠
• discriminator：支持OpenAPI discriminator关键字
• code：新增多个代码生成控制选项

移除选项

• errorDataPath、format、nullable、jsonPointers等已被移除或替换

迁移建议

1. 检查Schema兼容性：确保所有Schema不使用draft-04特性
2. 处理格式验证：显式添加需要的格式验证
3. 更新错误处理：适应新的错误报告格式
4. 考虑性能优化：对于性能敏感场景，考虑使用独立验证代码
5. 利用严格模式：启用严格模式提高Schema质量
6. 更新TypeScript代码：利用新的类型守卫和实用类型

通过理解这些变化并遵循上述建议，您可以顺利将项目从AJV v6迁移到v8，同时利用新版本提供的强大功能和改进。

ajv The fastest JSON schema Validator. Supports JSON Schema draft-04/06/07/2019-09/2020-12 and JSON Type Definition (RFC8927) 项目地址: https://gitcode.com/gh_mirrors/aj/ajv