浅谈前端项目API规范管理

参与过很多项目，项目API有的集中管理按前端模块划分，有的是书写在对应模块文件中，个人认为有以下几点问题：

• 项目api如何划分更佳合理
• 接口命名规范及方法重名问题
• 如何规避同一接口输出多个接口方法
• 开发人员如何快速知道有哪些接口方法及作用
• 如何快速输出所有接口说明
• 新项目如何快速高效生成项目api模块
• ……

针对上述问题点，在项目中规定通过配置形式自动生成对应的接口方法，并在控制台打印出api对象或通过命令一键快速输出所有接口明显说名，便于开发人员阅览。

话不多说，具体实现通过代码讲解：

项目API结构

├── src
    ├── api
        ├── docs
            └── index.js        #生成接口文档明显
        ├── modules
            ├── example.js      #接口模块配置
            └── ...
        ├── request
            ├── config.js       #公共请求方法配置
            └── index.js        #封装公共请求方法
        ├── docs.json           #接口方法明显
        └── index.js            #自动生成接口方法
    ├── ...
复制代码

modules 模块配置

接口模块按后端接口划分，不是按照前端业务或页面划分可以规避接口穿插引用或重写接口方法，和后端接口划分一致，通过模块配置、接口名取url最后一个单词，避免了命名规范及重名问题，使得api管理更佳清晰合理

// api/modules/example.js
export default [
    {
        name: 'query',          // 接口方法名取接口url最后一个单词
        method: 'get',          // 接口请求方法
        url: 'example/query',   // 接口url
        params: {},             // 接口默认传参
        docs: '接口说明'         // 接口说明
    }
]
复制代码

request 接口封装

config.js文件是根据具体业务封装接口方法

// api/request/index.js
// 接口封装
import http from './config'

export const httpGet = (url, params) => {
    return http({
        url,
        method: 'get',
        params
    })
}

export const httpPost = (url, data) => {
    return http({
        url,
        method: 'post',
        data
    })
}

export const httpPut = (url, data) => {
    return http({
        url,
        method: 'put',
        data
    })
}

export const httpDelete = (url, params, id) => {
    return http({
        url: id ? `${url}/${id}` : url ,
        method: 'detele',
        params
    })
}

export default {
    get: httpGet,
    post: httpPost,
    put: httpPut,
    delete: httpDelete
}
复制代码

自动生成接口方法

通过 require.context 自动生成接口方法

// api/index.js
import request from './requset'

const requireApi = require.context('./modules', false, /\.js$/)

const api = requireApi.keys().reduce((result, path) => {
    const moduleName = path.replace(/^\.\/([\w-]+)\.js$/, '$1')
    const moduleContent = requireApi(path).default || []

    const moduleApi = moduleContent.reduce((pre, cur) => {
        return {
            ...pre,
            // 生成接口方法
            [cur.name]: function (params = {}, id) {
                const method = request[cur.method]
                return method({
                    ...cur.params,
                    ...params
                }, id)
            },
            // 控制台查看接口说明
            [cur.name + '_docs']: cur.docs
        }

    }, {})

    return {
        ...result,
        [moduleName]: moduleApi
    }

}, {})

// 控制台打印api对象
console.log('api===', api)

export default api
复制代码

docs

快速输出所有接口接口说明

// api/docs.json
{
    "example": {
        "query": {
            "name": "example.query",
            "docs": "接口说明"
        }
    }
}
复制代码

使用

// api文件夹配置别名api
import api from 'api' // 或 import api from '@/api'

// 使用
api.example.query({ // 参数 })

复制代码

api-init

项目API管理已发布到npm，名称：api-init

快速初始化项目api：

npx api-init install
复制代码

api-init 文档地址：
hugolgw.github.io/api-main

api-init npm地址：
www.npmjs.com/package/api…

api-init 源码地址：
github.com/hugolgw/api…