本文目录导读：
在PHP项目中统一接口返回格式,通常采用JSON格式，并定义一套标准的响应结构，以下是业界常用的规范方案及PHP实现示例：
定义统一响应结构
建议包含以下核心字段：
{
"code": 200,
"message": "success",
"data": {}
}
| 字段 | 类型 | 说明 |
|---|---|---|
code |
int | 业务状态码，非HTTP状态码 |
message |
string | 提示信息 |
data |
mixed | 实际返回数据（对象/数组/null） |
PHP实现方式
1 基础实现（最通用）
<?php
class Response
{
/**
* 成功返回
* @param mixed $data 数据
* @param string $message 提示信息
* @param int $code 状态码
*/
public static function success($data = null, $message = 'success', $code = 200)
{
return self::output($code, $message, $data);
}
/**
* 失败返回
* @param string $message 错误信息
* @param int $code 状态码
* @param mixed $data 可选错误数据
*/
public static function error($message = 'error', $code = 400, $data = null)
{
return self::output($code, $message, $data);
}
/**
* 统一输出
*/
private static function output($code, $message, $data)
{
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
'code' => $code,
'message' => $message,
'data' => $data
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
exit;
}
}
使用示例：
// 成功返回列表
$users = [
['id' => 1, 'name' => '张三'],
['id' => 2, 'name' => '李四']
];
Response::success($users);
// 成功返回单个对象
$user = ['id' => 1, 'name' => '张三'];
Response::success($user);
// 成功无数据
Response::success();
// 错误返回
Response::error('参数缺失', 400);
Response::error('服务器内部错误', 500);
2 使用Trait（多控制器通用）
<?php
trait ApiResponse
{
public function success($data = null, $message = 'success', $code = 200)
{
return response()->json([
'code' => $code,
'message' => $message,
'data' => $data
]);
}
public function error($message = 'error', $code = 400, $data = null)
{
return response()->json([
'code' => $code,
'message' => $message,
'data' => $data
], $code);
}
}
状态码规范建议
常用业务状态码（非HTTP状态码）
| 状态码 | 含义 |
|---|---|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未认证/登录失效 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 422 | 验证失败 |
| 429 | 请求过于频繁 |
| 500 | 服务器内部错误 |
| 1001 | 自定义业务错误1 |
| 1002 | 自定义业务错误2 |
注意： 业务状态码 ≠ HTTP状态码，建议业务统一返回200，通过
code区分业务逻辑；或按实际HTTP语义返回，两者均可。
进阶规范（大型项目推荐）
1 增加分页结构
{
"code": 200,
"message": "success",
"data": {
"list": [],
"total": 100,
"page": 1,
"pageSize": 20
}
}
2 增加时间戳
{
"code": 200,
"message": "success",
"data": {},
"timestamp": 1700000000
}
3 Laravel/Symfony框架使用FormRequest验证
- 自动捕获验证异常,返回统一格式错误
- 示例：
422+ 验证失败详情
异常处理统一化
1 自定义异常类
class ApiException extends \Exception
{
protected $data;
public function __construct($message = "", $code = 400, $data = null)
{
parent::__construct($message, $code);
$this->data = $data;
}
public function getData() { return $this->data; }
}
2 全局异常处理
// Laravel 中在 App\Exceptions\Handler 处理
public function render($request, \Throwable $exception)
{
if ($exception instanceof ApiException) {
return response()->json([
'code' => $exception->getCode(),
'message' => $exception->getMessage(),
'data' => $exception->getData()
]);
}
// 其他异常处理
return parent::render($request, $exception);
}
推荐实践总结
| 实践 | 说明 |
|---|---|
| 统一使用JSON格式 | Content-Type: application/json |
| 固定三字段结构 | code + message + data |
| 所有入口统一使用Response类 | 禁止各处echo json_encode |
| 异常统一捕获并格式化 | 避免返回PHP原生错误 |
| 文档化状态码 | 团队共同维护status codes |
| 开发环境可扩展debug字段 | 但生产环境禁用 |
示例对比
❌ 不规范的返回（多处不一致）
// 接口A
{"status": 1, "msg": "成功", "data": [...]}
// 接口B
{"code": 0, "message": "成功", "result": {...}}
✅ 规范后的返回
// 所有接口统一
{
"code": 200,
"message": "success",
"data": [
{"id": 1, "name": "张三"},
{"id": 2, "name": "李四"}
]
}
通过以上方式,可以确保整个PHP项目的API响应格式高度统一，便于前端消费、团队协作和后期维护。
