必须分层拦截：重写Json类控制主动json()输出，中间件兜底异常响应，Trait封装success()/error()方法，并在所有环节判断CLI环境避免header错误。
直接改 json() 函数或配置项无法真正统一 ThinkPHP 的 API 响应格式——因为 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 类或中间件。
立即学习“PHP免费学习笔记（深入）”；
- 在
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 错误里。
