PHP json_decode 怎么用 JSON_THROW_ON_ERROR 保留错误上下文

接口收到一段损坏 JSON 时，json_decode() 默认失败只返回 null，调用方很容易只看到“解析失败”，却不知道数据来自哪个接口、哪条消息、哪一次导入。更稳妥的写法是把 JSON_THROW_ON_ERROR 作为第四个参数传入，让 PHP 抛出 JsonException，再在一个很小的 try/catch 边界里补上来源、错误码和安全摘要。

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

PHP json_decode 的异常入口要放在可追踪的边界内

这个 flag 从 PHP 7.3 开始可用。它把过去需要“判断返回值再调用 json_last_error()”的隐式流程，改成可以被捕获的异常流程。第四个参数是 flags 位掩码，第二个参数仍然决定 JSON 对象返回关联数组还是对象，第三个参数控制最大嵌套深度。

getCode(),
                $summary,
                $exception->getMessage()
            ),
            0,
            $exception
        );
    }
}

这里的“上下文”不是把原始 JSON 原封不动地塞进异常，而是建立一个可关联、可脱敏的诊断记录。source 可以是队列名、接口用途或导入批次；哈希摘要能帮助定位同一份坏数据，同时避免日志泄露令牌、手机号等字段。

四个参数要一起看，别只记住 JSON_THROW_ON_ERROR

真实项目里，异常处理效果还会受返回形态和深度限制影响。下面这张表适合在封装函数时直接变成团队约定：

如果业务依赖超大整数，还要额外考虑 JSON_BIGINT_AS_STRING；如果数据来自外部系统，也不要为了“让它先解析出来”就随意使用忽略或替换非法 UTF-8 的 flag。错误被隐藏后，后面的字段校验会变得更难解释。

错误码决定处理动作，不要把所有 JSON 失败都重试

捕获到 JsonException 后，先把解析层和业务层分开。语法错误通常意味着消息本身不可用，适合拒绝并记录；临时读取不完整可能走重试，但重试次数应由消息系统策略决定；JSON 解析成功后发现缺少 order_id，那是业务校验，不应伪装成 JSON 错误。

记录诊断信息时，建议至少保存以下字段：

• source：数据从哪里来，避免只记录一个通用“JSON error”。
• error_code 与 message：保留 PHP 给出的错误类型和可读说明。
• payload_length、摘要和关联 ID：帮助定位原始消息，但不要直接记录完整敏感内容。
• action：明确本次是 reject、retry 还是进入人工 inspect。

保留错误上下文时的三个常见坑

第一，不能用 if ($data === null) 代替异常处理：合法 JSON 字面量 null 也会得到 null，默认模式下还会和解析失败混淆。第二，不能在 catch 里只写一句固定日志；没有来源和关联 ID，线上仍然无法还原问题。第三，不要把异常包装后丢掉原异常，使用第三个参数传入 previous，才能在需要时继续查看原始错误。

如果项目还要兼容没有 JSON_THROW_ON_ERROR 的旧 PHP 版本，应在兼容层明确区分版本路径：旧路径调用 json_last_error()，新路径捕获 JsonException。不要让运行时版本判断替代已经发生的语法或编译问题。

相关问题

JSON_THROW_ON_ERROR 会自动修复无效 JSON 吗？

不会。它只是把解析失败变成 JsonException，具体的语法、编码和深度问题仍然需要数据生产方或调用方修复。

为什么还要保留 json_last_error？

旧版本兼容代码或不使用异常 flag 的路径仍可能依赖它；新代码如果开启了 JSON_THROW_ON_ERROR，优先捕获异常并读取异常上下文。

错误上下文应该保存完整 JSON 吗？

通常不应该。记录来源、长度、关联 ID、短哈希和截断后的非敏感片段即可，完整原文应放在受控的短期隔离存储中，并遵循项目的数据保留规则。

落地检查清单

• 确认运行环境支持 JSON_THROW_ON_ERROR，并统一 associative 与 depth 约定。
• 在小范围边界捕获 JsonException，保留 message、code 和 previous。
• 用来源、关联 ID 和安全摘要补足错误上下文，禁止把敏感原文直接写入日志。
• 把解析层错误和业务字段错误分开，分别决定拒绝、重试或人工排查。