Skip to content

评论

评论允许用户对资源进行评论的模块。

资源可以是任何具有 UUID 的站点内实体,最常见的用例是对帖子进行评论。

特性

  • 不支持嵌套评论。这是因为这不是常见的用例,并且会使实现变得更加复杂。
  • 支持访客评论。如果站点允许,访客可以对资源进行评论。
  • 支持通过代理 API 远程评论。如果站点允许,代理可以对远程资源进行评论。

本地评论和远程评论

本地评论是指发布在本地资源下的评论。例如,在同一网站或应用程序中对帖子进行的评论。

相反,远程评论是指发布在远程资源下的评论。注意,远程评论同样从本地发出,只是它最后会呈现在远程站点上。例如,在一个网站或应用程序中对另一个网站上的帖子进行的评论。

对本地资源进行评论

评论资源的终端点为 /api/comment/createComment

请求体应该是一个 JSON 对象,具有以下属性:

  • resource 对象
    • uuid 字符串,资源的 UUID
    • type 字符串,资源的类型,例如 post
  • content 字符串,评论的内容
  • is_guest 布尔值,评论是否由访客发布
  • guest_info 对象,可选,仅在 is_guest 为 true 时需要
    • name 字符串,访客的名称
    • email 字符串,访客的电子邮件
    • website 字符串,可选,访客的网站

如果评论成功创建,将返回状态码 200。

注意:如果站点禁用了访客评论,当 is_guest 为 true 时,请求将被拒绝。

对远程资源进行评论

要对远程资源进行评论,应使用代理 API。

评论资源的终端点为 /agent?endpoint=/comment/createComment&site=example.com/x/site1

请求体应该是一个 JSON 对象,属性同上。

如果评论成功创建,将返回状态码 200。

代理 API

代理 API 是一种特殊的 API,其端点为 /api/agent/proxyRequest,允许代理在远程站点上执行操作,而不是默认服务器上执行。

使用代理 API 需要一条已经存在的从本地站点到远程站点的出站连接。一旦建立连接,将使用远程站点签名的令牌将其存储在数据库中,同时存储远程站点的 URL。

工作原理

当向代理 API 发出请求时,服务器首先会检查远程站点是否与本地站点已经建立连接。如果没有,请求将被拒绝。

关于如何建立连接,请参阅 连接

如果远程站点与本地站点建立了连接,服务器将使用远程站点签名的令牌向远程站点发出请求。例如,如果使用代理 API 创建评论,服务器将向远程站点的 /api/comment/createComment 终端点发出请求。

要创建评论,远程端点需要知道评论的作者,但实际上,作者在远程站点上并不存在。因此,本地站点实际上会将虚拟作者附加到请求体中(作为字段 _agent),远程站点上的虚拟用户中间件将设置虚拟用户。

有三种类型的虚拟用户:

  • guest,虚拟用户是一个访客,没有实际的用户
  • user,虚拟用户是本地站点上的实际用户
  • system,虚拟用户代表本地站点的系统,因此被授予更高的权限

远程虚拟用户中间件将检查请求体中的 _agent 字段,并根据虚拟用户的类型设置虚拟用户。