From 4a674ee17a84f291cae20ce6c564190f7ead72de Mon Sep 17 00:00:00 2001 From: anghunk Date: Fri, 6 Feb 2026 19:37:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84API=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=BB=93=E6=9E=84=EF=BC=8C=E5=90=88=E5=B9=B6=E5=AD=90=E9=A1=B5?= =?UTF-8?q?=E9=9D=A2=E5=88=B0=E4=B8=BB=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将分散的API子页面内容合并到对应的主文档中，简化文档结构。具体合并内容包括： - 将 verify-admin.md 内容合并到 auth.md - 将 track-visit.md 内容合并到 analytics.md - 将 get-config.md 内容合并到 config.md - 将 get-comments.md、post-comment.md、like-comment.md 内容合并到 comments.md - 将 get-like-status.md、post-like.md 内容合并到 like.md 删除原有的独立子页面文件，使API文档更加集中和易于维护。 --- docs/api/public/analytics.md | 68 ++++ docs/api/public/analytics/track-visit.md | 67 ---- docs/api/public/auth.md | 76 +++++ docs/api/public/auth/verify-admin.md | 75 ----- docs/api/public/comments.md | 410 +++++++++++++++++++++++ docs/api/public/comments/get-comments.md | 96 ------ docs/api/public/comments/like-comment.md | 119 ------- docs/api/public/comments/post-comment.md | 194 ----------- docs/api/public/config.md | 56 ++++ docs/api/public/config/get-config.md | 55 --- docs/api/public/like.md | 144 ++++++++ docs/api/public/like/get-like-status.md | 67 ---- docs/api/public/like/post-like.md | 75 ----- 13 files changed, 754 insertions(+), 748 deletions(-) delete mode 100644 docs/api/public/analytics/track-visit.md delete mode 100644 docs/api/public/auth/verify-admin.md delete mode 100644 docs/api/public/comments/get-comments.md delete mode 100644 docs/api/public/comments/like-comment.md delete mode 100644 docs/api/public/comments/post-comment.md delete mode 100644 docs/api/public/config/get-config.md delete mode 100644 docs/api/public/like/get-like-status.md delete mode 100644 docs/api/public/like/post-like.md diff --git a/docs/api/public/analytics.md b/docs/api/public/analytics.md index 6f6298c..255a5e6 100644 --- a/docs/api/public/analytics.md +++ b/docs/api/public/analytics.md @@ -1,3 +1,71 @@ # 访问统计 页面访问统计接口，用于记录和分析页面访问数据。 + +## 记录页面访问 + +``` +POST /api/analytics/visit +``` + +前端组件在加载时调用此接口，记录页面访问数据，用于后台访问统计分析。 + +- 方法：`POST` +- 路径：`/api/analytics/visit` +- 鉴权：不需要 + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```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` + +```json +{ + "success": true +} +``` + +**错误响应** + +- 缺少 `postSlug`： + + - 状态码：`400` + + ```json + { + "message": "postSlug is required" + } + ``` + +- 服务器内部错误： + + - 状态码：`500` + + ```json + { + "message": "记录访问数据失败" +! } + ``` diff --git a/docs/api/public/analytics/track-visit.md b/docs/api/public/analytics/track-visit.md deleted file mode 100644 index ed5e53a..0000000 --- a/docs/api/public/analytics/track-visit.md +++ /dev/null @@ -1,67 +0,0 @@ -# 记录页面访问 - -``` -POST /api/analytics/visit -``` - -前端组件在加载时调用此接口，记录页面访问数据，用于后台访问统计分析。 - -- 方法：`POST` -- 路径：`/api/analytics/visit` -- 鉴权：不需要 - -**请求头** - -| 名称 | 必填 | 示例 | -| -------------- | ---- | ------------------ | -| `Content-Type` | 是 | `application/json` | - -**请求体** - -```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` - -```json -{ - "success": true -} -``` - -**错误响应** - -- 缺少 `postSlug`： - - - 状态码：`400` - - ```json - { - "message": "postSlug is required" - } - ``` - -- 服务器内部错误： - - - 状态码：`500` - - ```json - { - "message": "记录访问数据失败" -! } - ``` diff --git a/docs/api/public/auth.md b/docs/api/public/auth.md index 2eb3552..d1b66ce 100644 --- a/docs/api/public/auth.md +++ b/docs/api/public/auth.md @@ -1,3 +1,79 @@ # 身份验证 管理员评论密钥验证接口，用于博主发布评论时的身份验证。 + +## 验证管理员密钥 + +``` +POST /api/verify-admin +``` + +验证前台管理员评论所需的密钥，用于博主发布评论时的身份验证。 + +- 方法：`!POST` +- 路径：`/api/verify-admin` +- 鉴权：不需要 + +**请求头** + +| 名称 | 必填 | 示例 | +| -------------- | ---- | ------------------ | +| `Content-Type` | 是 | `application/json` | + +**请求体** + +```json +{ + "adminToken": "your-admin-key" +} +``` + +字段说明： + +| 字段名 | 类型 | 必填 | 说明 | +| ----------- | ------ | ---- | -------------- | +| `adminToken` | string | 是 | 管理员评论密钥 | + +**风控说明** + +- 本地密钥存活时间 72 小时 +- 同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟 +- 失败次数记录有效期为 1 小时 + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "验证通过" +} +``` + +或未设置密钥时： + +```json +{ + "message": "未设置管理员密钥" +} +``` + +**错误响应** + +- 密钥错误： + - 状态码：`401` + + ```json + { + "message": "密钥错误" + } + ``` + +- 验证失败次数过多： + - 状态码：`403` + + ```json + { + "message": "验证失败次数过多，请 30 分钟后再试" + } + ``` diff --git a/docs/api/public/auth/verify-admin.md b/docs/api/public/auth/verify-admin.md deleted file mode 100644 index 0f5a784..0000000 --- a/docs/api/public/auth/verify-admin.md +++ /dev/null @@ -1,75 +0,0 @@ -# 验证管理员密钥 - -``` -POST /api/verify-admin -``` - -验证前台管理员评论所需的密钥，用于博主发布评论时的身份验证。 - -- 方法：`!POST` -- 路径：`/api/verify-admin` -- 鉴权：不需要 - -**请求头** - -| 名称 | 必填 | 示例 | -| -------------- | ---- | ------------------ | -| `Content-Type` | 是 | `application/json` | - -**请求体** - -```json -{ - "adminToken": "your-admin-key" -} -``` - -字段说明： - -| 字段名 | 类型 | 必填 | 说明 | -| ----------- | ------ | ---- | -------------- | -| `adminToken` | string | 是 | 管理员评论密钥 | - -**风控说明** - -- 本地密钥存活时间 72 小时 -- 同一 IP 连续验证失败 3 次后，该 IP 将被锁定 30 分钟 -- 失败次数记录有效期为 1 小时 - -**成功响应** - -- 状态码：`200` - -```json -{ - "message": "验证通过" -} -``` - -或未设置密钥时： - -```json -{ - "message": "未设置管理员密钥" -} -``` - -**错误响应** - -- 密钥错误： - - 状态码：`401` - - ```json - { - "message": "密钥错误" - } - ``` - -- 验证失败次数过多： - - 状态码：`403` - - ```json - { - "message": "验证失败次数过多，请 30 分钟后再试" - } - ``` diff --git a/docs/api/public/comments.md b/docs/api/public/comments.md index 823d996..77c45fd 100644 --- a/docs/api/public/comments.md +++ b/docs/api/public/comments.md @@ -1,3 +1,413 @@ # 评论接口 评论相关的公开接口，包括获取评论列表、提交评论、评论点赞等。 + +## 获取评论列表 + +``` +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` + +```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 + } +} +``` + +说明： + +- 当 `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` | + +**请求体（Request Body）** + +```json +{ + "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 | 是 | 评论内容，内部会过滤 `` 片段 | +| `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 | +| `adminToken` | string | 否 | 管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 | + +**成功响应** + +- 状态码：`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": "评论不存在" +} +``` diff --git a/docs/api/public/comments/get-comments.md b/docs/api/public/comments/get-comments.md deleted file mode 100644 index 8b350bd..0000000 --- a/docs/api/public/comments/get-comments.md +++ /dev/null @@ -1,96 +0,0 @@ -# 获取评论列表 - -``` -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` - -```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 - } -} -``` - -说明： - -- 当 `nested=true`（默认）时，接口返回的是"根评论列表"，每条根评论包含其 `replies`。 -- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。 -- `priority` 字段：评论的置顶权重，数值越大排序越靠前。 -- `likes` 字段：评论的点赞数，默认为 0。 - -**错误响应** - -- 缺少 `post_slug`： - - - 状态码：`400` - - ```json - { - "message": "post_slug is required" - } - ``` - -- 服务器内部错误： - - - 状态码：`500` - - ```json - { - "message": "错误信息" - } - ``` diff --git a/docs/api/public/comments/like-comment.md b/docs/api/public/comments/like-comment.md deleted file mode 100644 index f899887..0000000 --- a/docs/api/public/comments/like-comment.md +++ /dev/null @@ -1,119 +0,0 @@ -# 评论点赞 - -## 点赞评论 - -``` -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": "评论不存在" -} -``` diff --git a/docs/api/public/comments/post-comment.md b/docs/api/public/comments/post-comment.md deleted file mode 100644 index c3ab213..0000000 --- a/docs/api/public/comments/post-comment.md +++ /dev/null @@ -1,194 +0,0 @@ -# 提交评论 - -``` -POST /api/comments -``` - -提交新评论或回复。 - -- 方法：`POST` -- 路径：`/api/comments` -- 鉴权：不需要 - -**请求头** - -| 名称 | 必填 | 示例 | -| -------------- | ---- | ---------------------------- | -| `Content-Type` | 是 | `application/json` | - -**请求体（Request Body）** - -```json -{ - "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 | 是 | 评论内容，内部会过滤 `` 片段 | -| `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 | -| `adminToken` | string | 否 | 管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 | - -**成功响应** - -- 状态码：`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" - } - ``` diff --git a/docs/api/public/config.md b/docs/api/public/config.md index 7de6a3f..0910656 100644 --- a/docs/api/public/config.md +++ b/docs/api/public/config.md @@ -1,3 +1,59 @@ # 配置接口 获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。 + +## 获取配置 + +``` +GET /api/config/comments +``` + +获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。 + +- 方法：`GET` +- 路径：`/api/config/comments` +- 鉴权：不需要 + +**成功响应** + +- 状态码：`200` + +```json +{ + "adminEmail": "admin@example.com", + "adminBadge": "博主", + "avatar": "https://gravatar.com/avatar", + "adminEnabled": true, + "allowedDomains": [], + "requireReview": false, + "enableCommentLike": true, + "enableArticleLike": true, + "enableImageLightbox": true, + "commentPlaceholder": "发表你的看法..." +} +``` + +字段说明： + +| 字段名 | 类型 | 说明 | +| -------------------- | ------ | -------------------------------------------------------------------- | +| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 | +| `adminBadge` | string | 博主标识文字，例如 `"博主"` | +| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 | +| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） | +| `allowedDomains` | Array\ | 允许调用组件的域名列表，留空则不限制 | +| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | +| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | +| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | +| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） | +| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 | + +**错误响应** + +- 状态!码：`500` + +```json +{ + "message": "加载评论配置失败" +} +``` diff --git a/docs/api/public/config/get-config.md b/docs/api/public/config/get-config.md deleted file mode 100644 index d39925a..0000000 --- a/docs/api/public/config/get-config.md +++ /dev/null @@ -1,55 +0,0 @@ -# 获取配置 - -``` -GET /api/config/comments -``` - -获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。 - -- 方法：`GET` -- 路径：`/api/config/comments` -- 鉴权：不需要 - -**成功响应** - -- 状态码：`200` - -```json -{ - "adminEmail": "admin@example.com", - "adminBadge": "博主", - "avatar": "https://gravatar.com/avatar", - "adminEnabled": true, - "allowedDomains": [], - "requireReview": false, - "enableCommentLike": true, - "enableArticleLike": true, - "enableImageLightbox": true, - "commentPlaceholder": "发表你的看法..." -} -``` - -字段说明： - -| 字段名 | 类型 | 说明 | -| -------------------- | ------ | -------------------------------------------------------------------- | -| `adminEmail` | string | 博主邮箱地址，用于在前端展示"博主"标识，并触发管理员身份验证流程 | -| `adminBadge` | string | 博主标识文字，例如 `"博主"` | -| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 需像地址 | -| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） | -| `allowedDomains` | Array\ | 允许调用组件的域名列表，留空则不限制 | -| `requireReview` | boolean | 是否开启新评论先审核再显示（true 表示新评论默认为待审核） | -| `enableCommentLike` | boolean | 是否启用评论点赞功能（默认 true） | -| `enableArticleLike` | boolean | 是否启用文章点赞功能（默认 true） | -| `enableImageLightbox` | boolean | 是否启用评论图片灯箱预览功能（默认 false） | -| `commentPlaceholder` | string \| null | 评论输入框的占位符文本，留空则使用默认值 | - -**错误响应** - -- 状态!码：`500` - -```json -{ - "message": "加载评论配置失败" -} -``` diff --git a/docs/api/public/like.md b/docs/api/public/like.md index e6d089e..3134dd5 100644 --- a/docs/api/public/like.md +++ b/docs/api/public/like.md @@ -1,3 +1,147 @@ # 点赞接口 文章和评论点赞相关的公开接口。 + +## 获取点赞状态 + +``` +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` + +```json +{ + "liked": false, + "alreadyLiked": false, + "totalLikes": 12 +} +``` + +字段说明： + +| 字段名 | 类型 | 说明 | +| ------------- | ------- | ---------------------------------------- | +| `liked` | boolean | 当前用户是否已点赞 | +| `alreadyLiked` | boolean | 预留字段，当前实现始终为 `false` | +| `totalLikes` | number | 当前页面的总点赞数 | + +**错误响应** + +- 缺少 `post_slug`： + + - 状态码：`400` + + ```json + { + "message": "post_slug is required" + } + ``` + +- 服务器内部错误： + + - 状态码：`500` + + ```json + { + "message": "获取点赞状态失败" + } + ``` + +## 点赞文章 + +``` +POST /api/like +``` + +对当前页面执行点赞操作，同一用户对同一页面只会计入一次点赞。 + +- 方法：`POST` +- 路径：`/api/like` +- 鉴权：不需要 + +**请求头** + +| 名称 | 必填 | 示例 | 说明 | +| ----------------- | ---- | ----------------------------- | ------------------------------ | +| `ContentC-Type` | 是 | `application/json` | | +| `X-CWD-Like-User` | 否 | `550e8400-e29b-41d4-a716...` | 前端生成的匿名用户标识，用于区分不同用户 | + +**请求体** + +```json +{ + "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` + +```json +{ + "liked": true, + "alreadyLiked": false, + "totalLikes": 13 +} +``` + +说明： + +- 第一次点赞：`liked=true`，`alreadyLiked=false`，`totalLikes` 增加 1； +- 重复点赞：服务器不会重复插入记录，`alreadyLiked=true`，`totalLikes` 不会继续增加。 + +**错误响应** + +- 缺少 `postSlug`： + + - 状态码：`400` + + ```json + { + "message": "postSlug is required" + } + ``` + +- 服务器内部错误： + + - 状态码：`500` + + ```json + { + "message": "点赞失败" + } + ``` diff --git a/docs/api/public/like/get-like-status.md b/docs/api/public/like/get-like-status.md deleted file mode 100644 index 9bfce38..0000000 --- a/docs/api/public/like/get-like-status.md +++ /dev/null @@ -1,67 +0,0 @@ -# 获取点赞状态 - -``` -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` - -```json -{ - "liked": false, - "alreadyLiked": false, - "totalLikes": 12 -} -``` - -字段说明： - -| 字段名 | 类型 | 说明 | -| ------------- | ------- | ---------------------------------------- | -| `liked` | boolean | 当前用户是否已点赞 | -| `alreadyLiked` | boolean | 预留字段，当前实现始终为 `false` | -| `totalLikes` | number | 当前页面的总点赞数 | - -**错误响应** - -- 缺少 `post_slug`： - - - 状态码：`400` - - ```json - { - "message": "post_slug is required" - } - ``` - -- 服务器内部错误： - - - 状态码：`500` - - ```json - { - "message": "获取点赞状态失败" - } - ``` diff --git a/docs/api/public/like/post-like.md b/docs/api/public/like/post-like.md deleted file mode 100644 index b46b0ec..0000000 --- a/docs/api/public/like/post-like.md +++ /dev/null @@ -1,75 +0,0 @@ -# 点赞文章 - -``` -POST /api/like -``` - -对当前页面执行点赞操作，同一用户对同一页面只会计入一次点赞。 - -- 方法：`POST` -- 路径：`/api/like` -- 鉴权：不需要 - -**请求头** - -| 名称 | 必填 | 示例 | 说明 | -| ----------------- | ---- | ----------------------------- | ------------------------------ | -| `ContentC-Type` | 是 | `application/json` | | -| `X-CWD-Like-User` | 否 | `550e8400-e29b-41d4-a716...` | 前端生成的匿名用户标识，用于区分不同用户 | - -**请求体** - -```json -{ - "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` - -```json -{ - "liked": true, - "alreadyLiked": false, - "totalLikes": 13 -} -``` - -说明： - -- 第一次点赞：`liked=true`，`alreadyLiked=false`，`totalLikes` 增加 1； -- 重复点赞：服务器不会重复插入记录，`alreadyLiked=true`，`totalLikes` 不会继续增加。 - -**错误响应** - -- 缺少 `postSlug`： - - - 状态码：`400` - - ```json - { - "message": "postSlug is required" - } - ``` - -- 服务器内部错误： - - - 状态码：`500` - - ```json - { - "message": "点赞失败" - } - ```