yunzer_go/frontend/src/api

API 接口管理使用说明

📁 文件结构

src/api/
├── axios.ts          # 🚀 Axios 配置、拦截器和通用请求方法
├── api.ts            # 📋 具体 API 接口定义和管理
├── status.ts         # ⚠️ HTTP 状态码处理
└── README.md         # 📖 使用说明（本文档）

🚀 快速开始

1. 环境变量配置

在项目根目录创建或编辑 .env 文件：

# API 基础地址
VITE_API_DOMAIN=http://localhost:8080/api

2. 在组件中使用 API

// 导入 API 服务
import { UserService, landRelevant } from '@/api/api'

// 在组件中使用
const handleLogin = async () => {
  try {
    const response = await UserService.login1({
      username: 'admin',
      password: '123456'
    })
    console.log('登录成功:', response.data)
  } catch (error) {
    console.error('登录失败:', error)
  }
}

const getLandList = async () => {
  try {
    const response = await landRelevant.landList({
      page: 1,
      size: 10
    })
    console.log('土地列表:', response.data)
  } catch (error) {
    console.error('获取列表失败:', error)
  }
}

📋 详细说明

axios.ts - HTTP 请求核心配置

🔧 主要功能：

• 超时配置：60秒超时
• 基础 URL：通过环境变量配置
• 请求拦截器：自动添加请求头和 token
• 响应拦截器：统一错误处理
• 通用请求方法：封装 GET/POST 请求

📝 配置详情：

// 超时时间
axios.defaults.timeout = 60000

// 基础 URL
axios.defaults.baseURL = import.meta.env.VITE_API_DOMAIN

// 请求头配置
config.headers = {
  "Content-Type": "application/json;charset=UTF-8",
  token: "80c483d59ca86ad0393cf8a98416e2a1"
}

🎯 使用通用请求方法：

import { request } from '@/api/axios'

// GET 请求
const getData = await request('/api/data', { id: 1 }, 'GET')

// POST 请求
const postData = await request('/api/submit', { name: 'test' }, 'POST')

api.ts - 业务接口管理

🏗️ 架构设计：

• 类化管理：按业务模块划分服务类
• 静态方法：所有接口方法都是静态方法
• 统一导入：所有接口都通过 request 方法调用

📚 当前接口模块：

UserService - 用户相关接口

// 用户登录相关接口
UserService.login1(params)  // 接口一
UserService.login2(params)  // 接口二
UserService.login3(params)  // 接口三

landRelevant - 土地相关接口

// 获取土地列表
landRelevant.landList(params)

menu - 菜单相关接口

// 获取头部菜单
menu.getHeaderMenu()

返回数据结构：

{
  "code": 0,
  "msg": "获取主菜单成功",
  "data": [
    {
      "id": 1,
      "parent_id": 0,
      "title": "站点资讯",
      "src": "/articles",
      "icon": "",
      "sort": 0,
      "children": []
    }
  ]
}

➕ 添加新的接口：

// 1. 在现有类中添加方法
export class UserService {
  // 添加新方法
  static async getUserInfo(params) {
    return request("/user/info", params, "get");
  }
}

// 2. 创建新的服务类
export class ProductService {
  // 产品相关接口
  static async getProductList(params) {
    return request("/product/list", params, "get");
  }

  static async createProduct(params) {
    return request("/product/create", params, "post");
  }
}

status.ts - 状态码处理

🎯 功能说明：

• HTTP 状态码映射：将状态码转换为用户友好的错误信息
• 统一错误提示：所有 HTTP 错误都有对应的中文提示

📊 支持的状态码：

状态码	说明	提示信息
400	请求错误	请求错误(400)
401	未授权	未授权，请重新登录(401)
403	拒绝访问	拒绝访问(403)
404	请求出错	请求出错(404)
408	请求超时	请求超时(408)
500	服务器错误	服务器错误(500)
501	服务未实现	服务未实现(501)
502	网络错误	网络错误(502)
503	服务不可用	服务不可用(503)
504	网络超时	网络超时(504)
505	HTTP版本不受支持	HTTP版本不受支持(505)

💡 使用示例

在 Vue 组件中使用

<template>
  <div>
    <el-button @click="handleLogin" :loading="loading">
      登录
    </el-button>
    <el-button @click="getLands">
      获取土地列表
    </el-button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { UserService, landRelevant } from '@/api/api'
import { ElMessage } from 'element-plus'

const loading = ref(false)

// 用户登录
const handleLogin = async () => {
  loading.value = true
  try {
    const response = await UserService.login1({
      username: 'admin',
      password: '123456'
    })

    if (response.data.code === 200) {
      ElMessage.success('登录成功')
      // 处理登录成功逻辑
    }
  } catch (error) {
    console.error('登录失败:', error)
    ElMessage.error('登录失败，请重试')
  } finally {
    loading.value = false
  }
}

// 获取土地列表
const getLands = async () => {
  try {
    const response = await landRelevant.landList({
      page: 1,
      size: 20
    })

    console.log('土地数据:', response.data)
    // 处理数据展示逻辑
  } catch (error) {
    console.error('获取土地列表失败:', error)
  }
}

// 获取菜单数据
const getMenus = async () => {
  try {
    const response = await menu.getHeaderMenu();
    console.log('菜单数据:', response.data);
    // 更新菜单状态
  } catch (error) {
    console.error('获取菜单失败:', error);
  }
}
</script>

在组合式函数中使用

// composables/useUser.ts
import { ref } from 'vue'
import { UserService } from '@/api/api'

export function useUser() {
  const userInfo = ref(null)
  const loading = ref(false)

  const login = async (credentials) => {
    loading.value = true
    try {
      const response = await UserService.login1(credentials)
      userInfo.value = response.data.user
      return response.data
    } catch (error) {
      throw error
    } finally {
      loading.value = false
    }
  }

  const logout = () => {
    userInfo.value = null
    // 清除本地存储等
  }

  return {
    userInfo,
    loading,
    login,
    logout
  }
}

⚠️ 注意事项

1. 错误处理

• 所有接口调用都需要 try-catch 包装
• 使用 Element Plus 的 ElMessage 显示错误信息

2. 环境变量

• 确保 .env 文件中配置了 VITE_API_DOMAIN
• 不同环境可以使用不同的配置文件

3. Token 管理

• 当前代码中 token 是硬编码的
• 实际项目中应该从 localStorage 或 Vuex/Pinia 中获取

4. 类型安全

• 建议为请求参数和响应数据添加 TypeScript 类型定义
• 可以创建 types.ts 文件定义接口类型

🔧 扩展指南

添加新的业务模块

// 1. 在 api.ts 中添加新的服务类
export class OrderService {
  static async getOrderList(params) {
    return request("/order/list", params, "get");
  }

  static async createOrder(params) {
    return request("/order/create", params, "post");
  }
}

// 2. 在组件中导入使用
import { OrderService } from '@/api/api'

自定义请求配置

// 如果需要特殊的请求配置，可以直接使用 axios
import axios from '@/api/axios'

// 自定义配置的请求
const customRequest = await axios({
  method: 'POST',
  url: '/custom/api',
  data: params,
  timeout: 30000,
  headers: {
    'Custom-Header': 'value'
  }
})

🎯 最佳实践

1. 统一错误处理：在组件中统一处理接口错误
2. Loading 状态：显示加载状态提升用户体验
3. 数据缓存：对不变数据使用缓存策略
4. 接口文档：为每个接口方法添加 JSDoc 注释
5. 模块化：按业务领域划分接口模块

📞 技术支持

如有问题，请检查：

1. 环境变量配置是否正确
2. 网络连接是否正常
3. 后端接口是否可用
4. 控制台是否有详细错误信息