ThinkPHP6接口必须用json()函数返回JSON数据，因直接return数组会触发模板渲染或类型错误；统一响应结构应为{"code":200,"msg":"操作成功","data":{}}，需手动封装或继承基类实现。
ThinkPHP 接口必须用 json() 返回，直接 return $data 会触发模板渲染或类型错误；统一结构应为 { "code": 200, "msg": "操作成功", "data": {} }，不能靠框架自动补全，得手动封装或继承基类。
为什么不能直接 return 数组
TP6 的响应机制按返回值类型匹配 Response 子类。直接 return ['code' => 200]，框架识别不出是 JSON，会走视图流程——轻则报 Template not found，重则输出 HTML 源码或空白页。而 json($data) 返回的是 think\Response\Json 实例，自带 Content-Type: application/json; charset=utf-8 响应头，且默认状态码为 200。
- 在中间件或控制器开头调用
$request->withJson(true)（仅 TP6.1+）只影响请求体解析，和返回无关，别混淆 - 若用了
echo json_encode(...); die;，响应头没设、中文可能乱码、fetch().json()会抛Unexpected token - TP5.1 的
json()不默认启用JSON_UNESCAPED_UNICODE，中文会被转成\u4f60，必须显式传参：json($data, 200, [], ['json_encode_param' => JSON_UNESCAPED_UNICODE])
怎么封装统一返回结构
硬编码每个接口的 json(['code'=>200, 'msg'=>'xxx', 'data'=>$x]) 不可持续。推荐两种落地方式：
- 在
app/common.php定义助手函数：function api($code = 200, $msg = '操作成功', $data = null, $httpCode = 200) { return json(['code' => $code, 'msg' => $msg, 'data' => $data])->code($httpCode); }，控制器中直接return api(200, 'ok', $user); - 建
BaseController，定义success($data, $msg = '操作成功')和error($msg, $code = 400)方法，子控制器继承后调用$this->success($user) - 避免用
ajaxReturn()（TP5.1 已废弃），继续用会报Method not found: think\Response::ajaxReturn
带语言标识和 HTTP 状态码的细节处理
多语言 API 不能依赖 json() 自动翻译文案，lang('success') 得手动调用；语言标识建议塞进 JSON body，而不是只靠响应头：
立即学习“PHP免费学习笔记（深入）”；
- 返回时显式加
'lang' => app()->getLocale()字段，app()->getLocale()是运行时实际语言码（如zh-cn），不是配置里的默认值 - HTTP 状态码和业务 code 要分清：权限拒绝该用
throw new \think\exception\HttpException(403, '无操作权限')，表单验证失败需手动return json(['code'=>422, 'msg'=>$validate->getError()])->code(422) - 中间件（如跨域、日志）可能覆盖
Content-Type，可在控制器末尾加dump(response()->getHeader('Content-Type'))排查；跨域请用allowCrossDomain()，别混用header('Access-Control-Allow-Origin: *')
最容易被忽略的是：语言包必须 UTF-8 无 BOM；json() 不接受资源类型（如 PDOStatement 或 mysqli_result），传之前得先 fetchAll()；DateTime 对象会自动转字符串，要自定义格式得先 format('Y-m-d H:i:s')。
