天天看點
傳回

前端API層架構，也許你做得還不夠石器時代，痛苦青銅器時代，中規中矩鐵器時代，it's cool蒸汽時代，真香電氣時代，更多暢想結語

上午好，今天為大家分享下個人對于前端

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

的痛點，我們一般會利用

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 (/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(/
  • 針對産品突然加的排序需求，我們可以在适配層去做預設入參的處理。首先，我們建立一個專門管理預設參數的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(/

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

檔案程式設計的能力，自動化生成前端接口層代碼，解放雙手。

結語

當然，以上隻是我的一點點經驗和設想，是在我能力範圍内能想到的東西，希望能幫助到一些有需要的同學。如果大佬們有更好的經驗，可以指點一二。

上一篇: 用國中數學知識撸一個canvas環形進度條效果圖安裝與使用靜态展示動畫展示其他效果結語
下一篇: Cocos2d-x 入門調研總結