Fastify中AJV anyOf校验单元素数组报错问题排查

我定义了如下数据校验Schema，当向packages字段传入长度为1的数组时，AJV会抛出anyOf校验错误；但传入长度大于1的数组时校验正常。调整anyOf内的校验项顺序后发现：把null类型校验放在首位会报错，放在第二位则校验正常。

想确认：AJV的anyOf校验顺序是否会影响结果？如果顺序无关，我的Schema存在什么问题？

说明：已确认传入的数据是合法的

校验Schema #

{
  "type": "object",
  "properties": {
    "title": { 
      "type": "string",
      "minLength": 3,
      "maxLength": 255
    },
    "isPublished": { "type": "boolean" },
    "packages": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "integer" },
              "title": { "type": "string" },
              "level": { "anyOf": [{ "type": "integer" }, { "type": "null" }] }
            }
          }
        },
        { 
          "type": "null"
        }
      ],
      "default": null
    }
  }
}

测试数据 #

以下两组数据均合法，但AJV拒绝第一组、接受第二组：

// 被拒绝的单元素数组数据
{
  "title": "test",
  "packages": [{ "id": 13, "title": "package title", "level": 1 }]
}

// 被接受的多元素数组数据
{
  "title": "test",
  "packages": [
    { "id": 13, "title": "package title", "level": 1 },
    { "id": 15, "title": "package title 2", "level": 2 }
  ]
}

依赖版本 #

fastify: "^4.28.x",
ajv-errors: "^3.0.0",
ajv: "^8.11.0"

Fastify应用配置 #

const app = Fastify({
  ajv: {
    customOptions: {
      allErrors: true,
      messages: true,
      removeAdditional: false,
    },
    plugins: [require('ajv-errors')],
  }
});

// 注册应用插件
app.register(Application);

// 优雅关闭配置
closeWithGrace({ delay: parseInt(process.env.FASTIFY_CLOSE_GRACE_DELAY as string) || 500 }, async function ({ signal, err, manual }) {
  if (err) {
    app.log.error(err)
  }

  await app.close()
} as closeWithGrace.CloseWithGraceAsyncCallback)

// 启动服务
app.listen({ port: parseInt(process.env.PORT as string) || 3000, host: process.env.HOST || '127.0.0.1' }, (err: any, address: string) => {
  if (err) {
    app.log.error(err);
    process.exit(1);
  }
});

补充说明：最初使用fastify-cli，之后转为独立项目，仅添加ajv-errors插件用于自定义错误信息。

问题分析与解决 #

1. AJV anyOf的校验顺序是否重要？ #

AJV的anyOf设计逻辑是顺序无关的，只要有任意一个校验规则匹配，就会判定为通过。你遇到的顺序影响结果的现象，本质不是顺序本身的问题，而是Schema或AJV配置存在隐性冲突，导致顺序变化时校验逻辑的表现不同。

2. 核心问题排查与解决方向 #

结合你的场景，可能的原因及修复方案：

• Schema格式不规范：你最初提供的Schema是JS对象格式，存在缺逗号、单引号等问题（虽然JS允许，但转为JSON Schema时可能触发隐性错误）。建议统一使用标准JSON Schema格式（补全所有逗号、使用双引号）。
• AJV Strict模式冲突：AJV 8.x默认开启strict模式，对Schema的规范性要求较高。可以在Fastify的AJV配置中关闭严格模式尝试解决：

  ajv: {
    customOptions: {
      allErrors: true,
      messages: true,
      removeAdditional: false,
      strict: false // 添加此行关闭严格模式
    },
    plugins: [require('ajv-errors')],
  }
  

• AJV版本bug：ajv@8.11.0存在一些已知的校验逻辑bug，尤其是在处理单元素数组与anyOf组合的场景。建议升级到最新稳定版（如8.17.x）。
• ajv-errors插件兼容性：结合allErrors: true配置时，ajv-errors可能出现错误收集逻辑异常。可以暂时移除该插件测试是否恢复正常，再调整自定义错误信息的实现方式。

3. 临时修复方案 #

在数组校验规则中明确添加minItems: 0并声明必填字段，避免隐性校验问题：

{
  "type": "array",
  "minItems": 0,
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "title": { "type": "string" },
      "level": { "anyOf": [{ "type": "integer" }, { "type": "null" }] }
    },
    "required": ["id", "title"] // 明确必填字段
  }
}

内容的提问来源于stack exchange，提问作者Farshad Fahimi