3b429bf82c
- 在站点隔离配置文档中详细说明 siteId 的使用方法和注意事项 - 为公开API接口添加 siteId 查询参数和请求头说明 - 更新前端配置文档，明确 siteId 为可选参数并说明默认值 - 修正常见问题中的表述和格式问题
447 lines
9.8 KiB
Markdown
447 lines
9.8 KiB
Markdown
# 评论接口
|
||
|
||
评论相关的公开接口，包括获取评论列表、提交评论、评论点赞等。
|
||
|
||
## 获取评论列表
|
||
|
||
```
|
||
GET /api/comments
|
||
```
|
||
|
||
获取指定文章的评论列表，支持分页和嵌套结构。
|
||
|
||
- 方法：`GET`
|
||
- 路径：`/api/comments`
|
||
- 鉴权：不需要
|
||
|
||
**查询参数**
|
||
|
||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||
| ----------- | ----- | ------- | ---- | ------------------------------------------ |
|
||
| `post_slug` | query | string | 是 | 文章 slug，与前端 `CWDComments` 的 `postSlug` 参数对应 |
|
||
| `siteId` | query | string | 否 | 站点 ID，用于多站点数据隔离，默认 `default` |
|
||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||
| `limit` | query | integer | 否 | 每页数量，默认 `20`，最大 `50` |
|
||
| `nested` | query | string | 否 | 是否返回嵌套结构，默认 `'true'` |
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"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,
|
||
"likes": 5,
|
||
"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,
|
||
"likes": 2
|
||
}
|
||
]
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 20,
|
||
"total": 1,
|
||
"totalCount": 2
|
||
}
|
||
}
|
||
```
|
||
|
||
返回字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ----------- | ------ | -------------------------- |
|
||
| `id` | number | 评论 ID |
|
||
| `author` | string | 评论者昵称 |
|
||
| `email` | string | 评论者邮箱（hash后） |
|
||
| `url` | string | null) | 评论者个人主页地址 |
|
||
| `contentText` | string | 评论内容（纯文本） |
|
||
| `contentHtml` | string | 评论内容（渲染后的 HTML） |
|
||
| `pubDate` | string | 发布时间（ISO 8601 格式） |
|
||
| `postSlug` | string | 文章 slug |
|
||
| `avatar` | string | 头像 URL（Gravatar） |
|
||
| `priority` | number | 置顶权重，数值越大排序越靠前 |
|
||
| `likes` | number | 点赞数，默认为 0 |
|
||
| `replies` | array | 子评论列表（嵌套结构时） |
|
||
| `parentId` | number | null) | 父评论 ID（回复时） |
|
||
| `replyToAuthor` | string( | null) | 被回复者的昵称（回复时） |
|
||
|
||
说明：
|
||
|
||
- 当 `nested=true`（默认）时，接口返回的是"根评论列表"，每条根评论包含其 `replies`。
|
||
- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。
|
||
- `priority` 字段：评论的置顶权重，数值越大排序越靠前。
|
||
- `likes` 字段：评论的点赞数，默认为 0。
|
||
|
||
**错误响应**
|
||
|
||
- 缺少 `post_slug`：
|
||
|
||
- 状态码：`400`
|
||
|
||
```json
|
||
{
|
||
"message": "post_slug is required"
|
||
}
|
||
```
|
||
|
||
- 服务器内部错误：
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "错误信息"
|
||
}
|
||
```
|
||
|
||
## 提交评论
|
||
|
||
```
|
||
POST /api/comments
|
||
```
|
||
|
||
提交新评论或回复。
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/api/comments`
|
||
- 鉴权：不需要
|
||
|
||
**请求头**
|
||
|
||
| 名称 | 必填 | 示例 |
|
||
| -------------- | ---- | ---------------------------- |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
|
||
**请求头**
|
||
|
||
| 名称 | 必填 | 示例 |
|
||
| -------------- | ---- | ---------------------------- |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
| `X-Site-Id` | 否 | `blog` |
|
||
|
||
**请求体（Request Body）**
|
||
|
||
```json
|
||
{
|
||
"post_slug": "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 | 是 | 文章 slug，应与前端组件初始化时的 `postSlug` 值一致，如 `hello-world` |
|
||
| `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` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 |
|
||
|
||
**请求头说明：**
|
||
|
||
| 名称 | 必填 | 说明 |
|
||
| ---------- | ---- | -------------------------- |
|
||
| `X-Site-Id` | 否 | 站点 ID，用于多站点数据隔离，默认 `default` |
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
评论直接通过时：
|
||
|
||
```json
|
||
{
|
||
"message": "评论已提交",
|
||
"status": "approved"
|
||
}
|
||
```
|
||
|
||
评论进入待审核状态时（开启"先审核再显示"且非管理员评论）：
|
||
|
||
```json
|
||
{
|
||
"message": "已提交评论，待管理员审核后显示",
|
||
"status": "pending"
|
||
}
|
||
```
|
||
|
||
**错误响应**
|
||
|
||
- 请求体缺失或字段类型错误：
|
||
|
||
- 状态码：`400`
|
||
|
||
```json
|
||
{
|
||
"message": "无效的请求体"
|
||
}
|
||
```
|
||
|
||
- 缺少必填字段：
|
||
|
||
- `post_slug` 为空：
|
||
|
||
```json
|
||
{
|
||
"message": "post_slug 必填"
|
||
}
|
||
```
|
||
|
||
- `content` 为空：
|
||
|
||
```json
|
||
{
|
||
"message": "评论内容不能为空"
|
||
}
|
||
```
|
||
|
||
- `author` 为空：
|
||
|
||
```json
|
||
{
|
||
"message": "昵称不能为空"
|
||
}
|
||
```
|
||
|
||
- `email` 为空或格式不正确：
|
||
|
||
```json
|
||
{
|
||
"message": "邮箱不能为空"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"message": "邮箱格式不正确"
|
||
}
|
||
```
|
||
|
||
- IP 或邮箱被限制：
|
||
|
||
- IP 被限制：
|
||
- 状态码：`403`
|
||
|
||
```json
|
||
{
|
||
"message": "当前 IP 已被限制评论，请联系站长进行处理"
|
||
}
|
||
```
|
||
|
||
- 邮箱被限制：
|
||
- 状态码：`403`
|
||
|
||
```json
|
||
{
|
||
"message": "当前邮箱已被限制评论，请联系站长进行处理"
|
||
}
|
||
```
|
||
|
||
- 管理员评论验证失败：
|
||
|
||
- 未输入密钥：
|
||
- 状态码：`401`
|
||
|
||
```json
|
||
{
|
||
"message": "请输入管理员密钥",
|
||
"requireAuth": true
|
||
}
|
||
```
|
||
|
||
- 密钥错误：
|
||
- 状态码：`401`
|
||
|
||
```json
|
||
{
|
||
"message": "密钥错误"
|
||
}
|
||
```
|
||
|
||
- 验证失败次数过多：
|
||
- 状态码：`403`
|
||
|
||
```json
|
||
{
|
||
"message": "验证失败次数过多，请 30 分钟后再试"
|
||
}
|
||
```
|
||
|
||
- 评论频率限制：
|
||
|
||
- 状态码：`429`
|
||
- 逻辑：同一 IP 最近一条评论时间在 10 秒内，则拒绝此次请求。
|
||
|
||
```json
|
||
{
|
||
"message": "评论频繁，等 10s 后再试"
|
||
}
|
||
```
|
||
|
||
- 服务器内部错误：
|
||
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "Internal Server Error"
|
||
}
|
||
```
|
||
|
||
## 点赞评论
|
||
|
||
```
|
||
POST /api/comments/like
|
||
```
|
||
|
||
对指定评论进行点赞操作。
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/api/comments/like`
|
||
- 鉴权：不需要
|
||
|
||
**请求头**
|
||
|
||
| 名称 | 必填 | 示例 |
|
||
| -------------- | ---- | ------------------ |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"id": 123
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
| ------ | ------ | ---- | ---------- |
|
||
| `id` | number | 是 | 评论 ID |
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"message": "点赞成功",
|
||
"likes": 5
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ------- | ------ | -------------- |
|
||
| `likes` | number | 更新后的点赞数 |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`400`
|
||
|
||
```json
|
||
{
|
||
"message": "评论不存在"
|
||
}
|
||
```
|
||
|
||
## 取消点赞评论
|
||
|
||
```
|
||
DELETE /api/comments/like
|
||
```
|
||
|
||
取消对指定评论的点赞。
|
||
|
||
- 方法：`DELETE`
|
||
- 路径：`/api/comments/like`
|
||
- 鉴权：不需要
|
||
|
||
**请求头**
|
||
|
||
| 名称 | 必填 | 示例 |
|
||
| -------------- | ---- | ------------------ |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"id": 123
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
| ------ | ------ | ---- | ---------- |
|
||
| `id` | number | 是 | 评论 ID |
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"message": "取消点赞成功",
|
||
"likes": 4
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
| ------- | ------ | -------------- |
|
||
| `likes` | number | 更新后的点赞数 |
|
||
|
||
**错误响应**
|
||
|
||
- 状态码：`400`
|
||
|
||
```json
|
||
{
|
||
"message": "评论不存在"
|
||
}
|
||
```
|