MyfronyProject/README_API.md

前端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实例，设置请求拦截器和响应拦截器，统一处理认证信息和错误响应。

// 创建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 >
getArticlesByAttributeId	根据属性ID获取文章列表	attributeid: number	Promise<ApiResponse<Article[]>>
getArticlesByTitle	根据标题查询文章列表	title: string	Promise<ApiResponse<Article[]>>
getPopularArticles	获取热门文章	无	Promise<ApiResponse<Article[]>>
createArticle	创建文章	articleData: ArticleDto	Promise<ApiResponse >
updateArticle	更新文章	articleid: number, articleData: ArticleDto	Promise<ApiResponse >
deleteArticle	删除文章	articleid: number	Promise<ApiResponse>
getArticlesByCategory	根据分类获取文章	categoryid: number	Promise<ApiResponse<Article[]>>
incrementArticleViews	增加文章浏览量	articleid: number	Promise<ApiResponse>
getLatestArticlesByAttribute	根据属性ID获取最新文章	attributeid: number	Promise<ApiResponse<Article[]>>
likeArticle	点赞文章	articleid: number	Promise<ApiResponse>

3. 分类服务 (categoryService.js)

提供分类的管理功能。

主要方法：

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

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

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

主要方法：

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

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

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

主要方法：

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

6. 留言服务 (messageService.js)

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

主要方法：

方法名	说明	参数	返回类型
getAllMessages	获取所有留言	无	Promise<ApiResponse<Message[]>>
getMessageById	获取单条留言	messageid: number	Promise<ApiResponse>
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>
saveMessage	创建留言	messageData: MessageDto	Promise<ApiResponse>
deleteMessage	删除留言	messageid: number	Promise<ApiResponse>
likeMessage	点赞留言	messageid: number	Promise<ApiResponse>

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

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

主要方法：

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

数据模型定义

1. 文章 (Article)

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)

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

interface CategoryDto {
  typename: string
  description?: string
}

3. 分类属性 (CategoryAttribute)

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

interface CategoryAttributeDto {
  categoryid: number
  attributename: string
}

4. 留言 (Message)

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)

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)

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

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

7. API响应 (ApiResponse)

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

API调用示例

导入服务

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

文章相关调用示例

// 获取文章列表
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)
  }
}

分类相关调用示例

// 获取所有分类
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)
  }
}

用户认证调用示例

// 用户登录
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组件显示
   • 支持自定义错误消息

开发指南

安装依赖

npm install

启动开发服务器

npm run dev

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

构建生产版本

npm run build

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

预览生产版本

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. 图片上传等大文件操作需要特别处理，避免超时