MyAfterProject/README_API.md

# MyAfterProject 开发文档（前端使用）

## 项目概述

MyAfterProject是一个基于Spring Boot的后端博客系统，提供文章管理、留言板等功能的RESTful API接口。系统集成了Spring Security和JWT认证机制，确保API的安全性和权限控制。本文档旨在帮助前端开发者理解和使用这些API接口，包括接口规范、请求/响应格式、认证方式及最佳实践。

## 技术栈

- **后端框架**: Spring Boot 2.x
- **ORM框架**: Spring Data JPA
- **数据库**: MySQL
- **缓存**: Redis
- **认证授权**: Spring Security + JWT Token
- **API风格**: RESTful API
- **错误处理**: 全局异常处理机制
- **权限控制**: 基于角色的访问控制(RBAC)

## 项目结构

```
src/main/java/com/qf/myafterprojecy/
├── controller/           # 控制器层，处理HTTP请求
│   ├── ArticleController.java  # 文章相关API
│   ├── MessageController.java  # 留言相关API
│   └── AuthController.java     # 认证相关API
├── pojo/                 # 实体类和数据传输对象
│   ├── Article.java            # 文章实体
│   ├── Message.java            # 留言实体
│   ├── User.java               # 用户实体
│   ├── Role.java               # 角色实体
│   ├── ResponseMessage.java    # 统一响应消息格式
│   └── dto/                    # 数据传输对象
│       ├── ArticleDto.java     # 文章DTO
│       └── MessageDto.java     # 留言DTO
├── repository/           # 数据访问层
│   ├── ArticleRepository.java  # 文章数据访问
│   ├── MessageRepository.java  # 留言数据访问
│   ├── UserRepository.java     # 用户数据访问
│   └── RoleRepository.java     # 角色数据访问
├── service/              # 业务逻辑层
│   ├── ArticleService.java     # 文章服务实现
│   ├── IArticleService.java    # 文章服务接口
│   ├── MessageService.java     # 留言服务实现
│   └── IMessageService.java    # 留言服务接口
├── config/               # 配置类
│   ├── SecurityConfig.java     # Spring Security配置
│   └── security/               # 安全相关组件
│       ├── JwtTokenProvider.java      # JWT令牌生成器
│       ├── JwtAuthenticationFilter.java # JWT认证过滤器
│       └── UserDetailsServiceImpl.java  # 用户认证服务
├── GlobalExceptionHandler.java   # 全局异常处理器
└── MyAfterProjecyApplication.java # 应用入口
```

## 配置信息

- **服务地址**: `http://localhost:8080`
- **API基础路径**: `/api`
- **认证头**: `Authorization: Bearer {token}`
- **默认测试账号**:
  - 作者账号: `test_author` / `password123` (拥有AUTHOR角色)
  - 管理员账号: `test_admin` / `admin123` (拥有ADMIN角色)

## 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角色 (通过`@PreAuthorize("hasRole('AUTHOR')")`控制)

**请求头**:
- `Authorization: Bearer {token}` (必需)

**请求体**: 
```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角色 (通过`@PreAuthorize("hasRole('AUTHOR')")`控制)

**请求头**:
- `Authorization: Bearer {token}` (必需)

**请求参数**: 
- `id`: 文章ID（路径参数）

**请求体**: 
```json
{
  "title": "更新后的标题",
  "content": "更新后的内容",
  "img": "更新后的图片URL",
  "status": 1
}
```

**返回数据**: 
```json
{
  "code": 200,
  "message": "更新成功",
  "success": true,
  "data": {
    // 更新后的文章信息
  }
}
```

#### 1.7 删除文章（需要认证）

```
DELETE /api/articles/{id}
```

**功能**: 删除指定文章

**权限**: 需要AUTHOR或ADMIN角色 (通过`@PreAuthorize("hasRole('AUTHOR') or hasRole('ADMIN')")`控制)

**请求头**:
- `Authorization: Bearer {token}` (必需)

**请求参数**: 
- `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表示主留言
      "replyid": 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角色

**请求头**:
- `Authorization: Bearer {token}` (必需)

**请求参数**: 
- `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**: 包含留言的基本信息，用于创建和更新留言
- **LoginRequest**: 登录请求参数
- **SignupRequest**: 注册请求参数
- **JwtResponse**: JWT认证响应

## 认证与授权

系统使用JWT (JSON Web Token) 进行身份认证。在访问需要授权的API接口时，前端需要在请求头中包含有效的JWT令牌。

### 获取JWT令牌

```
POST /api/auth/signin
```

**功能**: 用户登录并获取JWT令牌

**请求体**:
```json
{
  "username": "test_author",
  "password": "password123"
}
```

**返回数据**:
```json
{
  "code": 200,
  "message": "登录成功",
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "type": "Bearer",
    "id": 1,
    "username": "test_author",
    "email": "author@example.com",
    "roles": ["ROLE_AUTHOR"]
  }
}
```

### 用户注册

```
POST /api/auth/signup
```

**功能**: 用户注册新账号

**请求体**:
```json
{
  "username": "新用户名",
  "email": "user@example.com",
  "password": "密码123",
  "role": "author"  // 可选值: user, author, admin
}
```

## 前端调用示例

以下是使用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'
  }
});

// 认证相关API
export const authAPI = {
  // 用户登录
  login: (credentials) => api.post('/auth/signin', credentials),
  // 用户注册
  register: (userData) => api.post('/auth/signup', userData)
};

// 请求拦截器 - 添加认证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实现) |
           +-------------+
```