feat: 实现API文档支持与系统优化

refactor(ArticleRepository): 修正@Param注解导入错误并优化查询方法 fix(ArticleService): 解决事务回滚问题并优化日志配置 feat(SecurityConfig): 添加Spring Security配置禁用默认认证 docs: 添加详细API文档README_API.md feat(HelpController): 实现Markdown文档渲染API style: 清理无用注释和导入 build: 更新pom.xml依赖和插件配置 chore: 优化application.properties配置
2025-10-10 16:20:13 +08:00
parent fdb0608751
commit 60f4752124
14 changed files with 7792 additions and 39 deletions
--- a/README_API.md
+++ b/README_API.md
@@ -0,0 +1,595 @@
+# MyAfterProject 开发文档（前端使用）
+
+## 项目概述
+
+MyAfterProject是一个基于Spring Boot的后端博客系统，提供文章管理、留言板等功能的API接口。本文档旨在帮助前端开发者理解和使用这些API接口。
+
+## 技术栈
+
+- **后端框架**: Spring Boot 2.x
+- **ORM框架**: Spring Data JPA
+- **数据库**: MySQL
+- **缓存**: Redis
+- **认证**: Spring Security + JWT
+- **API风格**: RESTful
+
+## 项目结构
+
+```
+src/main/java/com/qf/myafterprojecy/
+├── controller/           # 控制器层，处理HTTP请求
+│   ├── ArticleController.java  # 文章相关API
+│   └── MessageController.java  # 留言相关API
+├── pojo/                 # 实体类和数据传输对象
+│   ├── Article.java              # 文章实体
+│   ├── Message.java              # 留言实体
+│   ├── ResponseMessage.java      # 统一响应消息格式
+│   └── dto/                      # 数据传输对象
+│       ├── ArticleDto.java       # 文章DTO
+│       └── MessageDto.java       # 留言DTO
+├── repository/           # 数据访问层
+│   ├── ArticleRepository.java    # 文章数据访问
+│   └── MessageRepository.java    # 留言数据访问
+├── service/              # 业务逻辑层
+│   ├── ArticleService.java       # 文章服务实现
+│   ├── IArticleService.java      # 文章服务接口
+│   ├── MessageService.java       # 留言服务实现
+│   └── IMessageService.java      # 留言服务接口
+├── GlobalExceptionHandler.java   # 全局异常处理器
+└── MyAfterProjecyApplication.java # 应用入口
+```
+
+## 配置信息
+
+后端服务默认运行在 `http://localhost:8080` 端口，前端项目需要将API请求指向该地址。
+
+## API接口详细说明
+
+### 统一响应格式
+
+所有API接口都返回统一的响应格式 `ResponseMessage<T>`：
+
+```json
+{
+  "code": 200,              // HTTP状态码
+  "message": "成功",        // 响应消息
+  "success": true,          // 是否成功
+  "data": {}                // 响应数据（具体类型根据接口而定）
+}
+```
+
+### 1. 文章管理API
+
+#### 1.1 获取所有文章
+
+```
+GET /api/articles
+```
+
+**功能**: 获取所有已发布的文章列表
+
+**请求参数**: 无
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "查询成功",
+  "success": true,
+  "data": [
+    {
+      "articleid": 1,
+      "title": "文章标题",
+      "content": "文章内容...",
+      "typeid": 1,
+      "img": "图片URL",
+      "createdAt": "2023-01-01T10:00:00",
+      "updatedAt": "2023-01-01T10:00:00",
+      "viewCount": 100,
+      "status": 1
+    },
+    // 更多文章...
+  ]
+}
+```
+
+#### 1.2 获取单篇文章
+
+```
+GET /api/articles/{id}
+```
+
+**功能**: 根据ID获取单篇文章详情（会自动增加浏览量）
+
+**请求参数**: 
+- `id`: 文章ID（路径参数）
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "查询成功",
+  "success": true,
+  "data": {
+    "articleid": 1,
+    "title": "文章标题",
+    "content": "文章内容...",
+    "typeid": 1,
+    "img": "图片URL",
+    "createdAt": "2023-01-01T10:00:00",
+    "updatedAt": "2023-01-01T10:00:00",
+    "viewCount": 101,
+    "status": 1
+  }
+}
+```
+
+#### 1.3 根据分类获取文章
+
+```
+GET /api/articles/category/{categoryId}
+```
+
+**功能**: 获取指定分类下的所有文章
+
+**请求参数**: 
+- `categoryId`: 分类ID（路径参数）
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "查询成功",
+  "success": true,
+  "data": [
+    // 文章列表（结构同获取所有文章）
+  ]
+}
+```
+
+#### 1.4 获取热门文章
+
+```
+GET /api/articles/popular
+```
+
+**功能**: 获取浏览量最高的文章列表
+
+**请求参数**: 无
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "查询成功",
+  "success": true,
+  "data": [
+    // 热门文章列表（结构同获取所有文章）
+  ]
+}
+```
+
+#### 1.5 创建文章（需要认证）
+
+```
+POST /api/articles
+```
+
+**功能**: 创建新文章
+
+**权限**: 需要AUTHOR角色
+
+**请求体**: 
+```json
+{
+  "title": "新文章标题",
+  "content": "新文章内容",
+  "img": "图片URL",
+  "status": 1  // 0-草稿，1-已发布
+}
+```
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "保存成功",
+  "success": true,
+  "data": {
+    "articleid": 2,
+    "title": "新文章标题",
+    "content": "新文章内容",
+    // 其他文章字段
+  }
+}
+```
+
+#### 1.6 更新文章（需要认证）
+
+```
+PUT /api/articles/{id}
+```
+
+**功能**: 更新现有文章
+
+**权限**: 需要AUTHOR或ADMIN角色
+
+**请求参数**: 
+- `id`: 文章ID（路径参数）
+
+**请求体**: 
+```json
+{
+  "title": "更新后的标题",
+  "content": "更新后的内容",
+  "img": "更新后的图片URL",
+  "status": 1
+}
+```
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "更新成功",
+  "success": true,
+  "data": {
+    // 更新后的文章信息
+  }
+}
+```
+
+#### 1.7 删除文章（需要认证）
+
+```
+DELETE /api/articles/{id}
+```
+
+**功能**: 删除指定文章
+
+**权限**: 需要AUTHOR或ADMIN角色
+
+**请求参数**: 
+- `id`: 文章ID（路径参数）
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "删除成功",
+  "success": true,
+  "data": {
+    // 被删除的文章信息
+  }
+}
+```
+
+### 2. 留言管理API
+
+#### 2.1 获取所有留言
+
+```
+GET /api/messages
+```
+
+**功能**: 获取所有留言列表
+
+**请求参数**: 无
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "查询成功",
+  "success": true,
+  "data": [
+    {
+      "messageid": 1,
+      "nickname": "用户名",
+      "email": "user@example.com",
+      "content": "留言内容",
+      "createdAt": "2023-01-01T10:00:00",
+      "parentid": null, // 父留言ID，null表示主留言
+      "articleid": null // 关联的文章ID，null表示无关联
+    },
+    // 更多留言...
+  ]
+}
+```
+
+#### 2.2 获取单条留言
+
+```
+GET /api/messages/{id}
+```
+
+**功能**: 根据ID获取单条留言详情
+
+**请求参数**: 
+- `id`: 留言ID（路径参数）
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "查询成功",
+  "success": true,
+  "data": {
+    // 留言详细信息（结构同上）
+  }
+}
+```
+
+#### 2.3 创建留言
+
+```
+POST /api/messages
+```
+
+**功能**: 发布新留言
+
+**请求体**: 
+```json
+{
+  "nickname": "用户名",
+  "email": "user@example.com",
+  "content": "新留言内容",
+  "parentid": null,  // 可选，回复时设置为被回复留言的ID
+  "articleid": null  // 可选，关联文章时设置为文章ID
+}
+```
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "保存成功",
+  "success": true,
+  "data": {
+    // 保存后的留言信息
+  }
+}
+```
+
+#### 2.4 删除留言（需要认证）
+
+```
+DELETE /api/messages/{id}
+```
+
+**功能**: 删除指定留言
+
+**权限**: 需要ADMIN角色
+
+**请求参数**: 
+- `id`: 留言ID（路径参数）
+
+**返回数据**: 
+```json
+{
+  "code": 200,
+  "message": "删除成功",
+  "success": true,
+  "data": {
+    // 被删除的留言信息
+  }
+}
+```
+
+## 数据模型详解
+
+### 1. 文章模型 (Article)
+
+| 字段名 | 类型 | 描述 | 是否可为空 |
+|-------|------|-----|-----------|
+| articleid | Integer | 文章ID（主键） | 否 |
+| title | String | 文章标题 | 否 |
+| content | String | 文章内容 | 否 |
+| typeid | Integer | 分类ID | 否 |
+| img | String | 文章图片URL | 是 |
+| createdAt | LocalDateTime | 创建时间 | 是 |
+| updatedAt | LocalDateTime | 更新时间 | 是 |
+| viewCount | Integer | 浏览次数 | 是 |
+| status | Integer | 状态（0-草稿，1-已发布，2-已删除） | 是 |
+
+### 2. 留言模型 (Message)
+
+| 字段名 | 类型 | 描述 | 是否可为空 |
+|-------|------|-----|-----------|
+| messageid | Integer | 留言ID（主键） | 否 |
+| nickname | String | 昵称 | 是 |
+| email | String | 邮箱 | 是 |
+| content | String | 留言内容 | 是 |
+| createdAt | Date | 创建时间 | 是 |
+| parentid | Integer | 父留言ID（用于回复功能） | 是 |
+| articleid | Integer | 关联的文章ID | 是 |
+
+### 3. 数据传输对象 (DTO)
+
+DTO类用于前后端数据传输，是对实体类的简化，只包含需要传输的字段。
+
+- **ArticleDto**: 包含文章的基本信息，用于创建和更新文章
+- **MessageDto**: 包含留言的基本信息，用于创建和更新留言
+
+## 前端调用示例
+
+以下是使用Axios调用后端API的示例代码：
+
+### 1. 安装Axios
+
+```bash
+npm install axios
+```
+
+### 2. 创建API服务文件
+
+创建一个 `api.js` 文件来封装所有的API调用：
+
+```javascript
+import axios from 'axios';
+
+// 创建axios实例
+const api = axios.create({
+  baseURL: 'http://localhost:8080/api', // 后端API基础URL
+  timeout: 10000, // 请求超时时间
+  headers: {
+    'Content-Type': 'application/json'
+  }
+});
+
+// 请求拦截器 - 添加认证token
+api.interceptors.request.use(
+  config => {
+    const token = localStorage.getItem('token');
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  },
+  error => {
+    return Promise.reject(error);
+  }
+);
+
+// 响应拦截器 - 统一处理响应
+api.interceptors.response.use(
+  response => {
+    // 检查响应是否成功
+    if (response.data && response.data.success) {
+      return response.data;
+    } else {
+      // 处理业务错误
+      return Promise.reject(new Error(response.data?.message || '请求失败'));
+    }
+  },
+  error => {
+    // 处理HTTP错误
+    console.error('API请求错误:', error);
+    // 可以在这里添加全局错误处理，如显示错误提示
+    return Promise.reject(error);
+  }
+);
+
+// 文章相关API
+export const articleAPI = {
+  // 获取所有文章
+  getAllArticles: () => api.get('/articles'),
+  // 获取单篇文章
+  getArticleById: (id) => api.get(`/articles/${id}`),
+  // 根据分类获取文章
+  getArticlesByCategory: (categoryId) => api.get(`/articles/category/${categoryId}`),
+  // 获取热门文章
+  getPopularArticles: () => api.get('/articles/popular'),
+  // 创建文章
+  createArticle: (articleData) => api.post('/articles', articleData),
+  // 更新文章
+  updateArticle: (id, articleData) => api.put(`/articles/${id}`, articleData),
+  // 删除文章
+  deleteArticle: (id) => api.delete(`/articles/${id}`)
+};
+
+// 留言相关API
+export const messageAPI = {
+  // 获取所有留言
+  getAllMessages: () => api.get('/messages'),
+  // 获取单条留言
+  getMessageById: (id) => api.get(`/messages/${id}`),
+  // 创建留言
+  saveMessage: (messageData) => api.post('/messages', messageData),
+  // 删除留言
+  deleteMessage: (id) => api.delete(`/messages/${id}`)
+};
+
+export default api;
+```
+
+### 3. 在组件中使用API
+
+```javascript
+import { articleAPI, messageAPI } from './api';
+
+// 获取文章列表
+async function fetchArticles() {
+  try {
+    const response = await articleAPI.getAllArticles();
+    // 处理获取到的文章数据
+    console.log('文章列表:', response.data);
+  } catch (error) {
+    console.error('获取文章列表失败:', error);
+  }
+}
+
+// 发布留言
+async function postMessage(messageData) {
+  try {
+    const response = await messageAPI.saveMessage(messageData);
+    console.log('留言发布成功:', response.data);
+    return response.data;
+  } catch (error) {
+    console.error('发布留言失败:', error);
+    throw error;
+  }
+}
+```
+
+## 错误处理指南
+
+### 常见错误码及处理方式
+
+| HTTP状态码 | 错误描述 | 可能原因 | 处理方式 |
+|-----------|---------|---------|---------|
+| 400 | Bad Request | 请求参数错误或缺失 | 检查请求参数是否正确 |
+| 401 | Unauthorized | 未授权访问 | 需要登录获取token |
+| 403 | Forbidden | 权限不足 | 确认用户是否有足够权限 |
+| 404 | Not Found | 请求资源不存在 | 检查请求URL或资源ID是否正确 |
+| 500 | Internal Server Error | 服务器内部错误 | 查看服务器日志，联系后端开发人员 |
+
+### 全局错误处理建议
+
+1. 在前端实现全局响应拦截器，统一处理API返回的错误
+2. 为不同类型的错误显示相应的提示信息
+3. 对于需要认证的API，在401错误时引导用户登录
+4. 添加请求超时处理和重试机制
+
+## 开发环境配置
+
+### 跨域配置
+
+后端已配置CORS，允许从 `http://localhost:3000` 访问（前端开发服务器默认端口）。如果前端开发服务器使用其他端口，需要修改后端的 `application.properties` 中的 `cors.allowed-origins` 配置。
+
+### 认证配置
+
+对于需要认证的API，前端需要在请求头中添加JWT token。获取token的方式可以通过登录接口（本项目暂未实现完整的用户认证功能）。
+
+## 性能优化建议
+
+1. **请求防抖和节流**：在频繁触发的操作中使用防抖和节流，减少不必要的API调用
+2. **数据缓存**：对于不经常变动的数据，可在前端进行缓存
+3. **分页加载**：对于大量数据，使用分页加载而不是一次性获取全部数据
+4. **图片懒加载**：对文章中的图片实现懒加载，提高页面加载速度
+5. **错误重试**：对非关键API添加自动重试机制，提高用户体验
+
+## 附录：完整实体关系图
+
+```
+-------------+       +-------------+
+|   Article   |       |   Message   |
+-------------+       +-------------+
+| articleid   |<--+   | messageid   |
+| title       |   |   | nickname    |
+| content     |   |   | email       |
+| typeid      |   |   | content     |
+| img         |   |   | createdAt   |
+| createdAt   |   |   | parentid    |-->|
+| updatedAt   |   |   | articleid   |-->+
+| viewCount   |   |   +-------------+
+| status      |   |
+-------------+   |
+                  |
+                  |
+           +-------------+
+           |    Reply    |
+           +-------------+
+           | (通过Message.parentid实现) |
+           +-------------+
+```