cwd/docs/api/public/comments.md

评论接口

评论相关的公开接口，包括获取评论列表、提交评论、评论点赞等。

获取评论列表

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

{
  "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)
replyToAuthor	string(	null)

说明：

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

错误响应

• 缺少 post_slug：

  • 状态码：400

  {
    "message": "post_slug is required"
  }
  

• 服务器内部错误：

  • 状态码：500

  {
    "message": "错误信息"
  }
  

提交评论

POST /api/comments

提交新评论或回复。

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

请求头

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

请求头

名称	必填	示例
Content-Type	是	application/json
X-Site-Id	否	blog

请求体（Request Body）

{
  "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

评论直接通过时：

{
  "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"
  }
  

点赞评论

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": "评论不存在"
}

取消点赞评论

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": "评论不存在"
}