TP5中不能直接调用$this->json()，因json()是think\Response的静态方法而非控制器实例方法；必须用return json($data)并推荐封装BaseController或ApiResponse Trait统一响应格式。
json() 在 ThinkPHP5 里不是控制器方法，直接写 $this->json($data) 会报错：`Call to undefined method app\controller\User::json()`。必须用 return json($data)，但裸用它不带状态码、消息字段，也不处理模型序列化失败。
为什么不能直接在控制器里调用 json() 方法
因为 json() 是 think\Response 类的静态方法，不是控制器基类 think\Controller 的实例方法。TP5 的控制器默认不继承响应类，所以 $this->json() 语法非法。
常见错误还有两种：
- 误以为
json($data)是全局函数——其实它是think\Response::json()的别名，需通过return触发输出 - 混用
return $this->success()（TP5 内置）和手动json()，导致前端解析时结构不一致（前者是['code'=>1,'msg'=>'ok','data'=>...]，后者是纯data）
推荐做法：封装 BaseController 统一输出方法
新建 app/common/controller/BaseController.php，让所有 API 控制器继承它：
namespace app\common\controller;
use think\Controller;
class BaseController extends Controller
{
protected function success($data = [], $msg = '请求成功', $code = 200)
{
return json(['code' => $code, 'msg' => $msg, 'data' => $data]);
}
protected function fail($msg = '操作失败', $data = [], $code = 500)
{
return json(['code' => $code, 'msg' => $msg, 'data' => $data]);
}
}
关键点：
立即学习“PHP免费学习笔记（深入）”；
- 不要在方法里用
echo+exit，TP5 的json()已自动设置Content-Type并终止后续执行 - 避免在
success()里硬编码code => 1，TP5 官方示例常用1，但行业通用是200表示 HTTP 成功，业务码另放errorCode字段更清晰 - 如果返回模型对象（如
UserModel::find(1)），确保模型没挂载资源句柄或闭包，否则json()会抛出Object of class could not be converted to string
进阶：用 Trait 替代继承，解耦更灵活
若项目已有控制器继承链（比如已继承了某个权限基类），就不能再 extends BaseController。此时改用 Trait：
namespace app\common\traits;
use think\Response;
trait ApiResponse
{
protected function apiSuccess($data = [], $msg = '成功', $code = 200)
{
return Response::json(['code' => $code, 'msg' => $msg, 'data' => $data]);
}
protected function apiFail($msg = '失败', $data = [], $code = 400)
{
return Response::json(['code' => $code, 'msg' => $msg, 'data' => $data]);
}
}
在控制器中使用：
use app\common\traits\ApiResponse;
class UserController extends Controller
{
use ApiResponse;
public function index()
{
return $this->apiSuccess(['users' => User::select()]);
}
}
注意：
- Trait 中必须显式调用
Response::json()，不能省略命名空间，否则会找错类 - TP5.0 和 TP5.1 的
Response::json()参数签名一致，但 TP5.0 不支持传入 HTTP 状态码第二参数，只能靠 header 手动设；TP5.1+ 支持Response::json($data, 200) - 别在 Trait 方法里做日志记录或异常捕获——那是中间件或全局异常处理器的事
容易被忽略的序列化陷阱
TP5 的 json() 底层调用 json_encode()，对以下类型直接失败：
- 未定义
__toString()的对象（如原始 PDOStatement） - 资源类型（
resource，比如fopen()返回值） - 包含循环引用的数组/对象
解决方案不是在响应层兜底，而是在数据组装阶段过滤：
- 模型查询后用
toArray()而非直接传对象 - 敏感字段（如
password）必须在组装$data前用unset()或only()显式剔除，别指望响应函数自动识别 - 若真要加 JSON 安全包装，建议在
BaseController的success()里加 try/catch，捕获JsonException后 fallback 到空数组并记录 warning 日志
真正难处理的不是格式统一，而是数据源头是否干净——响应层越薄，越可靠。
