Ajv 从 v6 迁移到 v8:完整变更清单、API 对比与实战迁移指南

原创2026-09-21 12:52:561,910 阅读
文章标签:后端API设计

Ajv 从 v6 迁移到 v8:完整变更清单、API 对比与实战迁移指南

本文以 Ajv 官方迁移文档(docs/v6-to-v8-migration.md)为骨架,逐条讲解 Ajv v6.12.6 到 v8.0.0 之间的全部破坏性变更与新特性:包括新增的 JSON Schema 草案与 JSON Type Definition 支持、全新的严格模式(strict mode)、重写的代码生成(codegen)、独立验证代码(standalone)能力、TypeScript 类型提升,以及所有新增/变更/移除的构造器选项。读完本文,你将能系统评估现有 v6 代码的迁移工作量,并按照清单逐项完成升级。

如果你是从 v7 迁移到 v8,可参考 v8.0.0 发布说明,本文聚焦 v6.12.6 → v8.0.0 这条迁移路径。

迁移总览:v8 相比 v6 的三大变化方向

v8 的核心变化可以概括为三个方向:

  1. 语言与规范支持扩展:新增 JSON Type Definition(RFC8927)支持,新增 JSON Schema draft-2019-09 / draft-2020-12 支持,以及 OpenAPI discriminator 关键字。
  2. 安全与正确性加固:代码生成被彻底重写以杜绝代码注入;引入严格模式,让"被静默忽略"或"有歧义"的 schema 在编译期就暴露出来。
  3. 架构与工程现代化:代码迁移到 TypeScript,schema 编译输出 ES6 代码(可选 ES5),Ajv 变成 ES6 class(必须用 new 创建),format 全部移出核心包。

新特性详解

支持新的 schema 规范

v6 只支持 JSON Schema draft-07 及更早版本,v8 则在不同的类中分别提供支持:

从源码结构看,这种"按规范拆分"体现在类层次上:lib/ajv.ts 导出 draft-07 的 Ajv 类(默认 meta schema 为 http://json-schema.org/draft-07/schema),lib/2020.ts 导出 Ajv2020(构造时自动开启 dynamicRef: true、next: true、unevaluated: true),lib/jtd.ts 导出 JTD 专用的 Ajv 类(构造时自动设置 jtd: true)。因此 v8 的导入方式也随类不同而不同,详见 docs/guide/getting-started.md。

JTD 编译出的 parser 与 serializer

v8 可以从 JTD schema 编译出解析器(parser)和序列化器(serializer):parser 在解析合法 JSON 时速度与 JSON.parse 相当,但会替换校验过程,且在解析非法 JSON 时失败得更快;serializer 比 JSON.stringify 快 10 倍以上。

从 lib/jtd.ts 的源码可以看到 compileParser 和 compileSerializer 两个方法的实现——它们先通过 _addSchema 注册 schema,再复用编译产物 sch.parse / sch.serialize,对应实现在 lib/compile/jtd/parse.ts 与 lib/compile/jtd/serialize.ts。用法示例见 docs/guide/getting-started.md(JavaScript)与 docs/guide/typescript.md(TypeScript 类型安全 parser/serializer)。

独立的验证代码(standalone validation code)

v8 全面支持将 schema 在构建期编译为独立的验证模块:可以编译一个或多个 schema,生成带一个或多个导出的 JS 文件,运行时无需初始化 Ajv。这有三个典型收益:减小浏览器 bundle(Ajv 不再被打包)、缩短启动时间(编译发生在构建期)、规避 Function 构造器(当页面 CSP 禁止动态代码求值时)。

该能力由 lib/standalone/index.ts 提供。完整的使用方法(CLI 方式 ajv compile -s schema.json -o validate_schema.js、JS 库方式、CJS/ESM 导出差异、code.formats 处理自定义 format 等)见 docs/standalone.md。

严格模式(strict mode)

为减少 schema 书写错误和"验证结果出乎意料"的情况,v8 引入严格模式:它不改变任何验证结果,但会让部分 schema 在编译期直接报错(或仅告警),从而阻止被忽略或有歧义的 JSON Schema 元素。详细规则见 docs/strict-mode.md,对应选项说明见 docs/options.md。

代码生成重写:类型级防注入

v8 将代码生成(codegen)彻底重写,使其在类型层面就杜绝"由不可信 schema 引发的代码注入"。schema 被编译为 ES6 代码(可通过选项生成 ES5)。新的 codegen 实现在 lib/compile/codegen/index.ts、lib/compile/codegen/code.ts 与 lib/compile/codegen/scope.ts,设计说明见 docs/codegen.md。

自定义关键字新 API

用于预定义关键字的新关键字 API 现在对用户自定义关键字开放,尤其是带子 schema 的关键字,定义起来比以前容易得多。v8 中关键字定义统一使用 code(代码生成)关键字格式,详见 docs/keywords.md。

TypeScript 迁移

代码全部迁移到 TypeScript,以提升可靠性与可维护性。同时 draft-07、draft-2019-09、draft-2020-12 与 JTD 各自有独立的 Ajv 类,默认导入各不相同(见 docs/guide/getting-started.md)。

迁移时必须注意的破坏性变化

官方文档明确标注了以下"请注意"事项,属于升级后立即会遇到的差异:

  1. 移除 JSON Schema draft-04 支持:若 schema 使用 id 属性,必须替换为 $id(v6 会支持到 2021-06-30)。
  2. format 全部移出核心包:所有 format 被拆分到独立的 ajv-formats 包,需要显式安装并注册。
  3. 必须用 new 创建实例:Ajv 现在是 ES6 class,不能以函数方式调用。
  4. 浏览器 bundle 自动发布到 ajv-dist 包(cdnjs.com 上仍可用)。
  5. 关键字验证顺序改变:适用于所有类型的关键字(如 allOf 等)现在先于类型特定关键字被验证。如需定义"适用于所有类型且在所有类型特定关键字之后验证"的自定义关键字,可在关键字定义中使用 post: true 选项——该选项在 lib/types/index.ts 的 _KeywordDef 接口中有明确定义。
  6. 正则表达式语义变化:pattern 与 patternProperties 关键字中的正则现在按带 u(unicode)标志处理(符合 JSON Schema 规范要求)。这意味着部分在 v6 中合法的正则现在不合法(反之亦然),迁移时需检查现有正则。

验证错误对象的变化

v8 的验证错误对象(ErrorObject,见 lib/types/index.ts)有三处破坏性变更:

  • dataPath 属性被 instancePath 替代;
  • 错误消息中的 "should" 被 "must" 替代;
  • propertyName 关键字的错误消息中不再包含属性名(但属性名仍可通过 error.params.propertyName 获取)。

从源码看,ErrorObject 接口现在固定包含 keyword、instancePath、schemaPath、params,以及可选的 propertyName、message(messages: false 时排除)、schema/parentSchema/data(仅 verbose 选项开启时添加)。

TypeScript 支持增强

v8 在类型层面做了多项增强:

  • compile 与 compileAsync 方法现在返回类型守卫(type-guards)——见 lib/types/index.ts 中 ValidateFunction<T> 的签名 (data: any, dataCxt?: DataValidationCxt): data is T,以及 docs/guide/getting-started.md。
  • validate 方法本身也是类型守卫。
  • 异步 schema 在类型层面与同步 schema 更好地区分(AsyncValidateFunction 与 AnyValidateFunction 类型)。
  • 新增三个 schema 工具类型,让书写 schema 时获得编译期类型检查:
    • JSONSchemaType<T>:根据类型参数 T 生成对应的 JSON Schema 类型(lib/types/json-schema.ts)。
    • JTDSchemaType<T>:根据类型参数 T 生成对应的 JSON Type Definition schema 类型。
    • JTDDataType<T>:根据 JTD schema 类型参数生成对应的数据类型(后两者在 lib/types/jtd-schema.ts)。

潜在迁移难点

编译更安全但更慢

schema 编译现在对代码注入更安全,但比 v6 更慢(对应 issue #1386)。如果编译速度是瓶颈,建议使用 standalone 验证代码 把编译挪到构建期。验证性能与 v6 持平或更好(得益于 codegen 优化)。

编译缓存键从序列化字符串变为 schema 对象

v8 使用 schema 对象本身作为编译函数的缓存键,而非序列化字符串(对应 issue #1413)。如果每次验证都传入新的 schema 对象,会导致每次验证都重新编译。缓存管理策略参见 docs/guide/managing-schemas.md。

自定义 format 与 standalone 代码

在 standalone 模式下使用用户自定义 format(对应 issue #1470)时,需要向 code.formats 选项传入代码片段,例如 _require("./my-formats")``,详见 docs/options.md 与 docs/standalone.md。

API 变更

新增方法

  • addVocabulary:允许一次性添加一组关键字定义(内部等价于多次调用 addKeyword)。

addKeyword 的变化

  • 关键字名称必须作为定义对象中的属性传入,而不是作为第一个参数(旧 API 仍可用,但会打印 "deprecated" 警告)。
  • inline 关键字支持被移除,代码生成类关键字现在用 code 关键字定义——与所有预定义关键字使用的定义格式相同。
  • 关键字名称中允许出现 : 字符。

从 lib/types/index.ts 可以看到新旧两类关键字定义接口:FuncKeywordDefinition(validate 函数式)与 CodeKeywordDefinition(含 code: (cxt: KeywordCxt, ruleType?: string) => void)。预定义关键字就按这种词汇表组织,例如 lib/vocabularies/validation/index.ts 中的 validation 词汇表由 limitNumber、multipleOf、limitLength、pattern、limitProperties、required、limitItems、uniqueItems、const、enum 等定义组成。

实例创建方式

Ajv 是 ES6 class,不允许不带 new 关键字创建实例。

选项变更全清单

新增选项

选项 默认值 说明
strict undefined true/false/"log",统一开关全部严格模式限制
strictSchema true 等价于 v6 中 strictKeywords + strictDefaults 的组合,另加额外限制(见 strict mode)
strictTypes "log" 阻止与类型关键字及关键字适用性相关的错误(见 Strict Types)
strictTuples "log" 阻止不完整的元组 schema(见 Prohibit unconstrained tuples)
strictRequired false 对 required 中使用了但未在 properties 中定义的属性,选择告警或报错(见 Defined required properties)
allowUnionTypes false 允许 type 关键字中出现多个非 null 类型
allowMatchingProperties false 允许 properties 与 patternProperties 关键字重叠
discriminator false 支持 OpenAPI discriminator 关键字
loopEnum 200 优化 enum 的验证,类似 loopRequired 选项(见 docs/options.md)
validateFormats true 是否启用 format 验证
code.optimize true 控制代码优化(见 code optimization)
code.es5 false 生成 ES5 代码,默认生成 ES6 代码
code.lines false 为生成代码添加换行,便于调试编译后的 schema

这些选项在 lib/core.ts 的 CurrentOptions 与 CodeOptions 接口中有完整定义;默认值汇总见 docs/options.md。注意其中部分选项(如 strictSchema、validateFormats、loopEnum 等)仅对 JSON Schema 生效,而 timestamp、parseDate、allowDate、int32range 等仅对 JTD 生效。

变更的选项

  • keywords:现在期望传入关键字定义数组(旧 API 仍可用,但会打印 "deprecated" 警告)。
  • strictNumbers:默认值改为 true——即默认情况下 Infinity 与 NaN 不能被验证为 {"type": "number"} 或 {"type": "integer"}(可用 strictNumbers: false 放开)。

移除的选项

移除选项 v8 替代方案
errorDataPath 已移除(曾标记废弃)
format 用 validateFormats: false 替代;format 模式通过 ajv-formats 包选择
nullable nullable 关键字默认受支持
jsonPointers 默认使用 JSON Pointer 报告错误;如需旧格式可传 jsPropertySyntax: true(已废弃)
unicode 已废弃,字符串长度默认按多字节字符正确计算
extendRefs $ref 兄弟关键字默认被验证(与 draft 2019-09 一致);可用 ignoreKeywordsWithRef(已废弃)忽略 $ref 兄弟
missingRefs 现在总是抛出异常;对被忽略的引用,可向 ajv.addSchema 传入带 $id 的空 schema
processCode 由 code: {process: (code, schemaEnv: object) => string} 替代
sourceCode 由 code: {source: true} 替代
schemaId 已移除,因为 JSON Schema draft-04 不再被支持
strictDefaults、strictKeywords 现在默认开启,由 strict 或 strictSchema 控制
uniqueItems uniqueItems 关键字始终被验证
unknownFormats 可通过 ajv.addFormat 或 formats 选项传入 true 来忽略特定 format
cache 和 serialize 使用 Map 作为缓存,schema 对象作为缓存键

这些"移除选项"在 lib/core.ts 的 RemovedOptions 接口中有完整列表,且源码中为每个被移除选项都维护了对应的提示文案,例如 nullable: '"nullable" keyword is supported by default.'、cache: "Map is used as cache, schema object as key.",用户误传这些选项时会收到明确指引。

迁移路线图:v6 → v8 实操建议

结合上述变更,推荐的迁移步骤为:

  1. 先升级到 v7 再升 v8(如从 v6 直接迁移):v8 在 v7 基础上主要是 draft-2020-12 与若干选项的细化,先按 v7 迁移文档把 id→$id、format 外置、dataPath→instancePath、严格模式告警处理完,能大幅降低直接跳到 v8 的难度。
  2. 安装并注册 format:npm install ajv-formats,然后 import addFormats from "ajv-formats"; addFormats(ajv)。
  3. 跑一遍测试,把严格模式告警当成待办清单:默认 strictSchema: true、strictTypes: "log"、strictTuples: "log" 会暴露 schema 中的未知关键字、未知 format、遗漏的 type、未约束的元组等潜在问题。迁移初期可用 strict: "log" 观察告警,再逐个修复,最后再开成 strict: true。
  4. 处理验证错误对象的差异:把所有读取 error.dataPath 的代码改为 error.instancePath,并检查依赖 "should" 消息的文本断言。
  5. 检查正则与数字校验:确认 pattern/patternProperties 中的正则兼容 u 标志;确认数据中不会出现 NaN/Infinity(strictNumbers: true 默认开启)。
  6. 关注编译性能:如果 schema 数量大且频繁编译,考虑用 standalone 模式把编译挪到构建期;注意 v8 以 schema 对象为缓存键,复用 schema 对象以避免重复编译。

延伸阅读

登录后查看全文
ajv