花枫咖啡馆内部扩展 API — 博客与文章模块 (Blog)

基础信息

• 前缀URL: /v1/internal
• 主要功能: 发布博客文章、查看详情与自动增加阅读量、博客列表筛选、修改/删除文章、博客分类 CRUD、全站热门标签统计。

---

接口列表

1. 发布博客文章

POST /v1/internal/blog.create

发布一篇新博客文章。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
title	string	是	文章标题
content	string	是	文章内容
category_id	number	否	所属分类 ID
tags	string | string[]	否	标签（字符串逗号分隔或数组）
content_type	string	否	内容格式 (text / markdown / html)，默认 text

请求示例

{
  "title": "我的第一篇博客",
  "content": "# Hello World\n这是内容",
  "category_id": 1,
  "tags": ["Node.js", "Bun"],
  "content_type": "markdown"
}

成功响应示例

{
  "id": "101"
}

---

2. 获取博客文章详情

POST /v1/internal/blog.get

获取文章详情（调用后阅读数加 1）。

请求参数

参数名	类型	必填	描述
id	number	是	博客文章 ID

请求示例

{
  "id": 101
}

成功响应示例

{
  "id": 101,
  "user_id": 1,
  "title": "我的第一篇博客",
  "content": "# Hello World\n这是内容",
  "type": "blog",
  "category_id": 1,
  "content_type": "markdown",
  "tags": "[\"Node.js\",\"Bun\"]",
  "view_count": 5,
  "created_at": "2026-02-01 12:00:00"
}

---

3. 获取博客文章列表

POST /v1/internal/blog.list

查询博客文章列表。支持按作者 user_id 或标签 tag 筛选。

请求参数

参数名	类型	必填	描述
page	number	否	页码，默认 1
limit	number	否	每页数量，默认 20
user_id	number	否	作者用户 ID
tag	string	否	按标签搜索

请求示例

{
  "page": 1,
  "limit": 10,
  "user_id": 1
}

成功响应示例

{
  "data": [
    {
      "id": 101,
      "title": "我的第一篇博客",
      "type": "blog",
      "view_count": 5
    }
  ],
  "page": 1,
  "limit": 10
}

---

4. 更新博客文章

POST /v1/internal/blog.update

修改本人已发布的博客文章。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
id	number	是	博客文章 ID
title	string	否	新标题
content	string	否	新内容
content_type	string	否	内容类型
category_id	number	否	新分类 ID

请求示例

{
  "id": 101,
  "title": "修改后的标题",
  "content": "修改后的内容"
}

成功响应示例

{
  "success": true,
  "data": 1
}

---

5. 删除博客文章

POST /v1/internal/blog.delete

删除本人发布的博客文章。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
id	number	是	博客文章 ID

请求示例

{
  "id": 101
}

成功响应示例

{
  "success": true
}

---

6. 创建博客分类

POST /v1/internal/blog.category.create

创建个人博客分类。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
name	string	是	分类名称
description	string	否	分类描述

请求示例

{
  "name": "技术笔记",
  "description": "关于前端与后端的笔记"
}

成功响应示例

{
  "id": 1,
  "user_id": 1,
  "name": "技术笔记",
  "description": "关于前端与后端的笔记"
}

---

7. 获取博客分类列表

POST /v1/internal/blog.category.list

获取特定用户创建的博客分类列表。

请求参数

参数名	类型	必填	描述
user_id	number	否	目标用户 ID（缺省则尝试获取当前 Token 用户）

请求示例

{
  "user_id": 1
}

成功响应示例

{
  "data": [
    {
      "id": 1,
      "name": "技术笔记",
      "description": "关于前端与后端的笔记"
    }
  ]
}

---

8. 更新博客分类

POST /v1/internal/blog.category.update

修改个人博客分类。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
id	number	是	分类 ID
name	string	否	新分类名称
description	string	否	新分类描述

请求示例

{
  "id": 1,
  "name": "架构设计"
}

成功响应示例

{
  "id": 1,
  "name": "架构设计"
}

---

9. 删除博客分类

POST /v1/internal/blog.category.delete

删除个人博客分类。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
id	number	是	分类 ID

请求示例

{
  "id": 1
}

成功响应示例

{
  "success": true,
  "data": 1
}

---

10. 获取热门博客标签

POST /v1/internal/blog.popular_tags

获取全站热门使用的博客标签。

请求参数

参数名	类型	必填	描述
limit	number	否	返回标签数量，默认 20

请求示例

{
  "limit": 10
}

成功响应示例

{
  "data": ["Node.js", "React", "TypeScript"]
}