AI_OJ/aioj-backend-blog-service/接口文档.md

# AIOJ 博客服务接口文档

## 服务信息

- **服务名称**: aioj-blog-service
- **服务端口**: 18086
- **基础路径**: `/api`
- **API 文档**: `/swagger-ui.html`

## 通用说明

### 统一响应格式

所有接口均使用统一的响应格式 `Result<T>`：

```json
{
  "code": "0",        // 响应码，"0"表示成功
  "message": "success", // 响应信息
  "data": {}          // 响应数据
}
```

### 分页响应格式

分页查询返回 `IPage<T>` 格式：

```json
{
  "code": "0",
  "message": "success",
  "data": {
    "records": [],    // 数据列表
    "total": 100,     // 总记录数
    "size": 10,       // 每页数量
    "current": 1,     // 当前页码
    "pages": 10       // 总页数
  }
}
```

---

## 1. 文章管理接口

### 1.1 创建文章

- **接口**: `POST /api/v1/article/create`
- **描述**: 创建新文章，支持 Markdown 格式

**请求参数**:

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| title | String | 是 | 文章标题 | Spring Boot 3.5.7 新特性详解 |
| slug | String | 否 | 文章别名（URL友好标识） | spring-boot-3-5-7-features |
| summary | String | 否 | 文章摘要 | 本文详细介绍Spring Boot 3.5.7版本的新特性... |
| content | String | 是 | 文章内容（Markdown格式） | # 欢迎使用... |
| coverImage | String | 否 | 封面图片URL | https://example.com/images/cover.jpg |
| categoryId | Long | 是 | 分类ID | 1 |
| tagIds | List\<Long\> | 否 | 标签ID列表 | [1, 2, 3] |
| isTop | Integer | 否 | 是否置顶（0=否，1=是） | 0 |
| isEssence | Integer | 否 | 是否精华（0=否，1=是） | 0 |
| isPublished | Integer | 否 | 是否发布（0=草稿，1=已发布） | 1 |

**响应示例**:

```json
{
  "code": "0",
  "message": "success",
  "data": 123
}
```

### 1.2 更新文章

- **接口**: `PUT /api/v1/article/update`
- **描述**: 更新已存在的文章信息

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 文章ID |
| 其他字段 | - | - | 同创建文章 |

### 1.3 删除文章

- **接口**: `DELETE /api/v1/article/delete/{articleId}`
- **描述**: 逻辑删除指定文章

**路径参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| articleId | Long | 是 | 文章ID |

### 1.4 查询文章详情

- **接口**: `GET /api/v1/article/{articleId}`
- **描述**: 根据文章ID查询文章详细信息

**响应示例**:

```json
{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "title": "Spring Boot 3.5.7 新特性详解",
    "slug": "spring-boot-3-5-7-features",
    "summary": "本文详细介绍Spring Boot 3.5.7版本的新特性...",
    "content": "# 欢迎使用...",
    "contentHtml": "<h1>欢迎使用...</h1>",
    "coverImage": "https://example.com/images/cover.jpg",
    "authorId": 1,
    "authorName": "admin",
    "categoryId": 1,
    "categoryName": "算法题解",
    "tags": [
      {
        "id": 1,
        "name": "数据结构",
        "slug": "data-structure",
        "color": "#3498db"
      }
    ],
    "viewCount": 100,
    "likeCount": 10,
    "commentCount": 5,
    "collectCount": 3,
    "isTop": 0,
    "isEssence": 0,
    "isPublished": 1,
    "status": 1,
    "publishTime": "2026-01-26T10:00:00",
    "createTime": "2026-01-26T09:00:00",
    "updateTime": "2026-01-26T10:00:00",
    "isLiked": false,
    "isCollected": false
  }
}
```

### 1.5 根据slug查询文章

- **接口**: `GET /api/v1/article/slug/{slug}`

### 1.6 分页查询文章列表

- **接口**: `POST /api/v1/article/list`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| current | Integer | 否 | 页码，默认1 |
| size | Integer | 否 | 每页数量，默认10 |
| id | Long | 否 | 文章ID |
| title | String | 否 | 文章标题（模糊查询） |
| categoryId | Long | 否 | 分类ID |
| tagId | Long | 否 | 标签ID |
| authorId | Long | 否 | 作者ID |
| isTop | Integer | 否 | 是否置顶 |
| isEssence | Integer | 否 | 是否精华 |
| isPublished | Integer | 否 | 是否发布（0=草稿，1=已发布） |
| status | Integer | 否 | 文章状态（1=正常，2=审核中，3=已关闭，4=已删除） |
| sortField | String | 否 | 排序字段（view_count/like_count/comment_count/publish_time） |
| sortOrder | String | 否 | 排序方式（asc/desc） |

### 1.7 发布文章

- **接口**: `PUT /api/v1/article/publish/{articleId}`

### 1.8 取消发布文章

- **接口**: `PUT /api/v1/article/unpublish/{articleId}`

### 1.9 增加文章浏览量

- **接口**: `POST /api/v1/article/view/{articleId}`

---

## 2. 分类管理接口

### 2.1 创建分类

- **接口**: `POST /api/v1/category/create`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | 是 | 分类名称 |
| slug | String | 否 | 分类别名 |
| description | String | 否 | 分类描述 |
| icon | String | 否 | 分类图标 |
| sortOrder | Integer | 否 | 排序序号 |
| parentId | Long | 否 | 父分类ID |
| isEnabled | Integer | 否 | 是否启用 |

### 2.2 更新分类

- **接口**: `PUT /api/v1/category/update`

### 2.3 删除分类

- **接口**: `DELETE /api/v1/category/delete/{categoryId}`

### 2.4 查询分类详情

- **接口**: `GET /api/v1/category/{categoryId}`

**响应示例**:

```json
{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "name": "算法题解",
    "slug": "algorithm-solutions",
    "description": "算法题目解题思路和代码分享",
    "icon": "💡",
    "sortOrder": 1,
    "parentId": 0,
    "articleCount": 10,
    "isEnabled": 1,
    "createTime": "2026-01-26T09:00:00",
    "updateTime": "2026-01-26T09:00:00"
  }
}
```

### 2.5 根据slug查询分类

- **接口**: `GET /api/v1/category/slug/{slug}`

### 2.6 查询所有分类

- **接口**: `GET /api/v1/category/list/all`

### 2.7 查询启用的分类

- **接口**: `GET /api/v1/category/list/enabled`

---

## 3. 标签管理接口

### 3.1 创建标签

- **接口**: `POST /api/v1/tag/create`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | 是 | 标签名称 |
| slug | String | 否 | 标签别名 |
| description | String | 否 | 标签描述 |
| color | String | 否 | 标签颜色 |
| isEnabled | Integer | 否 | 是否启用 |

### 3.2 更新标签

- **接口**: `PUT /api/v1/tag/update`

### 3.3 删除标签

- **接口**: `DELETE /api/v1/tag/delete/{tagId}`

### 3.4 查询标签详情

- **接口**: `GET /api/v1/tag/{tagId}`

**响应示例**:

```json
{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "name": "数据结构",
    "slug": "data-structure",
    "description": "数据结构与算法相关内容",
    "color": "#3498db",
    "articleCount": 5,
    "isEnabled": 1,
    "createTime": "2026-01-26T09:00:00",
    "updateTime": "2026-01-26T09:00:00"
  }
}
```

### 3.5 根据slug查询标签

- **接口**: `GET /api/v1/tag/slug/{slug}`

### 3.6 查询所有标签

- **接口**: `GET /api/v1/tag/list/all`

### 3.7 查询启用的标签

- **接口**: `GET /api/v1/tag/list/enabled`

### 3.8 查询文章的标签

- **接口**: `GET /api/v1/tag/article/{articleId}`

---

## 4. 评论管理接口

### 4.1 发表评论

- **接口**: `POST /api/v1/comment/create`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| articleId | Long | 是 | 文章ID |
| content | String | 是 | 评论内容（支持Markdown） |
| parentId | Long | 否 | 父评论ID（0表示一级评论） |
| replyToId | Long | 否 | 回复的评论ID（用于@提醒） |

### 4.2 回复评论

- **接口**: `POST /api/v1/comment/reply`

### 4.3 删除评论

- **接口**: `DELETE /api/v1/comment/delete/{commentId}`

### 4.4 查询评论详情

- **接口**: `GET /api/v1/comment/{commentId}`

**响应示例**:

```json
{
  "code": "0",
  "message": "success",
  "data": {
    "id": 1,
    "articleId": 1,
    "userId": 1,
    "userName": "admin",
    "userAvatar": "https://example.com/avatar.jpg",
    "parentId": 0,
    "replyToId": 0,
    "replyToName": null,
    "content": "这篇文章写得很好！",
    "contentHtml": "<p>这篇文章写得很好！</p>",
    "likeCount": 5,
    "replyCount": 2,
    "isAuthor": 1,
    "status": 1,
    "createTime": "2026-01-26T10:00:00",
    "updateTime": "2026-01-26T10:00:00",
    "isLiked": false,
    "children": []
  }
}
```

### 4.5 查询文章评论

- **接口**: `GET /api/v1/comment/article/{articleId}`
- **描述**: 根据文章ID查询该文章的所有评论（树形结构）

### 4.6 分页查询评论列表

- **接口**: `POST /api/v1/comment/list`

### 4.7 查询子评论

- **接口**: `GET /api/v1/comment/children/{parentId}`

---

## 5. 点赞管理接口

### 5.1 点赞

- **接口**: `POST /api/v1/like/like`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| targetId | Long | 是 | 目标ID |
| targetType | Integer | 是 | 目标类型（1=文章，2=评论） |

### 5.2 取消点赞

- **接口**: `POST /api/v1/like/unlike`

### 5.3 查询点赞状态

- **接口**: `GET /api/v1/like/check`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| targetId | Long | 是 | 目标ID |
| targetType | Integer | 是 | 目标类型（1=文章，2=评论） |

### 5.4 切换点赞状态

- **接口**: `POST /api/v1/like/toggle`

---

## 6. 收藏管理接口

### 6.1 收藏文章

- **接口**: `POST /api/v1/collection/collect`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| articleId | Long | 是 | 文章ID |
| folderId | Long | 否 | 收藏夹ID |

### 6.2 取消收藏文章

- **接口**: `DELETE /api/v1/collection/uncollect/{articleId}`

### 6.3 查询收藏状态

- **接口**: `GET /api/v1/collection/check/{articleId}`

### 6.4 创建收藏夹

- **接口**: `POST /api/v1/collection/folder/create`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | String | 是 | 收藏夹名称 |
| description | String | 否 | 收藏夹描述 |

### 6.5 删除收藏夹

- **接口**: `DELETE /api/v1/collection/folder/delete/{folderId}`

### 6.6 查询收藏夹列表

- **接口**: `GET /api/v1/collection/folder/list`

### 6.7 分页查询收藏列表

- **接口**: `GET /api/v1/collection/list`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| current | Integer | 是 | 页码 |
| size | Integer | 是 | 每页数量 |
| folderId | Long | 否 | 收藏夹ID |

---

## 7. 关注管理接口

### 7.1 关注用户

- **接口**: `POST /api/v1/follow/follow`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| followingId | Long | 是 | 被关注者ID |

### 7.2 取消关注用户

- **接口**: `DELETE /api/v1/follow/unfollow/{followingId}`

### 7.3 查询关注状态

- **接口**: `GET /api/v1/follow/check/{followingId}`

### 7.4 查询关注列表

- **接口**: `GET /api/v1/follow/following/list`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| userId | Long | 是 | 用户ID |
| current | Integer | 是 | 页码 |
| size | Integer | 是 | 每页数量 |

### 7.5 查询粉丝列表

- **接口**: `GET /api/v1/follow/followers/list`

### 7.6 查询关注数

- **接口**: `GET /api/v1/follow/following/count`

### 7.7 查询粉丝数

- **接口**: `GET /api/v1/follow/followers/count`

---

## 8. 通知管理接口

### 8.1 分页查询通知列表

- **接口**: `POST /api/v1/notification/list`

### 8.2 标记通知为已读

- **接口**: `PUT /api/v1/notification/read/{notificationId}`

### 8.3 批量标记通知为已读

- **接口**: `PUT /api/v1/notification/read/batch`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| - | List\<Long\> | 是 | 通知ID列表 |

### 8.4 标记所有通知为已读

- **接口**: `PUT /api/v1/notification/read/all`

### 8.5 清空所有通知

- **接口**: `DELETE /api/v1/notification/clear/all`

### 8.6 查询未读通知数量

- **接口**: `GET /api/v1/notification/unread/count`

---

## 9. 草稿箱管理接口

### 9.1 保存草稿

- **接口**: `POST /api/v1/draft/save`

**请求参数**:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | String | 否 | 草稿标题 |
| content | String | 否 | 草稿内容 |
| coverImage | String | 否 | 封面图片 |
| categoryId | Long | 否 | 分类ID |
| tagIds | List\<Long\> | 否 | 标签ID列表 |

### 9.2 删除草稿

- **接口**: `DELETE /api/v1/draft/delete/{draftId}`

### 9.3 查询草稿详情

- **接口**: `GET /api/v1/draft/{draftId}`

### 9.4 分页查询草稿列表

- **接口**: `GET /api/v1/draft/list`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| current | Integer | 是 | 页码 |
| size | Integer | 是 | 每页数量 |

### 9.5 查询最新草稿

- **接口**: `GET /api/v1/draft/latest`

---

## 附录：数据模型

### ArticleResponseDTO（文章响应）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 文章ID |
| title | String | 文章标题 |
| slug | String | 文章别名 |
| summary | String | 文章摘要 |
| content | String | 文章内容（Markdown格式） |
| contentHtml | String | 渲染后的HTML内容 |
| coverImage | String | 封面图片URL |
| authorId | Long | 作者用户ID |
| authorName | String | 作者用户名 |
| categoryId | Long | 分类ID |
| categoryName | String | 分类名称 |
| tags | List\<TagResponseDTO\> | 标签列表 |
| viewCount | Integer | 浏览次数 |
| likeCount | Integer | 点赞数 |
| commentCount | Integer | 评论数 |
| collectCount | Integer | 收藏数 |
| isTop | Integer | 是否置顶 |
| isEssence | Integer | 是否精华 |
| isPublished | Integer | 是否发布 |
| status | Integer | 文章状态 |
| publishTime | Date | 发布时间 |
| createTime | Date | 创建时间 |
| updateTime | Date | 更新时间 |
| isLiked | Boolean | 当前用户是否点赞 |
| isCollected | Boolean | 当前用户是否收藏 |

### ArticleListResponseDTO（文章列表响应）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 文章ID |
| title | String | 文章标题 |
| slug | String | 文章别名 |
| summary | String | 文章摘要 |
| coverImage | String | 封面图片URL |
| authorId | Long | 作者用户ID |
| authorName | String | 作者用户名 |
| authorAvatar | String | 作者头像 |
| categoryId | Long | 分类ID |
| categoryName | String | 分类名称 |
| tags | List\<TagResponseDTO\> | 标签列表 |
| viewCount | Integer | 浏览次数 |
| likeCount | Integer | 点赞数 |
| commentCount | Integer | 评论数 |
| collectCount | Integer | 收藏数 |
| isTop | Integer | 是否置顶 |
| isEssence | Integer | 是否精华 |
| publishTime | Date | 发布时间 |
| createTime | Date | 创建时间 |
| isLiked | Boolean | 当前用户是否点赞 |
| isCollected | Boolean | 当前用户是否收藏 |

### CommentResponseDTO（评论响应）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 评论ID |
| articleId | Long | 文章ID |
| userId | Long | 评论用户ID |
| userName | String | 评论用户名 |
| userAvatar | String | 评论用户头像 |
| parentId | Long | 父评论ID |
| replyToId | Long | 回复的评论ID |
| replyToName | String | 回复的用户名 |
| content | String | 评论内容 |
| contentHtml | String | 渲染后的HTML内容 |
| likeCount | Integer | 点赞数 |
| replyCount | Integer | 回复数 |
| isAuthor | Integer | 是否为作者评论 |
| status | Integer | 状态 |
| createTime | Date | 创建时间 |
| updateTime | Date | 更新时间 |
| isLiked | Boolean | 当前用户是否点赞 |
| children | List\<CommentResponseDTO\> | 子评论列表 |

### CategoryResponseDTO（分类响应）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 分类ID |
| name | String | 分类名称 |
| slug | String | 分类别名 |
| description | String | 分类描述 |
| icon | String | 分类图标 |
| sortOrder | Integer | 排序序号 |
| parentId | Long | 父分类ID |
| articleCount | Integer | 该分类下的文章数量 |
| isEnabled | Integer | 是否启用 |
| createTime | Date | 创建时间 |
| updateTime | Date | 更新时间 |

### TagResponseDTO（标签响应）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 标签ID |
| name | String | 标签名称 |
| slug | String | 标签别名 |
| description | String | 标签描述 |
| color | String | 标签颜色 |
| articleCount | Integer | 使用该标签的文章数量 |
| isEnabled | Integer | 是否启用 |
| createTime | Date | 创建时间 |
| updateTime | Date | 更新时间 |