axios-api
@no-996/axios-api基于 axios 可建立结构化实例的工具,有以下特点:
- 基于 axios,兼容 axios 的 api,可无缝的迁移使用。
- 内置了两种常用的请求终止(基于cancelToken)场景,可防止接口重复调用。
- 内置了接口调用的缓存机制,在设置的有效期内,可从缓存中获得历史请求结果。
- 内置了接口地址模板插入功能,满足基于 url 包含变量值的场景。
- 关键:通过结构化的 api 定义生成结构化的 api 请求实例,在项目中畅快的快速调用业务接口。配套使用 webpack 插件(@no-996/axios-api-webpack-plugin),可以自动生成 d.ts 声明文件,在 IDE 中可以获得 api 定义的提醒信息。
第一次生成d.ts文件后,vscode可能需要重启才能显示请求示例的调用提示!
目录
安装使用
npm install --save @no-996/axios-api
// src/api/index.js
import ApiModule from '@no-996/axios-api'
import options from './options'
export default new ApiModule(
// 接口定义
options,
// axios配置
{
baseURL: 'https://jsonplaceholder.typicode.com',
onUploadProgress: (progressEvent, percentCompleted) => {
console.log(percentCompleted)
},
},
// axios-api配置
{
cacheStorage: localStorage,
debug: true,
}
)
import instance from './api'
// 即可根据结构化的实例进行调用,如:
// instance.module001.request()
// instance.module001.sub.request()
// instance.module002.request()
// ...
结构化的api定义
// src/api/options/index.js
export default [
{
name: 'posts',
des: '帖子',
url: '/posts',
params: {
userId: undefined,
},
children: [
{
name: 'comments',
des: '评论',
url: '/posts/{postId}/comments',
urlParams: {
postId: undefined,
},
metadata: {
urlParams: {
postId: {
name: '帖子id',
required: true,
},
},
},
},
],
metadata: {
params: {
userId: {
name: '用户id',
des: '用户唯一标识',
type: 'string',
},
},
},
},
{
name: 'albums',
url: '/albums',
des: '专辑',
params: {
id: undefined,
},
children: [],
},
{
name: 'photos',
url: '/photos',
des: '相片',
params: {},
children: [],
cache: 3000,
},
{
name: 'todos',
url: '/todos',
des: '待办事项',
params: {},
children: [],
cancel:'current'
},
{
name: 'users',
url: '/users',
des: '用户',
params: {},
children: [],
cancel:'previous'
},
]
结构化的api请求实例
通过结构化的 api 定义生成结构化的 api 请求实例,在项目中畅快的快速调用业务接口。
生成d.ts声明文件
没有定义metadata:
一层:
二层:
调用提示:
定义了metadata:
调用提示:
关于上述示例
示例使用Vue,并把请求实例挂载至Vue.prototype上:
// src/App.vue
import Vue from 'vue'
import instance from './api'
// ...
Vue.prototype.$api = instance
// ...
// src/index.d.ts
import Vue from 'vue'
import api from '@/api/index'
declare module 'vue/types/vue' {
interface Vue {
$api: typeof api
}
}
请求中止cancel
cancel: 'current'
cancel: 'previous'
缓存cache
cache: 3000
接口定义配置说明
baseURL | string/function/Promise | 否 | '' | 原baseURL的扩展,支持function/Promise返回 |
onUploadProgress | (progressEvent: any, percentCompleted: number) => void | 否 | / | 原onUploadProgress的扩展,增加第二参数,返回百分比值 |
name | string | 是 | / | 接口名 |
des | string | 否 | / | 接口描述 |
cancel | 'current'/'previous' | 否 | / | 请求中止方式 |
cache | number | 否 | / | 接口结果缓存时长毫秒数 |
urlOnly | boolean | 否 | / | 是否仅返回处理好的url地址(融合params、urlParams) |
urlParams | object | 否 | / | url地址模板替换映射 |
metadata | ApiMetadata | 否 | / | 请求参数的元数据描述,用于d.ts生成并产生智能提示 |
children | array<api配置> | 否 | [] | api配置嵌套 |
/**
* 参数元数据内容 / Params metadata info
*/
interface ApiMetadataItem {
/**
* 参数名
* / field name
*/
name: string
/**
* 参数描述
* / field des
*/
des: string
// TODO: 参数校验
/**
* 参数类型
* / field type
*/
type?: string
/**
* 参数必填
* / field required
*/
required?: boolean
/**
* 自定义校验
* / field validator
*/
// validator?:
}
/**
* 参数元数据 / Params metadata
*/
interface ApiMetadata {
[index: string]: ApiMetadataItem | string
}
axios-api配置说明
debug | boolean | false | 是否显示调试日志 |
cacheStorage | CacheStorage | / | 缓存工具(如:localStorage、sessionStorage) |
interface CacheStorage {
// 获取缓存
getItem(key: string): string | null
// 设置缓存
setItem(key: string, value: string): void
}
依赖说明
"dependencies": {
"@types/md5": "2.3.1",
"@types/qs": "6.9.7",
"@types/uuid": "8.3.4",
"axios": "0.24.0",
"md5": "2.3.0",
"qs": "6.7.0",
"uuid": "8.3.2"
}