Api请求

11/20/2022

# 一、背景与问题

对于前端ajax请求,我们都知道为了更好的维护,需要在api目录进行封装一下,但是业内有很多不同的写法,可谓五花八门;有如下几个问题:

  • 因ajax是异步,很多人使用promise,但既然有了更简洁的async 和 await, 为什么不用呢?
  • api种封装了很多接口,import导入的时候,需要逐一导入,但事实上,在一个vue文件中,我们需要导入多个方法,略显麻烦
  • api 文件名重复等问题

# 二、架构思想

解决以上问题,我们还是借鉴了很多其他编程语言在中大型项目中的架构设计,比如java语言,在后端中对于接口有如下几个特性:

    1. 所有接口都写到Controller中
    1. 所有接口文件都以Controller为结尾
    1. 接口中写明作者信息

以上几点都是很好的借鉴

# 三、我们的接口写法

这里复制一下《Vue3规范 V2.0》中的 api规范要求:

  • api文件要以api为结尾,比如 employee-api.js、login-api.js,方便查找
  • api文件必须导出对象必须以Api为结尾,如:employeeApi、noticeApi
  • api中以一个对象将方法包裹
  • api中的注释,必须和后端 swagger 文档保持一致,同时保留后端作者

更多可以查看:api请求规范

# 3.1、以api为文件结尾

所有的文件要以api为结尾,比如 employee-api.jslogin-api.js 等等,那么对应java端的EmployeeController.javaLoginController.java
好处:

  • 很方便快速找到文件,比如在文件搜索中直接输入 login api,有且找到唯一的一个对应文件
  • 当看到文件时,知道这是一个接口 api 文件
  • 避免和 状态管理 vuex或者路由router 中、异或常量中的 login.js 这类重名

如图:

# 3.2、导出一个api对象

我们需要将一个模块的接口封装到一个api对象中,进行导出export,且 这个api对象必须以 Api为结尾,比如employeeApiloginApi,好处:

  • 我们只需要导入这一个api对象即可使用 所有的接口
  • Api为结尾,这样我们在使用的时候,一眼就知道这个变量是 api接口

正例:


department-api.js文件

import { getRequest, postRequest } from '/@/lib/axios';
export const departmentApi = {
  /**
   * @description: 查询部门列表 @author 卓大
   */
  queryAllDepartment: () => {
    return getRequest('/department/listAll');
  },

  /**
   * @description: 查询部门树形列表 @author 卓大
   */
   queryDepartmentTree: () => {
    return getRequest('/department/treeList');
  },

  /**
   * @description: 添加部门 @author 卓大
   */
  addDepartment: (param) => {
    return postRequest('/department/add', param);
  },
  /**
   * @description: 更新部门信息 @author 卓大
   */
  updateDepartment: (param) => {
    return postRequest('/department/update', param);
  }
};

在department-form-modal.vue文件中使用:

import { departmentApi } from '/@/api/system/department-api';

async function save(param){
  loading();
  try{
    if(condition){
      await departmentApi.save(param);
    }else{
      await departmentApi.delete(param);
    }
  }catch(e){
    sentry.log(e);
  }finally{
    unloading();
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

比较乱的写法:

import { getRequest, postRequest } from '/@/lib/axios';
  /**
   * @description: 查询部门列表 @author 卓大
   */
  export const queryAllDepartment: () => {
    return getRequest('/department/listAll');
  },

  /**
   * @description: 查询部门树形列表 @author 卓大
   */
   export const queryDepartmentTree: () => {
    return getRequest('/department/treeList');
  },

  /**
   * @description: 添加部门 @author 卓大
   */
  export const addDepartment: (param) => {
    return postRequest('/department/add', param);
  },
  /**
   * @description: 更新部门信息 @author 卓大
   */
  export const updateDepartment: (param) => {
    return postRequest('/department/update', param);
  }

在department-form-modal.vue文件中使用:

import { save, delete } from '/@/api/system/department-api';

async function save(param){
  loading();
  try{
    if(condition){
      await save(param);
    }else{
      await delete(param);
    }
  }catch(e){
    sentry.log(e);
  }finally{
    unloading();
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

import { save, delete } from '/@/api/system/department-api'; 这行代码中,delete 是 js的一个关键字,会有可能冲突,第二个,如果页面简单,那么每次用这个接口,导入会变成
import { save, delete,xxx, xxx, xxx, xxxx, xxxx, xxxx, } from '/@/api/system/department-api';
很长很长....

# 3.3 标注后端接口作者

如下代码,写清楚了后端接口作者是谁?好处:

  • 找接口问题的时候知道后端找谁
  • 本身在后端swagger中就有接口作者,一举两得

import { getRequest, postRequest } from '/@/lib/axios';
export const departmentApi = {
  /**
   * @description: 查询部门列表 @author 卓大
   */
  queryAllDepartment: () => {
    return getRequest('/department/listAll');
  },

  /**
   * @description: 查询部门树形列表 @author 卓大
   */
   queryDepartmentTree: () => {
    return getRequest('/department/treeList');
  },
  ...
  ...
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 联系我们

1024创新实验室-主任:卓大 (opens new window),混迹于各个技术圈,研究过计算机,熟悉点 java,略懂点前端。
1024创新实验室(河南·洛阳) (opens new window) 致力于成为中原领先、国内一流的技术团队,以技术创新为驱动,合作各类项目。

加 主任 “卓大” 微信
拉你入群,一起学习
关注 “小镇程序员”
分享代码与生活、技术与赚钱
请 “1024创新实验室” 喝咖啡
支持我们的开源与分享

告白气球 (钢琴版)
JESSE T