上午好,今天为大家分享下个人对于前端API层架构的一点经验和看法。架构设计是一条永远走不完的路,没有最好,只有更好。这个道理适用于软件设计的各个场景,前端API层的设计也不例外,如果您觉得在调用接口时还存在诸多槽点,那就说明您的接口层架构还待优化。今天我以vue + 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的痛点,我们一般会利用Promiseaxios二次封装,对接口响应状态进行集中判断,对外暴露get, post, put, deletehttp方法。

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 (/timeout\sof\s\d+ms\sexceeded/.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接口。如果每个调用者都要判断是不是输入了关键词,再决定调用哪个接口,你觉得出错几率有多大,用起来烦不烦?
  • 产品说,这些场景需要优化,默认按创建时间降序排序。我擦,又一个个改一遍?
  • ......

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

铁器时代,it's cool

我想到的方案是在底层封装和调用者之间再增加一层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放在前面,是为了满足如果出现其他排序需求,调用者传入的排序字段能覆盖掉默认参数。

mock先行

一个完善的API层设计,肯定是离不开mock的。在后端提供接口之前,前端必须通过模拟数据并行开发,否则进度无法保证。那么如何设计一个跟真实接口契合度高的mock系统呢?我这里简单做下分享。

  • 首先,创建mock专用的axios实例

我们在src目录下新建mock目录,并在src/mock/index.js简单封装一个axios实例

// 仅限模拟数据使用
import axios from "axios"
const mock = axios.create({
baseURL: ''
});
// 返回状态拦截
mock.interceptors.response.use(
response => {
return Promise.resolve(response.data)
},
error => {
return Promise.reject(error.response)
}
) export default mock
  • mock同样也要分模块,以usercenter微服务下的角色管理mock接口为例
├─mock
index.js mock底层axios封装
├─user 负责调用基础服务,usercenter
├─role
├─index.js

我们在src/mock/user/role/index.js中简单模拟一个获取所有角色的接口getAllRoles

import mock from "@/mock";

export const getAllRoles = () => mock.get('/static/mock/user/role/getAllRoles.json')

可以看到,我们是在mock接口中获取了static/mock目录下的json数据。因此我们需要根据接口文档或者约定好的数据结构准备好getAllRoles.json数据

{
"success": true,
"result": {
"pageNo": 1,
"pageSize": 10,
"total": 2,
"list": [
{
"id": 1,
"createTime": "2019-11-19 12:53:05",
"updateTime": "2019-12-03 09:53:41",
"name": "管理员",
"code": "管理员",
"description": "一个拥有部分权限的管理员角色",
"sort": 1,
"menuIds": "789,2,55,983,54",
"menuNames": "数据字典, 后台, 账户信息, 修改密码, 账户中心"
},
{
"id": 2,
"createTime": "2019-11-27 17:18:54",
"updateTime": "2019-12-01 19:14:30",
"name": "前台测试",
"code": "前台测试",
"description": "一个拥有部分权限的前台测试角色",
"sort": 2,
"menuIds": "15,4,1",
"menuNames": "油耗统计, 车联网, 物联网监管系统"
}
]
},
"message": "请求成功",
"code": 0
}
  • 我们来看看mock是怎么做的

先看下真实接口的调用方式

import { getAllRoles } from "@/api/user/role";

created() {
this.getAllRolesData()
},
methods: {
async getAllRolesData() {
const res = await getAllRoles()
console.log(res)
}
}

那么mock时怎么做呢?非常简单,只要将mock中提供的方法替代掉api提供的方法即可。

// import { getAllRoles } from "@/api/user/role";
import { getAllRoles } from "@/mock/user/role";

可以看到,这种mock方式与调用真实接口的契合度还是挺高的,正式调试接口时,只需将注释的代码调整即可,过渡非常平滑!

  • 注意,在生产环境下,为了防止打包时将static/mock目录下的内容copydist目录下,我们需要配置下CopyWebpackPlugin,以vue-cli@2为例,我们修改webpack.base.conf.js即可。
const devMode = process.env.NODE_ENV === 'development';

new CopyWebpackPlugin([
{
from: path.resolve(__dirname, '../static'),
to: devMode ? config.dev.assetsSubDirectory : config.build.assetsSubDirectory,
ignore: devMode ? '' : 'mock/**/*'
}
])

蒸汽时代,真香

下一步的设想,使用类型安全的typescript,让前端API层真正做到面向接口文档编程,规范入参,出参,可选参数,等等,提高可维护性,在编码阶段就大大降低出错几率。虽然还在重构阶段,但是我想说,重拾typescript是真香,突然怀念使用Angular的那两年了,期待vue3.0能将typescript结合得更加完美......

电气时代,更多畅想

未来还有无限可能,面对日渐复杂和多样化的业务场景,我们会提炼出更好的架构和设计模式。目前有一个不成熟的设想,是否能在接口设计上做到更规范化,后端输出接口文档的同时,提炼出API json之类的数据结构?前端拿到API json,通过nodejs文件编程的能力,自动化生成前端接口层代码,解放双手。

结语

当然,以上只是我的一点点经验和设想,是在我能力范围内能想到的东西,希望能帮助到一些有需要的同学。如果大佬们有更好的经验,可以指点一二。


首发链接


往期精彩:

前端API层架构,也许你做得还不够的更多相关文章

  1. [译]ABP框架使用AngularJs,ASP.NET MVC,Web API和EntityFramework构建N层架构的SPA应用程序

    本文转自:http://www.skcode.cn/archives/281 本文演示ABP框架如何使用AngularJs,ASP.NET MVC,Web API 和EntityFramework构建 ...

  2. 如何通过 Vue+Webpack 来做通用的前端组件化架构设计

    目录:   1. 架构选型     2. 架构目录介绍     3. 架构说明     4. 招聘消息 目前如果要说比较流行的前端架构哪家强,屈指可数:reactjs.angularjs.emberj ...

  3. 一个简单可参考的API网关架构设计

    网关一词较早出现在网络设备里面,比如两个相互独立的局域网段之间通过路由器或者桥接设备进行通信, 这中间的路由或者桥接设备我们称之为网关. 相应的 API 网关将各系统对外暴露的服务聚合起来,所有要调用 ...

  4. ABP理论学习之N层架构

    返回总目录 自从写这个系列博客之后,发现很多园友还是希望有个直接运行的demo,其实在github上就有官方的demo,我直接把这demo的链接放到这里吧,另外,我分析,这些找不到demo的同学,很可 ...

  5. Web API应用架构在Winform混合框架中的应用(5)--系统级别字典和公司级别字典并存的处理方式

    在我这个系列中,我主要以我正在开发的云会员管理系统为例进行介绍Web API的应用,由于云会员的数据设计是支持多个商家公司,而每个公司又可以包含多个店铺的,因此一些字典型的数据需要考虑这方面的不同.如 ...

  6. Web API应用架构设计分析(2)

    在上篇随笔<Web API应用架构设计分析(1)>,我对Web API的各种应用架构进行了概括性的分析和设计,Web API 是一种应用接口框架,它能够构建HTTP服务以支撑更广泛的客户端 ...

  7. Web API应用架构设计分析(1)

    Web API 是一种应用接口框架,它能够构建HTTP服务以支撑更广泛的客户端(包括浏览器,手机和平板电脑等移动设备)的框架, ASP.NET Web API 是一种用于在 .NET Framewor ...

  8. ABP-N层架构

    ABP理论学习之N层架构   返回总目录 自从写这个系列博客之后,发现很多园友还是希望有个直接运行的demo,其实在github上就有官方的demo,我直接把这demo的链接放到这里吧,另外,我分析, ...

  9. 分享一套Code Smith 搭建N层架构模板

    开篇 平常开发时,由于冗余代码过多,程序员做重复的工作过多势必会影响开发效率.倘若 对重复性代码简单的复制.粘贴,虽然也能节省时间,但也需仔细一步步替换,这无疑也是一件费力的事.这时我们急需代码生成工 ...

随机推荐

  1. Caused by: java.lang.IllegalArgumentException: Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required [ IDEA mybatis项目报错 ]

    今天笔者用Springboot框架整合Mybatis做一个小小的项目: 代码写完,在运行项目时,IDEA给我报了3处错误: org.springframework.beans.factory.Unsa ...

  2. mui iOS云打包修改权限提示语

    打包提交appstore如果用到了如下权限需要修改提示语,详细描述使用这个权限的原因,如不修改提示语appstore审核可能会被拒绝 设置方法如下: 使用视图方式打开manifest.json文件, ...

  3. 基于verdaccio的npm私有仓库搭建

    详见个人博客:https://shengchangwei.github.io/verdaccio/ 一.使用npm安装 npm install --global verdaccio 二.cmd 启动 ...

  4. 学习笔记11全局处理程序global.asax

    *全局处理程序Clobal.asax只能叫这个名字,不能修改文件名,如果网站没有的话,可以自己添加. *Application[]类似于session,是全局的,Application["k ...

  5. 合并JSON对象的正确方式

    一. 前言 “JSON对象合并”是前端开发和 NodeJS 环境开发中非常常见的操作.开发者通常会通过循环遍历或一些库封装的方法或 JavaScript ECMAScript 2015 定义的 Obj ...

  6. Git基础使用

    前言 Git是版本控制系统,由Linux开源社区开发.与其他的版本系统相比,Git更加快速,便捷.主要是Git存储的是快照,而非差异性比较.并且绝大数操作都是访问本地文件和资源,没有网络时也可以直接提 ...

  7. 详谈Generator

    Generator究竟有什么样的作用呢???? 他是ES6提出的一个解决异步问题方案 先看一段代码, 感受一下generator函数和普通函数的区别 function* test(){ yield 2 ...

  8. [校内自测 NOIP模拟题] chenzeyu97要请客(单调栈)

    题目描述 chenzeyu97的家可以看成是一个n*m的矩阵,每块区域都有独一无二的海拔高度h(h>0)!其最大值为n*m. 现在他要选择一个子矩阵摆放一张桌子,在他眼里,这样摆放桌子的美观度为 ...

  9. python内置模块collections介绍

    目录 python内置模块collections介绍 1.namedtuple 2.deque 3.defaultdict 4.OrderedDict 5.ChainMap 6.Counter 7.小 ...

  10. php自定义截取中文字符串-utf8版

    php自定义截取中文字符串-utf8版 UTF-8的编码范围(utf-8使用1-6个字节编码字符,实际上只使用了1-4字节): 1个字节:00——7F 2个字节:C080——DFBF 3个字符:E08 ...