12 API 与路由

路由规则

ThinkPHP 多应用 约定路由（config/route.php 中 url_route_must = false）：

/{app}/{Controller}/{action}

示例：

GET  /admin/addon/index?type=addon
POST /admin/marketplace/install
GET  /home/content/siteConfig
POST /api/notify/callback?gateway=alipay_1

route/app.php 还定义了：

路径	用途
/ · /ping	首页提示 / 探活
/gateway/{plugin}/...	魔方支付兼容
/console/module/... · /admin/module/...	魔方 server 模块
/setup/...	安装向导 API
/license/...	授权状态

插件对接全量 API（管理、市场、支付/短信/实名、自定义 REST）：见 04b 插件对接 API。

---

开发服务器分流（router.php）

请求	处理
真实静态文件	直接返回
/admin/{ctrl}/{action}	ThinkPHP
`/home	api
/tpl/*	主题 SSR
/admin/* 其他	后台 SPA index.html
其余	前台 SPA index.html

生产环境由 Nginx 实现相同规则，见 13-deploy。

---

响应格式

统一 JSON（ApiResponse trait）：

{
  "status": 200,
  "msg": "ok",
  "data": { }
}

错误：status 4xx/5xx，msg 为可读信息。

---

鉴权

应用	方式
admin	Header Authorization: Bearer {token}
home 会员接口	同上（UserAuth 中间件）
home 公开接口	无 token（siteConfig、banners 等）

---

后台权限模块

AdminPermissionService::MODULES 定义模块键，控制器映射见 CONTROLLER_MAP。

插件相关：

• Addon、Marketplace → 需 plugin 权限

---

常用公开 API

接口	说明
GET /home/content/siteConfig	站点+主题 bundle
GET /home/content/banners	轮播
GET /ping	探活

---

支付 / 实名回调

POST|GET /api/notify/callback?gateway={网关实例 name}
POST|GET /api/notify/sync?gateway=&invoice=
GET      /api/notify/status?invoice=
POST|GET /api/notify/realname
GET|POST /gateway/{plugin}/[controller/[action]]   # 魔方兼容

支付由 PaymentService::handleNotify() 验签入账；实名见 07 / 04b §8。

---

下一章：13-deploy