跳到主要内容

第 16 期 · M3 第三部分:管理类兼容接口

· 阅读需 4 分钟

M3 第三部分补上了 Blessing Skin OAuth 资源 API 的最后一块:/api/admin/*。管理员的脚本和面板可以用应用令牌或个人访问令牌管理用户、角色、衣柜、举报,发送通知。到这里,BS 第三方应用能调用的接口都已兼容。

本期完成​

  • 用户:列表(q 搜索、page 翻页)、改邮箱、切换邮箱验证、改昵称、改密码、改积分、改权限(-1 / 0 / 1)、删除。
  • 角色:列表(q=uid:N 查某个用户的角色)、改名、转移、换材质、删除。
  • 衣柜:查看某个用户的衣柜、免费放入、取出。
  • 举报:列表(q=status:0 等)、处理(删除材质、封禁上传者、驳回)。
  • 通知:发给所有人、普通用户、某个 ID 或邮箱。
  • 设计记录:ADR 0024;开放平台页面增加了管理类接口。

一套逻辑,两种接口​

BS 的管理端页面、用户端和 OAuth API 各写一份逻辑,行为不一样:OAuth API 换材质不检查类型,发通知后返回一个 302 跳转。这次兼容层不直接查库,而是调用后台页面用的同一批服务:

  • 处理举报、发通知、角色改名与转移原来写在 /api/v1 的处理函数里,抽成共用函数,两套接口都调用,审计日志里看到的是同样的记录;
  • 权限规则不变:管理员只管普通用户,超级管理员管所有人,谁都不能改自己的权限;
  • 管理类 scope 只有管理员能授予;令牌主人被降为普通用户后,令牌立即不能再调用这些接口。

为了 BS 的分页格式(页码加总数),用户、角色、举报三个列表的过滤条件增加了偏移量和计数,后台页面仍然用游标翻页。

开发中的小插曲​

  • 测试里封禁 alice 之后,她的个人访问令牌返回 401 而不是预期的 403。原因是封禁会吊销用户的全部令牌(上一期的改动),令牌已经不存在了,这是对的,改的是测试。同理,她的网页登录也被退出了,测试要重新登录。
  • 跑测试时 C 盘被占满(VS Code 的更新下载占了约 1 GB),工具输出开始被截断。征得同意清理后继续,之后的测试临时文件都放在 E 盘。

本地实测(skinloom up --dev)​

初始化站点后,超级管理员创建一个带管理类 scope 的个人访问令牌,alice 注册并创建角色 Steve。用 curl:

  1. GET /api/admin/users?q=alice:Laravel 分页格式,用户对象带 ip。
  2. 把 alice 的积分设为 321:返回 {"code":0},alice 自己看到的积分是 321。
  3. GET /api/admin/players?q=uid:2 列出 Steve;改名为 Steve_Admin 成功。
  4. alice 的衣柜和举报列表为空时返回空数组和空分页。
  5. 给 alice 发通知:返回 {"code":0},alice 的未读数是 1。
  6. 修改自己的权限:403,{"code":1,"message":"你没有权限这么做。"}。

服务端日志没有警告或错误。

测试​

  • HTTP(SQLite 与 PostgreSQL 都跑):
    • 普通用户不能创建管理类令牌,普通用户的令牌调用管理接口 403;
    • 用户列表的搜索与翻页,昵称、积分、验证状态、封禁与解封、设为管理员,不能设超级管理员;管理员不能改自己、不能改超级管理员,可以改普通用户;
    • 角色按主人筛选、改名、不存在的材质、不存在的新主人、转移、删除;
    • 衣柜放入、重复放入、查看、取出、重复取出;
    • 举报列表的形状与筛选、驳回、重复处理;
    • 通知按 ID、按不存在的邮箱、给普通用户;
    • 被降级的管理员的令牌 403;审计日志里有对应记录。
  • 全量回归:
    • Go:go test ./...(SQLite 与 PostgreSQL)、vet、staticcheck、govulncheck;
    • 生成代码无差异、迁移无漂移。

问题与风险​

  • BS 完整的 search-string 语法(排序、比较、多个条件)不支持,只认第一个 字段:值 和普通文字。
  • 和前两部分一样,没有用真实的 BS 管理面板或脚本实际接过。

下期计划​

M3 最后一部分:社交登录(GitHub、Microsoft 等通用 OAuth2 / OIDC 登录)。