MySQL JSON_VALUE 如何避免静默 NULL：RETURNING 与 ERROR ON ERROR 的校验边界

订单扩展字段里混着数字、缺失字段和 JSON null 时，直接写 JSON_VALUE(meta, '$.retry_count') 很容易把三种情况都看成 SQL NULL。排查到最后才发现，真正的问题不是查询语法，而是默认的返回类型和错误处理把数据质量问题藏起来了。MySQL 8.4 中可以用 RETURNING 明确目标类型，再用 ERROR ON ERROR 把类型转换失败升级为可见错误。

如果 JSON 字段是业务必填值，优先使用明确的 RETURNING 类型和 ERROR ON ERROR；如果字段允许缺省，则把“路径不存在”和“值格式错误”分别交给 ON EMPTY、ON ERROR 处理，别让默认 NULL 替你做决定。

先把 JSON_VALUE 返回 NULL 的来源拆开

准备三条测试数据：第一条有合法数字，第二条缺少 retry_count，第三条把它写成字符串 "many"。这个例子特意不把 JSON null 混进来，先观察缺失路径和类型错误的差别。

SET @j1 = '{"retry_count": 3}';
SET @j2 = '{"status": "pending"}';
SET @j3 = '{"retry_count": "many"}';

SELECT
  JSON_VALUE(@j1, '$.retry_count') AS ok_value,
  JSON_VALUE(@j2, '$.retry_count') AS missing_value,
  JSON_VALUE(@j3, '$.retry_count' RETURNING UNSIGNED) AS bad_value;
SHOW WARNINGS;

第一列会得到字符形式的 3，第二列因为路径没有命中而按默认的 NULL ON EMPTY 返回 SQL NULL，第三列则发生转换问题。默认的 NULL ON ERROR 会让结果看起来像“没有值”，但转换失败会产生 warning，这就是必须同时检查结果与警告的原因。

用 RETURNING 和 ERROR ON ERROR 保护必填数字

报表或任务调度字段通常不能接受“随便转不出来就当 NULL”。把返回类型写死为 UNSIGNED，并把转换错误显式升级：

SELECT JSON_VALUE(
  @j3,
  '$.retry_count'
  RETURNING UNSIGNED
  ERROR ON ERROR
) AS retry_count;

这条查询遇到 "many" 时会报错，不会返回一个可以继续参与计算的 NULL。注意，ERROR ON ERROR 只能处理取值后的错误，例如把字符串转换成无符号整数，不能替代 JSON 文档和路径语法的合法性检查；文档损坏或路径表达式本身无效时，MySQL 会直接报 SQL 错误。

当字段确实允许缺失，可以把两个边界写在一起，但顺序不能反：

SELECT JSON_VALUE(
  @j2,
  '$.retry_count'
  RETURNING UNSIGNED
  DEFAULT 0 ON EMPTY
  ERROR ON ERROR
) AS retry_count;

这里“没有这个路径”才使用默认值 0；路径存在但值是 "many"，仍然走错误分支。实际接入时要把默认值当成业务决策，而不是为了让 SQL 永远有结果就随手填 0。

把 SQL NULL、JSON null 和转换警告分别验收

JSON 文档中的 JSON null 会映射成 SQL NULL，这和路径不存在的结果值相同；要区分它们，必须结合原始文档或额外的路径存在性检查。不要只靠结果列的 NULL 做数据质量判断。

SET @j4 = '{"retry_count": null}';

SELECT
  JSON_VALUE(@j2, '$.retry_count') AS missing_value,
  JSON_VALUE(@j4, '$.retry_count') AS json_null_value,
  JSON_CONTAINS_PATH(@j2, 'one', '$.retry_count') AS missing_exists,
  JSON_CONTAINS_PATH(@j4, 'one', '$.retry_count') AS json_null_exists;

SHOW WARNINGS;

missing_exists 为 0 而 json_null_exists 为 1 时，说明两个 SQL NULL 来自不同状态。至于 "many" 这种转换错误，使用默认行为时还要读 SHOW WARNINGS，否则应用层只看到了一个空值。

上线前按字段用途选处理策略

最后再复查三件事：返回类型是否与后续比较一致，ON EMPTY 是否写在 ON ERROR 前面，默认值是否真的符合业务含义。JSON_VALUE 的参数很短，但它把“没有数据”“数据为空”和“数据坏了”都放进了一条表达式里，边界没有写清楚，后面的聚合、排序和告警都会跟着失真。

常见问题

JSON_VALUE 不写 RETURNING 时返回什么类型？

默认返回 VARCHAR(512)。需要数字、日期或明确字符长度时，应显式写出 RETURNING 类型。

ERROR ON ERROR 能捕获无效 JSON 路径吗？

不能。JSON 文档或路径本身无效时，MySQL 会直接抛出 SQL 错误；ON ERROR 处理的是取值后的对象、数组、转换和截断等错误。

为什么结果是 NULL 还要执行 SHOW WARNINGS？

默认 NULL ON ERROR 会把转换失败映射成 NULL，但转换错误仍可能留下 warning。只看结果列会漏掉坏数据。

ON EMPTY 和 ON ERROR 的顺序能交换吗？

不能。语法要求 ON EMPTY 在前、ON ERROR 在后，顺序反过来会产生语法错误。

把 JSON_VALUE 的边界写进查询约定

JSON_VALUE 适合把 JSON 中的标量值带入 SQL，但它不是数据质量的自动修复器。字段必填就让坏值显式失败，字段可缺省就只对路径缺失提供默认值，探索性查询则把 warning 送进告警或审计。只要同时核对返回类型、NULL 来源和 SHOW WARNINGS，静默空值就不会再被误当成正常业务数据。