json_validate 怎样只验证 JSON

接收 Webhook、队列消息或配置片段时，有些代码只想知道“这段文本是不是语法正确的 JSON”，并不准备马上把它变成数组或对象。PHP 8.3 提供的 json_validate() 就是为这个边界准备的：它返回布尔值，判断输入是否是语法有效的 JSON；如果只需要这个判断，就不必为了拿一个真假结果而先构建完整的数据结构。

官方文档：https://www.php.net/manual/en/function.json-validate.php

只验证 JSON 的最小写法是 json_validate($json)。返回 true 表示语法有效，返回 false 表示内容不是有效 JSON；但如果后面立刻还要用 json_decode() 取字段，就不要把两个解析动作机械地连起来。

json_validate() 只做哪一层判断

它检查的是 JSON 文本的语法，而不是业务字段是否齐全。下面的例子只关心文本能否被当作 JSON 读取，因此函数返回一个可以直接用于分支判断的 bool：

这里的重点是“结果够不够用”。如果入口只需要把非法文本拒绝、放入死信队列或记录一条原因，那么布尔值就足够。相反，如果下一行马上要读取 event，最终仍然需要解码出结构，提前调用 json_validate() 就会把同一份文本解析两次。

它也不是 JSON Schema 校验器。像“必须存在 event 字段”“retry 必须是布尔值”这类约束，需要在解码后由业务代码或专门的 Schema 工具处理；json_validate() 本身不会替你做字段级契约判断。

三个参数和两类失败要分开看

函数签名是 json_validate(string $json, int $depth = 512, int $flags = 0): bool。默认深度是 512，默认标志是 0。只有在输入边界确实需要时才调整它们，避免把默认行为改得难以解释。

• $json 必须是 UTF-8 编码的字符串。
• $depth 必须大于 0 且不超过 2147483647，用来限制嵌套深度；超出范围会抛出 ValueError。
• $flags 当前可使用 0，或 PHP 手册允许的 JSON_INVALID_UTF8_IGNORE；传入不被接受的标志同样会抛出 ValueError。

因此要把“内容无效”和“调用参数错误”分开处理。内容语法错误通常是正常业务分支，参数越界则更像配置或代码错误：

getMessage()}";
}

json_last_error_msg() 用来解释 false 对应的 JSON 错误；它不会把无效内容变成结构，也不应该被当作业务 Schema 错误消息。日志里可以记录错误类别，但不要把原始敏感 JSON 无条件写入日志。

只需要格式判断时，入口可以这样放

我更愿意把它放在“只需要决定是否接收”的边界上，例如接收一个稍后再处理的文本消息。这样入口只产生判断结果，后续消费者是否解码由自己的职责决定：

这个函数仍然只回答“能不能作为 JSON 文本继续流转”。它没有承诺字段存在，也没有承诺数组、对象或标量的业务类型；这些约束应该在真正消费数据的地方表达。

什么时候不要先验证再解码

官方手册特别提醒：json_decode() 自己也会在解码过程中验证 JSON。下面这种连续写法虽然直观，却把同一份字符串解析了两遍：

如果业务马上需要字段，应直接采用带异常的解码路径，并在同一个地方处理失败；如果业务只需要判断文本是否合规，再使用 json_validate()。这个取舍不是“哪个函数更先进”，而是是否真的需要解码后的数据结构。

版本与 JSON 语义边界

json_validate() 从 PHP 8.3.0 开始提供。部署在更早 PHP 版本的项目不能直接假设该函数存在，应该先确认运行时版本，再决定升级或采用项目已有的兼容方案。本文只讨论原生 json_validate() 的使用，不把兼容实现冒充成同一个函数。

另外，语法有效不等于“符合你的业务模型”。例如文本通过语法判断后，仍然可能缺少订单号、把金额写成字符串，或使用了业务不允许的顶层类型。可以把边界记成一句话：json_validate() 负责 JSON 文本的语法门槛，解码后的代码负责数据语义。

最后的选择清单

常见追问

json_validate() 返回 false 时会抛异常吗？

对于 JSON 内容本身无效，正常结果是 false，可以再调用 json_last_error() 或 json_last_error_msg() 读取原因。深度或标志参数不合法则属于参数错误，会抛出 ValueError。

json_validate() 能检查字段是否存在吗？

不能。它只检查语法有效性；字段、类型、范围和业务必填项需要解码后单独判断。

为什么验证后不能马上 json_decode()？

可以调用，但通常没有必要，因为解码本身也会进行 JSON 验证。若最终一定要用解码结果，直接设计解码和错误处理路径更省一次解析。

PHP 8.2 能直接使用 json_validate() 吗？

原生函数从 PHP 8.3.0 开始提供。PHP 8.2 项目需要先确认版本并采用明确的兼容策略，不能把不存在的原生函数当作可用。