ThinkPHP怎样统一API响应格式_API响应格式方法【详解】

必须分层拦截：重写Json类控制主动json()输出，中间件兜底异常响应，Trait封装success()/error()方法，并在所有环节判断CLI环境避免header错误。

直接改 json() 函数或配置项？那只能管一小半。因为 return json($data)、异常抛出、验证失败、success()/error() 方法，走的是完全不同的响应生成路径。要统一格式，必须分层拦截：类替换管住主动调用，中间件兜底异常，Trait 或函数封装收口业务逻辑。

重写 think\response\Json 类控制主动 json() 输出

这是最干净的起点，只影响你显式调用 json() 的地方（比如 return json($data)），不碰异常流。关键不是“继承后大改”，而是精准重写 output() 方法，把原始数据包进标准结构里。

• 在 app\common\response\Json.php 中定义新类，namespace app\common\response;，继承 think\response\Json
• 只重写 protected function output($data): string，构造 ['code' => $this->code, 'msg' => $this->message, 'data' => $data] 后 json_encode(..., JSON_UNESCAPED_UNICODE)
• 在 AppServiceProvider::register() 里绑定：$this->app->bind('think\response\Json', \app\common\response\Json::class);
• 别动 __construct 或 init —— $this->code 和 $this->message 是框架根据 json($data, 200, [], ['code' => 1]) 第四个参数自动设的，破坏它会导致 return json($data, 400) 失效

用中间件兜底所有非 Json 响应（异常、验证失败等）

上面只管住了 return json()，但 throw new ValidateException()、未捕获异常、HttpException 仍走原生 think\response\Json 或 Html，结构不一致。必须在响应发出前做一次“强制统一封装”。

• 新建中间件 app\middleware\UniformJsonResponse，handle() 中检查 $response instanceof \think\Response 且不是 Json 实例
• 若响应体是数组（如异常默认结构），提取 ['code' => ..., 'msg' => ..., 'data' => ...]；若不是，统一包装为 ['code' => 500, 'msg' => 'server error', 'data' => null]
• 用 json($wrapped)->header(['Content-Type' => 'application/json; charset=utf-8']) 替换原响应
• 注册为全局中间件，确保它在 ResponseTrace 之后、输出之前执行

用 Trait 封装业务层 success()/error() 方法

控制器里写 return $this->success($user) 比反复调用 json() 更直观，也更容易统一字段（比如加 timestamp、version）。但注意：Trait 只是语法糖，底层仍要走你重写的 Json 类或中间件。

• 在 app\common\traits\ResponseTrait.php 中定义 success($data, $msg = 'ok', $code = 200) 和 error($msg = 'error', $code = 400, $data = null)
• 两个方法都返回 json(['code' => $code, 'msg' => $msg, 'data' => $data, 'timestamp' => time()]) —— 这样会触发你重写的 Json::output()
• 在 BaseController 中 use 该 Trait，并确保控制器方法以 return $this->success(...) 结尾
• 不要在 Trait 里做敏感字段过滤（如删 password），那是 service 层或 DTO 组装时的事；ResponseTrait 只负责格式，不负责数据净化

CLI 场景必须单独处理，否则会报错

命令行下 json() 会尝试设置 HTTP header，触发 headers already sent 错误。所有封装层（类重写、中间件、Trait）都得先判断运行环境。

• 在 Json::output() 开头加：if (php_sapi_name() === 'cli') { return json_encode([...], JSON_UNESCAPED_UNICODE); }
• 中间件里加同样判断，CLI 下直接放行原响应，不包装、不设 header
• Trait 中的 success()/error() 不要直接调用 json()，改用 response()->json(...) 并手动处理 CLI 分支
• 别依赖 IS_CLI 常量 —— ThinkPHP 6 不定义它，用 php_sapi_name() === 'cli' 更可靠

最易被忽略的是异常链路和 CLI 兼容性：90% 的人只改了 json()，结果验证失败返回 {"code":0,"msg":"validate error","data":{}}，而 throw new Exception() 返回 {"code":500,"msg":"Internal Server Error","data":null}，结构看着像但字段名（msg vs message）、空值处理（null vs []）全都不一致；CLI 下一旦漏判，整个命令就卡死在 header 错误里。