meowrain/AI_OJ
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 实现题目服务完整校验责任链和流量控制

Browse Source 
- 责任链校验系统
  * 题目创建参数校验（标题、内容、难度、判题配置、标签）
  * 题目编辑参数校验（可选字段校验）
  * 题目更新参数校验（管理员、存在性校验）
  * 题目提交参数校验（存在性、状态、语言、代码安全）

- Sentinel 流量控制
  * 添加 Sentinel 依赖和配置
  * 题目提交接口添加限流注解和降级处理

- 数据模型优化
  * QuestionResponseDTO 返回对象类型（JudgeConfig、JudgeCase）
  * 实现 Entity 与 DTO 的 JSON 转换

- 接口文档
  * 生成博客服务完整 API 文档

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
meowrain
2026-01-26 23:10:19 +08:00
parent c06cfc10ee
commit 5681b6bcef
27 changed files with 1918 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

708
aioj-backend-blog-service/接口文档.md Normal file
View File

@@ -0,0 +1,708 @@
# 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 | 更新时间 |