统一响应格式包含状态码、消息和数据，通过封装Response类和全局异常处理，确保API返回一致结构，提升系统健壮性和前后端协作效率。1. 定义标准响应体{code, message, data}；2. 封装success/fail静态方法并输出JSON；3. 设置异常和错误处理器转换为统一格式；4. 控制器中调用Response终止脚本，避免重复输出。
在PHP开发中，尤其是构建API接口时，统一响应格式能提升前后端协作效率，增强错误排查能力。一个标准的响应体通常包含状态码（code）、消息（message）和数据（data），同时配合异常处理机制，使系统更健壮。
1. 定义统一响应格式
建议所有接口返回结构一致的数据，例如：
{
"code": 200,
"message": "请求成功",
"data": {}
}
其中：
- code：业务状态码，如200表示成功，400表示参数错误，500表示服务器异常
- message：提示信息，用于前端展示或调试
- data：实际返回的数据内容，可以是数组、对象或null
2. 封装响应类 Response
创建一个静态类来封装常用响应方法：
立即学习“PHP免费学习笔记（深入）”；
class Response {
public static function success($data = null, $message = '请求成功', $code = 200) {
http_response_code(200);
header('Content-Type: application/json');
echo json_encode([
'code' => $code,
'message' => $message,
'data' => $data
], JSON_UNESCAPED_UNICODE | JSON_NUMERIC_CHECK);
exit;
}
public static function fail($message = '请求失败', $code = 400, $data = null) {
http_response_code(200); // 保持HTTP状态码为200，避免被网关拦截
header('Content-Type: application/json');
echo json_encode([
'code' => $code,
'message' => $message,
'data' => $data
], JSON_UNESCAPED_UNICODE | JSON_NUMERIC_CHECK);
exit;
}
}
使用示例：
// 成功返回
Response::success(['id' => 1, 'name' => '张三']);
// 失败返回
Response::fail('用户不存在', 404);
3. 全局异常处理捕获错误
通过设置异常处理器，将未捕获的异常也转为统一格式输出：
function exceptionHandler($exception) {
Response::fail(
'系统内部错误，请稍后重试',
500,
[
'debug_message' => $exception->getMessage(),
'file' => $exception->getFile(),
'line' => $exception->getLine()
]
);
}
function errorHandler($severity, $message, $file, $line) {
if (!(error_reporting() & $severity)) {
return;
}
throw new ErrorException($message, 0, $severity, $file, $line);
}
set_exception_handler('exceptionHandler');
set_error_handler('errorHandler');
这样即使出现致命错误或手动抛出异常，也能以标准格式返回，避免暴露原始错误信息。
4. 结合控制器使用示例
在实际业务逻辑中调用：
class UserController {
public function getUser($id) {
if (!$id) {
Response::fail('缺少用户ID', 400);
}
// 模拟查询
$user = ['id' => $id, 'name' => '测试用户'];
if (!$user) {
Response::fail('用户不存在', 404);
}
Response::success($user);
}
}
基本上就这些。通过封装Response类和全局异常处理，可以让PHP接口始终返回一致格式，提升可维护性和用户体验。关键是尽早退出脚本（exit），防止后续代码执行造成重复输出。
