API v1 基本定义 - geekapk-r/ServerR GitHub Wiki

哪些是通知

GeekApk 里,通知 作为一种对 用户 的提醒而存在,一般在 动作执行后 直接保存等待用户阅读,GeekApk 中有这些通知:

  • 用户评论回复 的通知
  • 用户@ 提到 的通知
  • 用户用户 跟随 的通知
  • 用户评论星标 的通知

Timeline(时间线)

类似 GitHub,GeekApk 也会记录每个 用户 的公开活动并允许所有人自由查询,这个特性被称为 Timeline(时间线),GeekApk 中有这些时间线记录:

  • 用户 Follow 了某个 用户
  • 用户 Star 了某个 评论
  • 用户 创建了 某个 评论
  • 用户 更新了 某个 评论
  • 用户 发布了 某个 应用
  • 用户 发布了 某个 应用更新
  • 用户 删除了 某个 应用
  • 用户 Star 了某个 应用

WebHooks

GeekApk 可以与 第三方服务 进行 集成,服务端使用的支持方式就是 WebHooks

WebHooks 可以让 GeekApk 服务器在进行某种操作后 通知 外部服务进行相应的处理

GeekApk 目前支持 3WebHooks

  • replyToMessage 在回复指定 评论 时触发
  • commentApp 在回复指定 应用 时触发
  • newUser 在添加一个 用户 时触发

GeekApk 服务器内部使用 环境变量 存储 WebHooks 设置,同时,要应用新 WebHooks 设置需要 重启服务器

WEBHOOKS='replyToMessage:2333:https://bar.org/bot;commentApp:23:https://geekbot.com/webhook;newUser:https://webhooks.org/bot;'

触发时 GeekApk 服务器使用 POSTHTTP 方法,相应 对象IDPOST body 请求目标地址

如果请求失败,错误记录只会被打印在服务程序的 标准错误输出

身份验证和权限管理

GeekApk 使用 基于角色 的权限系统,验证需要的令牌保存在 cookie

GeekApk 有以下 3 种角色:

  • 权限汪 :dog:(确信)
  • 用户
  • 未登录用户

无论是 权限汪用户 还是 未登录用户 实体都可以有多个

权限细则

权限汪(独立于用户的概念) < 未登录用户

权限汪不一定需要有一个 GeekApk 账户,实际上,权限汪只需要服务器的 管理令牌 就可以验证自己的身份

这也意味着权限汪其实只代表了 GeekApk 管理人员普通用户 的权限,但它没有普通用户所拥有的权限 233

  • 权限汪可以创建/删除 用户
  • 权限汪可以修改 用户分发密码
  • 权限汪可以停用/激活 用户
  • 权限汪可以创建/修改/删除 分类
  • 权限汪可以删除 评论
  • 权限汪可以删除 应用

权限汪需要知道服务器根据启动时 DOGETOK 环境变量设置的密码并在请求相应 管理 API 时作为 cookie 参数 doge_token 填写

用户 < 未登录用户
  • 用户不能创建 用户
  • 用户不能创建 分类
  • 用户可以 创建 未禁止创建的 实体修改/删除 自己所创建的 实体notification 记录
  • 用户可以 登录 WebSocket 平台

用户需要使用 分发密码 创建一个自己的 密码(内部表示为 passhash

在创建之后,用户也可以使用 分发密码(内部表示为 metapass)重置自己的密码

WebSocket 验证方式参见上文 WebSocket API,请求需要 验证身份 的 API 时,必须携带 geekapk_uidgeekapk_passhash 两个 cookie 来验证自己的身份,服务器 不会猜测 你需要使用的用户身份

未登录用户

除了 只读访问登录 WebSocket 平台 外没有其它限制

GeekApk 包含的 对象 数据设计

中文名 实体名 表名 ID 描述
用户 user users uid GeekApk 用户帐号
分类 category categories tid GeekApk 应用分类
应用 app apps aid GeekApk 应用
评论 comment comments cid GeekApk 评论

对象的辅助表:

中文名 实体名 表名 所属对象 描述
跟随 follow 用户 用户跟随
密码 _security 用户 用户密码
更新 update updates 应用 应用更新
星标 stars 应用 应用星标
评论星标 comment_stars 评论 评论星标
时间线 timeline timelines 用户 时间线记录
通知 notification notifications 用户 通知条目

用户 对象关系:

  • 只能有一个 密码
  • 可以有很多个 应用
  • 可以有很多条 评论
  • 可以有很多条 跟随
  • 可以有很多个 星标
  • 可以有很多个 评论星标
  • 可以有很多条 时间线
  • 可以有很多条 通知

分类 对象关系:

  • 只能有一个 父 分类
  • 可以包含很多个 应用

应用 对象关系:

  • 只能有一个创建人 用户
  • 只能有一个归属 分类
  • 可以有很多条 评论
  • 可以有很多条 更新
  • 可以有很多条 星标

评论 对象关系:

  • 只能有一个创建人 用户
  • 只能有一个评论目标 应用
  • 只能有一个回复目标 评论
  • 可以有很多个 评论星标

排行设计:

  • 用户 可以按 创建时间、上线时间、跟随者人数 排行
  • 应用 可以按 创建时间、更新时间、星标数、评论数、体积 徘行
  • 评论 可以按 创建时间、更新时间、评论星标数、回复数 排行

分页设计: 时间线、评论、用户、应用 可以设置返回的 最大条数

检索设计:

  • 用户 可以用 简单名、用户名、别名、GitHub、自述、开发者自述 检索
  • 应用 可以用 应用名、包名、描述 检索
  • 评论 可以用 内容 检索

考虑到清晰度的原因,设计上不会添加 rate limit,但实践中有可能在文档规定外添加一定的限制