跳到主要内容
万能墙开放平台
插件开发教程

注册 API 接口

全部内容基于万能墙真实的插件平台(清单 + 钩子 + 接口 + 后台页 + 数据 + 定时任务),示例可直接复制运行。

最小例子

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,自检会报「写接口没交代参数」。