API v1 基本定义 - geekapk-r/ServerR GitHub Wiki
哪些是通知
GeekApk 里,通知 作为一种对 用户 的提醒而存在,一般在 动作执行后 直接保存等待用户阅读,GeekApk 中有这些通知:
- 用户 的 评论 被 回复 的通知
- 用户 被
@
提到 的通知 - 用户 被 用户 跟随 的通知
- 用户 的 评论 被 星标 的通知
Timeline(时间线)
类似 GitHub,GeekApk 也会记录每个 用户 的公开活动并允许所有人自由查询,这个特性被称为 Timeline(时间线),GeekApk 中有这些时间线记录:
- 用户 Follow 了某个 用户
- 用户 Star 了某个 评论
- 用户 创建了 某个 评论
- 用户 更新了 某个 评论
- 用户 发布了 某个 应用
- 用户 发布了 某个 应用 的 更新
- 用户 删除了 某个 应用
- 用户 Star 了某个 应用
WebHooks
GeekApk 可以与 第三方服务 进行 集成,服务端使用的支持方式就是 WebHooks
WebHooks 可以让 GeekApk 服务器在进行某种操作后 通知 外部服务进行相应的处理
GeekApk 目前支持 3 种 WebHooks:
- 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 服务器使用 POST
为 HTTP 方法,相应 对象 的 ID 为 POST body 请求目标地址
如果请求失败,错误记录只会被打印在服务程序的 标准错误输出 里
身份验证和权限管理
GeekApk 使用 基于角色 的权限系统,验证需要的令牌保存在 cookie 里
GeekApk 有以下 3 种角色:
- 权限汪 :dog:(确信)
- 用户
- 未登录用户
无论是 权限汪、用户 还是 未登录用户 实体都可以有多个
权限细则
权限汪(独立于用户的概念) < 未登录用户
权限汪不一定需要有一个 GeekApk 账户,实际上,权限汪只需要服务器的 管理令牌 就可以验证自己的身份
这也意味着权限汪其实只代表了 GeekApk 管理人员 比 普通用户 多 的权限,但它没有普通用户所拥有的权限 233
- 权限汪可以创建/删除 用户
- 权限汪可以修改 用户 的 分发密码
- 权限汪可以停用/激活 用户
- 权限汪可以创建/修改/删除 分类
- 权限汪可以删除 评论
- 权限汪可以删除 应用
权限汪需要知道服务器根据启动时 DOGETOK
环境变量设置的密码并在请求相应 管理 API 时作为 cookie 参数 doge_token
填写
用户 < 未登录用户
- 用户不能创建 用户
- 用户不能创建 分类
- 用户可以 创建 未禁止创建的 实体 和 修改/删除 自己所创建的 实体 或 notification 记录
- 用户可以 登录 WebSocket 平台
用户需要使用 分发密码 创建一个自己的 密码(内部表示为 passhash
)
在创建之后,用户也可以使用 分发密码(内部表示为 metapass
)重置自己的密码
WebSocket 验证方式参见上文 WebSocket API,请求需要 验证身份 的 API 时,必须携带 geekapk_uid
和 geekapk_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,但实践中有可能在文档规定外添加一定的限制