最实用的ThinkPHP6.x统一API返回格式方案是：重写Json响应类控制return json()输出、用Trait封装success()/error()提升控制器可读性、中间件兜底异常与验证失败响应。
ThinkPHP6.x 本身不强制统一 API 返回格式，但项目上线后必须统一。核心不是“能不能”，而是“怎么稳、怎么少改、怎么不漏”。最实用的组合是：重写 Json 响应类管住主动调用 + Trait 提供业务层快捷方法 + 中间件兜底异常和验证失败。
重写 Json 响应类，精准控制 return json() 输出
这是最干净的起点，只影响你显式写的 return json($data)，不影响异常流或视图渲染。
- 在
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, 'time' => time()] - 用
json_encode($wrapped, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)编码，避免中文转义和斜杠双转义 - 在
AppServiceProvider::register()中绑定：$this->app->bind('think\response\Json', \app\common\response\Json::class)
用 Trait 封装 success()/error()，提升控制器可读性
控制器里写 return $this->success($user) 比反复拼数组直观得多，也便于后期加字段（如 version、request_id）。
- 在
app\common\traits\ResponseTrait.php定义 trait，提供success($data, $msg = 'ok', $code = 0)和error($msg = 'error', $code = 400, $data = null) - 内部仍调用
json(...)，确保走你重写的 Json 类；不要在__construct或initialize里预设响应逻辑，会干扰模板渲染 - 子控制器
use ResponseTrait后即可直接使用，无需继承特定基类，兼容已有结构
中间件兜底所有非主动 JSON 响应
上面两步只覆盖了 return json() 和 $this->success()，但验证失败、未捕获异常、ValidateException 还是走原生响应路径，结构不一致。
立即学习“PHP免费学习笔记（深入）”；
- 新建中间件
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之后、输出之前
工具类与助手函数作为轻量补充
适合不想动响应类或需跨模块调用的场景，比如命令行任务、事件监听器中返回 API 格式数据。
- 在
app\common\tool\ApiResult.php写静态方法：success($data, $msg = 'ok', $code = 0)、fail($msg = 'fail', $code = -1, $data = null) - 内部一律用
response()->json(...)构造，不依赖控制器上下文，避免$this->json()报错 - 在
app/common.php补充助手函数：function api_success($data = null, $msg = 'ok', $code = 0) { return \app\common\tool\ApiResult::success($data, $msg, $code); }
