前言
前端经常要和后端对接接口了，封装一个通用的接口请求很有必要，不过光有统一的接口库还不够库，能不能用typescript的d.ts文件外加webpack插件实现代码提示的自动化呢？今天我来分享我的项目实践总结。
效果
原理
在热更新时每次读取api目录下所有js文件，解析每个接口函数的jsdoc风格的注释，生成一个对应的d.ts描述文件
动手做
创建plugins目录
在src目录创建plugins目录，再新建一个api目录
目录中手动新建index.js、runner.js、webpack.js三个文件,apis.js和index.d.ts是由webpack插件生成的，这里暂时先不管。
index.js
这是请求的主体了，一般的api请求封装就写在这里，最后注入到Vue的原型上，vue中可以用this.$api调用接口，下面放上我的代码
import Vue from 'vue'
import axios from 'axios'
import config from '../../../local_env.json'
import store from '../../stores'
// 将所有接口合并到apis.js中，这个文件由webpack插件生成
import { normalAPIs, successMessageAPIs } from './apis'
let instance = null
let api = null
Vue.use({
install(Vue, option) {
// 实例化axios,并且设置一些通用信息，例如请求地址
instance = axios.create({
baseURL: option.baseURL || '',
headers: option.headers || {},
})
// 合并到接口列表
const APIs = {
...normalAPIs,
...successMessageAPIs
}
// 接口包装，将axios实例传入接口函数调用网络请求
const result = {}
for (const k in APIs) {
result[k] = async (data) => {
// 网络请求需要捕获错误
try {
const reqRes = await APIs[k](instance, data)
if (successMessageAPIs[k] && (reqRes.data.msg || reqRes.data.message)) {
store.commit('alert', {
type: 'success',
message: reqRes.data.msg || reqRes.data.message
})
}
return reqRes.data
} catch (e) {
// 如果返回结果报错，打印报错信息
if (e.response) {
store.commit('alert', {
type: 'error',
message: e.response.data.msg || e.response.data.message
})
throw e
} else { // 代码内其他报错
store.commit('alert', {
type: 'error',
message: e.message
})
throw new Error(e.message)
}
}
}
}
// 注入到Vue的原型，在vue实例中可以通过this.$api调用接口
api = result
Vue.prototype.$api = result
}
}, {
baseURL: config.api,
headers: config.headers
})
export default api
这里我将接口的函数限定为接收两个参数的函数，第一个参数是axios的实例，第二个参数是要发给接口的参数，这样能统一写接口函数的格式。
这里还做了一些别的事情，代码里调用store.commit的部分是为了方便给有提示信息的接口发送一个通知，直接把后台返回的message信息交给一个全局的toast之类的组件来弹出提示，所以相应的把接口放在了normalAPI和successMessageAPI两个对象里
runner.js
这个文件是当文件发生变化时，将各个接口的normalAPIs和successMessageAPIs合并成一个总的对象，生成apis.js；将每个接口函数的注释中，分解出描述、参数以及返回值，最终一股脑塞到d.ts的declare interface部分，代码如下
const fs = require('fs')
const path = require('path')
/**
* 将各个api文件中的接口合并成一个文件
*/
function mergeApis () {
let list = fs.readdirSync(path.resolve(__dirname, '../../api')).filter((f) => {
return f != 'index.js' && f.endsWith('.js')
})
let apis = list.map((f) => {
let objName = path.basename(f).split(path.extname(f))[0]
let filename = f
return {
objName,
filename,
importStr: `import ${objName} from '../../api/${filename}'`
}
})
let filecontent = `
${apis.map(({importStr}) => {
return importStr
}).join('\n')
}
const normalAPIs = {
${apis.map((api) => {
return `...${api.objName}.normalAPIs`
}).join(', ')}
}
const successMessageAPIs = {
${apis.map((api) => {
return `...${api.objName}.successMessageAPIs`
}).join(', ')}
}
export {
normalAPIs,
successMessageAPIs
}
`
fs.writeFileSync(path.resolve(__dirname, './apis.js'), filecontent)
return filecontent
}
/**
* 更新api的index.d.ts文件
*/
function updateApiTypeList() {
let list = fs.readdirSync(path.resolve(__dirname, '../../api')).filter((f) => {
return f != 'index.js'
})
let finalFuncs = []
let interfaces = []
for(let j of list) {
// console.log(j)
// js文件处理
if (j.endsWith('.js')) {
finalFuncs = finalFuncs.concat(handleJsFile(j))
}
// d.ts文件处理
if (j.endsWith('.d.ts')) {
interfaces.push(handleDesTypeFile(j))
}
}
let filecontent = `
declare interface IApi {
${finalFuncs.join(',\n')}
}
${interfaces.join('\n')}
declare module 'vue/types/vue' {
interface Vue {
$api: IApi
}
}
declare var api: IApi
export default api
`
fs.writeFileSync(path.resolve(__dirname, './index.d.ts'), filecontent)
}
function handleJsFile (filename) {
// 读取文件
let module = fs.readFileSync(path.resolve(__dirname, `../../api/${filename}`), 'utf-8')
// 注释import
module = module.replace(/import(\s+)/g, '//')
// 去掉es6 module
let res = module.match(/export(\s+)default(\s+){([\sa-zA-Z0-9,]+)}/)
module = module.split(res[0])
// 包裹代码为自调用函数，返回接口对象
let moduleObj = eval(`
(() => {
${module[0]}
let result = Object.assign(normalAPIs, successMessageAPIs)
return result
})()`)
let funcs = Object.values(moduleObj)
const finalFuncs = []
for(let f of funcs) {
// console.log(f.name, '------------------')
// 获取注释的正则
let regStr = new RegExp(`(/(\\**[^\\*]*(\\*[^\\*]+)+\\*)?\\/[^\\r\\n]*)(\\s+)(const|let)(\\s+)${f.name} `)
// 获取注释
let comment = (module[0].match(regStr) || [])[0] || ''
if (comment.startsWith('}')) {
comment = comment.slice(1)
}
if (comment.endsWith(`${f.name} `)) {
let endReg = new RegExp(`(const|let)(\\s)+${f.name} `)
comment = comment.replace(endReg, '')
}
// 获取参数，暂时不支持用解构来写参数，定义接口 的时候要注意
let define = (f.toString().match(/\([a-zA-z\d,\s]+\)(\s+)=>(\s+){/) || [])[0]
if (!define) continue
define = define.replace(/\)(\s+)=>(\s+){/, '')
define = define.replace(/\((\s*)rq(\s*)([,]*)/, '')
// 参数类型从注释中获取
let defineType = ''
// 参数注释正则
const paramCommentReg = new RegExp(`@param \{([A-Za-z0-9\\[\\]<>]+)\} ${define.trim()}`)
if (define) {
const match = comment.match(paramCommentReg)
if (match) {
defineType = match[1]
}
}
// 返回结果类型获取
let returnType = 'any'
const returnCommentReg = new RegExp(`@return \{([A-za-z0-9\\[\\]<>]+)\}`)
const returnMatch = comment.match(returnCommentReg)
// console.log(f.name ,comment, returnMatch)
if (returnMatch) {
returnType = returnMatch[1]
}
// console.log(returnType)
finalFuncs.push(`${comment}${f.name}(${define.trim()}${defineType ? `:${defineType}` : ''}): Promise<${returnType}>`)
}
return finalFuncs
}
function handleDesTypeFile (filename) {
const str = fs.readFileSync(path.resolve(__dirname, `../../api/${filename}`), 'utf-8')
return str
}
module.exports = {updateApiTypeList, mergeApis}
webpack.js
这个文件是webpack插件的定义部分了，代码如下
const {updateApiTypeList, mergeApis} = require('./runner')
function AutoApiPlugin(options) {}
AutoApiPlugin.prototype.apply = function(compiler) {
let filelist = mergeApis()
compiler.plugin('emit', function(compilation, callback) {
try {
updateApiTypeList()
} finally {
callback()
}
})
}
module.exports = AutoApiPlugin
这里写得不是很严谨，如果有新增或者删除文件的话，需要重启项目，正确的写法应该是在每次变更时重新获取文件列表，再执行更新
注册插件
在main.js中引入api
import './plugins/api'
在vue.config.js中添加webpack插件
const AutoApiPlugin = require('./src/plugins/api/webpack')
module.exports = {
configureWebpack: (config) => {
config.plugins.push(
new AutoApiPlugin({})
)
}
}
写一个接口试试
在src/api目录下新建一个demo.js，代码如下
/**
*
* @param {*} rq AxiosInstance
* @param {IProduct} data 添加物料的格式
* @return {IReturn}
*/
const CreateProduct = async (rq, data) => {
let { files=[], ...rest } = data
files = files.map((file) => {
return {
file_url: file.url,
name: file.name
}
})
const postData = {
files,
...rest
}
let res = await rq.post('product/create', postData)
return res
}
在同目录下建一个demo.d.ts，代码如下
interface IProduct {
name: string,
code: string,
remark: string
}
interface IReturn {
message: string,
data: IProduct
}
运行项目npm run serve,插件执行完之后，会在plugins/api目录下生成apis.js和index.d.ts文件
在编辑器中也就能看到代码提示啦
如果第一次运行没有看到代码提示，那就重新开启项目，再启动一次。
总结
通过这么一次实验，自己尝试了一下简单的webpack插件编写，通过d.ts规范了接口文件的书写，后续可以结合swagger或者其他的插件完成更多简化接口编写的工作
