AJV 校验器：组合模式的高级应用指南

AJV 校验器：组合模式的高级应用指南

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 作为一款高效的 JSON Schema 校验器，提供了多种强大的模式组合功能。本文将深入解析 AJV 中组合模式的各种高级用法，帮助开发者构建更加灵活和可维护的数据校验逻辑。

基础引用模式 ($ref)

$ref 关键字是 AJV 中实现模式组合的基础工具，它允许跨文件引用其他模式定义。

典型应用场景

// 主模式文件
const schema = {
  $id: "http://example.com/schemas/schema.json",
  type: "object",
  properties: {
    foo: {$ref: "defs.json#/definitions/int"},
    bar: {$ref: "defs.json#/definitions/str"},
  }
}

// 定义文件
const defsSchema = {
  $id: "http://example.com/schemas/defs.json",
  definitions: {
    int: {type: "integer"},
    str: {type: "string"},
  }
}

引用解析机制

1. URI 解析：$ref 使用基础 URI（由 $id 定义）进行解析
2. 递归支持：支持递归和相互递归引用，适合复杂数据结构
3. 标识符系统：既可以使用 $id 也可以使用自定义标识符

最佳实践

• 保持 $id 唯一性，避免冲突
• 对于大型项目，建议采用分层引用结构
• 考虑使用异步加载（compileAsync）实现动态模式加载

递归模式扩展技术

传统递归模式扩展存在局限性，AJV 提供了更先进的解决方案。

静态递归的局限

const treeSchema = {
  $id: "https://example.com/tree",
  type: "object",
  required: ["data"],
  properties: {
    data: true,
    children: {
      type: "array",
      items: {$ref: "#"},  // 硬编码递归
    },
  }
}

动态递归方案

JSON Schema 2019-09 引入了 $recursiveRef 和 $recursiveAnchor：

const treeSchema = {
  $id: "https://example.com/tree",
  $recursiveAnchor: true,
  type: "object",
  required: ["data"],
  properties: {
    data: true,
    children: {
      type: "array",
      items: {$recursiveRef: "#"},
    },
  }
}

const strictTreeSchema = {
  $id: "https://example.com/strict-tree",
  $recursiveAnchor: true,
  $ref: "tree",
  unevaluatedProperties: false,  // 扩展功能
}

实现细节

1. 目前仅支持在根节点使用锚点
2. 引用仅限于哈希片段（无 URI）
3. 异步模式中不支持动态引用

数据引用 ($data)

$data 选项实现了校验规则与数据的动态绑定。

核心功能

支持在以下关键字中使用数据引用：

• 数值比较类：maximum/minimum 等
• 长度限制类：maxLength/minLength 等
• 其他：pattern, required, uniqueItems 等

实用示例

const schema = {
  properties: {
    smaller: {
      type: "number",
      maximum: {$data: "1/larger"},  // 动态绑定
    },
    larger: {type: "number"},
  }
}

安全特性

1. 安全解析：遇到 undefined 不会抛出异常
2. 类型安全：自动检查引用值的类型
3. 灵活的指针支持：JSON-pointer 和 relative JSON-pointer

模式合并技术 ($merge/$patch)

通过 ajv-merge-patch 包实现模式合并功能。

初始化配置

require("ajv-merge-patch")(ajv);

合并操作示例

使用 $merge：

{
  $merge: {
    source: { /* 基础模式 */ },
    with: { /* 扩展内容 */ }
  }
}

使用 $patch：

{
  $patch: {
    source: { /* 基础模式 */ },
    with: [ /* JSON Patch 操作 */ ]
  }
}

应用场景

1. 渐进式模式开发
2. 模式版本管理
3. 跨团队模式协作

总结

AJV 提供了全方位的模式组合能力，从基础的 $ref 引用到高级的动态递归和数据绑定，再到模式合并操作，能够满足各种复杂场景下的数据校验需求。掌握这些技术可以显著提升 JSON Schema 的可维护性和灵活性，特别适合大型项目中的复杂数据验证场景。

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