GeekApk 后端完整文档

Complete Documentation of Project GeekApk :: Backend

这是 GeekApk Project 后端的完整文档，包含：

额外定义

• 通知/Timeline 的 定义
• WebSocket API
• WebHooks 支持
• 身份验证 模式

API/数据结构

• Postgres 表结构、限制和描述 文档
• JSON RESTFul API 对象 文档
• GeekApk RESTFul API 文档
• 使用 PostgreSQL 语言编写的 database migration 程序
• Diesel Rust Queryable, Insertable 数据结构定义

文档和设计标准

• 应该尽可能符合 GitHub Styled Markdown 语法规范，使用合适的中文文体并合理使用 斜体 粗体 代码块 链接
• 粗体 在强调对象描述时使用、斜体 在引用对象时使用、 代码块 在引用代码时使用、如果有必要，可以给 资源 添加链接
• 不应该有不正确的 缩进、空格、大小写、全半角符号，中文字符（非全角标点）和 数字/英文字符 间必须添加空格

在合适的地方也可以使用 Markdown 引用 添加额外 注意事项

• 数据库字段的英文单词的 单复数 问题： 数据库表 使用 复数，其他 则使用 单数
• 有可能为字段添加所存储数据模式描述的，则添加描述，如： install_url、icon_url、parent_category
• 记录 创建时间 和 更新时间 的字段使用命名 created_at 和 updated_at
• RDBMS 对象引用字段使用 所引用对象单数名称 为名称，如 user、app
• Postgres 中，可能为 NULL 的字段在 Rust 中表示为 Option<T>
• 关于排行所用自动生成字段的问题，必须加 _num
• 仔细检查 database migration up/down、rust struct 中字段和表的名称是否对应
• 在数据结构中合理的增加 限制，如 版本名长度 限制
• 其实这个文档是很 可爱 的 (´・ω・`)

额外定义

通知

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

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

Timeline（时间线）

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

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

WebSocket API

WebSocket 为 GeekApk 提供了即使推送的特性，除此之外还有查询 WebSocket 在线 和发送 即时消息 的能力

GeekApk 服务会把 WebSocket 服务开在 2333 端口上，要建立连接 URL 使用以下格式：

wss://api.geekapk.org/:uid/:passhash

由于推送和送信服务只对 已登录用户 有意义，WebSocket 必须 先验证身份才可以连接

其实这个是可以有状态机描述的，我不想写，这文档也很明了了

发送

• o 以查询 WebSocket 在线人数，服务器会返回一个 短整数(smallint) 的字符串表示如 12、322、0
• o? + 以分号 ',' 切分的 UID 短整数 列表以查询目标用户是否在线，服务器返回以 '*' 打头的 0 和 1 组成的在线状态字符串，其长度等于 UID 列表 的长度，与 UID 列表对应位置的 UID 对应，如 发送 o?12,32,43,32,43 接收 *01010
• uid:message 以向 UID 发送一条消息，若不在线即收到发送错误

接收

• 可能是一个数字字符串，代表 o 的查询结果
• 可能是一个以 '*' 打头的字符串，代表 o? 的查询结果
• 可能是一个包含 ':' 的字符串，在 ':' 前的部分为发送者 UID，后面的部分为 消息
• 可能是一个值等于 ERROR 的字符，代表发送操作出现错误

WebHooks

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

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

GeekApk 目前支持 2 种 WebHook

• replyToMessage 在回复指定 评论 时触发
• commentApp 在回复指定 应用 时触发

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

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

触发时 GeekApk 服务器使用 POST 为 HTTP 方法，相应 对象 的 ID 为 POST body 请求目标地址，如果失败只会被记录在服务程序的 错误输出 里

身份验证和权限管理

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

GeekApk 有以下 3 种角色：

• 权限汪 🐶（确信）
• 用户
• 未登录用户

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

权限细则

权限汪（独立于用户的概念） < 未登录用户

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

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

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

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

用户 < 未登录用户

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

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

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

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

未登录用户

除了 创建实体 和 登录 WebSocket 平台 外没有其它限制

后端数据结构

PostgreSQL

对应的 Rust 结构

RESTFul API

RESTFul JSON 对象