【Vue后台管理二】vue-admin-template 对接后端API JWT认证

发表于 更新于

本文是一篇实战教程，详细记录了如何将 vue-admin-template 项目从使用前端 Mock 数据，切换为对接真实的、基于 JWT 认证的后端 API（本例后端为 FastAPI）。涵盖环境配置、请求封装、登录认证、用户信息获取及页面路由调整等核心环节。

一、 概述与目标

项目背景：vue-admin-template 是一个极简的 Vue.js 后台管理基础模板，默认使用前端 Mock 数据模拟接口。

对接目标：

  1. 配置前端请求指向真实后端地址。
  2. 实现基于 JWT Token 的登录认证流程。
  3. 修改用户信息获取逻辑，匹配后端数据结构。
  4. 调整前端页面（如个人中心）和路由。

最终效果：前端能成功调用后端 API 完成登录、获取数据，并实现完整的权限控制流程。

后台效果演示

二、 核心对接步骤

1. 配置后端 API 基础地址

前端通过环境变量 VUE_APP_BASE_API 控制请求的基础 URL。

  1. 打开项目根目录下的环境配置文件 .env.development（开发环境）。
  2. 修改变量值为你的后端 API 地址：
    1
    2
    # 例如，后端服务运行在本地 8010 端口
    VUE_APP_BASE_API = 'http://127.0.0.1:8010/api/admin/v1'
    生产环境配置在 .env.production 文件中。
2. 修改登录认证逻辑

（1）调整登录接口 (src/api/user.js)
找到 login 函数，修改 url 和 method 以匹配后端登录接口。

1
2
3
4
5
6
7
export function login(data) {
  return request({
    url: '/auth/login/access-token', // 根据后端接口修改
    method: 'post',
    data // 通常包含 username/email 和 password
  })
}

（2）修改账号验证规则 (src/utils/validate.js)
默认模板验证用户名只能是 admin 或 editor。需要改为验证邮箱（或其他你的登录凭证）。

1
2
3
4
5
6
7
8
9
10
11
/**
 * 验证邮箱格式
 * @param {string} str
 * @returns {Boolean}
 */
export function validEmail(str) {
  const emailReg = /^(\w-*\.*)+@(\w-?)+(\.\w{2,})+$/
  return emailReg.test(str)
}

// 在 `src/views/login/index.vue` 中，将 `validUsername` 的调用替换为 `validEmail`

（3）调整 Axios 请求拦截器 (src/utils/request.js)
后端通常要求在请求头中携带 Token 进行认证。

1
2
3
4
5
6
7
8
9
10
11
12
13
// request interceptor
service.interceptors.request.use(
  config => {
    if (store.getters.token) {
      // 根据后端约定修改 header 字段名，例如 'Authorization' 或 'token'
      config.headers['token'] = getToken() // 将默认的 'X-Token' 改为 'token'
    }
    return config
  },
  error => {
    return Promise.reject(error)
  }
)

（4）调整 Axios 响应拦截器 (src/utils/request.js)
根据后端统一的响应格式修改成功/失败的判断逻辑。假设后端成功时 code 为 200。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
service.interceptors.response.use(
  response => {
    const res = response.data

    // 判断请求是否成功（根据后端返回的 code）
    if (res.code !== 200) { // 将默认的 20000 改为 200
      // 处理错误...
      return Promise.reject(new Error(res.message || 'Error'))
    } else {
      return res // 直接返回 res，其中包含 data, code, message
    }
  },
  error => {
    // 处理 HTTP 错误...
    return Promise.reject(error)
  }
)
3. 处理用户信息

登录成功后，前端会请求用户信息。需要修改 Vuex 中的处理逻辑以匹配后端返回的数据结构。

**修改 src/store/modules/user.js**：
在 getInfo action 中，根据后端返回的字段名进行赋值。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// 假设后端返回数据格式: { code:200, data: { nickname: 'xxx', avatar: 'xxx' } }
getInfo({ commit, state }) {
  return new Promise((resolve, reject) => {
    getInfo(state.token).then(response => {
      const { data } = response

      if (!data) {
        reject('Verification failed, please Login again.')
      }

      const { nickname, avatar } = data // 解构出后端返回的字段

      commit('SET_NAME', nickname) // 修改字段映射
      commit('SET_AVATAR', avatar)
      resolve(data)
    }).catch(error => {
      reject(error)
    })
  })
}

三、 页面与路由调整

1. 创建个人中心页面
  1. 在 src/views/ 目录下创建 profile 文件夹。
  2. 在文件夹内创建 index.vue 组件文件，作为个人中心主页。
2. 添加个人中心路由

在路由配置文件（如 src/router/index.js 或对应的模块文件）中添加路由。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  path: '/profile',
  component: Layout, // 使用主布局
  redirect: '/profile/index',
  hidden: true, // 不在侧边栏显示
  children: [
    {
      path: 'index',
      component: () => import('@/views/profile/index'),
      name: 'Profile',
      meta: { title: '个人中心', icon: 'user', noCache: true }
    }
  ]
}
3. 修改导航栏下拉菜单 (src/layout/components/Navbar.vue)

将用户下拉菜单中的链接指向首页和个人中心。

1
2
3
4
5
6
7
8
9
10
11
12
<template>
  <!- 简化示例 ->
  <router-link to="/">
    <el-dropdown-item>首页</el-dropdown-item>
  </router-link>
  <router-link to="/profile">
    <el-dropdown-item>我的主页</el-dropdown-item>
  </router-link>
  <el-dropdown-item divided @click.native="logout">
    <span style="display:block;">退出</span>
  </el-dropdown-item>
</template>

四、 测试与验证

  1. 启动服务：确保后端 API 服务已运行。
  2. 登录测试：在前端登录页面，使用后端有效的账号（邮箱）和密码登录。观察网络请求，确认 Token 被正确设置和携带。
  3. 页面跳转：登录后，点击右上角用户头像，检查下拉菜单中的“我的主页”是否能正确跳转到个人中心页面。
  4. 数据请求：测试其他数据接口（如 Table 列表），确认能正常获取并渲染后端返回的数据。

五、 关键注意事项

  1. **跨域问题 (CORS)**：开发时，确保后端已正确配置 CORS，允许前端域名/端口进行跨域请求。
  2. Token 存储与刷新：本文示例将 Token 存储在 Cookie 和 Vuex 中。生产环境需要考虑 Token 的自动刷新机制。
  3. 接口格式统一：确保前端 Axios 拦截器中关于响应成功 (code) 的判断与后端所有接口的返回格式严格一致。
  4. 路由权限：如果后端返回的用户角色/权限信息结构有变，需要同步修改 src/permission.js 和侧边栏生成逻辑。

六、 参考资源