PHP json_decode 怎样用异常模式处理错误

如果接口收到的 JSON 不是合法格式，json_decode() 默认可能只返回 null。麻烦在于，输入字符串本来就是 JSON null 时，返回值同样是 null，调用方很容易把“合法结果”和“解析失败”混为一谈。

官方地址：https://www.php.net/function.json-decode

在 PHP 7.3 及更高版本中，可以把 JSON_THROW_ON_ERROR 放到 json_decode() 的第四个参数中。解析失败时捕获 JsonException，成功时再处理返回值，这样就不用先猜测 null 到底代表什么。

先看清 null 为什么会误导判断

旧写法常见于接口适配层：调用 json_decode($body, true)，然后用 if ($data === null) 判断失败。这个判断没有错，但它只告诉你“结果是 null”，并没有说明输入是合法的 JSON null、语法错误、非法 UTF-8，还是超过了嵌套深度。

这条兼容写法仍然适合旧项目，但要记住 json_last_error() 和 json_last_error_msg() 依赖最近一次没有指定异常模式的 JSON 操作。代码中间如果又执行了其他 JSON 操作，排查上下文会变得不直观。

把 JSON_THROW_ON_ERROR 放进 flags

json_decode() 的第四个参数是 flags 位掩码。把 JSON_THROW_ON_ERROR 放进去后，解析错误不再只写入全局错误状态，而是抛出 JsonException。如果还需要把 JSON 对象解码为关联数组，可以把第二个参数设为 true。

getMessage(), 0, $e);
}

这里的 512 是默认最大嵌套深度，不是每个项目都必须写死的业务限制；显式写出来只是为了让调用方看到第四个参数的位置。实际代码如果使用默认深度，也可以省略第三个参数，但 flags 仍要放在正确的位置。

在 catch 中保留真正有用的线索

异常模式的价值不只是“改成 try/catch”，而是让错误沿着当前请求的调用栈传递。捕获时至少保留异常消息和原始异常对象；日志中再补充请求标识、来源接口等上下文，避免把用户提交的完整敏感 JSON 直接写进日志。

getMessage());
        throw new InvalidArgumentException('请求体格式错误', 0, $e);
    }

    // 合法 JSON null 不是关联数组，业务层需要明确决定是否接受它。
    if (!is_array($value)) {
        throw new InvalidArgumentException('请求体必须是 JSON 对象');
    }

    return $value;
}

示例有两个独立判断：JSON 语法是否成立，由 JsonException 负责；解析结果是否符合接口契约，由 is_array() 负责。不要把“解析成功”误写成“业务数据一定完整”。

不要把 associative、depth 和 UTF-8 混成一个问题

JSON_THROW_ON_ERROR 只改变错误报告方式，不会替你决定返回对象还是数组，也不会把任意字符串自动变成合法 JSON。排查时可以按下面三条分开看：

• 返回形态：associative=true 时 JSON 对象通常解码为关联数组；设为 false 时返回对象；null 时由 flags 中的 JSON_OBJECT_AS_ARRAY 决定。
• 嵌套深度：depth 必须大于 0，超过限制会失败；PHP 8 还会对越界的 depth 抛出 ValueError，这与 JSON 内容语法错误不是同一类问题。
• 编码问题：json_decode() 只处理 UTF-8 编码的 JSON。若选择 JSON_INVALID_UTF8_IGNORE 或 JSON_INVALID_UTF8_SUBSTITUTE，要先确认业务是否允许丢弃或替换字符；不要为了“成功解析”而静默改变原文。

如果接口要求严格保留原始字节，宁可让 UTF-8 错误失败，也不要直接加入替换 flag。flags 是位掩码，多个选项用按位或组合；每个选项都应该对应一个明确的业务取舍。

旧版本项目怎样渐进迁移

JSON_THROW_ON_ERROR 自 PHP 7.3 起可用。如果项目还要支持更早版本，就不能直接把新常量写进所有共享代码。可以先把旧逻辑收口到一个适配函数，新版本分支使用异常模式，旧版本分支继续检查 json_last_error()，让调用方获得相同的失败契约。

= 70300) {
        // 新版本使用异常模式，失败原因随异常向上抛出。
        $value = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    } else {
        // 旧版本没有 JSON_THROW_ON_ERROR，只能立即读取全局错误状态。
        $value = json_decode($body, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new InvalidArgumentException(json_last_error_msg());
        }
    }

    // 两条版本路径都在这里统一检查接口需要的对象形态。
    if (!is_array($value)) {
        throw new InvalidArgumentException('JSON 顶层必须是对象');
    }

    return $value;
}

迁移时先盘点调用方是否把 null 当作合法业务值，再决定异常由哪一层捕获。不要在底层捕获后返回空数组来“兼容”，否则上层会把坏请求当成空数据继续处理。

用这份清单复查异常模式

1. 确认运行环境至少是 PHP 7.3，或已经提供旧版本适配分支。
2. 确认 JSON_THROW_ON_ERROR 位于 json_decode() 的第四个参数，并与其他 flags 用按位或组合。
3. 确认 JsonException 被捕获或交给统一异常处理器，没有只记录日志后继续使用不确定的返回值。
4. 确认合法 JSON null、顶层类型不符、语法错误、UTF-8 错误和 depth 问题分别有清晰语义。
5. 确认日志保留 message、code 和请求上下文，但不会把完整敏感请求体原样写入日志。

总结来说，异常模式解决的是 JSON 解析失败的表达和传递问题；它不替代业务字段校验，也不替代输入大小、编码和返回类型约束。把解析错误交给 JsonException，再把业务形态交给显式判断，排查路径会更清楚。

相关问题

JSON_THROW_ON_ERROR 会让合法的 JSON null 抛异常吗？不会。合法的 JSON null 仍然是正常返回值，只有发生 JSON 错误时才抛出 JsonException。

已经使用异常模式，还要调用 json_last_error() 吗？对同一次指定了 JSON_THROW_ON_ERROR 的失败解析，通常应从异常读取信息，不要再依赖全局错误状态来判断同一个失败。

JsonException 和 ValueError 有什么区别？JsonException 主要表示 JSON 编解码错误；例如 depth 参数本身越界属于参数错误，PHP 8 起可能抛出 ValueError。