最小例子
php
registerApiRoute('my_stats', [
'method' => 'GET', // GET | POST | ANY
'auth' => 'none', // none | login
'admin' => false, // true = 仅管理员可调用
'desc' => '返回本站统计(示例)',
'params' => [
'days' => 'int 统计天数,默认 7',
],
], function ($ctx) {
$days = max(1, min(90, (int)($ctx['input']['days'] ?? 7)));
return ['days' => $days, 'ok' => true];
});访问:api?action=my_stats&days=30。
回调能拿到什么($ctx)
| 键 | 说明 |
| --- | --- |
| $ctx['db'] | PDO 连接(已连好当前站点数据库) |
| $ctx['action'] | 当前 action 名 |
| $ctx['input'] | 合并后的入参(GET + POST) |
| $ctx['user_id'] | 当前登录用户 ID(0 = 未登录) |
| $ctx['is_admin'] | 是否管理员 |
| $ctx['method'] | GET / POST |
返回值
- 直接
return ['key' => 'value'];→ 自动包成统一响应:
json
{ "success": true, "code": "OK", "api_version": "1", "data": { "key": "value" } }- 想自定义错误:
return ['ok' => false, 'error' => '参数不对', 'code' => 'BAD_PARAM']; - 想直接输出并结束:
echo json_encode(...); exit;(不推荐,除非你在做流式输出)
鉴权与参数说明
| 选项 | 说明 |
| --- | --- |
| 'auth' => 'login' | 未登录访问会被拦下并提示「请先登录」 |
| 'admin' => true | 需要管理员身份 |
| 'params' => [...] | 写进接口文档;每个写接口都要写参数说明,确实无参数就声明 'no_params' => true |
| 'module' => 'chat' | 绑定模块开关:模块被关掉时该接口返回 MODULE_CLOSED |
命名与冲突
- action 名只允许小写字母、数字、下划线,2~40 位;
- 建议加插件前缀(
my_plugin_xxx),避免与核心或别的插件重名; - 冲突时后加载的插件会覆盖前面的注册 —— 用
priority控制加载顺序,或在文档里写清依赖。
接口文档自动生成
只要声明了 desc(和参数),你的接口就会出现在万能墙后台「API 与插件 → 接口文档」里,
并计入接口覆盖率自检。若声明了写接口却没写参数说明、也没有 no_params,自检会报「写接口没交代参数」。