#yyds干货盘点#前端架构API层的封装

上午好,今天为大家分享下个人对于前端​​API​​​层架构的一点经验和看法。架构设计是一条永远走不完的路,没有最好,只有更好。这个道理适用于软件设计的各个场景,前端​​API​​​层的设计也不例外,如果您觉得在调用接口时还存在诸多槽点,那就说明您的接口层架构还待优化。今天我以​​vue + axios​​为例,为大家梳理下我的一些经历和设想。

axios直接调用

直接调用​axios​,真的痛苦,每个调用的地方都要进行响应状态的判断,冗余代码超级多。

import axios from "axios"

axios.get('/usercenter/user/page?pageNo=1&pageSize=10').then(res => {
const data = res.data
// 判断请求状态,success字段为true代表成功,视前后端约束而定
if (data.success) {
// 结果成功后的业务代码
} else {
// 结果失败后的业务代码
}
})

看起来确实很难受,每调用一次接口,就有这么多重复的工作!

为了解决直接调用​​axios​​​的痛点,我们一般会利用​​Promise​​对​​axios​​二次封装,对接口响应状态进行集中判断,对外暴露​​get​​, ​​post​​, ​​put​​, ​​delete​​等​​http​​方法。

axios二次封装

import axios from "axios"
import router from "@/router"
import { BASE_URL } from "@/router/base-url"
import { errorMsg } from "@/utils/msg";
import { stringify } from "@/utils/helper";
// 创建axios实例
const v3api = axios.create({
baseURL: process.env.BASE_API,
timeout: 10000
});
// axios实例默认配置
v3api.defaults.headers.common['Content-Type'] = 'application/x-www-form-urlencoded';
v3api.defaults.transformRequest = data => {
return stringify(data)
}
// 返回状态拦截,进行状态的集中判断
v3api.interceptors.response.use(
response => {
const res = response.data;
if (res.success) {
return Promise.resolve(res)
} else {
// 内部错误码处理
if (res.code === 1401) {
errorMsg(res.message || '登录已过期,请重新登录!')
router.replace({ path: `${BASE_URL}/login` })
} else {
// 默认的错误提示
errorMsg(res.message || '网络异常,请稍后重试!')
}
return Promise.reject(res);
}
},
error => {
if (/timeoutsofsd+mssexceeded/.test(error.message)) {
// 超时
errorMsg('网络出了点问题,请稍后重试!')
}
if (error.response) {
// http状态码判断
switch (error.response.status) {
// http status handler
case 404:
errorMsg('请求的资源不存在!')
break
case 500:
errorMsg('内部错误,请稍后重试!')
break
case 503:
errorMsg('服务器正在维护,请稍等!')
break
}
}
return Promise.reject(error.response)
}
)

// 处理get请求
const get = (url, params, config = {}) => v3api.get(url, { ...config, params })
// 处理delete请求,为了防止和关键词delete冲突,方法名定义为deletes
const deletes = (url, params, config = {}) => v3api.delete(url, { ...config, params })
// 处理post请求
const post = (url, params, config = {}) => v3api.post(url, params, config)
// 处理put请求
const put = (url, params, config = {}) => v3api.put(url, params, config)
export default {
get,
deletes,
post,
put
}

调用者不再判断请求状态

import api from "@/api";

methods: {
getUserPageData() {
api.get('/usercenter/user/page?pageNo=1&pageSize=10').then(res => {
// 状态已经集中判断了,这里直接写成功的逻辑
// 业务代码......
const result = res.result;
}).catch(res => {
// 失败的情况写在catch中
})
}
}

async/await改造

使用语义化的异步函数

methods: {
async getUserPageData() {
try {
const res = await api.get('/usercenter/user/page?pageNo=1&pageSize=10')
// 业务代码......
const { result } = res;
} catch(error) {
// 失败的情况写在catch中
}
}
}

存在的问题

  • 语义化程度有限,调用接口还是需要查询接口​​url​
  • 前端​​api​​层难以维护,如后端接口发生改动,前端每处都需要大改。
  • 如果​​UI​​组件的数据模型与后端接口要求的数据结构存在差异,每处调用接口前都需要进行数据处理,抹平差异,比如​​[1,2,3]​​转​​1,2,3​​这种(当然,这只是最简单的一个例子)。这样如果数据处理不慎,调用者出错几率太高!
  • 难以满足特殊化场景,举个例子,一个查询的场景,后端要求,如果输入了搜索关键词​​keyword​​,必须调用​​/user/search​​接口,如果没有输入关键词,只能调用​​/user/page​​接口。如果每个调用者都要判断是不是输入了关键词,再决定调用哪个接口,你觉得出错几率有多大,用起来烦不烦?
  • 产品说,这些场景需要优化,默认按创建时间降序排序。我擦,又一个个改一遍?
  • ......

那么怎么解决这些问题呢?请耐心接着看......

解决办法

我想到的方案是在底层封装和调用者之间再增加一层​​API​​​适配层(适配层,取量身定制之意),在适配层做统一处理,包括参数处理,请求头处理,特殊化处理等,提炼出更语义化的方法,让调用者“傻瓜式”调用,不再为了查找接口​​url​​​和处理数据结构这些重复的工作而烦恼,把​​ViewModel​​层绑定的数据模型直接丢给适配层统一处理。

对齐微服务架构

首先,为了对齐后端微服务架构,在前端将​​API​​调用分为三个模块。

├─api
index.js axios底层封装
├─base 负责调用基础服务,basecenter
├─iot 负责调用物联网服务,iotcenter
└─user 负责调用用户相关服务,usercenter
复制代码

每个模块下都定义了统一的微服务命名空间,例如​​/src/api/user/index.js​​:

export const namespace = 'usercenter';
复制代码

特性模块

每个功能特性都有独立的​​js​​模块,以角色管理相关接口为例,模块是​​/src/api/user/role.js​

import api from '../index'
import { paramsFilter } from "@/utils/helper";
import { namespace } from "./index"
const feature = 'role'

// 添加角色
export const addRole = params => api.post(`/${namespace}/${feature}/add`, paramsFilter(params));
// 删除角色
export const deleteRole = id => api.deletes(`/${namespace}/${feature}/delete`, { id });
// 更新角色
export const updateRole = params => api.put(`/${namespace}/${feature}/update`, paramsFilter(params));
// 条件查询角色
export const findRoles = params => api.get(`/${namespace}/${feature}/find`, paramsFilter(params));
// 查询所有角色,不传参调用find接口代表查询所有角色
export const getAllRoles = () => findRoles();
// 获取角色详情
export const getRoleDetail = id => api.get(`/${namespace}/${feature}/detail`, { id });
// 分页查询角色
export const getRolePage = params => api.get(`/${namespace}/${feature}/page`, paramsFilter(params));
// 搜索角色
export const searchRole = params => params.keyword ? api.get(`/${namespace}/${feature}/search`, paramsFilter(params)) : getRolePage(params);
复制代码
  • 每一条接口都根据RESTful风格,调用增(api.post)删(api.deletes)改(api.put)查(api.get)的底层方法,对外输出语义化方法。
  • 调用的url由三部分组成,格式:/微服务命名空间/特性命名空间/方法
  • 接口适配层函数命名规范:
  • 新增:​​addXXX​
  • 删除:​​deleteXXX​
  • 更新:​​updateXXX​
  • 根据ID查询记录:​​getXXXDetail​
  • 条件查询一条记录:​​findOneXXX​
  • 条件查询:​​findXXXs​
  • 查询所有记录:​​getAllXXXs​
  • 分页查询:​​getXXXPage​
  • 搜索:​​searchXXX​
  • 其余个性化接口根据语义进行命名

解决问题

  • 语义化程度更高,配合vscode的代码提示功能,用起来不要太爽!
  • 迅速响应接口改动,适配层统一处理
  • 集中进行数据处理(对于公用的数据处理,我们用paramsFilter解决,对于特殊的情况,再另行处理),调用者安心做业务即可
  • 满足特殊场景,佛系应对后端和产品朋友
  • 针对上节提到的关键字查询场景,我们在适配层通过在入参中判断是否有​​keyword​​字段,决定调用​​search​​还是​​page​​接口。对外我们只需暴露​​searchRole​​方法,调用者只需要调用​​searchRole​​方法即可,无需做其他考虑。
export const searchRole = params => params.keyword ? api.get(`/${namespace}/${feature}/search`, paramsFilter(params)) : getRolePage(params);
复制代码
  • 针对产品突然加的排序需求,我们可以在适配层去做默认入参的处理。

首先,我们新建一个专门管理默认参数的​​js​​,如​​src/api/default-options.js​

// 默认按创建时间降序的参数对象
export const SORT_BY_CREATETIME_OPTIONS = {
sortField: 'createTime',
// desc代表降序,asc是升序
sortType: 'desc'
}
复制代码

接着,我们在接口适配层做集中化处理

import api from '../index'
import { SORT_BY_CREATETIME_OPTIONS } from "../default-options"
import { paramsFilter } from "@/utils/helper";
import { namespace } from "./index"
const feature = 'role'

export const getRolePage = params => api.get(`/${namespace}/${feature}/page`, paramsFilter({ ...SORT_BY_CREATETIME_OPTIONS, ...params }));
复制代码

​SORT_BY_CREATETIME_OPTIONS​​放在前面,是为了满足如果出现其他排序需求,调用者传入的排序字段能覆盖掉默认参数。

发表评论

相关文章