PHP接口返回JSON数据完整指南：响应头、编码与错误结构设计

PHP 写接口时，最常见的返回格式就是 JSON。前端通过 Ajax、fetch 或移动端客户端请求接口后，需要拿到结构稳定、编码正确、错误信息清晰的 JSON 数据。

很多接口不是逻辑复杂，而是返回格式不规范：有时返回字符串，有时返回数组，有时错误直接输出 HTML，前端很难统一处理。本文从响应头、编码、成功结构、错误结构和状态码几个方面，整理 PHP 接口返回 JSON 的完整实践。

设置响应头

返回 JSON 时，应明确设置响应头，让客户端知道内容类型和编码。

header('Content-Type: application/json; charset=utf-8');

如果没有正确设置响应头，浏览器或客户端可能按普通文本甚至 HTML 解析结果。接口响应头应该在输出任何内容之前设置。

基础输出

PHP 可以使用 json_encode() 把数组转换成 JSON 字符串。

$data = [
  'success' => true,
  'message' => 'ok'
];

echo json_encode($data);

接口输出时不要混入调试信息、空格外的警告、HTML 片段或 var_dump 内容，否则前端解析 JSON 时会失败。

中文编码

默认情况下，json_encode() 可能会把中文转义成 Unicode。为了让返回内容更易读，可以加上 JSON_UNESCAPED_UNICODE。

echo json_encode($data, JSON_UNESCAPED_UNICODE);

如果包含 URL，也可以结合 JSON_UNESCAPED_SLASHES，避免斜杠被转义。

echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

成功结构

接口成功返回时，建议保持结构稳定。常见格式包括成功状态、数据和提示信息。

echo json_encode([
  'success' => true,
  'data' => $result,
  'message' => '获取成功'
], JSON_UNESCAPED_UNICODE);

无论 data 是对象、数组还是 null，外层结构最好保持一致。这样前端不用针对不同接口写大量特殊判断。

错误结构

接口失败时，也应该返回 JSON，而不是直接输出一段错误文本或 HTML。

echo json_encode([
  'success' => false,
  'message' => '参数错误',
  'errors' => [
    'email' => '邮箱格式不正确'
  ]
], JSON_UNESCAPED_UNICODE);

message 可以给用户展示，errors 适合表单字段级错误，前端可以把错误显示到对应输入框附近。

HTTP 状态码

业务错误和 HTTP 状态码要配合使用。比如未登录可以返回 401，权限不足返回 403，资源不存在返回 404，服务器异常返回 500。

http_response_code(400);

echo json_encode([
  'success' => false,
  'message' => '请求参数不完整'
], JSON_UNESCAPED_UNICODE);

不要所有接口都返回 200 再靠 message 判断错误。合理状态码能让前端和监控系统更容易识别问题。

封装响应函数

项目中可以封装统一响应函数，避免每个接口重复写响应结构。

function jsonResponse($data = null, $message = 'ok', $status = 200) {
  http_response_code($status);
  header('Content-Type: application/json; charset=utf-8');

  echo json_encode([
    'success' => $status < 400,
    'message' => $message,
    'data' => $data
  ], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
  exit;
}

统一出口能减少格式不一致的问题。接口越多，统一封装越重要。

处理异常

接口执行过程中可能出现数据库异常、参数异常、权限异常等。生产环境不要把异常堆栈直接返回给前端，而应记录日志并返回通用错误。

try {
  // 业务逻辑
} catch (Throwable $e) {
  error_log($e->getMessage());
  jsonResponse(null, '服务器繁忙，请稍后重试', 500);
}

开发环境可以显示详细错误，生产环境要避免泄露路径、SQL、配置等敏感信息。

输入 JSON

如果前端以 JSON 请求体提交数据，PHP 不能从 $_POST 直接读取，需要读取原始输入。

$raw = file_get_contents('php://input');
$body = json_decode($raw, true);

读取后要判断 JSON 是否解析成功，并对字段做校验。

if (!is_array($body)) {
  jsonResponse(null, 'JSON 格式错误', 400);
}

分页结构

列表接口通常需要分页信息。可以把列表放在 items，分页信息放在 pagination。

jsonResponse([
  'items' => $items,
  'pagination' => [
    'page' => $page,
    'pageSize' => $pageSize,
    'total' => $total
  ]
]);

分页结构统一后，前端表格、列表和加载更多组件都更容易复用。

常见错误

第一种错误是接口成功返回 JSON，失败却返回 HTML。第二种错误是输出前已经有 warning，导致 JSON 解析失败。第三种错误是中文编码不统一。第四种错误是没有 HTTP 状态码。第五种错误是接口结构每个页面都不一样。

实践建议

PHP 接口返回 JSON 时，建议固定响应头、固定外层结构、统一成功和错误格式、合理设置 HTTP 状态码、封装响应函数、异常写日志不直接暴露。

接口结构稳定，前端才容易写得稳定。JSON 返回不是简单 echo 一个数组，而是接口规范的一部分。