必须用 UniformJsonResponse 全局中间件拦截响应，因其在响应生成出口前执行，可统一处理验证失败、路由未匹配等所有情况；需按顺序注册在 ResponseTrace 之后、CheckRequestCache 之前，并手动控制 json_encode 的 flags 以避免中文转义。
必须用 UniformJsonResponse 中间件拦截最终响应体
只靠 ExceptionHandler::render() 无法统一所有接口返回格式，因为它在生命周期末尾才执行，而验证失败、路由未匹配等框架级异常早被其他中间件处理并输出了 HTML 或原始错误；真正能稳定拦截全部响应类型的，只有在「响应生成出口前」注册的全局中间件。
关键动作是：在中间件 handle() 方法中调用 $next($request) 获取原始响应，再判断是否为非 JSON 响应，强制封装成标准 JSON 结构。
- 必须用
json($data, $code)->header(...)构造新\think\response\Json对象，不能直接return $array，否则框架会 fallback 成 HTML 响应 - 若原始响应已是
\think\response\Json实例（比如控制器里写了return json(...)），跳过重包装，避免重复编码 -
$response->getData()取出原始数据后，优先检查是否已含code字段——有些业务层已手动返回结构化数组，应保留原意，不强行覆盖
中间件注册顺序决定能否拿到真实响应
UniformJsonResponse 必须放在 \think\middleware\ResponseTrace::class 之后、\think\middleware\CheckRequestCache::class 之前。位置太靠前，$request->controller() 和 $response->getData() 可能为空或不完整；位置太靠后，缓存中间件可能已截断输出，导致你的 JSON 封装失效。
在 app/middleware.php 中确认顺序类似这样：
立即学习“PHP免费学习笔记（深入）”；
return [
\app\middleware\UniformJsonResponse::class,
\think\middleware\ResponseTrace::class,
\think\middleware\CheckRequestCache::class,
// 其他中间件...
];
- 不要把它塞进路由级中间件（如
Route::rule(...)->middleware(...)），那只能覆盖部分路由 - 别和
AllowCrossDomain等头操作类中间件冲突——JSON 封装后记得显式设置Content-Type: application/json; charset=utf-8 - TP8.1+ 支持中间件分组，可将它归入
api组，但需确保该组在全局 HTTP 链中实际生效
中文不转义要从 json_encode 底层控制
即使响应已是 JSON 格式，中文默认仍会被编码成 \uXXXX。这不是中间件能绕开的问题，得从 PHP 的 json_encode() 行为入手。
最稳妥的方式是在 config/app.php 加配置（TP6.1+ 支持）：
'json_encode' => [
'flags' => JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES,
],
- 旧版 TP6.0 不识别该配置项，只能在中间件里手动调用
json_encode($data, JSON_UNESCAPED_UNICODE)并构造响应对象 - 注意：
json_encode()返回字符串，必须配合response($str)->header(...)，不能传给json()函数二次编码 - 别漏掉
JSON_UNESCAPED_SLASHES，否则/会被转成\/，对前端解析虽无害，但日志和调试体验差
别让 post() 和 param() 返回不一致
如果你在同一个中间件里做了参数清洗（比如 trim 白名单字段），又依赖 $request->post() 读取数据，大概率会拿到旧值——因为 post() 是只读缓存，首次调用即固化，merge() 或 setPost() 不影响它。
- 推荐方案：全程只用
$request->param()，它受merge()影响，行为可预期 - TP8.0+ 可调用
$request->setPost($cleaned)同步更新，但需确认框架版本，低版本无此方法 - 绝对避免控制器里先调
post()再调param()，两处读到的数据可能不一致，引发隐藏 bug
统一返回格式这事，难点不在写几行代码，而在理清「谁在什么时候拿到了什么数据」。中间件链的执行时机、响应对象的生命周期、PHP 原生 JSON 编码的默认行为——三者叠在一起，少盯住一个点，就容易出现前端看到 HTML 错误页、中文乱码、或字段值莫名被截空的情况。
