前端API层架构，也许你作得还不够

时间  2021-08-12
标签 javascript 前端 vue java node webpack ios web vue-cli typescript 栏目 系统架构 繁體版
原文   原文链接

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

石器时代，痛苦

直接调用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 {
        // 结果失败后的业务代码
    }
})
复制代码

看起来确实很难受，每调用一次接口，就有这么多重复的工做！vue

青铜器时代，中规中矩

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

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改造

使用语义化的异步函数node

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接口。若是每一个调用者都要判断是否是输入了关键词，再决定调用哪一个接口，你以为出错概率有多大，用起来烦不烦？
  • 产品说，这些场景须要优化，默认按建立时间降序排序。我擦，又一个个改一遍？
  • ......

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

铁器时代，it's cool

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

对齐微服务架构

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

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

每一个模块下都定义了统一的微服务命名空间，例如/src/api/user/index.js：vue-cli

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

特性模块

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

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目录下的内容copy到dist目录下，咱们须要配置下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文件编程的能力，自动化生成前端接口层代码，解放双手。

结语

固然，以上只是个人一点点经验和设想，是在我能力范围内能想到的东西，但愿能帮助到一些有须要的同窗。若是大佬们有更好的经验，能够指点一二。

往期精彩：

我是Tusi，一个创业公司前端小leader，天天依然为写不完的业务代码烦恼，在打磨产品道路上沉淀技术，探索成长路线。若是你与我同样，正在思考本身的技术成长与价值，欢迎加我微信交流探讨，微信号ice_lloly。我会在公众号大前端技术沙龙和小程序Tusi博客同步博客内容，快来撩我！

欢迎关注
相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程