Build_God/Build_God_Admin_Frontend/Frontend/API_QUICK_REFERENCE.md

API 快速参考卡片

📋 一页纸速查表

项目文件对应关系

文件	作用	修改频率
src/api/index.ts	axios 配置 + 拦截器	很少
src/api/auth.ts	API 接口定义	经常
src/stores/auth.ts	认证状态管理	偶尔
src/views/LoginView.vue	登录页面	偶尔
.env.development	开发环境 API 地址	很少
.env.production	生产环境 API 地址	很少

工作流程简图

前端组件
    ↓
import { loginApi } from '@/api/auth'
    ↓
await loginApi({ username, password })
    ↓
axios instance (请求拦截器添加 token)
    ↓
POST /api/auth/login
    ↓
后端返回 JSON
    ↓
axios instance (响应拦截器提取 data)
    ↓
return response.data
    ↓
前端接收数据

常用代码片段

1. 登录

import { useAuthStore } from '@/stores/auth'

const authStore = useAuthStore()
const success = await authStore.login('admin', '123456')

2. 获取当前用户

const authStore = useAuthStore()
console.log(authStore.user)
console.log(authStore.token)

3. 登出

const authStore = useAuthStore()
await authStore.logout()

4. 创建新 API 接口

// src/api/users.ts
import http from './index'

export const getUsersApi = () => {
  return http.get('/users')
}

// 组件中使用
import { getUsersApi } from '@/api/users'
const response = await getUsersApi()

后端需要的东西

登录接口

POST /api/auth/login

请求：
{
  "username": "admin",
  "password": "123456"
}

响应：
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "1",
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin"
    }
  }
}

所有其他接口

Authorization: Bearer <token>  (自动添加)

返回格式：
{
  "code": 200,
  "message": "...",
  "data": {...}
}

调试技巧

1. 查看网络请求

• 打开浏览器开发者工具 (F12)
• 点击 Network 标签
• 登录看看 POST /api/auth/login 的请求和响应

2. 查看存储的 token

• 打开浏览器开发者工具 (F12)
• 点击 Application 标签
• 找到 LocalStorage
• 查看 auth_token 和 user

3. 打印错误

try {
  await loginApi(...)
} catch (error) {
  console.log(error) // 查看具体错误
}

环境变量配置

开发环境 (.env.development)

VITE_API_URL=http://localhost:3000/api

生产环境 (.env.production)

VITE_API_URL=https://api.yourdomain.com/api

在代码中使用

console.log(import.meta.env.VITE_API_URL)

常见错误解决

错误	原因	解决
CORS error	跨域问题	后端配置 CORS
401	token 过期	自动清除，跳转登录
404	接口不存在	检查后端路由
500	服务器错误	检查后端日志
网络错误	后端未启动	启动后端服务

完整登录示例

<script setup lang="ts">
import { ref } from 'vue'
import { useRouter } from 'vue-router'
import { useAuthStore } from '@/stores/auth'
import { ElMessage } from 'element-plus'

const router = useRouter()
const authStore = useAuthStore()
const username = ref('admin')
const password = ref('123456')
const loading = ref(false)

const handleLogin = async () => {
  loading.value = true
  try {
    // 调用异步登录
    const success = await authStore.login(username.value, password.value)
    if (success) {
      ElMessage.success('登录成功')
      router.push('/admin/dashboard')
    } else {
      ElMessage.error('登录失败')
    }
  } catch (error: any) {
    ElMessage.error(error?.message || '登录错误')
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <input v-model="username" type="text" placeholder="用户名" />
  <input v-model="password" type="password" placeholder="密码" />
  <button @click="handleLogin" :disabled="loading">
    {{ loading ? '登录中...' : '登录' }}
  </button>
</template>

API 调用模板

// 1. 创建接口文件 src/api/xxx.ts
import http from './index'

export interface XXXRequest {
  // 请求参数
}

export interface XXXResponse {
  code: number
  message: string
  data: {
    // 响应数据
  }
}

export const xxxApi = (params: XXXRequest): Promise<XXXResponse> => {
  return http.post('/xxx', params)
}

// 2. 在组件中使用
import { xxxApi } from '@/api/xxx'

const response = await xxxApi({ /* 参数 */ })
if (response.code === 200) {
  // 成功处理
}

HTTP 方法速查

// GET 请求
http.get('/users')
http.get('/users?page=1&limit=10')
http.get('/users', { params: { page: 1 } })

// POST 请求
http.post('/users', { name: 'John' })

// PUT 请求
http.put('/users/1', { name: 'Jane' })

// DELETE 请求
http.delete('/users/1')

// PATCH 请求
http.patch('/users/1', { name: 'Bob' })

token 在请求中的流程

1. 用户登录 → token 保存到 localStorage
2. 请求拦截器检查 localStorage 中的 token
3. 如果有 token，添加到请求头：Authorization: Bearer <token>
4. 后端验证 token
5. 后端返回数据或 401 错误
6. 响应拦截器检查状态码
7. 如果 401，清除 token 并跳转登录页

测试后端接口的命令

# 测试登录
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 获取响应中的 token
# 复制 token 值

# 测试其他接口（需要 token）
curl -X GET http://localhost:3000/api/users \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

🚀 快速启动清单

• 后端启动在 http://localhost:3000
• 后端实现 POST /api/auth/login 接口
• 后端返回正确的 JSON 格式
• 前端运行 npm run dev
• 前端 .env.development 中 VITE_API_URL 指向后端
• 打开浏览器访问 http://localhost:5173
• 输入用户名和密码登录
• 查看浏览器 Network 标签验证请求
• 检查 localStorage 中是否保存了 token
• 登录成功后跳转到仪表板

📞 获取帮助

1. 查看 API_INTEGRATION_GUIDE.md - 详细教程
2. 查看 BACKEND_API_EXAMPLE.md - 后端代码示例
3. 查看组件代码注释
4. 打开浏览器开发者工具查看错误
5. 检查后端日志