响应与接口前缀
2026/10/26大约 3 分钟
响应与接口前缀
统一响应结构、状态码与路由前缀的速查表。所有内容由 am-serve/app/functions.php、am-web/src/utils/http 实际代码核对而来。
统一响应体
后端所有 JSON 接口返回同一结构，由 ret()（及其封装 success() / warning() / error()）生成：
{
"code": 200,
"msg": "操作成功",
"total": 0,
"data": {},
"page": 1
}| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码，见下表。前端只按它分流 |
msg | string | 提示文案。键名是 msg 不是 message |
total | int | 列表分页总数，非列表接口为 0 |
data | mixed | 业务数据负载 |
page | int | 当前页码，非列表接口为 1 |
msg 而非 message
am-web/src/utils/http/index.ts 的响应拦截器读 response.data.msg 做成功/失败提示；写成 message 取不到文案。示例插件 am_demo 的部分接口手写了 'message' => 'ok'，是图省事的偏离，不要照抄。
对应 helper：
return success('操作成功', $data, $total, $page); // code 200
return warning('参数错误'); // code 400，msg 为空时回落 trans('system.fail')
return error('写库失败'); // code 500，msg 前缀 trans('system.error')状态码
code 取值（与 am-web/src/utils/http/status.ts 的 ApiStatus 对齐）：
| code | 含义 | 前端处理 |
|---|---|---|
200 | 成功 | 放行，按需弹 msg 成功提示 |
400 | 参数/业务错误（warning） | 弹 msg 警告 |
401 | 未登录 / token 失效（unauthorized） | 触发登出、跳登录 |
403 | 已登录但无权限（forbidden） | 提示无权访问 |
500 | 服务器错误（error） | 弹错误提示 |
会员鉴权也用 msg
插件会员鉴权 MemberAuth 的错误体同样用 msg：未登录 {code:401,msg:'请先登录'}、非会员 {code:403,msg:'当前账号无权访问会员内容'}。
JWT 与鉴权头
- 登录成功返回
accessToken、refreshToken（tinywan/jwt，形如Bearer xxx）与用户payload，exp默认time() + 7200（2 小时）。 - payload 关键字段：
id、sid、username、nickname、avatar、account_type、is_admin。is_admin只是便捷标记（超管id===1或account_type为管理员得出），能否操作具体功能仍由 RBAC 查库权威判定。 - 请求携
token头（Bearer前缀会被剥离）；基座AuthCheck中间件校验有效性。
接口前缀
路由前缀按"是否需要登录 / 归谁管"分层，#[RouteGroup] 声明类级前缀、方法级 Get/Post 拼子路径：
| 前缀 | 归属 | 鉴权 |
|---|---|---|
/pub/* | 公开接口（如 /pub/auth/login、/pub/auth/captcha） | 免登录（$noNeedLogin） |
/sys/* | 基座系统管理：user/role/dept/menu/config/dict/tags/remote/file/storage/dashboard/server/systemInfo/log/loginLog/backup/cache | 登录 + #[Permission] RBAC |
/notify/* | 通知中心：template/inbox/log/preference/sms-provider | 登录 + RBAC |
/plugin/* | 插件管理后台：app（装配/依赖/可见范围）、store（应用插件、主程序升级、授权） | 登录 + RBAC |
/oauth/* | 免登票据：ticket/issue（需基座登录态）、ticket/consume（后端服务器间）、ticket/exchange（前端同域换主 JWT，白名单） | 见各端点 |
/app/{name}/* | 插件自身的页面入口与业务接口 | 由插件 $noNeedLogin 与会员鉴权决定 |
页面入口例外
/app/{name}、/app/{name}/manage 这类无尾斜杠页面入口注解生成不了，必须在插件 config/route.php 手动 Route::get 注册。详见控制器与路由。