# 前端API调用文档

## 项目概述

这是一个基于Vue 3的博客前端项目，提供文章展示、分类管理、留言板、用户认证和疯言疯语等功能。项目使用Vue 3 Composition API进行开发，集成了Vue Router进行路由管理，并使用Element Plus等UI库提供用户界面。

## 技术栈

- **前端框架**: Vue 3
- **构建工具**: Vite
- **路由管理**: Vue Router 4
- **UI组件库**: Element Plus
- **HTTP客户端**: Axios
- **类型定义**: TypeScript类型接口

## 项目结构

```
src/
├── App.vue                # 应用根组件
├── main.js                # 应用入口文件
├── router/                # 路由配置
├── services/              # API服务模块
│   ├── apiService.js      # 基础API服务配置
│   ├── articleService.js  # 文章相关API
│   ├── categoryService.js # 分类相关API
│   ├── categoryAttributeService.js # 分类属性相关API
│   ├── loginService.js    # 用户认证相关API
│   ├── messageService.js  # 留言相关API
│   ├── nonsenseService.js # 疯言疯语相关API
│   └── index.js           # 服务导出文件
├── types/                 # 类型定义
│   └── index.ts           # 所有接口类型定义
├── views/                 # 视图组件
└── components/            # 可复用组件
```

## API服务模块详解

### 1. 基础API服务 (apiService.js)

基础API服务配置了Axios实例，设置请求拦截器和响应拦截器，统一处理认证信息和错误响应。

```javascript
// 创建axios实例
const api = axios.create({
  baseURL:'http://localhost:8080/api', // API基础URL
  timeout: 10000, // 请求超时时间
  withCredentials: true // 允许跨域请求携带凭证
})
```

**核心功能**：
- 自动添加认证token到请求头
- 统一处理HTTP错误（401、403、404、500等）
- 自动显示错误提示信息
- 未授权时自动清除token并重定向到登录页

### 2. 文章服务 (articleService.js)

提供文章的CRUD操作和各种查询功能。

**主要方法**：

| 方法名 | 说明 | 参数 | 返回类型 |
|-------|------|------|----------|
| getAllArticles | 获取已发布文章列表 | params: PaginationParams（可选） | Promise<ApiResponse<Article[]>> |
| getArticlesByStatus | 根据状态获取文章列表 | status: number（0：未发表 1：已发表 2：已删除） | Promise<ApiResponse<Article[]>> |
| getAllArticlesWithDeleted | 获取所有文章列表（包含已删除） | params: PaginationParams（可选） | Promise<ApiResponse<Article[]>> |
| getArticleById | 根据ID获取文章详情 | articleid: number | Promise<ApiResponse<Article>> |
| getArticlesByAttributeId | 根据属性ID获取文章列表 | attributeid: number | Promise<ApiResponse<Article[]>> |
| getArticlesByTitle | 根据标题查询文章列表 | title: string | Promise<ApiResponse<Article[]>> |
| getPopularArticles | 获取热门文章 | 无 | Promise<ApiResponse<Article[]>> |
| createArticle | 创建文章 | articleData: ArticleDto | Promise<ApiResponse<Article>> |
| updateArticle | 更新文章 | articleid: number, articleData: ArticleDto | Promise<ApiResponse<Article>> |
| deleteArticle | 删除文章 | articleid: number | Promise<ApiResponse<boolean>> |
| getArticlesByCategory | 根据分类获取文章 | categoryid: number | Promise<ApiResponse<Article[]>> |
| incrementArticleViews | 增加文章浏览量 | articleid: number | Promise<ApiResponse<boolean>> |
| getLatestArticlesByAttribute | 根据属性ID获取最新文章 | attributeid: number | Promise<ApiResponse<Article[]>> |
| likeArticle | 点赞文章 | articleid: number | Promise<ApiResponse<boolean>> |

### 3. 分类服务 (categoryService.js)

提供分类的管理功能。

**主要方法**：

| 方法名 | 说明 | 参数 | 返回类型 |
|-------|------|------|----------|
| getAllCategories | 获取所有分类 | 无 | Promise<ApiResponse<Category[]>> |
| getCategory | 获取指定分类 | typeid: number | Promise<ApiResponse<Category>> |
| createCategory | 创建新分类 | categoryData: CategoryDto | Promise<ApiResponse<Category>> |
| updateCategory | 更新分类 | typeid: number, categoryData: CategoryDto | Promise<ApiResponse<Category>> |
| deleteCategory | 删除分类 | typeid: number | Promise<ApiResponse<boolean>> |

### 4. 分类属性服务 (categoryAttributeService.js)

提供分类属性（标签）的管理功能。

**主要方法**：

| 方法名 | 说明 | 参数 | 返回类型 |
|-------|------|------|----------|
| getAllAttributes | 获取所有分类属性 | 无 | Promise<ApiResponse<CategoryAttribute[]>> |
| getAttributeById | 根据ID获取分类属性 | attributeid: number | Promise<ApiResponse<CategoryAttribute>> |
| getAttributesByCategory | 根据分类ID获取属性列表 | categoryid: number | Promise<ApiResponse<CategoryAttribute[]>> |
| createAttribute | 创建分类属性 | attributeData: CategoryAttributeDto | Promise<ApiResponse<CategoryAttribute>> |
| updateAttribute | 更新分类属性 | attributeid: number, attributeData: CategoryAttributeDto | Promise<ApiResponse<CategoryAttribute>> |
| deleteAttribute | 删除分类属性 | attributeid: number | Promise<ApiResponse<boolean>> |
| checkAttributeExists | 检查分类下是否存在指定名称的属性 | categoryid: number, attributename: string | Promise<ApiResponse<boolean>> |

### 5. 用户认证服务 (loginService.js)

提供用户登录、注册和个人信息管理功能。

**主要方法**：

| 方法名 | 说明 | 参数 | 返回类型 |
|-------|------|------|----------|
| login | 用户登录 | loginData: LoginDto | Promise<ApiResponse<User>> |
| register | 用户注册 | registerData: RegisterDto | Promise<ApiResponse<User>> |
| logout | 用户登出 | 无 | Promise<any> |
| getCurrentUser | 获取当前用户信息 | 无 | Promise<ApiResponse<User>> |
| updateUser | 更新用户信息 | userData: UserDto | Promise<ApiResponse<User>> |
| changePassword | 修改密码 | passwordData: ChangePasswordDto | Promise<ApiResponse<boolean>> |

### 6. 留言服务 (messageService.js)

提供留言的管理和查询功能。

**主要方法**：

| 方法名 | 说明 | 参数 | 返回类型 |
|-------|------|------|----------|
| getAllMessages | 获取所有留言 | 无 | Promise<ApiResponse<Message[]>> |
| getMessageById | 获取单条留言 | messageid: number | Promise<ApiResponse<Message>> |
| getMessagesByArticleId | 根据文章ID获取留言 | articleid: number | Promise<ApiResponse<Message[]>> |
| getRootMessages | 获取根留言 | 无 | Promise<ApiResponse<Message[]>> |
| getRepliesByParentId | 根据父留言ID获取回复 | parentid: number | Promise<ApiResponse<Message[]>> |
| searchMessagesByNickname | 根据昵称搜索留言 | nickname: string | Promise<ApiResponse<Message[]>> |
| getMessageCountByArticleId | 获取文章评论数量 | articleid: number | Promise<ApiResponse<number>> |
| saveMessage | 创建留言 | messageData: MessageDto | Promise<ApiResponse<Message>> |
| deleteMessage | 删除留言 | messageid: number | Promise<ApiResponse<boolean>> |
| likeMessage | 点赞留言 | messageid: number | Promise<ApiResponse<boolean>> |

### 7. 疯言疯语服务 (nonsenseService.js)

提供疯言疯语内容的管理功能。

**主要方法**：

| 方法名 | 说明 | 参数 | 返回类型 |
|-------|------|------|----------|
| getAllNonsense | 获取所有疯言疯语内容 | 无 | Promise<ApiResponse<Nonsense[]>> |
| getNonsenseByStatus | 根据状态获取疯言疯语内容 | status: number（1:已发表, 0:草稿） | Promise<ApiResponse<Nonsense[]>> |
| saveNonsense | 保存疯言疯语内容 | nonsense: Nonsense | Promise<ApiResponse<Nonsense>> |
| deleteNonsense | 删除疯言疯语内容 | id: number | Promise<ApiResponse<boolean>> |
| updateNonsense | 更新疯言疯语内容 | nonsense: Nonsense | Promise<ApiResponse<Nonsense>> |

## 数据模型定义

### 1. 文章 (Article)

```typescript
interface Article {
  articleid: number
  title: string
  content: string
  attributeid: Number
  categoryName: string
  img?: string
  createdAt: string
  updatedAt: string
  viewCount?: number
  likes?: number
  commentCount?: number
  status?: number
  markdownscontent: string
}

interface ArticleDto {
  id?: number
  title: string
  content: string
  attributeid: number
  img?: string
  status?: number
  viewCount?: number
  likes?: number
  markdownscontent: string
}
```

### 2. 分类 (Category)

```typescript
interface Category {
  typeid: number
  typename: string
  description?: string
  createdAt?: string
  updatedAt?: string
  articleCount?: number
}

interface CategoryDto {
  typename: string
  description?: string
}
```

### 3. 分类属性 (CategoryAttribute)

```typescript
interface CategoryAttribute {
  attributeid: number
  categoryid: number
  attributename: string
}

interface CategoryAttributeDto {
  categoryid: number
  attributename: string
}
```

### 4. 留言 (Message)

```typescript
interface Message {
  messageid: number
  content: string
  nickname: string
  email: string
  articleid?: number
  parentid?: number
  createdAt: string
  replyid?: number
  likes?: number
  messageimg?: string
}

interface MessageDto {
  messageid?: number
  nickname?: string
  email?: string
  content?: string
  createdAt?: string
  parentid?: number
  replyid?: number
  articleid?: number
  messageimg?: string
}
```

### 5. 用户 (User)

```typescript
interface User {
  id?: number
  username?: string
  password?: string
  email?: string
  phone?: string
  role?: number
  createTime?: string
  avatar?: string
  token?: string
}

interface UserDto {
  username: string
  password: string
  email: string
  phone: string
  role?: number
}
```

### 6. 疯言疯语 (Nonsense)

```typescript
interface Nonsense {
  nonsenseid: number
  content: string
  status?: number
  time: string
}

interface NonsenseDto {
  content: string
  status?: number
  time?: string
}
```

### 7. API响应 (ApiResponse)

```typescript
interface ApiResponse<T = any> {
  success: boolean
  code: number
  message?: string
  data?: T
  total?: number
}
```

## API调用示例

### 导入服务

```javascript
import { articleService, categoryService, messageService, loginService } from '@/services'
```

### 文章相关调用示例

```javascript
// 获取文章列表
async function fetchArticles() {
  try {
    const response = await articleService.getAllArticles({ page: 1, size: 10 })
    if (response.success) {
      console.log('文章列表:', response.data)
    } else {
      console.error('获取文章列表失败:', response.message)
    }
  } catch (error) {
    console.error('请求错误:', error)
  }
}

// 创建新文章
async function createNewArticle() {
  try {
    const articleData = {
      title: '新文章标题',
      content: '文章内容',
      attributeid: 1,
      markdownscontent: '# 文章标题\n文章内容'
    }
    const response = await articleService.createArticle(articleData)
    if (response.success) {
      console.log('文章创建成功:', response.data)
    }
  } catch (error) {
    console.error('创建文章失败:', error)
  }
}
```

### 分类相关调用示例

```javascript
// 获取所有分类
async function fetchCategories() {
  try {
    const response = await categoryService.getAllCategories()
    if (response.success) {
      console.log('分类列表:', response.data)
    }
  } catch (error) {
    console.error('获取分类失败:', error)
  }
}

// 创建新分类
async function createCategory() {
  try {
    const categoryData = {
      typename: '新技术',
      description: '关于新技术的文章分类'
    }
    const response = await categoryService.createCategory(categoryData)
    if (response.success) {
      console.log('分类创建成功:', response.data)
    }
  } catch (error) {
    console.error('创建分类失败:', error)
  }
}
```

### 用户认证调用示例

```javascript
// 用户登录
async function userLogin() {
  try {
    const loginData = {
      username: 'testuser',
      password: 'password123'
    }
    const response = await loginService.login(loginData)
    if (response.success) {
      // 保存token
      localStorage.setItem('token', response.data.token)
      console.log('登录成功:', response.data)
    }
  } catch (error) {
    console.error('登录失败:', error)
  }
}

// 获取当前用户信息
async function getCurrentUserInfo() {
  try {
    const response = await loginService.getCurrentUser()
    if (response.success) {
      console.log('用户信息:', response.data)
    }
  } catch (error) {
    console.error('获取用户信息失败:', error)
  }
}
```

## 错误处理机制

前端API服务集成了统一的错误处理机制，包括：

1. **HTTP状态码处理**：
   - 401: 未授权，自动清除token并跳转登录页
   - 403: 拒绝访问
   - 404: 请求资源不存在
   - 500: 服务器错误

2. **请求错误处理**：
   - 网络连接错误
   - 请求超时
   - 服务器无响应

3. **错误信息提示**：
   - 所有错误通过Element Plus的ElMessage组件显示
   - 支持自定义错误消息

## 开发指南

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

开发服务器将在 http://localhost:3000 启动

### 构建生产版本

```bash
npm run build
```

构建后的文件将生成在 `dist` 目录中

### 预览生产版本

```bash
npm run preview
```

## 部署说明

1. 确保后端服务已部署并运行在正确的端口上
2. 修改 `apiService.js` 中的基础URL指向实际的后端服务地址
3. 构建生产版本并部署到Web服务器
4. 配置Web服务器以支持单页应用路由 (SPA fallback)

## 注意事项

1. 所有API调用都应该使用services目录下导出的服务实例
2. 对于需要认证的操作，确保用户已登录并持有有效的token
3. 在生产环境中，确保修改API基础URL为实际的后端服务地址
4. 对于分页查询，合理设置page和size参数以优化性能
5. 图片上传等大文件操作需要特别处理，避免超时