qingfeng/MyAfterProject
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
60f4752124f2b3d9d25f4bddd5b4c86eac74ea0f
MyAfterProject/README_API.md
qingfeng1121 60f4752124 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

14 KiB
Raw Blame History

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>：

{
  "code": 200,              // HTTP状态码
  "message": "成功",        // 响应消息
  "success": true,          // 是否成功
  "data": {}                // 响应数据（具体类型根据接口而定）
}

1. 文章管理API

1.1 获取所有文章

GET /api/articles

功能: 获取所有已发布的文章列表

请求参数: 无

返回数据:

{
  "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（路径参数）

返回数据:

{
  "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（路径参数）

返回数据:

{
  "code": 200,
  "message": "查询成功",
  "success": true,
  "data": [
    // 文章列表（结构同获取所有文章）
  ]
}

1.4 获取热门文章

GET /api/articles/popular

功能: 获取浏览量最高的文章列表

请求参数: 无

返回数据:

{
  "code": 200,
  "message": "查询成功",
  "success": true,
  "data": [
    // 热门文章列表（结构同获取所有文章）
  ]
}

1.5 创建文章（需要认证）

POST /api/articles

功能: 创建新文章

权限: 需要AUTHOR角色

请求体:

{
  "title": "新文章标题",
  "content": "新文章内容",
  "img": "图片URL",
  "status": 1  // 0-草稿，1-已发布
}

返回数据:

{
  "code": 200,
  "message": "保存成功",
  "success": true,
  "data": {
    "articleid": 2,
    "title": "新文章标题",
    "content": "新文章内容",
    // 其他文章字段
  }
}

1.6 更新文章（需要认证）

PUT /api/articles/{id}

功能: 更新现有文章

权限: 需要AUTHOR或ADMIN角色

请求参数:

  • id: 文章ID（路径参数）

请求体:

{
  "title": "更新后的标题",
  "content": "更新后的内容",
  "img": "更新后的图片URL",
  "status": 1
}

返回数据:

{
  "code": 200,
  "message": "更新成功",
  "success": true,
  "data": {
    // 更新后的文章信息
  }
}

1.7 删除文章（需要认证）

DELETE /api/articles/{id}

功能: 删除指定文章

权限: 需要AUTHOR或ADMIN角色

请求参数:

  • id: 文章ID（路径参数）

返回数据:

{
  "code": 200,
  "message": "删除成功",
  "success": true,
  "data": {
    // 被删除的文章信息
  }
}

2. 留言管理API

2.1 获取所有留言

GET /api/messages

功能: 获取所有留言列表

请求参数: 无

返回数据:

{
  "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（路径参数）

返回数据:

{
  "code": 200,
  "message": "查询成功",
  "success": true,
  "data": {
    // 留言详细信息（结构同上）
  }
}

2.3 创建留言

POST /api/messages

功能: 发布新留言

请求体:

{
  "nickname": "用户名",
  "email": "user@example.com",
  "content": "新留言内容",
  "parentid": null,  // 可选，回复时设置为被回复留言的ID
  "articleid": null  // 可选，关联文章时设置为文章ID
}

返回数据:

{
  "code": 200,
  "message": "保存成功",
  "success": true,
  "data": {
    // 保存后的留言信息
  }
}

2.4 删除留言（需要认证）

DELETE /api/messages/{id}

功能: 删除指定留言

权限: 需要ADMIN角色

请求参数:

  • id: 留言ID（路径参数）

返回数据:

{
  "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

npm install axios

2. 创建API服务文件

创建一个 api.js 文件来封装所有的API调用：

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

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实现) |
           +-------------+