PHP JSON_THROW_ON_ERROR 抛错后怎么保留原始字段位置

接口收到一段坏 JSON 时，JSON_THROW_ON_ERROR 能让 PHP 立即抛出 JsonException，但它不会替你恢复业务字段路径。$e->getLine() 是 PHP 源码中抛异常的位置，也不是 JSON 内部的行号。要保留“原始字段位置”，应把信息拆成三层：未经改写的请求体、异常的错误码与消息、调用方明确传入的字段路径。

先把异常信息和原始 JSON 分开保存

PHP 手册把 JSON_THROW_ON_ERROR 列为 json_decode() 的 flags。发生错误时，调用返回路径被异常打断，错误类型在 JsonException 的 code 中，文本在 message 中。RFC 还明确了：这次带 flag 的调用不会更新全局 JSON 错误状态。因此，捕获异常后再调用 json_last_error_msg()，不能当成这次异常的定位结果。

入口层先保存原始字符串，日志中只保留必要片段，并给每次请求一个 request_id。这样即使消息只有 “Syntax error”，仍能根据原文重现，而不是把已经 trim()、替换 UTF-8 或重新编码的内容当作证据。

 json_decode($raw, true, 512, JSON_THROW_ON_ERROR),
            'error' => null,
        ];
    } catch (JsonException $e) {
        // getLine() 是 PHP 文件行号，不能冒充 JSON 字段行号。
        $location = null;
        if (preg_match('/near location (\d+):(\d+)/', $e->getMessage(), $m)) {
            $location = ['line' => (int) $m[1], 'column' => (int) $m[2]];
        }

        return [
            'value' => null,
            'error' => [
                'field_path' => $fieldPath,
                'code' => $e->getCode(),
                'message' => $e->getMessage(),
                'json_location' => $location,
                'raw_json' => $raw,
            ],
        ];
    }
}

// 顶层失败时路径只能诚实记录为 $，不要猜测具体字段。
$raw = file_get_contents('php://input');
$result = decodeJsonWithContext($raw);
if ($result['error'] !== null) {
    error_log(json_encode($result['error'], JSON_UNESCAPED_UNICODE));
}

正则只兼容“消息里已经出现位置提示”的环境；它不是 PHP 的公开位置 API。没有提示时，json_location 保持 null，但原始 JSON、错误码和 $ 路径仍然完整。

PHP 源码行号和 JSON 字段位置不是一回事

排查时最容易混淆两个“位置”。异常的 getFile()、getLine() 指向执行 json_decode() 的 PHP 文件；它们说明哪段程序抛了异常，不说明 JSON 的第几个字段。当前 PHP JSON 实现对部分解析错误消息可以附带 near location line:column，这能帮助定位原文附近字符，但仍未提供业务 JSON Pointer，也不应被当成稳定的对象属性。

所以，错误响应可以返回“请求体格式错误”，日志则记录 request_id、code、message、原文摘要和可选行列。不要直接把整段请求体回显给客户端，尤其是其中可能含有令牌或个人数据。

字段级解码才能稳定保留业务路径

如果一个外层请求合法，但 metadata_json、规则表达式或供应商回调字段本身又是一段 JSON 字符串，就先解码外层，再在字段边界调用同一个辅助函数。路径由业务代码传入，因而不会依赖解析器“猜”字段。

 $requestId,
        'field_path' => $nested['error']['field_path'],
        'json_code' => $nested['error']['code'],
        'json_location' => $nested['error']['json_location'],
    ];
    error_log(json_encode($diagnostic, JSON_UNESCAPED_UNICODE));
}

这种方式的前提是外层对象已经能被解析。如果最外层逗号、引号或括号就坏了，任何字段路径都可能只是猜测；此时只能记录 $，保留原文，或者改用能公开返回 offset/JSON Pointer 的流式解析器。

上线前用四项清单检查定位链路

• 原始请求体是否在解码前保存，且没有先做会改变字节位置的清洗？
• 异常是否同时记录 getCode()、getMessage() 和 request_id？
• PHP 源码行号是否与 JSON 行列、业务字段路径明确分开？
• 嵌套 JSON 是否在字段边界单独解码，并显式传入 JSON Pointer？

还要注意深度限制和 UTF-8 错误。它们不一定对应某个语法字符，单纯展示“第几列”反而会误导。对外错误可以简洁，对内诊断记录应完整；这是可追溯性和敏感信息控制之间更稳妥的取舍。

常见问题

catch 之后调用 json_last_error_msg() 能得到这次错误吗？

不能把它当作可靠来源。使用 JSON_THROW_ON_ERROR 时，应从捕获到的 JsonException 读取错误码和消息。

JsonException::getLine() 是 JSON 的行号吗？

不是。它是 PHP 源码抛出异常的位置；JSON 行列只能使用消息中明确提供的提示，或交给支持位置报告的解析器。

为什么不直接用正则找出坏字段？

JSON 有字符串、转义、数组和嵌套对象，正则很容易把字符串里的逗号误当结构。顶层损坏时记录原文，字段级数据则在边界解码，更容易保持正确上下文。

一句话收束：JSON_THROW_ON_ERROR 负责把失败变成可捕获异常，原始字段位置则要靠入口留存原文、字段边界和显式路径共同建立。两者职责分开，日志才既能定位又不容易误导。