PHP进行JSON编码转换时，标准JSON规范是不支持注释语法的，这导致很多开发者在需要标注JSON数据含义、记录修改说明时遇到阻碍。下面介绍几种在PHP中处理JSON编码时添加注释的可行方案。
方案一：使用非标准JSON格式临时添加注释
如果JSON数据仅在内部使用，不需要严格遵循标准规范，可以在编码时手动拼接注释内容，不过这种方式生成的不是合法JSON，仅适合临时调试场景。
<?php
// 原始数据
$data = [
'name' => '测试用户',
'age' => 25
];
// 先编码为JSON字符串
$jsonStr = json_encode($data, JSON_UNESCAPED_UNICODE);
// 手动拼接注释，注意这不是标准JSON
$jsonWithComment = "/* 这是用户基础信息 */" . $jsonStr;
echo $jsonWithComment;
?>
方案二：自定义编码逻辑嵌入注释字段
可以在数据数组中新增专门的注释字段，编码后注释会作为普通字段存在，这种方式生成的JSON是合法的，适合需要传递注释信息的场景。
<?php
// 原始数据加上注释字段
$data = [
'_comment' => '该数据为用户基础信息，2024年3月更新',
'name' => '测试用户',
'age' => 25
];
// 编码为合法JSON
$jsonStr = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
echo $jsonStr;
?>
方案三：转换时保留注释的自定义解析
如果需要处理带注释的JSON字符串再重新编码，可以先自定义解析函数去除注释，完成处理后如果需要保留注释，可以再反向拼接。
<?php
// 带注释的JSON字符串
$jsonWithComment = '/* 用户基础信息 */{"name":"测试用户","age":25}';
// 去除注释的函数
function removeJsonComment($jsonStr) {
// 去除单行注释
$str = preg_replace('///.*/', '', $jsonStr);
// 去除多行注释
$str = preg_replace('//*.*?*//s', '', $str);
return trim($str);
}
// 去除注释后解析
$cleanJson = removeJsonComment($jsonWithComment);
$data = json_decode($cleanJson, true);
// 处理数据后重新编码，可再次添加注释
$newData = $data;
$newData['_update_comment'] = '新增更新时间字段';
$newJson = json_encode($newData, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
echo $newJson;
?>
不同方案对比
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 非标准JSON拼接注释 | 实现简单，无需修改数据结构 | 生成内容不是合法JSON，无法被标准解析器识别 | 临时调试、内部非标准场景 |
| 添加注释字段 | 生成合法JSON，兼容性好 | 注释会作为普通字段存在，可能干扰业务逻辑 | 需要传递注释信息的内部接口 |
| 自定义解析保留注释 | 灵活处理带注释的JSON，可控制注释的保留和去除 | 实现逻辑相对复杂，需要自定义解析规则 | 需要处理历史带注释JSON的场景 |
注意事项
- 如果JSON数据需要对外提供或者对接第三方标准接口，不要使用非标准JSON格式，避免解析失败。
- 使用注释字段时，建议字段名加上特殊前缀比如
_comment，避免和业务字段冲突。 - 自定义解析注释时，要注意注释中可能出现的特殊字符，避免正则表达式匹配错误。