PHP项目接口返回格式如何统一规范

本文目录导读：

1. 定义统一响应结构
2. PHP实现方式
3. 状态码规范建议
4. 进阶规范（大型项目推荐）
5. 异常处理统一化
6. 推荐实践总结
7. 示例对比

在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响应格式高度统一，便于前端消费、团队协作和后期维护。