PHP 使用 json_encode() 封装数据库 JSON 数据及 API 响应

季宁

发布时间：2026-10-14 | 2人浏览过

原创

本文讲解如何在 PHP 中将 MySQL 查询出的数据通过 json_encode 函数转换为标准的 JSON 格式对象，详细演示了单一数据行与多数据集的构建方式、数组嵌套逻辑，并针对 UTF-8 编码问题提供了实用的处理方法。

核心方法与目标

json_encode() 是 PHP 中用于生成 JSON 格式字符串的核心函数。在 Web 开发特别是 API 接口设计中，后端通常需要将数据库检索到的关联数组（Array）直接序列化为前端可解析的 JSON 数据。该方法要求输入必须是有效的数组或对象，且能自动处理数字、字符串等基础类型的转义。

准备条件

已配置好的 PHP 运行环境（支持 MySQL 扩展或 PDO）。
具备可执行的基本 SQL 查询权限。
了解基本的 PHP 数组定义与循环结构。

真实操作顺序

第1步：建立数据库连接并获取结果集

首先需要引入数据库配置文件，并执行具体的 SQL 语句。为了演示清晰，这里使用基础的 mysql_fetch_* 系列函数获取资源指针（注意：现代开发推荐优先使用 PDO 或 MySQLi），并在操作完成后务必释放资源以防内存泄漏。

<?php
// 引入数据库连接文件
require('Conn.php');

// 假设 $result 为执行 select 查询后返回的资源标识符
if ($result) {
    // 后续数据处理代码将在此处展开
} else {
    die("Query Failed");
}

// 操作结束后必须执行的清理工作
mysql_free_result($result);
mysql_close();
?>

第2步：封装单条数据记录

当只需返回某张表中的一条特定记录时，可以使用 mysql_fetch_row() 或 fetch_assoc() 获取关联数组。随后将该数组作为值，挂载在一个更高层级的容器数组中（如 'data' => $row），这有助于前端统一解析层级结构。

// 获取单行数据并转为关联数组
$row = mysql_fetch_assoc($result);

// 输出封装后的单条数据 JSON
// 示例结果: {"objId":{"id":"1","name":"admin"}}
echo json_encode(array('objId' => $row));
?>

第3步：构建多条数据列表（数据集）

面对分页或列表查询，需要将每一行数据存入一个大的索引数组中。以下方法通过 While 循环遍历结果集，逐行提取数据并追加到列表中：

$users = array();
$i = 0;
while ($row = mysql_fetch_array($result, MYSQL_ASSOC)) {
    // 可选：打印日志以确认数据正确性
    echo $row['id'] . ' - ' . $row['name'];
    
    // 将当前行的数据保存到总数组
    $users[$i] = $row;
    $i++;
}

// 将整个数据集包裹在 'dataList' 键名下
// 示例输出: {"dataList":[{"id":"1","name":"zhangsan"},{...}]}
echo json_encode(array('dataList' => $users));
?>

第4步：实现深层嵌套与格式化 API 响应

在实际业务场景中，一个请求往往需要同时返回成功载荷（Payload）和状态元数据（Metadata）。通过将不同功能的数组进行嵌套组合，可以形成清晰的 JSON 结构：

// 构造成功载荷数据
$payload = array(
    'request_name' => 'login',
    'api_key_value' => '8a9c7d6e5f4g3h2j'
);

// 构造错误/状态响应数据
$status_response = array(
    'error_code' => 'NO_ERROR',
    'msg' => '请求已成功处理'
);

// 组装最终的顶层响应对象
$response_structure = array(
    'UserKeyGetResponse' => $payload,
    'error_response' => $status_response
);

echo json_encode($response_structure);
?>

生成的 JSON 结构如下所示，便于各类客户端统一按 Key 读取对应信息：

{
  "UserKeyGetResponse": {
    "request_name": "login",
    "api_key_value": "8a9c7d6e5f4g3h2j"
  },
  "error_response": {
    "error_code": "NO_ERROR",
    "msg": "请求已成功处理"
  }
}

第5步：解决中文乱码与通用化处理

json_encode() 在默认情况下会将非 ASCII 字符（如中文）转换为 Unicode 编码（\uXXXX），虽然符合 JSON 规范但在可读性上较差，且在部分旧系统对接中可能出现乱码。可通过 JSON_UNESCAPED_UNICODE 标志位解决。

如果项目中存在大量深层嵌套数组需要统一做安全过滤或中文输出，可以封装一个静态辅助方法：

function output_json_safe($array) {
    // JSON_UNESCAPED_UNICODE 保持中文显示；JSON_PRETTY_PRINT 美化输出格式
    return json_encode($array, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
}

// 调用示例
$error_msg = array('code' => 404, 'msg' => '用户不存在');
echo output_json_safe($error_msg);

此时将直接输出：{"code":404,"msg":"用户不存在"}，不仅直观而且易于前端直接展示。