Files

anghunk e0be92b1fe feat(评论): 新增功能开关管理及评论点赞功能优化

- 在管理后台添加功能开关页面，支持控制评论点赞和文章点赞功能的开启/关闭
- 优化评论点赞功能，支持取消点赞和本地存储点赞状态
- 更新点赞UI样式，提升用户体验
- 添加相关API接口和文档说明

2026-01-22 22:26:43 +08:00

17 KiB

Raw Blame History

公开 API 相关

无需认证即可访问的公开接口，包括评论获取、评论提交、配置获取和身份验证。

包含路径、方法、参数、请求体和响应示例。

1. 评论相关

1.1 获取指定文章的评论列表

GET /api/comments

获取指定文章的评论列表，支持分页和嵌套结构。

方法：GET
路径：/api/comments
鉴权：不需要

查询参数

名称	位置	类型	必填	说明
`post_slug`	query	string	是	`window.location.origin + window.location.pathname`
`page`	query	integer	否	页码，默认 `1`
`limit`	query	integer	否	每页数量，默认 `20`，最大 `50`
`nested`	query	string	否	是否返回嵌套结构，默认 `'true'`

成功响应

状态码：200

{
  "data": [
    {
      "id": 1,
      "author": "张三",
      "email": "zhangsan@example.com",
      "url": "https://example.com",
      "contentText": "很棒的文章！",
      "contentHtml": "很棒的文章！",
      "pubDate": "2026-01-13T10:00:00Z",
      "postSlug": "/blog/hello-world",
      "avatar": "https://gravatar.com/avatar/...",
      "priority": 2,
      "replies": [
        {
          "id": 2,
          "author": "李四",
          "email": "lisi@example.com",
          "url": null,
          "contentText": "同感！",
          "contentHtml": "同感！",
          "pubDate": "2026-01-13T11:00:00Z",
          "postSlug": "/blog/hello-world",
          "avatar": "https://gravatar.com/avatar/...",
          "parentId": 1,
          "replyToAuthor": "张三",
          "priority": 1
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalCount": 2
  }
}

说明：

当 nested=true（默认）时，接口返回的是"根评论列表"，每条根评论包含其 replies。
当 nested=false 时，接口返回扁平列表，所有评论都在 data 中，replies 为空。
priority 字段：评论的置顶权重，数值越大排序越靠前。
likes 字段：评论的点赞数，默认为 0。

错误响应

缺少 post_slug：

状态码：400

{
  "message": "post_slug is required"
}

服务器内部错误：
- 状态码：500
```
{
  "message": "错误信息"
}
```

1.2 提交新评论或回复

POST /api/comments

提交新评论或回复。

方法：POST
路径：/api/comments
鉴权：不需要

请求头

名称	必填	示例
`Content-Type`	是	`application/json`

请求体（Request Body）

{
  "post_slug": "https://example.com/blog/hello-world",
  "post_title": "博客标题，可选",
  "post_url": "https://example.com/blog/hello-world",
  "name": "张三",
  "email": "zhangsan@example.com",
  "url": "https://zhangsan.me",
  "content": "很棒的文章！",
  "parent_id": 1,
  "adminToken": "your-admin-key"
}

字段说明：

字段名	类型	必填	说明
`post_slug`	string	是	文章唯一标识符，应与前端组件初始化时的 `postSlug` 值一致，`window.location.origin + window.location.pathname`
`post_title`	string	否	文章标题，用于邮件通知内容
`post_url`	string	否	文章 URL，用于邮件通知中的跳转链接
`name`	string	是	评论者昵称
`email`	string	是	评论者邮箱，需为合法邮箱格式
`url`	string	否	评论者个人主页或站点地址
`content`	string	是	评论内容，内部会过滤 `<script>...</script>` 片段
`parent_id`	number	否	父评论 ID，用于回复功能；缺省或 `null` 表示根评论
`adminToken`	string	否	管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响

成功响应

状态码：200

评论直接通过时：

{
  "message": "评论已提交",
  "status": "approved"
}

评论进入待审核状态时（开启"先审核再显示"且非管理员评论）：

{
  "message": "已提交评论，待管理员审核后显示",
  "status": "pending"
}

错误响应

请求体缺失或字段类型错误：
- 状态码：400
```
{
  "message": "无效的请求体"
}
```

缺少必填字段：

post_slug 为空：
```
{
  "message": "post_slug 必填"
}
```

content 为空：

{
  "message": "评论内容不能为空"
}

author 为空：
```
{
  "message": "昵称不能为空"
}
```

email 为空或格式不正确：

{
  "message": "邮箱不能为空"
}

或

{
  "message": "邮箱格式不正确"
}

IP 或邮箱被限制：

IP 被限制：

状态码：403

{
  "message": "当前 IP 已被限制评论，请联系站长进行处理"
}

邮箱被限制：

状态码：403

{
  "message": "当前邮箱已被限制评论，请联系站长进行处理"
}

管理员评论验证失败：

未输入密钥：

状态码：401

{
  "message": "请输入管理员密钥",
  "requireAuth": true
}

密钥错误：
- 状态码：401
```
{
  "message": "密钥错误"
}
```

验证失败次数过多：

状态码：403

{
  "message": "验证失败次数过多，请 30 分钟后再试"
}

评论频率限制：
- 状态码：429
- 逻辑：同一 IP 最近一条评论时间在 10 秒内，则拒绝此次请求。
```
{
  "message": "评论频繁，等 10s 后再试"
}
```

服务器内部错误：

状态码：500

{
  "message": "Internal Server Error"
}

1.3 获取点赞状态

GET /api/like

获取当前页面的点赞状态和总点赞数，一般由前端组件在页面加载时自动调用。

方法：GET
路径：/api/like
鉴权：不需要

查询参数

名称	位置	类型	必填	说明
`post_slug`	query	string	是	页面唯一标识符，`window.location.origin + window.location.pathname`

请求头（可选）

名称	必填	示例	说明
`X-CWD-Like-User`	否	`550e8400-e29b-41d4-a716...`	前端生成的匿名用户标识，用于区分不同用户

未显式传入 X-CWD-Like-User 时，服务端会尝试使用 cf-connecting-ip 作为用户标识，找不到时退回到 anonymous。

成功响应

状态码：200

{
  "liked": false,
  "alreadyLiked": false,
  "totalLikes": 12
}

字段说明：

字段名	类型	说明
`liked`	boolean	当前用户是否已点赞
`alreadyLiked`	boolean	预留字段，当前实现始终为 `false`
`totalLikes`	number	当前页面的总点赞数

错误响应

缺少 post_slug：

状态码：400

{
  "message": "post_slug is required"
}

服务器内部错误：

状态码：500

{
  "message": "获取点赞状态失败"
}

1.4 点赞当前页面

POST /api/like

对当前页面执行点赞操作，同一用户对同一页面只会计入一次点赞。

方法：POST
路径：/api/like
鉴权：不需要

请求头

名称	必填	示例	说明
`Content-Type`	是	`application/json`
`X-CWD-Like-User`	否	`550e8400-e29b-41d4-a716...`	前端生成的匿名用户标识，用于区分不同用户

请求体

{
  "postSlug": "https://example.com/blog/hello-world",
  "postTitle": "博客标题，可选",
  "postUrl": "https://example.com/blog/hello-world"
}

字段说明：

字段名	类型	必填	说明
`postSlug`	string	是	页面唯一标识符，应与评论接口中的 `post_slug` 一致
`postTitle`	string	否	页面标题，用于点赞统计中显示
`postUrl`	string	否	页面 URL，用于点赞统计中跳转

成功响应

状态码：200

{
  "liked": true,
  "alreadyLiked": false,
  "totalLikes": 13
}

说明：

第一次点赞：liked=true，alreadyLiked=false，totalLikes 增加 1；
重复点赞：服务器不会重复插入记录，alreadyLiked=true，totalLikes 不会继续增加。

错误响应

缺少 postSlug：

状态码：400

{
  "message": "postSlug is required"
}

服务器内部错误：
- 状态码：500
```
{
  "message": "点赞失败"
}
```

1.5 评论点赞

POST /api/comments/like

对指定评论进行点赞操作。

方法：POST
路径：/api/comments/like
鉴权：不需要

请求头

名称	必填	示例
`Content-Type`	是	`application/json`

请求体

{
  "id": 123
}

字段说明：

字段名	类型	必填	说明
`id`	number	是	评论 ID

成功响应

状态码：200

{
  "message": "点赞成功",
  "likes": 5
}

字段说明：

字段名	类型	说明
`likes`	number	更新后的点赞数

错误响应

状态码：400

{
  "message": "评论不存在"
}

1.6 取消评论点赞

DELETE /api/comments/like

取消对指定评论的点赞。

方法：DELETE
路径：/api/comments/like
鉴权：不需要

请求头

名称	必填	示例
`Content-Type`	是	`application/json`

请求体

{
  "id": 123
}

字段说明：

字段名	类型	必填	说明
`id`	number	是	评论 ID

成功响应

状态码：200

{
  "message": "取消点赞成功",
  "likes": 4
}

字段说明：

字段名	类型	说明
`likes`	number	更新后的点赞数

错误响应

状态码：400

{
  "message": "评论不存在"
}

2. 配置相关

2.1 获取评论相关的公开配置

GET /api/config/comments

获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。

方法：GET
路径：/api/config/comments
鉴权：不需要

成功响应

状态码：200

{
  "adminEmail": "admin@example.com",
  "adminBadge": "博主",
  "avatar": "https://gravatar.com/avatar",
  "adminEnabled": true,
  "allowedDomains": [],
  "requireReview": false
}

字段说明：

字段名	类型	说明
`adminEmail`	string	博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程
`adminBadge`	string	博主标识文字，例如 `"博主"`
`avatarPrefix`	string	头像地址前缀，如 Gravatar 或 Cravatar 镜像地址
`adminEnabled`	boolean	是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱）
`allowedDomains`	Array<string>	允许调用组件的域名列表，留空则不限制
`requireReview`	boolean	是否开启新评论先审核再显示（true 表示新评论默认为待审核）
`enableCommentLike`	boolean	是否启用评论点赞功能（默认 true）
`enableArticleLike`	boolean	是否启用文章点赞功能（默认 true）

错误响应

状态码：500

{
  "message": "加载评论配置失败"
}

3. 身份验证相关

3.1 验证管理员密钥

POST /api/verify-admin

验证前台管理员评论所需的密钥，用于博主发布评论时的身份验证。

方法：POST
路径：/api/verify-admin
鉴权：不需要

请求头

名称	必填	示例
`Content-Type`	是	`application/json`

请求体

{
  "adminToken": "your-admin-key"
}

字段说明：

字段名	类型	必填	说明
`adminToken`	string	是	管理员评论密钥

风控说明

本地密钥存活时间 72 小时
同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟
失败次数记录有效期为 1 小时

成功响应

状态码：200

{
  "message": "验证通过"
}

或未设置密钥时：

{
  "message": "未设置管理员密钥"
}

错误响应

寽钥错误：
- 状态码：401
```
{
  "message": "密钥错误"
}
```

验证失败次数过多：

状态码：403

{
  "message": "验证失败次数过多，请 30 分钟后再试"
}

4. 访问统计相关

4.1 记录页面访问

POST /api/analytics/visit

前端组件在加载时调用此接口，记录页面访问数据，用于后台访问统计分析。

方法：POST
路径：/api/analytics/visit
鉴权：不需要

请求头

名称	必填	示例
`Content-Type`	是	`application/json`

请求体

{
  "postSlug": "https://example.com/blog/hello-world",
  "postTitle": "博客标题",
  "postUrl": "https://example.com/blog/hello-world"
}

字段说明：

字段名	类型	必填	说明
`postSlug`	string	是	文章唯一标识符，`window.location.origin + window.location.pathname`
`postTitle`	string	否	文章标题，用于后台展示页面名称
`postUrl`	string	否	文章 URL，用于后台展示页面链接和域名统计

成功响应

状态码：200

{
  "success": true
}

错误响应

缺少 postSlug：

状态码：400

{
  "message": "postSlug is required"
}

服务器内部错误：

状态码：500

{
  "message": "记录访问数据失败"
}

17 KiB Raw Blame History Unescape Escape

公开 API 相关

1. 评论相关

1.1 获取指定文章的评论列表

1.2 提交新评论或回复

1.3 获取点赞状态

1.4 点赞当前页面

1.5 评论点赞

1.6 取消评论点赞

2. 配置相关

2.1 获取评论相关的公开配置

3. 身份验证相关

3.1 验证管理员密钥

4. 访问统计相关

4.1 记录页面访问

17 KiB

Raw Blame History