MySQL JSON_SCHEMA_VALIDATION_REPORT 怎样定位校验失败字段

遇到 JSON 校验失败时，只看 JSON_SCHEMA_VALID() 返回的 0，通常还不知道是哪一个字段出了问题。MySQL 的 JSON_SCHEMA_VALIDATION_REPORT() 会把失败原因、JSON 文档位置、Schema 位置和失败关键字一起返回，定位嵌套字段时应优先读取这几个字段。

最实用的排查顺序是：先看 valid，再读 document-location 找到数据字段，接着用 schema-location 和 schema-failed-keyword 判断规则，最后保留 reason 作为日志说明。

官方文档：https://dev.mysql.com/doc/refman/8.4/en/json-validation-functions.html

先看报告里的四个定位字段

这个函数接收两个参数：JSON Schema 和待校验的 JSON 文档。文档符合规则时，结果通常是只有 valid 的对象；校验失败时，还会出现四个有用的定位字段：

• reason：适合直接写入日志的人类可读说明。
• document-location：JSON 文档中失败字段的位置。
• schema-location：Schema 中对应规则的位置。
• schema-failed-keyword：触发失败的规则名，例如 maximum、minimum 或 required。

路径使用 JSON Pointer 片段标记：# 表示整个文档，#/user/age 表示顶层 user 对象里的 age 字段。它不是 JSON_EXTRACT() 使用的 $.user.age JSON 路径，日志解析时不要混用两种写法。

用 JSON_PRETTY 读取嵌套字段

值越界是最容易看出定位效果的例子。下面的 Schema 要求 user.age 至少为 18，但文档传入了 16。代码中的注释只说明关键输入和观察点，便于把示例改成自己的字段。

-- 准备一个包含嵌套年龄字段的 Schema
SET @schema = '{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "age": {"type": "integer", "minimum": 18}
      },
      "required": ["age"]
    }
  },
  "required": ["user"]
}';

-- 这个文档的 user.age 低于 minimum，预期校验失败
SET @document = '{"user":{"age":16}}';

-- JSON_PRETTY 只负责展开结果，便于人工阅读日志
SELECT JSON_PRETTY(
  JSON_SCHEMA_VALIDATION_REPORT(@schema, @document)
) AS validation_report;

失败报告中，document-location 会指向类似 #/user/age 的文档位置，schema-location 会指向包含 minimum 的规则，schema-failed-keyword 则告诉你失败类型是 minimum。这样可以把“JSON 校验失败”缩小到具体字段和具体约束。

如果是数组字段，路径还会包含数组下标，例如某个元素的位置可能表现为 #/items/0/code。排障程序应把路径当作字符串保存，不要假设它一定只有两层。

把报告字段提取成排障结果

人工看完整 JSON 适合临时排查，线上日志或管理查询更适合直接取出几个字段。JSON_EXTRACT() 读取报告属性，JSON_UNQUOTE() 去掉 JSON 字符串外层的引号：

-- 先把完整报告保存到变量，避免重复计算校验结果
SET @report = JSON_SCHEMA_VALIDATION_REPORT(@schema, @document);

-- 将 JSON Pointer 和失败关键字拆成可检索的排障字段
SELECT
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.valid')) AS is_valid,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.document-location')) AS document_location,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.schema-location')) AS schema_location,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.schema-failed-keyword')) AS failed_keyword,
  JSON_UNQUOTE(JSON_EXTRACT(@report, '$.reason')) AS failure_reason;

可按下面的方式解释查询结果：

注意 document-location 只是定位信息，不会自动把错误字段的原始值放进报告。需要审计时，应在应用侧按脱敏规则保存原始请求或请求编号，避免把密码、令牌等敏感值直接写入日志。

处理 required、NULL 与非法输入

不同失败类型的处理方式不一样，不能都归结为“字段值不对”。例如文档缺少 Schema 的必填字段时，失败关键字通常是 required，位置可能落在包含缺失字段的对象或整个文档上。

-- 保留 user.age 的 required 规则，但不传入 age
SET @document = '{"user":{}}';

-- required 失败时，reason 和 failed_keyword 一起说明缺少必填字段
SELECT JSON_PRETTY(
  JSON_SCHEMA_VALIDATION_REPORT(@schema, @document)
) AS required_report;

-- SQL NULL 不是 JSON 文档中的 null；参数为 SQL NULL 时函数返回 NULL
SELECT JSON_SCHEMA_VALIDATION_REPORT(@schema, NULL) AS sql_null_result;

还要区分下面几类结果：

• 参数为 SQL NULL：函数返回 NULL，这不是一次正常的 Schema 失败报告。
• 参数不是合法 JSON：MySQL 会抛出无效 JSON 类型相关错误，无法按报告字段解析。
• Schema 不是 JSON 对象：会返回无效 JSON 类型相关错误。
• 文档是合法 JSON，但不符合规则：返回 valid: false，再读取定位字段。

因此，应用层处理时应先判断数据库调用是否报错，再判断返回值是否为 SQL NULL，最后才解析 valid 和失败字段。把三种状态混在一起，容易把输入格式问题误报成业务字段问题。

上线前保留回滚与告警信息

如果报告用于写入检查失败日志，建议至少保留请求编号、Schema 版本、document-location、schema-location、schema-failed-keyword 和脱敏后的 reason。告警可以按失败关键字聚合，例如 required 代表字段缺失，minimum 或 maximum 代表数值范围问题。

回滚时不要直接删除 Schema 约束。先把失败报告中的文档路径和规则路径导出，再决定是修正生产数据、调整输入映射，还是回退到上一版应用校验逻辑。若同时使用 JSON_SCHEMA_VALID() 做 CHECK 约束，插入失败后可以紧接着执行 SHOW WARNINGS，检查 MySQL 给出的约束错误和 JSON 位置说明。

速查结论：document-location 找字段，schema-location 找规则，schema-failed-keyword 找失败类型，reason 负责给人读。先把这四个值记录下来，再处理数据或改 Schema，定位会比只看 0/1 结果稳定得多。

相关问题

• JSON_SCHEMA_VALIDATION_REPORT 返回 valid: true 时，为什么没有失败字段？因为成功结果不需要失败定位属性。
• 为什么 #/user/age 不能直接当作 $.user.age 使用？前者是 JSON Pointer，后者是 MySQL JSON 路径，语法和语义不同。
• 如何定位缺少的必填字段？先看 schema-failed-keyword 是否为 required，再结合 reason 和 Schema 的 required 数组确认。
• 为什么报告没有返回原始字段值？报告提供位置和规则信息；原始值需要由调用方按脱敏要求另行保存。