Step by Step之Vben Admin项目集成系列(一)

去年上线的项目前端使用了Vue2+Element UI，组件外观觉得差了些意思，而前年上的项目因外包团队原因已经引入Vben Admin+Vue3，所以就筹划着将去年的项目更为Vben Admin，不过找了下网站文档，发现只有最基础的介绍，百度也没找到特别合适的，于是就动心按照集成进程整理系列文章的想法，先尝试着做做看吧。

因我是前端小白，主要的知识积累只有HTML+JAVASCRIPT，所以这个系列所面向的对象就是对前端了解甚少的小伙伴，如何能够根据项目需要快速实现在Vben Admin的基线上进行各项基础功能的借鉴和开发，对接后台需求以满足项目需求。

Vben Admin是一个基于Vue3.0、Vite、Ant-Design-Vue、TypeScript构建的后台解决方案，为中大型项目开发提供开箱即用的UI框架，包括二次封装组件、utils、hooks、动态菜单、权限校验、按钮级别权限控制等功能。

包含了两个版本，一个是完整版，一个是精简版，维护团队建议新项目使用精简版作为基线，以便于增加各项功能。

一、下载及环境配置

1、基础环境配置

前端开发环境主要就是Node，我用的MACBook Pro M1pro，之前用的是node@16版本，结果提示信息最低要用node@18，于是重新更新了环境。

brew uninstall node@16
brew install node@18
//更新.zshrc环境文件，增加node相关路径
echo 'export PATH="/opt/homebrew/opt/node@18/bin:$PATH"' >> ~/.zshrc
echo 'export LDFLAGS="-L/opt/homebrew/opt/node@18/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/node@18/include"' >> ~/.zshrc
source ./.zshrc

//安装pnpm
npm install pnpm -g

2、版本下载

同时下载了精简版和完整版，因为都包含了本地Mock可以看到整个效果，策略就是基于精简版开发，但是精简版内容太少，一些功能可以从完整版中单独整合过来。

//完整版地址：https://github.com/vbenjs/vue-vben-admin
//精简版地址：https://github.com/vbenjs/vue-vben-admin/tree/thin
//因为精简版只是一个分支，所以两个版本要放在不同目录下面
//获取精简版代码
cd work
git clone https://github.com/vbenjs/vue-vben-admin.git
//安装精简版依赖包
cd vue-vben-admin
git checkout thin
//运行精简版
pnpm install 

//获取完整版代码
cd work/full
git clone https://github.com/vbenjs/vue-vben-admin.git
//安装完整版依赖包
cd vue-vben-admin
//运行完整版
pnpm install 

3、开发环境

使用微软的Visual Code作为开发IDE，安装了开发调试工具的Chrome作为浏览器。

开发时，用Visual Code的两个窗口分别打开精简版和完整版工程，相互对照，一切就绪，只等开工！

二、基础信息修改

1、应用基本信息

这部分最简单，可以通过.env文件直接配置，改为项目应用即可。

# port
VITE_PORT = 3100

# spa-title
VITE_GLOB_APP_TITLE = <XXX> ShopMall

# spa shortname
VITE_GLOB_APP_SHORT_NAME = <YYY>

2、调试环境信息

需要关闭本地Mock，并根据本地后端系统的端口进行调整，通过修改.env.development文件即可，大家可根据自己本地开发环境的端口进行设置。

# Whether to open mock
VITE_USE_MOCK = false

# Cross-domain proxy, you can configure multiple
# Please note that no line breaks
VITE_PROXY = [["/basic-api","http://localhost:8085"],["/upload","http://localhost:8085/upload"]]
# VITE_PROXY=[["/api","https://vvbin.cn/test"]]

3、更新登录页信息

（1）更新平台欢迎词

在/src/locales/lang/zh-CN或en/sys.ts，找到signInTitle和signInDesc，改为自己希望的中英文欢迎词内容。

（2）更新欢迎图片和Logo

在/src/views/sys/login目录的login.vue文件中，登录页大图为src/assets/svg/login-box-bg.svg，可以更改为自己想要的大图，修改名称并拷贝文件。

在这张登录页大图的上方，还有VBen的Logo，这个替换更加简单，不需要修改页面文件，只需要拿自己的logo.png去替换/src/assets/images下的同名文件即可。

以上步骤完成后，点击登录已经向后端发送用户名与密码，此时默认为vben和123456的明文信息，所以后端肯定返回错误消息，需要通过下一步完成登录过程集成后才能继续。

注：生产环境放在后面文章专项说明，前面几期以开发环境为主，逐步扩充典型功能。

三、登录过程集成（图形验证码）

项目工程最基础的登录方式是用户名密码加验证码登录，在此基础上可用手机验证码登录，以及第三方账号关联登录。

这一期先完成基础登录方式集成。

1、验证码组件集成

公司之前使用的组件是AJ-Captcha，后端库重新封装成Jar包，前端也有对应的库，但是基于JS的，为了简化，直接使用这款，TS的移植放以后再说。

（1）将组件，包含Verify.vue和其他对应的目录，直接拷贝到/src/components目录下，命名为Verify目录；

（2）修改/src/views/sys/login目录的LoginForm.vue，调整较多，主要是引入Verify组件，并调整登录逻辑，在用户名密码输入后，先弹出验证码框（图形），移动小图块到正确位置后再调用登录操作，与后端交互完成登录操作，主要修改说明及相关代码见下：

// LoginForm.vue
// 原@keypress.enter对应的是handleLogin，改为handleCaptcha
<template>
  <LoginFormTitle v-show="getShow" class="enter-x" />
  <Form
    class="p-4 enter-x"
    :model="formData"
    :rules="getFormRules"
    ref="formRef"
    v-show="getShow"
    @keypress.enter="handleCaptcha"
  >
...//其他代码
// 原登录按钮中@click对应的是handleLogin，改为handleCaptcha
    <FormItem class="enter-x">
      <Button type="primary" size="large" block @click="handleCaptcha" :loading="loading">//在Form结束后，模板的最后部分引入验证框组件，指定滑动类型，验证成功后才调用handleLogin
...//其他代码
  </Form>
  <LoginVerify
      ref="verifyRef"
      :captcha-type="'blockPuzzle'"
      :img-size="{width:'400px',height:'200px'}"
      @success="handleLogin"
  />
</template>
<script lang="ts" setup>
	...//其他代码
	//引入验证框组件
  import LoginVerify from '/@/components/Verify/Verify.vue'
	...//其他代码
	//增加响应式变量
  const verifyRef = ref(null)
	...//其他代码
	//增加验证框回调函数
  async function handleCaptcha() {
    const data = await validForm();
    if (!data) return;
    // add by LJ, deal with captcha check
    verifyRef.value?.show();
  }
	//修改原来的handleLogin回调函数，API请求时增加验证码字段
  async function handleLogin(verifyResult) {
    try {
      loading.value = true
      const userInfo = await userStore.login({
        password: data.password,
        username: data.account,
        captchaVerification: verifyResult.captchaVerification,
      })
	...//其他代码
</script>

（3）因为Vben中，所有接口的传入和返回参数都有结构定义，所以还需要在LoginParams中增加对应的验证码参数。

即在/src/api/sys/model/userModel.ts中的LoginParams接口（interface）中，增加一行：captchaVerification: string。

（4）修改Vben登录访问的URL，因为默认为/login，而公司项目工程中这个URL一般给APP或小程序等最终用户使用，后台管理端一般为/adminLogin，所以需要进行修改。

即在/src/api/sys/user.ts中，将enum Api中的Login值改为后端系统对应的URL就好。

2、与后端通讯机制集成

公司前几年就进行了前后端分离开发，对前后端交互协议的定义也遵循了业界规范，即每个数据包会有状态码字段、结果字段和消息字段。Vben也是如此，不过因为没有业界统一的命名规范，所以肯定需要重新匹配。

（1）字段名称匹配

在/src/utils/http/axios/index.ts文件中，Vben使用了code、result和message三个字段名称，而公司使用的是code、data和msg。另外关于接口返回目标码定义也需要修改，如Vben默认为0，而公司使用了“0000”代表成功。

注：这里看到注释说，可以在types.ts内修改为项目自己的接口返回格式，但在项目中没有找到这个文件，所以就直接进行了修改。

//在/src/utils/http/axios/index.ts文件中
		// 解决data命名冲突
    // 删除此行 const { data } = res
    if (!res.data) {
    ...//其他代码
		// 根据公司规则修改接口对应必填字段
    const { code, data, msg } = res.data;

		// 根据公司规则修改返回字段成功判断规则
    const hasSuccess = data || code === ResultEnum.SUCCESS;

（2）token方式适配

对照了一下，Vben存储Token的机制与公司项目的一致，都是在登录成功后的回包中，获取token并保存，后续每次发包时，在包头中增加Authorization字段，并附加token上传。

需要调整的是接口字段名称，公司使用的字段是accessToken，而Vben使用token，主要修改部分如下：

//在src/api/sys/model/userModel.ts中
export interface LoginResultModel {
  // userId: string | number;
  // token: string;
  // roles: RoleInfo[];
  accessToken: string;
  expiresIn: number;
  refreshToken: string;
}

//在/src/store/modules/user.ts中
        const data = await loginApi(loginParams, mode);
        const { accessToken } = data;

        // save token
        this.setToken(accessToken);

（3）加密方式适配

主要是密码的加密传输，因之前工程项目采用了约定的密钥，并增加了随机的时间戳，所以无法直接使用Vben已经封装的加密函数，简化方案就是在对应文件中增加一个加密函数。

//在src/utils/cipher.ts中
...//其他代码
import CryptoJS from 'crypto-js';
...//其他代码
//预定义对称加密密钥，前后端必须一致，我们使用了16位的字符串
const keyStr = '<user-defined-enrypted-key>'; // key for encrypt and decrypt

export function encryptByTime(word) {
  const time = Date.now();
  const key = CryptoJS.enc.Utf8.parse(keyStr);
  const srcs = CryptoJS.enc.Utf8.parse(time + word);
  const encrypted = CryptoJS.AES.encrypt(srcs, key, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7,
  });
  return encrypted.toString();
}

然后对/src/views/sys/login/LoginForm.vue进行针对性修改，即用户输入密码先要进行加密后再上传给后端。

//在/src/views/sys/login/LoginForm.vue中
...//其他代码
  import { encryptByTime } from '/@/utils/cipher';
...//其他代码
			//在handleLogin回调函数中
      const userInfo = await userStore.login({
        userName: formData.account,
        passWord: encryptByTime(formData.password),
        captchaVerification: verifyResult.captchaVerification,
      });
...//其他代码

上述修改完成后，就可以使用用户名、密码并完成图像验证后进行登录。因为，菜单模式默认是使用前端的，所以还能进入dashboard页面，下一篇就是更加复杂的菜单和权限集成了——to be continued。