RuoYi-Vue3前后端联调技巧：接口文档与Mock服务使用

引言

在前后端分离开发模式中，接口联调是连接前端与后端的关键环节。开发者常常面临接口文档不清晰、后端接口未就绪、联调环境依赖复杂等问题，导致开发效率低下。本文将以RuoYi-Vue3权限管理系统为例，详细介绍如何利用接口文档工具和Mock服务解决这些痛点，帮助开发者实现高效的前后端协作。

读完本文后，你将能够：

• 快速搭建和使用RuoYi-Vue3项目的接口文档
• 配置和使用Mock服务进行前端独立开发
• 掌握前后端接口联调的实用技巧和最佳实践
• 解决联调过程中常见的问题和错误

RuoYi-Vue3接口文档搭建与使用

Swagger接口文档集成

RuoYi-Vue3后端采用SpringBoot框架，集成Swagger（OpenAPI）作为接口文档工具。通过Swagger，开发者可以自动生成API文档，并进行在线接口测试。

1. Swagger配置

在RuoYi-Vue3项目中，通常会创建一个SwaggerConfig配置类来启用和配置Swagger：

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ruoyi.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("RuoYi-Vue3 API文档")
                .description("前后端分离权限管理系统接口文档")
                .version("1.0.0")
                .build();
    }
}

2. 接口注解使用

在Controller类和方法上添加Swagger注解，生成详细的接口文档：

@RestController
@RequestMapping("/system/user")
@Api(tags = "用户管理接口")
public class SysUserController extends BaseController {
    
    @Autowired
    private ISysUserService userService;
    
    @GetMapping("/list")
    @ApiOperation("获取用户列表")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "pageNum", value = "页码", dataType = "int", paramType = "query", required = true),
        @ApiImplicitParam(name = "pageSize", value = "每页条数", dataType = "int", paramType = "query", required = true),
        @ApiImplicitParam(name = "userName", value = "用户名", dataType = "String", paramType = "query")
    })
    public TableDataInfo list(SysUser user) {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }
    
    @PostMapping
    @ApiOperation("新增用户")
    public AjaxResult add(@Validated @RequestBody SysUser user) {
        if (StringUtils.isNotNull(user.getUserId()) && user.getUserId().longValue() > 0) {
            return AjaxResult.error("新增用户不能设置用户ID");
        }
        return toAjax(userService.insertUser(user));
    }
}

3. 访问接口文档

启动后端服务后，访问以下地址即可查看和测试接口文档：

• Swagger UI地址：http://localhost:8080/swagger-ui.html

接口文档使用技巧

1. 接口搜索与过滤

在Swagger UI页面，可以通过顶部的搜索框快速查找需要的接口。同时，可以使用页面左侧的标签分类来过滤不同模块的接口。

2. 在线接口测试

Swagger提供了在线接口测试功能，点击接口名称进入详情页，填写参数后点击"Try it out"按钮即可发送请求并查看响应结果。

3. 接口版本管理

随着项目迭代，接口可能会有多个版本。可以通过在Docket中配置groupName来实现多版本接口文档的管理：

@Bean
public Docket createV1Api() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .groupName("v1")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ruoyi.web.controller.v1"))
            .paths(PathSelectors.any())
            .build();
}

@Bean
public Docket createV2Api() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            .groupName("v2")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.ruoyi.web.controller.v2"))
            .paths(PathSelectors.any())
            .build();
}

RuoYi-Vue3 Mock服务配置与使用

Mock服务简介

Mock服务是一种模拟后端接口的技术，允许前端开发者在后端接口未完成的情况下进行独立开发和测试。在RuoYi-Vue3项目中，可以通过Axios拦截器结合本地数据模拟来实现Mock功能。

RuoYi-Vue3中的请求封装

RuoYi-Vue3前端使用Axios作为HTTP客户端，并对其进行了封装，方便统一处理请求和响应。

// src/utils/request.js
import axios from 'axios'
import { ElNotification, ElMessageBox, ElMessage, ElLoading } from 'element-plus'
import { getToken } from '@/utils/auth'
import errorCode from '@/utils/errorCode'
import { tansParams, blobValidate } from '@/utils/ruoyi'
import cache from '@/plugins/cache'
import { saveAs } from 'file-saver'
import useUserStore from '@/store/modules/user'

let downloadLoadingInstance
// 是否显示重新登录
export let isRelogin = { show: false }

axios.defaults.headers['Content-Type'] = 'application/json;charset=utf-8'
// 创建axios实例
const service = axios.create({
  // axios中请求配置有baseURL选项，表示请求URL公共部分
  baseURL: import.meta.env.VITE_APP_BASE_API,
  // 超时
  timeout: 10000
})

// request拦截器
service.interceptors.request.use(config => {
  // 是否需要设置 token
  const isToken = (config.headers || {}).isToken === false
  // 是否需要防止数据重复提交
  const isRepeatSubmit = (config.headers || {}).repeatSubmit === false
  if (getToken() && !isToken) {
    config.headers['Authorization'] = 'Bearer ' + getToken() // 让每个请求携带自定义token
  }
  // get请求映射params参数
  if (config.method === 'get' && config.params) {
    let url = config.url + '?' + tansParams(config.params)
    url = url.slice(0, -1)
    config.params = {}
    config.url = url
  }
  // 防止重复提交处理
  if (!isRepeatSubmit && (config.method === 'post' || config.method === 'put')) {
    // ...重复提交检查逻辑
  }
  return config
}, error => {
    console.log(error)
    Promise.reject(error)
})

// 响应拦截器
service.interceptors.response.use(res => {
    // 未设置状态码则默认成功状态
    const code = res.data.code || 200
    // 获取错误信息
    const msg = errorCode[code] || res.data.msg || errorCode['default']
    // 二进制数据则直接返回
    if (res.request.responseType ===  'blob' || res.request.responseType ===  'arraybuffer') {
      return res.data
    }
    if (code === 401) {
      // 登录状态过期处理
    } else if (code === 500) {
      ElMessage({ message: msg, type: 'error' })
      return Promise.reject(new Error(msg))
    } else if (code !== 200) {
      ElNotification.error({ title: msg })
      return Promise.reject('error')
    } else {
      return Promise.resolve(res.data)
    }
  },
  error => {
    // 错误处理
    console.log('err' + error)
    let { message } = error
    if (message == "Network Error") {
      message = "后端接口连接异常"
    } else if (message.includes("timeout")) {
      message = "系统接口请求超时"
    } else if (message.includes("Request failed with status code")) {
      message = "系统接口" + message.substr(message.length - 3) + "异常"
    }
    ElMessage({ message: message, type: 'error', duration: 5 * 1000 })
    return Promise.reject(error)
  }
)

export default service

Mock服务实现

在RuoYi-Vue3中，可以通过以下方式实现Mock服务：

1. 创建Mock数据文件

在src目录下创建mock文件夹，并添加模拟数据文件：

// src/mock/user.js
export default {
  // 用户列表
  'GET /system/user/list': (req, res) => {
    const { pageNum = 1, pageSize = 10 } = req.query
    const total = 50
    const list = []
    for (let i = 0; i < pageSize; i++) {
      const index = (pageNum - 1) * pageSize + i
      if (index >= total) break
      list.push({
        userId: index + 1,
        userName: `user${index + 1}`,
        nickName: `用户${index + 1}`,
        email: `user${index + 1}@example.com`,
        phonenumber: `1380013800${index % 10}`,
        status: index % 2 === 0 ? '0' : '1',
        createTime: '2023-01-01'
      })
    }
    res.json({
      code: 200,
      msg: '操作成功',
      total: total,
      rows: list
    })
  },
  
  // 用户详情
  'GET /system/user/:userId': (req, res) => {
    const { userId } = req.params
    res.json({
      code: 200,
      msg: '操作成功',
      data: {
        userId: userId,
        userName: `user${userId}`,
        nickName: `用户${userId}`,
        email: `user${userId}@example.com`,
        phonenumber: `1380013800${userId % 10}`,
        status: userId % 2 === 0 ? '0' : '1',
        createTime: '2023-01-01'
      }
    })
  },
  
  // 新增用户
  'POST /system/user': (req, res) => {
    res.json({
      code: 200,
      msg: '新增成功'
    })
  },
  
  // 修改用户
  'PUT /system/user': (req, res) => {
    res.json({
      code: 200,
      msg: '修改成功'
    })
  },
  
  // 删除用户
  'DELETE /system/user/:userIds': (req, res) => {
    res.json({
      code: 200,
      msg: '删除成功'
    })
  }
}

2. 配置Mock服务

安装mock相关依赖：

npm install mockjs vite-plugin-mock --save-dev

在vite.config.js中配置mock插件：

// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteMockServe } from 'vite-plugin-mock'

export default defineConfig({
  plugins: [
    vue(),
    viteMockServe({
      // mock文件目录
      mockPath: 'src/mock',
      // 开发环境启用mock
      localEnabled: process.env.NODE_ENV === 'development',
      // 生产环境禁用mock
      prodEnabled: false,
      // 为mock服务注入请求头
      injectCode: `
        import { setupProdMockServer } from './mockProdServer';
        setupProdMockServer();
      `
    })
  ]
})

3. 使用Mock服务

在开发环境下，vite-plugin-mock会自动拦截匹配的请求并返回模拟数据。不需要修改现有的API调用代码，只需确保请求的URL与mock数据中定义的一致。

前后端联调实用技巧

1. 环境配置管理

在RuoYi-Vue3中，可以通过环境变量来管理不同环境的接口地址：

// .env.development
VITE_APP_BASE_API = '/dev-api'

// .env.production
VITE_APP_BASE_API = '/prod-api'

在axios配置中使用环境变量：

const service = axios.create({
  baseURL: import.meta.env.VITE_APP_BASE_API,
  timeout: 10000
})

2. 请求拦截与响应处理

RuoYi-Vue3对Axios进行了封装，实现了请求拦截和响应拦截：

• 请求拦截：添加认证token、处理重复提交、转换请求参数
• 响应拦截：统一错误处理、登录状态过期处理、二进制数据处理

开发者可以根据项目需求扩展这些拦截器功能。

3. 接口调试工具

除了Swagger的在线测试功能，还可以使用以下工具进行接口调试：

• Postman：功能强大的API测试工具
• curl：命令行HTTP客户端
• Chrome DevTools：Network面板查看请求详情

4. 联调常见问题解决

跨域问题

跨域问题是前后端分离开发中常见的问题，可以通过以下方式解决：

1. 后端配置CORS：

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOriginPatterns("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

2. 前端配置代理（vite.config.js）：

server: {
  proxy: {
    '/dev-api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/dev-api/, '')
    }
  }
}

认证失败问题

如果出现401认证失败错误，可能的原因包括：

1. Token过期或无效：需要重新登录获取新的token
2. 请求头中未携带token：检查请求拦截器是否正确添加了Authorization头
3. 后端认证配置错误：检查Security配置是否正确

接口参数不匹配

前后端接口参数不匹配是常见的联调问题，建议：

1. 严格按照接口文档定义参数
2. 使用TypeScript定义接口类型，提高类型安全性
3. 联调前进行参数校验

总结与展望

本文详细介绍了RuoYi-Vue3项目中接口文档和Mock服务的使用方法，以及前后端联调的实用技巧。通过合理利用这些工具和方法，可以有效解决前后端协作中的痛点问题，提高开发效率。

随着项目的发展，建议进一步完善接口文档和Mock服务：

1. 引入接口自动化测试，确保接口的正确性和稳定性
2. 使用接口版本控制，平滑处理接口变更
3. 建立接口变更通知机制，及时同步前后端开发进度

希望本文能帮助开发者更好地应对前后端联调挑战，打造高质量的RuoYi-Vue3应用。

互动与反馈

如果您在使用RuoYi-Vue3进行前后端联调时遇到其他问题，或者有更好的实践经验，欢迎在评论区留言分享。同时，如果您觉得本文对您有所帮助，请点赞、收藏并关注我们，获取更多关于RuoYi-Vue3的技术文章。

下期预告：RuoYi-Vue3权限管理深入解析，敬请期待！