🔌 标准接口

ThinkAdmin 控制器默认通过 success() / error() 输出 JSON 响应。账号插件在此基础上提供终端账号、登录令牌和受保护接口基类。

本页只说明框架响应格式与账号插件接口约定。服务端之间的签名 POST 调用请查看签名接口。

基础响应

think\admin\Controller::success() 和 error() 输出固定 JSON 结构：

{
    "code": 1,
    "info": "操作成功",
    "data": {}
}

字段含义：

字段	说明
`code`	状态码，默认成功为 `1`，失败为 `0`
`info`	提示信息
`data`	返回数据，未传数据时为空对象
`token`	仅当 `JwtExtend::isRejwt()` 为真时附加

error() 实际调用 success($info, $data, 0)，因此响应结构与 success() 一致。

请求提交

普通接口参数来自 ThinkPHP 请求对象，常见提交方式包括 GET、POST 表单和 JSON。账号插件登录、短信、资料等接口主要按表单参数读取。

文件上传不要混用到标准业务接口中。后台上传组件走 /admin/api.upload/*，大文件或云存储直传可参考文件上传。

账号插件接口

账号插件接口路由使用插件前缀 plugin-account，常见接口包括：

接口	说明
`/plugin-account/api.login/in`	手机验证码登录
`/plugin-account/api.login/auto`	自动授权登录
`/plugin-account/api.login/pass`	手机密码登录
`/plugin-account/api.login/register`	手机注册绑定
`/plugin-account/api.login/forget`	短信找回密码
`/plugin-account/api.login/send`	发送短信验证码
`/plugin-account/api.login/image`	生成拼图验证码
`/plugin-account/api.login/verify`	验证拼图结果
`/plugin-account/api.auth.center/get`	获取当前账号资料
`/plugin-account/api.auth.center/set`	修改账号资料
`/plugin-account/api.auth.center/bind`	绑定主账号
`/plugin-account/api.auth.center/unbind`	解除主账号绑定
`/plugin-account/api.auth.center/forbid`	注销当前账号

微信相关接口由 api.wxapp 和 api.wechat 控制器提供，是否可用取决于微信插件和对应配置。

账号令牌

登录或授权接口在调用 get(true) 返回账号资料时，响应 data.token 为账号插件生成的授权令牌。当前实现中该值通常是由 JwtExtend::token() 包装过的 JWT，JWT 内部保存账号插件的终端类型和授权记录 token；未请求重新生成令牌的接口可能只返回账号资料，不一定包含 token 字段。

受保护接口继承 plugin\account\controller\api\Auth，初始化时按以下顺序读取令牌：

Authorization: Bearer your_token
api-token: your_token

示例：

GET /plugin-account/api.auth.center/get HTTP/1.1
Authorization: Bearer your_token

或：

GET /plugin-account/api.auth.center/get HTTP/1.1
api-token: your_token

注意：框架中间件 JwtSession 读取的是 jwt-token 请求头，用于恢复框架会话；账号插件受保护接口读取的是 Authorization Bearer 或 api-token。两者不是同一个入口。

终端类型

账号插件内置终端类型来自 plugin\account\service\Account：

类型	说明	默认识别字段
`wap`	手机浏览器	`phone`
`web`	电脑浏览器	`phone`
`wxapp`	微信小程序	`openid`
`wechat`	微信服务号	`openid`
`iosapp`	苹果 APP 应用	`phone`
`android`	安卓 APP 应用	`phone`

手机验证码登录和密码登录要求提交 type，并且该类型当前启用且识别字段为 phone。

状态码

框架本身只约定 success() 默认 code=1、error() 默认 code=0。账号插件受保护接口中还会使用这些状态码：

code	来源	含义
`401`	缺少令牌、令牌无效、账号不存在等	需要重新登录
`402`	已登录但未绑定正式账号	需要绑定或补全资料
`403`	授权过期、终端冻结、主账号冻结	不允许继续访问

其他接口可按业务自行定义 code，客户端不应只按 HTTP 状态判断业务结果。

请求示例

登录后访问账号资料：

$.ajax({
    url: 'https://your-domain.com/plugin-account/api.auth.center/get',
    type: 'GET',
    headers: {
        Authorization: 'Bearer ' + token
    },
    dataType: 'json',
    success: function (ret) {
        if (ret.code === 1) {
            console.log(ret.data);
        } else if (ret.code === 401 || ret.code === 403) {
            console.warn('需要重新登录：', ret.info);
        } else if (ret.code === 402) {
            console.warn('需要绑定资料：', ret.info);
        } else {
            console.warn(ret.info);
        }
    }
});

手机号验证码登录：

$.ajax({
    url: 'https://your-domain.com/plugin-account/api.login/in',
    type: 'POST',
    dataType: 'json',
    data: {
        type: 'wap',
        phone: '13800138000',
        verify: '1234'
    },
    success: function (ret) {
        if (ret.code === 1) {
            localStorage.setItem('account_token', ret.data.token);
        }
    }
});

接入建议

账号插件接口优先使用 Authorization: Bearer ...，兼容 api-token。
客户端保存的是账号插件返回的 data.token，不要把框架 jwt-token 会话头和账号插件令牌混用。
受保护接口里可通过继承 plugin\account\controller\api\Auth 获取 $this->account、$this->unid、$this->usid 和 $this->type。
终端冻结、资料未绑定、授权过期等状态由账号插件基类和 checkUserStatus() 判断；具体业务仍需自行做权限和数据归属校验。