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，但实践中有可能在文档规定外添加一定的限制