评论 ​

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

资源可以是任何具有 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 字段，并根据虚拟用户的类型设置虚拟用户。