API 规范

前后端统一走 JSON 信封，由 core\response\Api 组装。

响应体

{
  "code": 200,
  "message": "ok",
  "data": {},
  "timestamp": 1710000000
}

字段	含义
code	业务码。成功一般为 200
message	提示文案（经 lang()）
data	载荷；失败时也可能带结构化信息
timestamp	Unix 秒

业务错误 HTTP 仍为 200，靠 body 里的 code 区分（如未登录 401、无权限 403）。未捕获异常才是 HTTP 500。少数场景（未安装 503、真正的 404 路由）用 Api::errorWithStatus() 让 HTTP 状态跟随业务码。

校验失败

code 为 422，data.errors 为「字段 → 消息」：

{
  "code": 422,
  "message": "名称不能为空",
  "data": {
    "errors": {
      "name": "名称不能为空"
    }
  },
  "timestamp": 1710000000
}

由 ValidationException 经 app\exception\Handler 转成上述形状。

分页

列表的 data 为：

{
  "list": [],
  "pagination": {
    "current_page": 1,
    "per_page": 15,
    "total": 100,
    "last_page": 7
  }
}

入参使用 page / limit（控制器基类同时兼容 page_no / page_size）。

JWT 两个 scope

Scope	中间件	用途
admin	AdminAuthMiddleware	管理端 /adminapi
user	ApiAuthMiddleware	用户端 /api

两端 token 不可混用：管理端只验 admin，用户端只验 user。