1. 基础概念与核心函数
1.1 json_encode 的返回值与错误处理
在 PHP 中，json_encode 将一个 PHP 变量转换为 JSON 字符串，返回值为字符串类型，如果编码失败则返回 false。这意味着你需要对返回值进行判空和错误检查。
常见错误来自于输入数据中包含无效的 UTF-8 字符或不可序列化的资源类型等。此时可以借助 json_last_error_msg() 获取具体错误信息，方便调试。
'张三', 'age' => 28, 'roles' => ['admin', 'editor']];
$json = json_encode($data);
if ($json === false) {// 捕获并输出错误信息echo '编码错误: ' . json_last_error_msg();
}
?>1.2 json_decode 的返回类型与选项
json_decode 将 JSON 字符串转回 PHP 变量，默认返回 stdClass 对象，如果你需要关联数组，请将第二个参数设为 true。
通过明确定义返回类型，可以提升后续代码的可读性与一致性。你还可以使用第三个参数控制递归深度，第四个参数用来开启异常处理等扩展能力。
1.3 使用 JSON_THROW_ON_ERROR 的异常处理
在 PHP 7.3 及以上版本，JSON_THROW_ON_ERROR 选项可以让 json_decode 在遇到错误时抛出 JsonException，极大简化错误处理逻辑。
结合 try/catch，可以统一捕获编码与解码阶段的异常信息，提升健壮性与可维护性。
getMessage();
}
?>2. 实战场景：数据库与 API 数据交互
2.1 从数据库取数并输出 JSON 的步骤
在 API 服务中，常见需求是将数据库查询结果直接返回 JSON。从性能与易用性角度出发，建议将查询结果以 关联数组形式传递给 json_encode，并使用 JSON_UNESCAPED_UNICODE 以保持中文字符的可读性。
为防止意外注入或空数据导致的错误，务必对数据库返回的数据结构进行严格检查，并在输出前进行简单的校验。错误处理的策略应该统一化，以便前端可预测地处理响应。
PDO::ERRMODE_EXCEPTION
]);
$stmt = $pdo->query('SELECT id, name, email FROM users');
$rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
echo json_encode($rows, JSON_UNESCAPED_UNICODE);
?>2.2 控制输出格式与编码选项
在生产环境中，通常不会使用 JSON_PRETTY_PRINT 以减小带宽开销，但在调试阶段，它可以显著提升可读性。你可以在正式环境和调试环境之间灵活切换。
对于包含中文的字段，JSON_UNESCAPED_UNICODE 可以避免字符被转义为 \uXXXX 的形式，提升可读性与日志可分析性。也可以结合 JSON_NUMERIC_CHECK 把数字字符串转换为实际数字。
3. 常见坑点与解决方案
3.1 编码前数据的 UTF-8 问题与处理
JSON 编码对输入数据的编码要求非常严格，无效的 UTF-8 字符会导致 json_encode 失败。这在多源数据聚合时尤为常见。
解决方案是对输入进行编码规范化，例如使用 mb_convert_encoding 将源数据转换为 UTF-8，并清理 BOM 头。遇到错误时，优先定位为编码问题。
3.2 处理中文字符的编码选项
如果你需要在输出端展现原始中文文本，请使用 JSON_UNESCAPED_UNICODE，避免默认的 \u 转义序列。
对于前后端一致性，也要注意前端解析 JSON 时的字符编码设定，确保 Content-Type 为 application/json; charset=utf-8。
3.3 大数据量与内存管理坑
当要编码的数据量很大时，一次性编码大数组容易耗尽内存，导致脚本失败。
可以考虑分页查询或分块输出，或者在服务器端实现流式编码。注意保持 JSON 语法的完整性，例如在输出时正确管理逗号与方括号。
0) echo ',';echo json_encode($chunk, JSON_UNESCAPED_UNICODE);$offset += count($chunk);@ob_flush(); @flush();
}
echo ']';
?> 4. 调试与错误排查技巧
4.1 使用 json_last_error_msg 与错误码
遇到编码或解码错误时，json_last_error() 会指示具体错误类型，配合 json_last_error_msg() 能快速定位问题。
保持一个统一的错误处理流程，可以在前端接收错误信息时快速诊断。如果不使用异常，需要在每次 json_encode/json_decode 之后尽快检查返回值。
4.2 使用 json_decode 检查返回结构
明确判断解码后的数据结构是否符合预期，可以提升代码鲁棒性。对于对象或数组的深层结构，建议进行类型断言或结构校验。
例如，解码后要确保某个字段存在且是数组/字符串类型，才进行后续处理。
4.3 结合异常处理提升健壮性
使用 JSON_THROW_ON_ERROR 与 try/catch，可以在解码失败时抛出异常，避免继续处理错误数据。
getMessage();
}
?>5. 性能与最佳实践
5.1 选项组合对性能的影响
不同的编码选项会对性能产生直接影响。通常生产环境使用 JSON_UNESCAPED_UNICODE 与 JSON_NUMERIC_CHECK 的组合可以在保持数据精度的同时减少序列化后的字符长度。
如果你需要便于调试，可以临时开启 JSON_PRETTY_PRINT，但请务必在上线前去掉以减少网络传输开销。
5.2 控制缓存与传输大小
对 API 接口，设置正确的 Content-Type 是基础，例如 application/json; charset=utf-8，并结合 gzip 厮压缩，能显著降低带宽开销。
还可以在响应头中添加缓存策略，配合 CDN 或浏览器缓存，提升整体性能与用户体验。
5.3 在 API 服务中的应用场景
无论是数据接口、日志导出，还是跨系统数据同步，JSON 编码解码能力是 PHP 服务链路中的核心之一。通过合理的错误处理与编码选项，可以实现稳定、可维护的数据对接。
将数据规范化为统一的 JSON 结构，便于前端、移动端或第三方系统进行消费，提升整体系统的兼容性与扩展性。
0,'message' => 'OK','data' => $rows
];
echo json_encode($response, JSON_UNESCAPED_UNICODE);
?> 